Overview

Skill Level: Intermediate

In this recipe, we will learn how to deploy API Connect 2018 on ICP4I 2019.3.2.1. We will also configure API Connect cluster, topology, Provider & Consumer Organizations, Developer Portal and create a simple REST API, publish and test it.

Ingredients

1) IBM Cloud Pak for Integration 2019.3.2.1

2) Storage*: Appropriate storage should be configured. Below are the storages supported for deployments on-prem/cloud-native:

                      CephRBD : Recommended

                      CephFS:     Reported Working but Not Tested 

                      GlusterFS:   Not Supported 

                      NFS:           Not Supported

                      HostPath:    Known Limitation in Production 

                     IBM Block Storage: Recommended

                     AWS Elastic Block Storage (EBS) : Recommended

                     Azure Premium Storage:  Reported Working but Not Tested   

                     Azure Storage:  Reported Limitation but Not Tested

                     GCE Persistent Disk:  Reported Working but Not Tested   

* Source: APIConnect2018.4.1.x WhitePaper ( https://www.ibm.com/downloads/cas/30YERA2R )

3) Make sure that vm.max_map_count value is at least 1048575 on each storage cluster nodes

sudo sysctl -a | grep vm.max_map_count

You can also check using ‚Äúvi /etc/sysctl.conf‚ÄĚ

4) Get the configured subdomain in OCP cluster. Run the below command :

 kubectl -n openshift-console get route console -o jsonpath='{.spec.host}'| cut -f 2- -d "."

We will use this subdomain while configuring various endpoints for API Connect components

5) We will deploy API Connect instance in 'apic' project (namespace)

6) We will not cover Product and API life cycles, OAUTH security, roles & permissions, approval flows etc in this recipe. 

Step-by-step

  1. Verify Storage Class and Create Ceph User Secret

    Verify Storage Class: For this demo deployment, we have used Ceph RBD as storage solution. We have set-up a Ceph cluster. Login to Ceph monitor node and verify the health of Ceph cluster using below command:

    ceph -s

    It should show you that the Ceph cluster is in healthy state.

    To use Ceph with OCP, you need to create storage class. Below link explains how to configure Ceph RBD with Openshift.

    https://docs.openshift.com/container-platform/3.11/install_config/storage_examples/ceph_rbd_dynamic_example.html

     After completing this step, login to OCP master node and verify the storage class:

    oc login <<OpenshiftConsoleURL>> -u <<User>> -p <<Password>>
    oc get sc

    Screen-Shot-2019-10-14-at-10.24.46-PM

     We will use the Ceph storage class (ceph-storage-new) for deploying API Connect.

    ¬†Create Ceph User Secret:¬†¬†We need to create Ceph User secret in ‘apic’ namespace so that it can mount the storage.

    Login to Ceph monitor node, switch to the Ceph admin user and get the client key in base64 format.

    su - cephuser
    ceph auth get-key client.kube| base64

    Screen-Shot-2019-10-16-at-1.12.41-PM 

    Note down the key and login to OCP cluster.

    Get the ceph-user-secret name that is configured in ceph storage class. Run below command in OCP cluster:

    oc get sc ceph-storage-new -o yaml

    Here ‘ceph-storage-new’ is the name of storage class.

    Screen-Shot-2019-10-16-at-1.21.56-PM

    Note down the value of ‘userSecretName’ from the yaml definition of the storage class. We will need to create the user secret with this name in ‘apic’ namespace.

    Create yaml file, say ceph-user-secret.yaml. Below is the sample yaml file:

    apiVersion: v1
    kind: Secret
    metadata:
    name: ceph-user-secret
    namespace: apic
    data:
    key: QVFEY1dhUmRVMGF0Q3hBQVg5UTZxTmRsK2FOd0ZDTEhRcnVFeUE9PQ==
    type: kubernetes.io/rbd

    Give the ‘name’ of secret that you got from storage-class yaml file and client key noted down above. Change the namespace to ‘apic’. Now run below command to create the secret:

    oc create -f ceph-user-secret.yaml

    Screen-Shot-2019-10-16-at-1.29.17-PM

  2. Create image pull secret

    Create a registry secret in ‘apic’ project, say ‘apicregistrysecret’, to pull images from OpenShift docker registry.¬†

    kubectl -n apic create secret docker-registry apicregistrysecret \
    --docker-server=docker-registry.default.svc:5000 \
    --docker-username=admin --docker-password=$(oc whoami -t) \
    --docker-email=<email-address-doesn't-matter>

    Screen-Shot-2019-10-14-at-10.27.22-PM

  3. Create Helm TLS Secret

    Log in to the CLI of your IBM Cloud Private cluster by entering the following command:

    cloudctl login -a¬†<<ICP cluster host>> –skip-ssl-validation

    For example:

    cloudctl login -a https://icp-console.9.204.169.137.nip.io –skip-ssl-validation

    You might need to install ‘cloudctl’ in your client machine, or you can do it from ICP Console command window also.

    Screen-Shot-2019-10-15-at-2.19.57-PM

     

    Create a Helm TLS secret containing base64-encoded ca.pem, cert.pem, and key.pem artifacts. For example, you can use the following command on a single line:

    kubectl create secret generic helm-tls-secret \
    –from-file=cert.pem=$HOME/.helm/cert.pem \
    –from-file=ca.pem=$HOME/.helm/ca.pem \
    –from-file=key.pem=$HOME/.helm/key.pem \
    –namespace=<TARGET_NAMESPACE>

    Screen-Shot-2019-10-14-at-10.34.53-PM

  4. Create APIC instance

    Login to Platform home and click on ‘Add new instance’ for API Connect and click ‘Continue’.

    Screen-Shot-2019-10-15-at-2.33.31-PM

     

    We will leave other values to default except for the below specified ones.

    Enter the ‘Helm release name’, target cluster and namespace.

    Screen-Shot-2019-10-14-at-10.37.00-PM

    Enter the Cloud Pak for Integration platform endpoint. Since we are not deploying it for production, we will uncheck the ‘production deployment’ check-box.

    Screen-Shot-2019-10-14-at-10.38.22-PM

     

    Docker Registry: By default it would be entitlement registry “cp.icr.io/cp/icp4i/apic”. If you are pulling images from¬†Openshift docker registry, replace the it with your Openshift registry value for ‘apic’ images. In this case it is “docker-registry.default.svc:5000/apic”

    Registry Secret: Enter the image pull secret that was created in step 2.

    Storage Class: Enter the Ceph RBD storage class name from step 1

    Mode: Select ‘Dev’ mode as we are¬†deploying instance for Dev.

    Routing Type: Select routing type to ‘Route’ as we are deploying it on OCP cluster.

    Screen-Shot-2019-10-14-at-10.44.01-PM

     

    Helm TLS Secret: Enter the Helm TLS secret created in step 3

     

    Screen-Shot-2019-10-14-at-10.44.45-PM

    Enter the ‘Management’ endpoints. Use the subdomain to specify the endpoints. You can get the subdomain as mentioned in ‘Prerequisites step 4’ above.

    Screen-Shot-2019-10-14-at-10.46.20-PM

    Similarly specify the ‘Portal’ endpoints.

    Screen-Shot-2019-10-14-at-10.47.27-PM

     

    Similarly specify the ‘Analytics’ endpoints.

    Screen-Shot-2019-10-14-at-10.48.20-PM

    Similalrly specify ‘Gateway’ endpoints. I have changed ‘Replica Count’ to 1 to deploy only one instance of gateway.

    Screen-Shot-2019-10-14-at-10.49.14-PM

    Change ‘High Performance Peering’ to ‘off’.

    Screen-Shot-2019-10-14-at-10.49.46-PM

    Click on ‘Install’, sit-back and relax. It will take some time to deploy API Connect.

    Once API Connect is successfully installed, you can go to helm release and view all the configured endpoints.

    Screen-Shot-2019-10-15-at-3.12.04-PM

  5. Configure API Connect Cloud

    Login to Cloud Admin UI. In this recipe, we will use IBM Cloud Private Registry only as user registry. Setting-up custom registries is out of scope of this recipe.

    Screen-Shot-2019-10-15-at-7.23.36-AM

    Navigate to ‘Configure Cloud’ –> ‘Settings’ –> ‘Notifications’. Configure Name, email address and SMTP server.

    Screen-Shot-2019-10-15-at-7.32.23-AM

    Click on ‘Configure Email Server’ and specify SMTP server, Port, User name and Password as applicable.

    Screen-Shot-2019-10-15-at-9.05.03-AM

    Click on ‘Configure Topology’ from Cloud adminUI home page.

    We will create ‘Availability Zone’. Click on ‘Create availability zone’, fill the form and click on ‘create’.

    Screen-Shot-2019-10-15-at-7.24.17-AM

    Screen-Shot-2019-10-15-at-7.25.12-AM

     

     

    Register Gateway Service:¬†In the availability zone, click on ‘register service’ and select either ‘Datapower API Gateway’ or ‘Datapower API Gateway(v5 compatible)’, whichever is suitable for your use case.

    Screen-Shot-2019-10-15-at-7.27.17-AM

    Specify the name of the service, Management Endpoint and ‘API Endpoint base’. From the list of endpoints in previous step, ‘Gateway Service API’ will be the ‘Management Endpoint’ and ‘API Gateway’ will be the ‘API Endpoint base’. Leave other values to default and click on ‘Save’.

    Screen-Shot-2019-10-15-at-3.46.34-PM

    Register Analytics Service:¬†Similarly add ‘Analytics’ service using ‘Analytics Client API’ endpoint.

    Screen-Shot-2019-10-15-at-9.24.50-AM

    Register Portal Service:¬† In the same fashion add ‘Portal’ service using Portal director and Portal WebUI endpoints.

    Screen-Shot-2019-10-15-at-9.26.36-AM

    You should be able to see these services under the configured availability zone.

    Screen-Shot-2019-10-15-at-9.27.02-AM

    Click on ‘Associate Analytics Service’ and select the registered analytics service and save.

  6. Create a Provider Organization

    Depending on the level of segregation, ‘Provider Organization’ can be used as a ‘Business Unit’ (or project) and there could be various ‘Provider Organizations’ corressponding to ‘Business Units’ within a company or if it’s a small company, then provider organization could be speicific environments, e.g. DEV, QA, UAT etc…¬†API Connect gives you complete flexibility to decide topology and deployment patterns that best fit to your organization’s needs.

    Here we will create a Provider Organization with name ‘Finance’ and then will have different envionments, DEV, QA etc…, for ‘Finance’ organization with the help of ‘Catalogs’. In this recipe, we will create only one catalog with the name ‘DEV’, but you can create catalogs corresponding to your environments e.g. DEV, QA, UAT etc… and attach at least one Gateway service with each catalog.

    In Cloud Admin UI, click on ‘Provider Organizations’ and click ‘Add’.

    Screen-Shot-2019-10-15-at-9.08.04-AM

    Fill the form and click ‘Create’.

    Screen-Shot-2019-10-15-at-9.09.42-AM

    Screen-Shot-2019-10-15-at-9.09.56-AM

  7. Configure API Manager and Catalog for the Provider Organization

    Now login to the ‘API Manager’ of the Provider organization. In this case, we have created provider organization ‘Finance’. Endpoint for API Manager will be ‘API Manager UI’ endpoint appended with the provider organization name. For example, below is the API Manager endpoint for ‘Finance’ in this case:

    https://apim.9.204.169.137.nip.io/manager/finance 

    Make sure that valid email address is added for the account:

    Screen-Shot-2019-10-15-at-9.43.11-AM

    Configure Notification Email:¬†¬†Navigate to Settings –> Notifications and click on Edit. Enter the name and email address.

    Screen-Shot-2019-10-15-at-9.32.37-AM

     

    Add Catalog:¬†¬†We will add one catalog with the name ‘DEV’, indicating that this is DEV environment for ‘Finance’ organization APIs. Navigate to ‘Manage’ and click on ‘Add’. Enter the name of the catalog and click ‘Create’.

    Screen-Shot-2019-10-15-at-9.34.03-AM

     

    Navigate to ‘DEV’ catalog –> Settings –> Gateway Services and add the Gateway Service.¬†

    Screen-Shot-2019-10-15-at-9.35.36-AM

    Navigate to ‘DEV’ catalog –> Settings –> Portal and click on ‘Create’. APIs published to¬†DEV catalog will be available in this developer portal.

    Screen-Shot-2019-10-15-at-9.36.49-AM

     

    It will take few minutes to configure developer portal. An email will be sent to set the password for the account on developer portal. In case you miss the email, you can login to developer portal and reset the password using ‘forgot password’ option.

    Screen-Shot-2019-10-15-at-9.44.28-AM

    Login to Developer Portal and customize as needed.

    Screen-Shot-2019-10-15-at-5.10.41-PM

  8. Create a Consumer Organization

    Since we have self sign on enabled, we will create consumer organization from developer portal. Go¬†to Developer Portal and click on ‘Create Account’. Fill the form with all the necessary information and click on ‘sign up’. An email will be sent to provided email address for activation. Click on the link provided in email to activate the consumer organization.

    Screen-Shot-2019-10-15-at-5.32.04-PM

    Screen-Shot-2019-10-15-at-5.34.45-PM

    Sign in to Developer portal. You can add more contributors to this consumer organization with appropriate roles/permissions but that is out of scope of this recipe.

    Screen-Shot-2019-10-15-at-5.38.22-PM

    Alternatively, consumer organization can be created from API Manager either by directly creating or by invitation.

  9. Create a REST API

    Typically developers will author APIs using web-based API Connect toolkit and push the APIs to catalogs depending on configured roles/permissions. API Manager also allows to author & manage APIs, so here we will use API manager to create an API from existing API definition.

    Login to API Manager and navigate to ‘Develop’. Click on Add –> API. Select the option ‘From existing OpenAPI service’ and click ‘Next’.

    Screen-Shot-2019-10-15-at-7.13.14-PM

    Select the API definition yaml file and click Next.

    Screen-Shot-2019-10-15-at-7.15.36-PM

     

    Click Next –> Next to finish. Now click on ‘Edit API’. You can edit the API to define security, input/output message definitions, properties etc and¬†

    Now we have got the API created.

    Screen-Shot-2019-10-15-at-7.25.49-PM

     

    If you want to test API before publishing to DEV catalog, a gateway service needs to be attached to ‘Sandbox’ catalog. To configure Gateway service for ‘Sandbox’, in API Manager go to ‘Manage’ –> Sandbox –> Settings –> Gateway Services –> Edit –> Select the Gateway and save.

  10. Create Product and Plans

    In API Manager, navigate to Develop –> Add –> Product –> New Product. Fill the form and click Next.

    Screen-Shot-2019-10-15-at-7.39.33-PM

    Select the API(s) that need to be included in this product and click Next.

    Screen-Shot-2019-10-15-at-7.43.11-PM

    There is a Default Plan. You can add more Plans as per need. Click Next.

    Screen-Shot-2019-10-15-at-7.44.35-PM

    Enable ‘Publish Product’ and set Visibility and Subscribability.¬†

    Screen-Shot-2019-10-15-at-7.49.47-PM

     

    Click Next.

    Screen-Shot-2019-10-15-at-7.51.42-PM

  11. Publish the Product

    In API Manager, navigate to ‘Develop’ and click on the three dots against the product.

    Screen-Shot-2019-10-15-at-7.55.08-PM

    Click on Publish. Select the Catalog where this product needs to be published. If more than one Gateway services are associated with the Catalog, you can choose the Gateway service(s) to which you want to publish the product.

    Screen-Shot-2019-10-15-at-7.58.20-PM

     

    Click on Publish.

  12. Subscribe to Product

    Since now the product has been published, it will be available on developer portal for consumers/developers.

    Login to developer portal for this catalog. You should be able to see the product here now.

    Screen-Shot-2019-10-15-at-8.03.47-PM

    In order to subscribe to the product, consumer application should be created. Click on Apps –> Create New App.

    Note down the Key and Secret of the App. If you lose the Secret, it can not be recovered. You will need to reset Secret if you lose it.

    Screen-Shot-2019-10-15-at-8.07.47-PM

    Click Continue. Now click on the product and subscribe to a plan. 

    Screen-Shot-2019-10-15-at-8.10.53-PM

     

    Click on Subscribe and select the App.

    Screen-Shot-2019-10-15-at-8.12.42-PM

    Confirm Subscription screen will appear, click Next. Subscription complete screen will appear, click Done.

    Screen-Shot-2019-10-15-at-8.14.36-PM

  13. Test from Developer Portal

    Developer portal allows you try the APIs. You can test the APIs from Developer Portal.

    Click on the Product. It shows you the APIs, endpoint and enforced security.

    Screen-Shot-2019-10-15-at-8.17.54-PM

     

    Click on the API you want to test and click on ‘Try it’.

    Screen-Shot-2019-10-15-at-8.20.49-PM

     

    Specify the request body and click send. 

    Screen-Shot-2019-10-15-at-8.25.56-PM

    You may get certificate error in browser. To accept the certificate, just click on the url and accept. Then retry.

  14. Conclusion

    In this recipe, we learnt how to deploy IBM Cloud Pak for Integration’s API Management capability (API Connect) on Openshift 3.11 cluster. We also learnt how to configure API Connect clusters, topologies, Provider Organizations, Consumer Organizations, API Manager, Catalogs and Developer Portals. By taking a simple API, we also saw how to create an API, create product and plans, publish the product to catalog, subscribe to products and test using Developer portal.

Join The Discussion