Skip to main content
Redhat Developers  Logo
  • Products

    Featured

    • Red Hat Enterprise Linux
      Red Hat Enterprise Linux Icon
    • Red Hat OpenShift AI
      Red Hat OpenShift AI
    • Red Hat Enterprise Linux AI
      Linux icon inside of a brain
    • Image mode for Red Hat Enterprise Linux
      RHEL image mode
    • Red Hat OpenShift
      Openshift icon
    • Red Hat Ansible Automation Platform
      Ansible icon
    • Red Hat Developer Hub
      Developer Hub
    • View All Red Hat Products
    • Linux

      • Red Hat Enterprise Linux
      • Image mode for Red Hat Enterprise Linux
      • Red Hat Universal Base Images (UBI)
    • Java runtimes & frameworks

      • JBoss Enterprise Application Platform
      • Red Hat build of OpenJDK
    • Kubernetes

      • Red Hat OpenShift
      • Microsoft Azure Red Hat OpenShift
      • Red Hat OpenShift Virtualization
      • Red Hat OpenShift Lightspeed
    • Integration & App Connectivity

      • Red Hat Build of Apache Camel
      • Red Hat Service Interconnect
      • Red Hat Connectivity Link
    • AI/ML

      • Red Hat OpenShift AI
      • Red Hat Enterprise Linux AI
    • Automation

      • Red Hat Ansible Automation Platform
      • Red Hat Ansible Lightspeed
    • Developer tools

      • Red Hat Trusted Software Supply Chain
      • Podman Desktop
      • Red Hat OpenShift Dev Spaces
    • Developer Sandbox

      Developer Sandbox
      Try Red Hat products and technologies without setup or configuration fees for 30 days with this shared Openshift and Kubernetes cluster.
    • Try at no cost
  • Technologies

    Featured

    • AI/ML
      AI/ML Icon
    • Linux
      Linux Icon
    • Kubernetes
      Cloud icon
    • Automation
      Automation Icon showing arrows moving in a circle around a gear
    • View All Technologies
    • Programming Languages & Frameworks

      • Java
      • Python
      • JavaScript
    • System Design & Architecture

      • Red Hat architecture and design patterns
      • Microservices
      • Event-Driven Architecture
      • Databases
    • Developer Productivity

      • Developer productivity
      • Developer Tools
      • GitOps
    • Secure Development & Architectures

      • Security
      • Secure coding
    • Platform Engineering

      • DevOps
      • DevSecOps
      • Ansible automation for applications and services
    • Automated Data Processing

      • AI/ML
      • Data Science
      • Apache Kafka on Kubernetes
      • View All Technologies
    • Start exploring in the Developer Sandbox for free

      sandbox graphic
      Try Red Hat's products and technologies without setup or configuration.
    • Try at no cost
  • Learn

    Featured

    • Kubernetes & Cloud Native
      Openshift icon
    • Linux
      Rhel icon
    • Automation
      Ansible cloud icon
    • Java
      Java icon
    • AI/ML
      AI/ML Icon
    • View All Learning Resources

    E-Books

    • GitOps Cookbook
    • Podman in Action
    • Kubernetes Operators
    • The Path to GitOps
    • View All E-books

    Cheat Sheets

    • Linux Commands
    • Bash Commands
    • Git
    • systemd Commands
    • View All Cheat Sheets

    Documentation

    • API Catalog
    • Product Documentation
    • Legacy Documentation
    • Red Hat Learning

      Learning image
      Boost your technical skills to expert-level with the help of interactive lessons offered by various Red Hat Learning programs.
    • Explore Red Hat Learning
  • Developer Sandbox

    Developer Sandbox

    • Access Red Hat’s products and technologies without setup or configuration, and start developing quicker than ever before with our new, no-cost sandbox environments.
    • Explore Developer Sandbox

    Featured Developer Sandbox activities

    • Get started with your Developer Sandbox
    • OpenShift virtualization and application modernization using the Developer Sandbox
    • Explore all Developer Sandbox activities

    Ready to start developing apps?

    • Try at no cost
  • Blog
  • Events
  • Videos

3scale toolbox: Deploy an API from the CLI

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

Share:

    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:

    • 5 principles for deploying your API from a CI/CD pipeline
    • Deploy your API from a Jenkins Pipeline
    • Using the 3scale toolbox Jenkins Shared Library
    Last updated: May 30, 2024

    Recent Posts

    • How to run a fraud detection AI model on RHEL CVMs

    • How we use software provenance at Red Hat

    • Alternatives to creating bootc images from scratch

    • How to update OpenStack Services on OpenShift

    • How to integrate vLLM inference into your macOS and iOS apps

    Red Hat Developers logo LinkedIn YouTube Twitter Facebook

    Products

    • Red Hat Enterprise Linux
    • Red Hat OpenShift
    • Red Hat Ansible Automation Platform

    Build

    • Developer Sandbox
    • Developer Tools
    • Interactive Tutorials
    • API Catalog

    Quicklinks

    • Learning Resources
    • E-books
    • Cheat Sheets
    • Blog
    • Events
    • Newsletter

    Communicate

    • About us
    • Contact sales
    • Find a partner
    • Report a website issue
    • Site Status Dashboard
    • Report a security problem

    RED HAT DEVELOPER

    Build here. Go anywhere.

    We serve the builders. The problem solvers who create careers with code.

    Join us if you’re a developer, software engineer, web designer, front-end designer, UX designer, computer scientist, architect, tester, product manager, project manager or team lead.

    Sign me up

    Red Hat legal and privacy links

    • About Red Hat
    • Jobs
    • Events
    • Locations
    • Contact Red Hat
    • Red Hat Blog
    • Inclusion at Red Hat
    • Cool Stuff Store
    • Red Hat Summit

    Red Hat legal and privacy links

    • Privacy statement
    • Terms of use
    • All policies and guidelines
    • Digital accessibility

    Report a website issue