Chapter 8. Using the Kafka Bridge with 3scale

Procedure

1. Deploy 3scale API Management to the OpenShift cluster.

   1. Create a new project or use an existing project.

      oc new-project my-project \
          --description="description" --display-name="display_name"

   2. Deploy 3scale.

      Use the information provided in the Installing 3scale guide to deploy 3scale on OpenShift using a template or operator.

      Whichever approach you use, make sure that you set the WILDCARD_DOMAIN parameter to the domain of your OpenShift cluster.

      Make a note of the URLS and credentials presented for accessing the 3scale Admin Portal.

2. Grant authorization for 3scale to discover the Kafka Bridge service:

   oc adm policy add-cluster-role-to-user view system:serviceaccount:my-project:amp

3. Verify that 3scale was successfully deployed to the Openshift cluster from the OpenShift console or CLI.

   For example:

   oc get deployment 3scale-operator

4. Set up 3scale toolbox.

   1. Use the information provided in the Operating 3scale guide to install 3scale toolbox.

   2. Set environment variables to be able to interact with 3scale:

      export REMOTE_NAME=strimzi-kafka-bridge 1
      export SYSTEM_NAME=strimzi_http_bridge_for_apache_kafka 2
      export TENANT=strimzi-kafka-bridge-admin 3
      export PORTAL_ENDPOINT=$TENANT.3scale.net 4
      export TOKEN=3scale access token 5

      1

      REMOTE_NAME is the name assigned to the remote address of the 3scale Admin Portal.

      2

      SYSTEM_NAME is the name of the 3scale service/API created by importing the OpenAPI specification through the 3scale toolbox.

      3

      TENANT is the tenant name of the 3scale Admin Portal (that is, https://$TENANT.3scale.net).

      4

      PORTAL_ENDPOINT is the endpoint running the 3scale Admin Portal.

      5

      TOKEN is the access token provided by the 3scale Admin Portal for interaction through the 3scale toolbox or HTTP requests.

   3. Configure the remote web address of the 3scale toolbox:

      3scale remote add $REMOTE_NAME https://$TOKEN@$PORTAL_ENDPOINT/

      Now the endpoint address of the 3scale Admin portal does not need to be specified every time you run the toolbox.

5. Check that your Cluster Operator deployment has the labels and annotations properties required for the Kafka Bridge service to be discovered by 3scale.

   #...
   env:
   - name: STRIMZI_CUSTOM_KAFKA_BRIDGE_SERVICE_LABELS
       value: |
       discovery.3scale.net=true
   - name: STRIMZI_CUSTOM_KAFKA_BRIDGE_SERVICE_ANNOTATIONS
       value: |
       discovery.3scale.net/scheme=http
       discovery.3scale.net/port=8080
       discovery.3scale.net/path=/
       discovery.3scale.net/description-path=/openapi
   #...

   If not, add the properties through the OpenShift console or try redeploying the Cluster Operator and the Kafka Bridge.

6. Discover the Kafka Bridge API service through 3scale.

   1. Log in to the 3scale Admin portal using the credentials provided when 3scale was deployed.
   2. From the 3scale Admin Portal, navigate to New API Import from OpenShift where you will see the Kafka Bridge service.

   3. Click Create Service.

      You may need to refresh the page to see the Kafka Bridge service.

      Now you need to import the configuration for the service. You do this from an editor, but keep the portal open to check the imports are successful.

7. Edit the Host field in the OpenAPI specification (JSON file) to use the base URL of the Kafka Bridge service:

   For example:

   "host": "my-bridge-bridge-service.my-project.svc.cluster.local:8080"

   Check the host URL includes the correct:

   • Kafka Bridge name (my-bridge)
   • Project name (my-project)
   • Port for the Kafka Bridge (8080)

8. Import the updated OpenAPI specification using the 3scale toolbox:

   3scale import openapi -k -d $REMOTE_NAME openapiv2.json -t myproject-my-bridge-bridge-service

9. Import the header modification and routing policies for the service (JSON file).

   1. Locate the ID for the service you created in 3scale.

      Here we use the `jq` utility:

      export SERVICE_ID=$(curl -k -s -X GET "https://$PORTAL_ENDPOINT/admin/api/services.json?access_token=$TOKEN" | jq ".services[] | select(.service.system_name | contains(\"$SYSTEM_NAME\")) | .service.id")

      You need the ID when importing the policies.

   2. Import the policies:

      curl -k -X PUT "https://$PORTAL_ENDPOINT/admin/api/services/$SERVICE_ID/proxy/policies.json" --data "access_token=$TOKEN" --data-urlencode policies_config@policies_config.json

10. From the 3scale Admin Portal, navigate to Integration Configuration to check that the endpoints and policies for the Kafka Bridge service have loaded.
11. Navigate to Applications Create Application Plan to create an application plan.

12. Navigate to Audience Developer Applications Create Application to create an application.

    The application is required in order to obtain a user key for authentication.

13. (Production environment step) To make the API available to the production gateway, promote the configuration:

    3scale proxy-config promote $REMOTE_NAME $SERVICE_ID

14. Use an API testing tool to verify you can access the Kafka Bridge through the APIcast gateway using a call to create a consumer, and the user key created for the application.

    For example:

    https//my-project-my-bridge-bridge-service-3scale-apicast-staging.example.com:443/consumers/my-group?user_key=3dfc188650101010ecd7fdc56098ce95

    If a payload is returned from the Kafka Bridge, the consumer was created successfully.

    {
      "instance_id": "consumer1",
      "base uri": "https//my-project-my-bridge-bridge-service-3scale-apicast-staging.example.com:443/consumers/my-group/instances/consumer1"
    }

    The base URI is the address that the client will use in subsequent requests.