SupportConsoleDevelopersStart 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

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

Procedure

  1. Install the toolbox: 

    $ yum install 3scale_toolbox

  2. Verify the installation: 

    $ 3scale help

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

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

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

2.3. Copying services

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}

2.4. Copying service settings only

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}

2.5. Importing OpenAPI definitions

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}

2.5.1. Optional flags

-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

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

3scale remote list [--config-file <config_file>]

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

2.6.2. Adding remote web addresses

3scale remote add [--config-file <config_file>] <name> <url>

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

Example 

3scale remote add instance_a https://123456789@example_a.net

2.6.3. Removing remote web addresses

3scale remote remove [--config-file <config_file>] <name>

Removes the remote woth short name <name>.

Example 

3scale remote remove instance_a

2.6.4. Renaming remote web addresses

3scale remote rename [--config-file <config_file>] <old_name> <new_name>

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

Example 

3scale remote rename instance_a instance_b

2.7. Troubleshooting SSL issues

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

  2. Make sure it works by using it with curl 

    $ SSL_CERT_FILE=self-signed-cert.pem curl -v https://self-signed.badssl.com

    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
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.

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.

© 2024 Red Hat, Inc.