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: January 21, 2022