Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 2. Using the 3scale toolbox

The 3scale toolbox is a Ruby client that lets you manage 3scale services from the command line.

2.1. Installing the toolbox
Copy link

The only officially supported method of installing the toolbox is on Red Hat Enterprise Linux using yum or rpm.

Prerequisites

You must enable access to the following repositories:

  • rhel-7-server-3scale-amp-2.5-rpms
  • rhel-server-rhscl-7-rpms

For example: 

$ sudo subscription-manager repos --enable=rhel-7-server-3scale-amp-2.5-rpms --enable rhel-server-rhscl-7-rpms
Copy to Clipboard Toggle word wrap

Procedure

  1. Install the toolbox: 

    $ yum install 3scale_toolbox
    Copy to Clipboard Toggle word wrap

  2. Verify the installation: 

    $ 3scale help
    Copy to Clipboard Toggle word wrap

Additional resources

You can however use unsupported versions on Fedora Linux, Ubuntu Linux, Windows and macOS by downloading and installing the .rpm, .deb, .msi or .pkg file directly from GitHub.

2.2. Importing services
Copy link

Import services from a CSV file by specifying the following fields in this order (you also need to include these headers in your CSV file): 

service_name,endpoint_name,endpoint_http_method,endpoint_path,auth_mode,endpoint_system_name,type
Copy to Clipboard Toggle word wrap

You will need the following information:

  • 3scale admin account: {3SCALE_ADMIN}
  • domain your 3scale instance is running on: {DOMAIN_NAME} (if you are using hosted APICast this is 3scale.net)
  • access key of your account: {ACCESS_KEY}
  • CSV file of services (examples/import_example.csv)

Import the services by running: 

$ 3scale import csv --destination=https://{ACCESS_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME} --file=examples/import_example.csv
Copy to Clipboard Toggle word wrap

2.3. Copying services
Copy link

Create a new service based on an existing one from the same account or from another account. When you copy a service, the relevant ActiveDocs are also copied.

You need the following information:

  • service id you want to copy: {SERVICE_ID}
  • 3scale admin account: {3SCALE_ADMIN}
  • domain your 3scale instance is running on: {DOMAIN_NAME} (if you are using hosted APICast this is 3scale.net)
  • access key of your account: {ACCESS_KEY}
  • access key of the destination account if you are copying to a different account: {DEST_KEY}
  • name for the new service: {NEW_NAME} 
$ 3scale copy service {SERVICE_ID} --source=https://{ACCESS_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME} --destination=https://{DEST_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME} --target_system_name={NEW_NAME}
Copy to Clipboard Toggle word wrap

2.4. Copying service settings only
Copy link

Bulk copy (also known as updating) the service settings, proxy settings, metrics, methods, application plans, application plan limits and mapping rules from one service to another which already exists.

You will need the following information:

  • service id you want to copy: {SERVICE_ID}
  • service id of the destination: {DEST_ID}
  • 3scale admin account: {3SCALE_ADMIN}
  • domain your 3scale instance is running on: {DOMAIN_NAME} (if you are using hosted APICast this is 3scale.net)
  • access key of your account: {ACCESS_KEY}
  • access key of the destination account: {DEST_KEY}

And can use the following optional flags:

  • -f remove existing target service mapping rules before copying
  • -r copy only mapping rules to target service 
$ 3scale update [opts] service --source=https://{ACCESS_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME} --destination=https://{DEST_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME} {SERVICE_ID} {DEST_ID}
Copy to Clipboard Toggle word wrap

2.5. Importing OpenAPI definitions
Copy link

You can import definitions based on OpenAPI Specification (OAS) in the following formats: json and yaml. To create a new service or to update an existing service, use the definitions from a local file or a web address.

The default service name for the import is taken from info.title in the OpenAPI definition, and you can override it using --target_system_name=<NEW NAME>. If that service name already exists, it will be updated. Conversely, if the service name does not exist, it will be created.

The following rules apply to every import:

  • Definitions are validated as OpenAPI 2.0.
  • All mapping rules in the 3scale service are deleted.
  • In order to be replaced, all method names must be identical to methods defined in the OpenAPI definition (operation.operationId) by using exact pattern matching.
  • Only methods included in the OpenAPI definition are modified.
  • All methods that were present only in the OpenAPI definition are attached to the Hits metric.
  • All mapping rules from the OpenAPI definition are imported. View these in API > Integration. 
$ 3scale import openapi [opts] --destination=https://{DEST_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME}
Copy to Clipboard Toggle word wrap

2.5.1. Optional flags
Copy link

-d --destination=<value>
3scale target instance. Format: http[s]://<authentication>@3scale_domain
-t --target_system_name=<value>
Target system name

2.6. Managing remote web addresses
Copy link

To facilitate work with 3scale instances, you can define in a config file the remote web addresses (URLs) along with authentication, and refer to them by a short name in any 3scale toolbox command.

The default location for the config file is $HOME/.3scalerc.yaml but you can specify another location using the THREESCALE_CLI_CONFIG environment variable or the --config-file <config_file> option.

You can specify remotes using either an access_token or a provider_key:

  • http[s]://<access_token>@<3scale-instance-domain>
  • http[s]://<provider_key>@<3scale-instance-domain>

2.6.1. Listing remote web addresses
Copy link

3scale remote list [--config-file <config_file>]
Copy to Clipboard Toggle word wrap

Shows the list of existing remotes (name, URL and authentication key).

Example 

$ 3scale remote list
instance_a https://example_a.net 123456789
instance_b https://example_b.net 987654321
Copy to Clipboard Toggle word wrap

2.6.2. Adding remote web addresses
Copy link

3scale remote add [--config-file <config_file>] <name> <url>
Copy to Clipboard Toggle word wrap

Adds a remote with short name <name> at <url>.

Example 

3scale remote add instance_a https://123456789@example_a.net
Copy to Clipboard Toggle word wrap

2.6.3. Removing remote web addresses
Copy link

3scale remote remove [--config-file <config_file>] <name>
Copy to Clipboard Toggle word wrap

Removes the remote woth short name <name>.

Example 

3scale remote remove instance_a
Copy to Clipboard Toggle word wrap

2.6.4. Renaming remote web addresses
Copy link

3scale remote rename [--config-file <config_file>] <old_name> <new_name>
Copy to Clipboard Toggle word wrap

Renames remote with short name <old_name> to <new_name>.

Example 

3scale remote rename instance_a instance_b
Copy to Clipboard Toggle word wrap

2.7. Troubleshooting SSL issues
Copy link

There is more information on certificates in the Red Hat documentation, but if you are getting issues related to self-signed SSL certificates, SSL certificate problem: self signed certificate for example , you can download and use the remote certificate:

  1. Download the remote certificate using openssl 

    $ echo | openssl s_client -showcerts -servername self-signed.badssl.com -connect self-signed.badssl.com:443 2>/dev/null | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > self-signed-cert.pem
    Copy to Clipboard Toggle word wrap

  2. Make sure it works by using it with curl 

    $ SSL_CERT_FILE=self-signed-cert.pem curl -v https://self-signed.badssl.com
    Copy to Clipboard Toggle word wrap

    If the certificate is working properly, you will not get the SSL error.

  3. Prefix your 3scale commands with SSL_CERT_FILE=self-signed-cert.pem: 

    $ SSL_CERT_FILE=self-signed-cert.pem 3scale import csv
    Copy to Clipboard Toggle word wrap
Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat