Skip to main contentIBM Cloud Pak Playbook

API Management

This page contains guidance on how to configure the API Connect (APIC) release for both on-prem and IBM Cloud.

Prepare endpoints

We have to define the endpoint for each of the APIC subsystems. We can “construct” the endpoints by adding descriptive “prefixes” to the proxy URL. In the sample described here, the proxy URL was icp-proxy.icp4i-6550a99fb8cff23207ccecc2183787a9-0001.us-east.containers.appdomain.cloud so we defined the endpoints as follows:

ParameterSample Value
API Manager UI endpointmgmt.icp-proxy.icp4i-6550a99fb8cff23207ccecc2183787a9-0001.us-east.containers.appdomain.cloud
Cloud Admin UI endpointmcadmin.icp-proxy.icp4i-6550a99fb8cff23207ccecc2183787a9-0001.us-east.containers.appdomain.cloud
Platform API endpointmpapi.icp-proxy.icp4i-6550a99fb8cff23207ccecc2183787a9-0001.us-east.containers.appdomain.cloud
Consumer API endpointmcapi.icp-proxy.icp4i-6550a99fb8cff23207ccecc2183787a9-0001.us-east.containers.appdomain.cloud
API Gatewaygw.icp-proxy.icp4i-6550a99fb8cff23207ccecc2183787a9-0001.us-east.containers.appdomain.cloud
Gateway Servicegwd.icp-proxy.icp4i-6550a99fb8cff23207ccecc2183787a9-0001.us-east.containers.appdomain.cloud
Analytics Clientac.icp-proxy.icp4i-6550a99fb8cff23207ccecc2183787a9-0001.us-east.containers.appdomain.cloud
Analytics Ingestionai.icp-proxy.icp4i-6550a99fb8cff23207ccecc2183787a9-0001.us-east.containers.appdomain.cloud
Portalportal.icp-proxy.icp4i-6550a99fb8cff23207ccecc2183787a9-0001.us-east.containers.appdomain.cloud
Portal Directorpadmin.icp-proxy.icp4i-6550a99fb8cff23207ccecc2183787a9-0001.us-east.containers.appdomain.cloud

Obtain the pull secret

For online installs (where your cluster has connectivity to internet), you can pull the product images directly from the IBM Container Software Library aka the Entitled Container Registry. For this, you will need to create a kubernetes secret which contains the the value of your IBM Entitlement Key. Instructions for doing this are in the CP4I product documentation under the topic API management capability deployment. Search for the heading “imagePullSecret”.

For Offline or “air gap” installs, you will be pulling the images from your cluster’s internal registry. In this case, you can use one of the pull secrets that’s already configured in your target namespace (apic by default). Login to the OCP CLI and run:

oc get secrets -n <target-namespace>

The pull secret starts with deployer-dockercfg. In our case it was:

deployer-dockercfg-7mlqd

    Create the TLS secret

    The easiest way to accomplish this is to create the TLS Secret using the Visual Web Terminal inside of the Cloud Pak Foundation window. To access this window do the following

    1. Via the Platform Navigator. Select the Hamburger menu, top left and then select Cloud Pak Foundation

    2. Select the Visual Web Terminal icon. 2nd Icon from the right (looks like the box)

    3. The Visual Web Terminal will start and then once it connects to your cluster you can enter in commands. Try to enter a command like helm ls. You should see output like the following:

    4. Now you can run the following command to create the TLS secret:

      oc create secret generic apic-ent-helm-tls --from-file=cert.pem=$HOME/.helm/cert.pem --from-file=ca.pem=$HOME/.helm/ca.pem --from-file=key.pem=$HOME/.helm/key.pem -n apic

      where apic-ent-helm-tls is the name of the secret.

    Increase vm.max_map_count

    To check and increase vm.max_map_count we would need an ssh access to each of the cluster nodes.

    The alternative is to create a DaemonSet which will do that for us. Prepare the yaml file with the following content:

    apiVersion: extensions/v1beta1
    kind: DaemonSet
    metadata:
    labels:
    k8s-app: sysctl-conf
    name: sysctl-conf
    namespace: kube-system
    spec:
    template:

    and run apply it with:

    oc apply -f sysctl-conf.yaml

    Note if you have done something similar for eventstreams, note that the required value of vm.max_map_count is higher than what was required

    Storage class

    The block storage class is needed for APIC. You can obtain the class names with

    oc get storageclass

    The follwing classes are available on IBM Cloud:

    NAME PROVISIONER AGE
    default ibm.io/ibmc-file 9d
    ibmc-block-bronze (default) ibm.io/ibmc-block 9d
    ibmc-block-custom ibm.io/ibmc-block 9d
    ibmc-block-gold ibm.io/ibmc-block 9d
    ibmc-block-retain-bronze ibm.io/ibmc-block 9d
    ibmc-block-retain-custom ibm.io/ibmc-block 9d
    ibmc-block-retain-gold ibm.io/ibmc-block 9d
    ibmc-block-retain-silver ibm.io/ibmc-block 9d

    In our case, we decided to use ibmc-block-gold. This will work with IBM Cloud based installs. Offline Installs Require Ceph. Other Clouds like AWS have their own block storage. Be sure to check their documentation.

    Prepare a target namespace for your APIC instance

    Each instance of APIC must be deployed into a dedicated namespace. When CP4I is first installed, the apic namespace is created and pre-configured for this purpose. If you are deploying into the pre-configured apic namespace, you can proceed to instructions for creating your instance.

    If you are not installing into the pre-configured apic namespace, you need to issue the following oc adm commands to grant some needed permissions on the target namespace. The notation <target-namespace> in the instructions that follow, refer to the namespace into which you are deploying your APIC instance.

    oc project <target-namespace>
    oc adm policy add-scc-to-group ibm-anyuid-hostpath-scc system:serviceaccounts:<target-namespace>

    This command sequence grants any service account that is running in your target namespace, with the ibm-anyuid-hostid-scc security context permissions.

    Create an instance

    • Open platform navigator and select API Connect / Create instance

    • Click Continue

    • Define the helm release name, select apic namespace and the local-cluster.

    • Enter the registry secret name, helm TLS secret name and select storage class:

    • Enter the management and portal endpoints: Platform endpoints

    • Scroll enter the analytics and gateway endpoints: Gateway endpoints

    • If not already, switch the view to show all parameters All params

    • For the non-production installation, you may switch the mode to dev Mode

    • and the number of gateway replicas to 1 Replicas

    • Make sure the checkbox for v5 Gateway Compatibility is not checked (i.e. disabled), otherwise od tracing will not function. See here for more information. Only APIs using the API Gateway (not the v5 Compatible Gateway) will deliver data to the Operations Dashboard)

    • Ensure the Enable OD Tracing check box is enabled (i.e. checked). Ensure the proper tracing namespace is populated in the requisite box.

    • Click on Install, the confirmation message will appear: Install

    • You can check the status of the pods with the command:

    oc get pods -n apic
    • When deployment is completed, all pods must be in Running or Completed state. This entire process could take over an hour to complete. The list of pods should look similar to this one:
    apic-ibm-apiconnect-icp4i-prod-operator-0 1/1 Running 1 2h
    r09aaff73f9-analytics-proxy-5c95c649d9-2ld22 1/1 Running 0 2h
    r09aaff73f9-apiconnect-cc-0 1/1 Running 0 4h
    r09aaff73f9-apiconnect-cc-1 1/1 Running 0 3h
    r09aaff73f9-apiconnect-cc-2 1/1 Running 0 2h
    r09aaff73f9-apiconnect-cc-repair-1582765200-b5964 0/1 Completed 0 2h
    r09aaff73f9-apim-v2-857cd65d49-2mpsc 1/1 Running 0 2h
    r09aaff73f9-client-dl-srv-5c74686597-j5rmw 1/1 Running 0 2h
    r09aaff73f9-juhu-b995789c-c7glf 1/1 Running 0 2h

      Configure APIC to work with Tracing

      1. Near the end of the install of APIC, a job will be created that has the name odtracing.registration. This job will not complete until the Registration is completed inside of the Tracing capability.
      2. What will happen is that a request will be created inside of tracing that you need to act upon. Navigate to the Platform Navigator and via the Hamburger menu select Tracing and then when the window pops out select the name of your tracing instance which should be called tracing
      3. Within tracing, select the Manage icon from the menu. Looks like a cog wheel.
      4. Click on the Registration Requests icon.
      5. You should see a new registration request for your APIC install. Click the approve link
      6. You will see a pop up window with some lines to copy to your clipboard. Click the 2 boxes icon in the top right icon to copy the commands required.
      7. Ensuring you have an active oc session and in the apic project. Paste the commands to the window and it will run then and finish the processing.
      8. If you are slow in doing the steps above. It is possible you might see the odtracing.registration job fail. No worries. Once you complete the pasting of the commands to create your secret, the job will re-create itself.

      SMTP server

      In order to configure the API Connect, we need a SMTP server.

      A quick and easy setup for an smtp server required by API Connect is to use MailTrap.io. Go to https://mailtrap.io and set yourself an account. I believe you are limited to 500 emails per month for free. See pricing plans at https://mailtrap.io/pricing. Once you reach the monthly limit, you’ll get the SMTP protocol error: “535 5.7.

      Some key info you need in order to setup the smtp resource in the APIC Cloud are smtp server address. port number, username, and password.

      Once setup with MailTrap.io, clink on your inbox link in MailTrap and copy the username and password from the credentials section into the APIC username and password fields.

      You will see something similar below in the credentials section in MailTrap:

      config.action_mailer.smtp_settings = { :user_name => ‘xxxxxxxxxxxxx’, :password => ‘xxxxxxxxxxxxxx’, :address => ‘smtp.mailtrap.io’, :domain => ‘smtp.mailtrap.io’, :port => ‘2525’, :authentication => :cram_md5address: smtp.mailtrap.io

      address and port can also be take directly from the credentials section.

      address: smtp.mailtrap.io port: 2525 username: xxxxxxxxxxxxx password: xxxxxxxxxxxx

      Click the Test button in the APIC Cloud Manager and your email will be successfully sent and you can view it in MailTrap.io

      Configuring the API Connect

      • You can access your new install by starting from the Platform Navigator

      • Select IBM Cloud Private user, default username and password in this case are admin/admin Login CMC

      • Under Resources/Notifications define the SMTP server SMTP

      • For our Mailtrap server enter ClusterIP address and port: SMTP

      • Under Settings/Notifications edit the sender email server: SMTP

      • And select the SMTP server defined under resources: email

      • Start with the Topology configuration Topology

      • Register service: Register Service

      • Start with the Gateway, select the version that you defined under the Helm release properties when you started creating the instance.

      • Gateway
      • Give some name to the service (e.g. gateway1) enter the endpoints and click on Save: Gateway

      • The confirmation message should appear: Gateway

      • Click on Register service again and select Analytics: Analytics

      • Give some name to the service, enter Management endpoint (the one that you defined for analytics client) and click Save Analytics

      • The confirmation appears: Analytics

      • Before configuring the portal, you must make sure the admin_email is defined. This done by clicking the User icon in the Cloud Manager, then go to My Account. Fill out the details in the Profile window that comes up. The email field is mandatory, the remaining are optional. Click Save when complete. Portal

      • Repeat the same with portal: Portal

      • The confirmation appears again: Portal

      • Click on Associate Analytics Service to associate analytics with the gateway: Associate analytics

      • Select the analytics service: Associate analytics

      • Click on Provider organizations and add new organization: ProvOrg

      • Give some name to the organization: ProvOrg

      • Define the owner ProvOrg

      • After you submit the organization will appear on the list: ProvOrg

      • Navigate to the API Manager, in our case the endpoint was: https://mgmt.icp-proxy.icp4i-6550a99fb8cff23207ccecc2183787a9-0001.us-east.containers.appdomain.cloud/manage

      • Login as the owner (defined in the previous step), the API Manager page should open: API Mgr

      • You can navigate to the catalog: Sandbox

      • and create portal Create portal

      • You can also assign the gateway to the catalog Catalog

      With that, your API Connect instance is ready for usage.