3scale toolbox: Deploy an API from the CLI

July 29, 2019
Nicolas Massé
Related topics:
API Management
Related products:
Red Hat 3scale API Management

Deploying your API from a CI/CD pipeline can be a tremendous amount of work. The latest release of Red Hat Integration greatly improved this situation by adding new capabilities to the 3scale CLI. The 3scale CLI is named 3scale toolbox and strives to help API administrators to operate their services as well as automate the delivery of their API through Continuous Delivery pipelines.

Having a standard CLI is a great advantage for our customers since they can use it in the CI/CD solution of their choice (Jenkins, GitLab CI, Ansible, Tekton, etc.). It is also a means for Red Hat to capture customer needs as much as possible and offer the same feature set to all our customers.

3scale toolbox at a glance

The 3scale toolbox can manage a wide variety of objects:

  • Services: Import from a CSV or OpenAPI specification file.
  • Proxies: Promote a proxy configuration to production, show the current configuration.
  • ActiveDocs: Manage the OpenAPI specification repository.
  • Policies: Copy policies from a registry to another.
  • Methods and metrics.
  • Application plans: Import application plans from an artefact file.
  • Applications: Manage client applications.
  • Accounts: Manage client accounts.

The 3scale toolbox follows the usual conventions from CLIs:

  • Output a non-zero status code on error.
  • stderr contains error messages; stdout contains useful output.
  • For data that needs to be parsed by a script or pipeline, the 3scale toolbox can output JSON or YAML.

To those conventions, we added a key principle: most operations should be idempotent. This means you can simply state how you want the system to be and the 3scale toolbox will act accordingly: update the existing configuration if it exists, create when missing. Idempotence will help you build more reliable pipeline in case of an outage or transient perturbation.

Support status

The 3scale toolbox is a supported component of the Red Hat Integration solution. It is supported natively on Red Hat Enterprise Linux (RHEL) and on OpenShift. On RHEL, the toolbox is provided by the RPM "3scale-toolbox" that comes with the channel "rhel-7-server-3scale-amp-2.6-rpms." On OpenShift, the container image "3scale-amp26/toolbox" can be used.

In this release, we targeted Jenkins as the main use case for the 3scale toolbox, but you can use it with any other CI/CD solution as long as the toolbox runs on a supported configuration.

Target use cases

The 3scale toolbox can be used to achieve a wide variety of use cases:

  • CI/CD pipelines: Deploy your APIs continuously from your preferred CI/CD solution.
  • Disaster recovery plans: The 3scale toolbox can copy existing services and policies from one instance to another.
  • One-off scripts: Automate the deletion of unused services before a migration for instance.

Installation of the 3scale toolbox

Install the toolbox on your Red Hat Enterprise Linux server by running:

$ sudo yum install --enablerepo=rhel-7-server-3scale-amp-2.6-rpms 3scale-toolbox

You can confirm the toolbox is installed by executing:

$ 3scale --version
0.12.3

Configuration of the 3scale toolbox

To use the toolbox, you will have to generate an access token that has write permission on the Account Management API. Then, you can add a "remote":

$ 3scale remote add 3scale-saas "https://123...456@MY-TENANT-admin.3scale.net/"

You will have to replace "123...456" with the access token generated previously and "MY-TENANT" with the name of your 3scale Admin Portal.

You can confirm the configuration is working by listing existing services (there must be at least one):

$ 3scale service list 3scale-saas
ID             NAME      SYSTEM_NAME
2555417757658  Echo API  api

Simple use case: deploy an API from the CLI

For the first contact, let's choose a very simple use case: we would like to deploy an API from the CLI and make sure it is working end-to-end.

First, fetch the OpenAPI Specification file of the Beer Catalog service:

$ curl -sfk -o swagger.json https://raw.githubusercontent.com/microcks/api-lifecycle/master/beer-catalog-demo/api-contracts/beer-catalog-api-swagger.json

Deploy the new service:

$ 3scale import openapi -d 3scale-saas swagger.json --override-private-base-url=https://echo-api.3scale.net -t beer-catalog
Created service id: 2555417822198, name: Beer Catalog API
Service proxy updated
destroying all mapping rules
Created GET /beer/{name}$ endpoint
Created GET /beer/findByStatus/{status}$ endpoint
Created GET /beer$ endpoint

Create an application plan:

$ 3scale application-plan apply 3scale-saas beer-catalog test -n "Test Plan" --default
Applied application plan id: 2357356113164; Default: true

Create an application:

$ 3scale application apply 3scale-saas 1234567890abcdef --account=john --name="Test Application" --description="Created from the CLI" --plan=test --service=beer-catalog
Applied application id: 1409618501689

Get the URL of the staging gateway:

$ STAGING_URL=$(3scale proxy-config show 3scale-saas beer-catalog sandbox |jq -r .content.proxy.sandbox_endpoint)
$ echo $STAGING_URL
https://beer-catalog-2445582535750.staging.gw.apicast.io:443

Note: for this command to succeed, you will need to have jq installed.

Make sure the newly deployed API is working:

$ curl -D - -H "api-key: 1234567890abcdef" "$STAGING_URL/beer"
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 730
Connection: keep-alive

{
  "method": "GET",
  "path": "/beer",
  ...
}

Since the staging gateway is working perfectly, you can now promote the configuration to the production gateway:

$ 3scale proxy-config promote 3scale-saas beer-catalog
Proxy Configuration version 2 promoted to 'production'

Congratulations, your API is now up and running!

Run the toolbox in a container

In the previous examples, we ran the toolbox on a Red Hat Enterprise Linux server, but you can also run it in a container!

The first step would be to create a Kubernetes secret holding the toolbox configuration:

$ oc create secret generic 3scale-toolbox --from-file="$HOME/.3scalerc.yaml"
secret/3scale-toolbox created

Create a ConfigMap holding the OpenAPI specification file you want to deploy:

$ oc create configmap openapi --from-file=swagger.json
configmap/openapi created

Run the toolbox by creating a Kubernetes job:

$ oc create -f - <<EOF
apiVersion: batch/v1
kind: Job
metadata:
  name: toolbox
spec:
  backoffLimit: 0
  activeDeadlineSeconds: 300
  template:
    spec:
      restartPolicy: Never
      containers:
      - name: toolbox
        image: quay.io/redhat/3scale-toolbox:master
        imagePullPolicy: Always
        args: [ "3scale", "import", "openapi", "-d", "3scale-saas", "/artifacts/swagger.json", "--override-private-base-url=https://echo-api.3scale.net", "-t", "beer-catalog" ]
        env:
        - name: HOME
          value: /config
        volumeMounts:
        - name: toolbox-config
          mountPath: /config
        - name: artifacts
          mountPath: /artifacts
      volumes: 
      - name: toolbox-config
        secret: 
          secretName: 3scale-toolbox
      - name: artifacts
        configMap: 
          name: openapi
EOF

Note: The job definition above uses the community image. Red Hat customers can use this image instead: 3scale-amp26/toolbox.

Confirm the beer-catalog service has been updated:

$ oc logs -f job/toolbox 
Updated service id: 2555417822198, name: Beer Catalog API
Service proxy updated
destroying all mapping rules
Created GET /beer/{name}$ endpoint
Created GET /beer/findByStatus/{status}$ endpoint
Created GET /beer$ endpoint
Activedocs exists, update!

Conclusion

The 3scale toolbox is the basis for many automation involving APIs and the Red Hat Integration solution. It is a supported component that covers a wide range of use cases.

Discover how the API management capability of Red Hat Integration can help you deploy your API from a CI/CD pipeline:

Last updated: May 30, 2024