Chapter 2. Using the 3scale toolbox

The 3scale toolbox is a Ruby client that enables you to manage 3scale products from the command line.

Important

The 3scale toolbox does not support all API as a Product (APIaaP) features. For more details, see the Known issues in the 3scale Release Notes.

2.1. Installing the toolbox

The officially supported method of installing the 3scale toolbox is using the 3scale toolbox container image.

2.1.1. Installing the toolbox container image

Prerequisites

Procedure

  1. Log in to the Red Hat container registry: 

    $ docker login registry.redhat.io
Username: ${REGISTRY-SERVICE-ACCOUNT-USERNAME}
Password: ${REGISTRY-SERVICE-ACCOUNT-PASSWORD}
Login Succeeded!

  2. Pull the toolbox container image: 

    $ docker pull registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.7

  3. Verify the installation: 

    $ docker run registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.7 3scale help

Additional resources

2.1.2. Installing unsupported toolbox versions

Procedure

2.2. Using supported toolbox commands

Use the 3scale toolbox to manage your API from the command line tool (CLI).

Note

The update command has been deprecated and replaced by the copy command. Red Hat discourages the use of deprecated features.

The following commands are supported: 

COMMANDS
    account              account super command
    activedocs           activedocs super command
    application          application super command
    application-plan     application-plan super command
    copy                 copy super command
    help                 show help
    import               import super command
    method               method super command
    metric               metric super command
    policy-registry      policy-registry super command
    proxy-config         proxy-config super command
    remote               remotes super command
    service              services super command
    update               [DEPRECTATED] update super command

OPTIONS
    -c --config-file=<value>      3scale toolbox configuration file
                                  (default: $HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Prints the version of this command
       --verbose                  Verbose mode

2.3. 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 need the following information:

  • A 3scale admin account: {3SCALE_ADMIN}

  • The domain your 3scale instance is running on: {DOMAIN_NAME}

    • If you are using hosted APICast this is 3scale.net
  • The access key of your account: {ACCESS_KEY}
  • The CSV file of services, for example: examples/import_example.csv

Import the services by running:

Example

$ docker run -v $PWD/examples/import_example.csv:/tmp/import_example.csv registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.7 3scale import csv --destination=https://{ACCESS_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME} --file=/tmp/import_example.csv

This example uses a Docker volume to mount the resource file in the container. It assumes that the file is available in the current $PWD folder.

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

  • The service id you want to copy: {SERVICE_ID}
  • A 3scale admin account: {3SCALE_ADMIN}

  • The domain your 3scale instance is running on: {DOMAIN_NAME}

    • If you are using hosted APICast this is 3scale.net
  • The access key of your account: {ACCESS_KEY}
  • The access key of the destination account if you are copying to a different account: {DEST_KEY}
  • The name for the new service: {NEW_NAME}

Example

$ docker run registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.7 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}

Note

If the service to be copied has custom policies, make sure that their respective custom policy definitions already exist in the destination where the service is to be copied. To learn more about copying custom policy definitions check out the Copying a policy registry.

2.5. Copying service settings only

You can bulk copy and update the service and proxy settings, metrics, methods, application plans, application plan limits, as well as mapping rules from a service to another existing service.

You need the following information:

  • The service id you want to copy: {SERVICE_ID}
  • The service id of the destination: {DEST_ID}
  • A 3scale admin account: {3SCALE_ADMIN}

  • The domain your 3scale instance is running on: {DOMAIN_NAME}

    • If you are using hosted APICast this is 3scale.net
  • The access key of your account: {ACCESS_KEY}
  • The access key of the destination account: {DEST_KEY}

Additionally, you can use the optional flags:

  • The -f flag to remove existing target service mapping rules before copying.
  • The -r flag to copy only mapping rules to target service.
Note

The update command has been deprecated and replaced by the copy command. The use of deprecated commands is not supported.

The following example command does a bulk update from one service to another existing service:

Example

$ docker run registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.7 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.6. Importing OpenAPI definitions

To create a new service or to update an existing service, use the definitions from a local file or access credentials. If that service name already exists, it will be updated. Conversely, if the service name does not exist, it will be created.

The default service name for the import is taken from info.title in the OpenAPI definition. You can override this service name 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 product 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.
Note

While there is no security requirement in swagger specifications, the service is considered as an OpenAPI. Toolbox will add a default_credentials policy, which is also known as an anonymous_policy, if it is not already in the policy chain. The default_credentials policy will be configured with the userkey provided in optional parameter --default-credentials-userkey.

Example

$ docker run registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.7 3scale import openapi [opts] --destination=https://{DEST_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME}

2.6.1. Optional flags

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

2.7. Managing remote access credentials

To facilitate work with remote 3scale instances, define in a config file the remote web addresses (URLs) with authentication that you will use for accessing those instances. 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.7.1. Listing remote access credentials

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

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

Example

$ docker run registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.7 3scale remote list
instance_a https://example_a.net 123456789
instance_b https://example_b.net 987654321

2.7.2. Adding remote access credentials

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

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

Example

$ docker run registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.7 3scale remote add instance_a https://123456789@example_a.net

2.7.3. Removing remote access credentials

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

Removes the remote woth short name <name>.

Example

$ docker run registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.7 3scale remote remove instance_a

2.7.4. Renaming remote access credentials

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

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

Example

$ docker run registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.7 3scale remote rename instance_a instance_b

2.8. Application plans

Use the 3scale toolbox to create, update, list, delete, show, or export/import application plans in your Developer Portal.

2.8.1. Creating a new application plan

Use the following steps to create a new application plan:

  • You have to provide the application plan name.
  • To override the system-name, use the optional parameter.
  • If an application plan with the same name already exists, you will see an error message.
  • Set as default the application plan by using the --default flag.

  • Create a published application plan by using the --publish flag.

    • By default, it will be hidden.

  • Create a disabled application plan by using the --disabled flag.

    • By default, it will be enabled.
Note

  • The service positional argument is a service reference and can be either service id or service system_name.

    • The toolbox uses either one.

The following command creates a new application plan: 

3scale application-plan create [opts] <remote> <service> <plan-name>

Use the following options while creating application plans: 

Options
       --approval-required=<value>      The application requires approval: true or false
       --cost-per-month=<value>         Cost per month
    -d --default                        This will make the default application plan
       --disabled                       This will disable all methods and metrics in
                                        the application plan
       --end-user-required=<value>      End user required: true or false
    -p --published                      This will publish the application plan
       --setup-fee=<value>              Set-up fee
    -t --system-name=<value>            This will set application plan system name
       --trial-period-days=<value>      The trial period in days

Options for application-plan
    -c --config-file=<value>            3scale toolbox configuration file
                                        (default: $HOME/.3scalerc.yaml)
    -h --help                           show help for this command
    -k --insecure                       Proceed and operate even for server
                                        connections otherwise considered insecure
    -v --version                        This will print the version of this command
       --verbose                        Verbose mode

2.8.2. Creating or updating application plans

Use the following steps to create a new application plan if it does not exist, or to update an existing one:

  • Update the default application plan by using the --default flag.
  • Update the published application plan by using the --publish flag.
  • Update the hidden application plan by using the --hide flag.
  • Update the disabled application plan by using the --disabled flag.
  • Update the enabled application plan by using the --enabled flag.
Note

  • The service positional argument is a service reference and can be either service id or service system_name.

    • The toolbox uses either one.

  • The plan positional argument is a plan reference and can be either plan id or plan system_name.

    • The toolbox uses either one.

The following command updates the application plan: 

3scale application-plan create [opts] <remote> <service> <plan>

Use the following options while updating application plans: 

Options
       --approval-required=<value>      The application requires approval: true or false
       --cost-per-month=<value>         Cost per month
       --default                        This will make the default application plan
       --disabled                       This will disable all methods and metrics in
                                        the application plan
       --enabled                        This will enable the application plan
       --end-user-required=<value>      End user required: true or false
       --hide                           This will hide the application plan
    -n --name=<value>                   This will set the plan name
    -p --publish                        This will publish the application plan
       --setup-fee=<value>              Set-up fee
       --trial-period-days=<value>      The trial period in days

Options for application-plan
    -c --config-file=<value>            3scale toolbox configuration file
                                        (default: $HOME/.3scalerc.yaml)
    -h --help                           show help for this command
    -k --insecure                       Proceed and operate even for server
                                        connections otherwise considered
                                        insecure
    -v --version                        This will print the version of this command
       --verbose                        Verbose mode

2.8.3. Listing application plans

The following command lists the application plan: 

3scale application-plan list [opts] <remote> <service>

Use the following options while listing application plans: 

Options for application-plan
    -c --config-file=<value>      3scale toolbox configuration file
                                  (default:$HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  This will print the version of this command
       --verbose                  Verbose mode

2.8.4. Showing application plans

The following command shows the application plan: 

3scale application-plan show [opts] <remote> <service> <plan>

Use the following options while showing application plans: 

Options for application-plan
    -c --config-file=<value>      3scale toolbox configuration file
                                  (default: $HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  This will print the version of this command
       --verbose                  Verbose mode

2.8.5. Deleting application plans

The following command deletes the application plan: 

3scale application-plan delete [opts] <remote> <service> <plan>

Use the following options while deleting application plans: 

Options for application-plan
    -c --config-file=<value>      3scale toolbox configuration file
                                  (default: $HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  This will print the version of this command
       --verbose                  Verbose mode

2.8.6. Export/import application plans

You can export or import a single application plan to or from yaml content.

Note the following: * Limits defined in the application plan are included. * Pricing rules defined in the application plan are included. * Metrics/methods referenced by limits and pricing rules are included. * Features defined in the application plan are included. * Service can be referenced by id or system_name. * Application Plan can be referenced by id or system_name.

2.8.6.1. Exporting an application plan to a file

The following command exports the application plan: 

3scale application-plan export [opts] <remote> <service_system_name> <plan_system_name>

Example

$ docker run -u root -v $PWD:/tmp registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.7 3scale application-plan export --file=/tmp/plan.yaml remote_name service_name plan_name

This example uses a Docker volume to mount the exported file in the container for output to the current $PWD folder.

Note

Specific to the export command:

  • Read only operation on remote service and application plan.

  • Command output can be stdout or file.

    • If not specified by -f option, by default, yaml content will be written on stdout.

Use the following options while exporting application plans: 

Options
    -f --file=<value>             Write to file instead of stdout

Options for application-plan
    -c --config-file=<value>      3scale toolbox configuration file
                                  (default: $HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Prints the version of this command
       --verbose                  Verbose mode

2.8.6.2. Importing an application plan from a file

The following command imports the application plan: 

3scale application-plan import [opts] <remote> <service_system_name>

Example

$ docker run -v $PWD/plan.yaml:/tmp/plan.yaml registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.7 3scale application-plan import --file=/tmp/plan.yaml remote_name service_name

This example uses a Docker volume to mount the imported file in the container from the current $PWD folder.

2.8.6.3. Importing an application plan from URL

3scale application-plan import -f http[s]://domain/resource/path.yaml remote_name service_name
Note

Specific to import command:

  • Command input content can be stdin, file or URL format.

    • If not specified by -f option, by default, yaml content will be read from stdin.
  • If application plan cannot be found in remote service, it will be created.

  • Optional param -p, --plan to override remote target application plan id or system_name.

    • If not specified by -p option, by default, application plan will be referenced by plan attribute system_name from yaml content.
  • Any metric or method from yaml content that cannot be found in remote service, will be created.

Use the following options while importing application plans: 

Options
    -f --file=<value>                  Read from file or url instead of stdin
    -p --plan=<value>                  Override application plan reference

Options for application-plan
    -c --config-file=<value>           3scale toolbox configuration file
                                       (default: $HOME/.3scalerc.yaml)
    -h --help                          show help for this command
    -k --insecure                      Proceed and operate even for server
                                       connections otherwise considered
                                       insecure
    -v --version                       Prints the version of this command
       --verbose                       Verbose mode

2.9. Metrics

Use the 3scale toolbox to create, update, list, and delete metrics in your Developer Portal.

2.9.1. Creating metrics

Use the following steps for creating metrics:

  • You have to provide the metric name.
  • To override the system-name, use the optional parameter.
  • If metrics with the same name already exist, you will see an error message.

  • Create a disabled metric by using the --disabled flag.

    • By default, it will be enabled.
Note

  • The service positional argument is a service reference and can be either service id or service system_name.

    • The toolbox uses either one.

The following command creates metrics: 

3scale metric create [opts] <remote> <service> <metric-name>

Use the following options while creating metrics: 

Options
       --description=<value>      This will set a metric description
       --disabled                 This will disable this metric in all application plans
    -t --system-name=<value>      This will set the application plan system name
       --unit=<value>             Metric unit: default hit

Option for metric
    -c --config-file=<value>      3scale toolbox configuration file
                                  (default: $HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  This will print the version of this command
       --verbose                  Verbose mode

2.9.2. Creating or updating metrics

Use the following steps to create new metrics if they do not exist, or to update an existing one:

  • If metrics with the same name already exist, you will see an error message.
  • Update a disabled metric by using the --disabled flag.
  • Update to enabled metric by using the --enabled flag.
Note

  • The service positional argument is a service reference and can be either service id or service system_name.

    • The toolbox uses either one.

  • The metric positional argument is a metric reference and can be either metric id or metric system_name.

    • The toolbox uses either one.

The following commmand updates metrics: 

3scale metric apply [opts] <remote> <service> <metric>

Use the following options while updating metrics: 

Options
       --description=<value>      This will set a metric description
       --disabled                 This will disable this metric in all application plans
       --enabled                  This will enable this metric in all application plans
    -n --name=<value>             This will set the metric name
       --unit=<value>             Metric unit: default hit

Options for metric
    -c --config-file=<value>      3scale toolbox configuration file
                                  (default: $HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  This will print the version of this command
       --verbose                  Verbose mode

2.9.3. Listing metrics

The following command lists metrics: 

3scale metric list [opts] <remote> <service>

Use the following options while listing metrics: 

Options for metric
    -c --config-file=<value>      3scale toolbox configuration file
                                  (default: $HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  This will print the version of this command
       --verbose                  Verbose mode

2.9.4. Deleting metrics

The following command deletes metrics: 

3scale metric delete [opts] <remote> <service> <metric>

Use the following options while deleting metrics: 

Options for metric
    -c --config-file=<value>      3scale toolbox configuration file
                                  (default: $HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  This will print the version of this command
       --verbose                  Verbose mode

2.10. Methods

Use the 3scale toolbox to create, apply, list, and delete methods in your Developer Portal.

2.10.1. Creating methods

  • You have to provide the method name.
  • To override the system-name, use the optional parameter.
  • If a method with the same name already exists, you will see an error message.

  • Create a disabled method by --disabled flag.

    • By default, it will be enabled.
Note

  • The service positional argument is a service reference and can be either service id or service system_name.

    • The toolbox uses either one.

The following command creates a method: 

3scale method create [opts] <remote> <service> <method-name>

Use the following options while creating methods: 

Option
       --description=<value>      This will set a method description
       --disabled                 This will disable this method in all
                                  application plans
    -t --system-name=<value>      This will set the method system name

Options for method
    -c --config-file=<value>      3scale toolbox configuration file (default:
                                  $HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  This will print the version of this command
       --verbose                  Verbose mode

2.10.2. Creating or updating methods

Use the following steps for creating new methods if they do not exist, or to update an existing ones:

  • If a method with the same name already exists, command will fail.
  • Update to disabled method by using --disabled flag.
  • Update to enabled method by using --enabled flag.
Note

  • The service positional argument is a service reference and can be either service id or service system_name.

    • The toolbox uses either one.

  • The method positional argument is a method reference and can be either method id or method system_name.

    • The toolbox uses either one.

The following command updates a method: 

3scale method apply [opts] <remote> <service> <method>

Use the following options while updating methods: 

Options
       --description=<value>      This will set a method description
       --disabled                 This will disable this method in all
                                  application plans
       --enabled                  This will enable this method in all
                                  application plans
    -n --name=<value>             This will set the method name

Options for method
    -c --config-file=<value>      3scale toolbox configuration file
                                  (default: $HOME/.3scalerc.yaml)
    -h --help                     This will show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  This will print the version of this command
       --verbose                  Verbose mode

2.10.3. Listing methods

The following command lists methods: 

3scale method list [opts] <remote> <service>

Use the following options while listing methods: 

Options for method
    -c --config-file=<value>      3scale toolbox configuration file
                                  (default: $HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  This will print the version of this command
       --verbose                  Verbose mode

2.10.4. Deleting methods

The following command deletes methods: 

3scale method delete [opts] <remote> <service> <metric>

Use the following options while deleting methods: 

Options for method
    -c --config-file=<value>      3scale toolbox configuration file
                                  (default: $HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  This will print the version of this command
       --verbose                  Verbose mode

2.11. Creating services

Use the 3scale toolbox to create, apply, list, show, or delete services in your Developer Portal.

2.11.1. Creating a new service

The following command creates a new service: 

3scale service create [options] <remote> <service-name>

Use the following options while creating services: 

Options
    -a --authentication-mode=<value>      Specify authentication mode of the
                                          service ('1' for API key, '2' for
                                          App Id / App Key, 'oauth' for OAuth
                                          mode, 'oidc' for OpenID Connect)
    -d --deployment-mode=<value>          Specify the deployment mode of the
                                          service
       --description=<value>              Specify the description of the
                                          service
    -s --system-name=<value>              Specify the system-name of the
                                          service
       --support-email=<value>            Specify the support email of the
                                          service

Options for service
    -c --config-file=<value>              3scale toolbox configuration file
                                          (default:
                                          $HOME/.3scalerc.yaml)
    -h --help                             show help for this command
    -k --insecure                         Proceed and operate even for server
                                          connections otherwise considered
                                          insecure
    -v --version                          Prints the version of this command
       --verbose                          Verbose mode

2.11.2. Creating or updating services

Use the following to create new services if they do not exist, or to update an existing one:

Note

  • service-id_or_system-name positional argument is a service reference.

    • It can be either service id, or service system_name.
    • Toolbox will automatically figure this out.
  • This command is idempotent.

The following command updates services: 

3scale service apply <remote> <service-id_or_system-name>

Use the following options while updating services: 

Options
    -a --authentication-mode=<value>      Specify authentication mode of the
                                          service ('1' for API key, '2' for
                                          App Id / App Key, 'oauth' for OAuth
                                          mode, 'oidc' for OpenID Connect)
    -d --deployment-mode=<value>          Specify the deployment mode of the
                                          service
       --description=<value>              Specify the description of the
                                          service
    -n --name=<value>                     Specify the name of the metric
       --support-email=<value>            Specify the support email of the
                                          service

Options for services
    -c --config-file=<value>              3scale toolbox configuration file
                                          (default: $HOME/.3scalerc.yaml)
    -h --help                             show help for this command
    -k --insecure                         Proceed and operate even for server
                                          connections otherwise considered
                                          insecure
    -v --version                          Prints the version of this command
       --verbose                          Verbose mode

2.11.3. Listing services

The following command lists services: 

3scale service list <remote>

Use the following options while listing services: 

Options for services
    -c --config-file=<value>      3scale toolbox configuration file (default:
                                  $HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Prints the version of this command
       --verbose                  Verbose mode

2.11.4. Showing services

The following command shows services: 

3scale service show <remote> <service-id_or_system-name>

Use the following options while showing services: 

Options for services
    -c --config-file=<value>      3scale toolbox configuration file
                                  (default: $HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Prints the version of this command
       --verbose                  Verbose mode

2.11.5. Deleting services

The following command deletes services: 

3scale service delete <remote> <service-id_or_system-name>

Use the following options while deleting services: 

Options for services
    -c --config-file=<value>      3scale toolbox configuration file (default:
                                  $HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Prints the version of this command
       --verbose                  Verbose mode

2.12. ActiveDocs

Use the 3scale toolbox to create, update, list, or delete ActiveDocs in your Developer Portal.

2.12.1. Creating new ActiveDocs

To create a new ActiveDocs from your OpenAPI / Swagger compliant API defintion:

  1. Add your API defintion to 3scale, optionally giving it a name: 

    3scale activedocs create <remote> <activedocs-name> <spec>

    Use the following options while creating ActiveDocs: 

    Options
    -d --description=<value>           Specify the description of the
                                       ActiveDocs
    -i --service-id=<value>            Specify the Service ID associated to
                                       the ActiveDocs
    -p --published                     Specify it to publish the ActiveDoc on
                                       the Developer Portal. Otherwise it
                                       will be hidden
    -s --system-name=<value>           Specify the system-name of the
                                       ActiveDocs
       --skip-swagger-validations      Specify it to skip validation of the
                                       Swagger specification

Options for ActiveDocs
    -c --config-file=<value>           3scale toolbox configuration file
                                       (default: $HOME/.3scalerc.yaml)
    -h --help                          show help for this command
    -k --insecure                      Proceed and operate even for server
                                       connections otherwise considered
                                       insecure
    -v --version                       Prints the version of this command
       --verbose                       Verbose mode
  2. Publish the definition in your Developer Portal.

2.12.2. Creating or updating ActiveDocs

Use the following command to create new ActiveDoc if they do not exist, or to update existing ActiveDocs with a new API definition: 

3scale activedocs apply <remote> <activedocs_id_or_system_name>

Use the following options while updating ActiveDocs: 

Options
    -d --description=<value>           Specify the description of the
                                       ActiveDocs
       --hide                          Specify it to hide the ActiveDocs on
                                       the Developer Portal
    -i --service-id=<value>            Specify the Service ID associated to
                                       the ActiveDocs
       --openapi-spec=<value>          Specify the swagger spec. Can be a
                                       file, an URL or '-' to read from
                                       stdin. This option is mandatory when
                                       applying the ActiveDoc for the first
                                       time
    -p --publish                       Specify it to publish the ActiveDocs
                                       on the Developer Portal. Otherwise it
                                       will be hidden
    -s --name=<value>                  Specify the name of the ActiveDocs
       --skip-swagger-validations      Specify it to skip validation of the
                                       Swagger specification

Options for ActiveDocs
    -c --config-file=<value>           3scale toolbox configuration file
                                       (default: $HOME/.3scalerc.yaml)
    -h --help                          show help for this command
    -k --insecure                      Proceed and operate even for server
                                       connections otherwise considered
                                       insecure
    -v --version                       Prints the version of this command
       --verbose                       Verbose mode

2.12.3. Listing ActiveDocs

Use the following command to get information about all ActiveDocs in the developer portal, including:

  • id
  • name
  • system name
  • description
  • published (which means it can be shown in the developer portal)
  • creation date
  • latest updated date

The following command lists all defined ActiveDocs: 

3scale activedocs list <remote>

Use the following options while listing ActiveDocs: 

Options for ActiveDocs
    -c --config-file=<value>      3scale toolbox configuration file
                                  (default: $HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Prints the version of this command
       --verbose                  Verbose mode

2.12.4. Deleting ActiveDocs

The following command removes ActiveDocs: 

3scale activedocs delete <remote> <activedocs-id_or-system-name>

Use the following options while deleting ActiveDocs: 

Options for ActiveDocs
    -c --config-file=<value>      3scale toolbox configuration file
                                  (default: $HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Prints the version of this command
       --verbose                  Verbose mode

2.13. Proxy configurations

Use the 3scale toolbox to list, show, promote all defined proxy configurations in your Developer Portal.

2.13.1. Listing proxy configuration

The following command lists proxy configurations: 

3scale proxy-config list <remote> <service> <environment>

Use the following options while listing proxy configurations: 

Options for proxy-config
    -c --config-file=<value>      3scale toolbox configuration file (default:
                                  /home/msoriano/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Prints the version of this command
       --verbose                  Verbose mode

2.13.2. Showing proxy configurations

The following command shows proxy configurations: 

3scale proxy-config show <remote> <service> <environment>

Use the following options while showing proxy configurations: 

Options for proxy-config
    -c --config-file=<value>         3scale toolbox configuration file
                                     (default: /home/msoriano/.3scalerc.yaml)
    -h --help                        show help for this command
    -k --insecure                    Proceed and operate even for server
                                     connections otherwise considered
                                     insecure
    -v --version                     Prints the version of this command
       --verbose                     Verbose mode

2.13.3. Promoting proxy configurations

The following command promotes the latest staging proxy configuration to the production environment: 

3scale proxy-config promote <remote> <service>

Use the following options while promoting the latest staging proxy configurations to the production environment: 

Options for proxy-config
    -c --config-file=<value>      3scale toolbox configuration file (default:
                                  /home/msoriano/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Prints the version of this command
       --verbose                  Verbose mode

2.14. Copying a policy registry (custom policies)

Use the toolbox command to copy a policy registry from a 3scale source account to a target account when:

  • missing custom policies are being created in target account.
  • matching custom policies are being updated in target account.
  • this copy command is idempotent.
Note
  • Missing custom policies are defined as custom policies that exist in source account and do not exist in an account tenant.
  • Matching custom policies are defined as custom policies that exists in both source and target account.

The following command copies a policy registry: 

3scale policy-registry copy [opts] <source_remote> <target_remote>
Option for policy-registry
    -c --config-file=<value>      3scale toolbox configuration file (default:
                                  $HOME/.3scalerc.yaml)
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Prints the version of this command
       --verbose                  Verbose mode

2.15. Applications

Use the 3scale toolbox to list, create, show, apply, or delete applications Developer Portal.

2.15.1. Listing applications

The following command lists applications: 

3scale application list [opts] <remote>

Use the following options while listing applications: 

OPTIONS
       --account=<value>          Filter by account
       --plan=<value>             Filter by application plan.
                                  Service option required.
       --service=<value>          Filter by service

2.15.2. Creating applications

Use the create command to create one application linked to a given 3scale account and application plan.

The required positional paramaters are as follows:

  • <service> reference. It can be either service id, or service system_name.

  • <account> reference. It can be one of the following:

    • Account id
    • username, email, or user_id of the admin user of the account
    • provider_key
  • <application plan> reference. It can be either plan id, or plan system_name.
  • <name> application name.

The following command creates applications: 

3scale application create [opts] <remote> <account> <service> <application-plan> <name>

Use the following options while creating applications: 

Options
       --application-id=<value>       App ID or Client ID (for OAuth and
                                      OpenID Connect authentication modes) of
                                      the application to be created.
       --application-key=<value>      App Key(s) or Client Secret (for OAuth
                                      and OpenID Connect authentication
                                      modes) of the application to be
                                      created.
       --description=<value>          Application description
       --redirect-url=<value>         OpenID Connect redirect url
       --user-key=<value>             User Key (API Key) of the application
                                      to be created.

2.15.3. Showing applications

The following command shows applications: 

3scale application show [opts] <remote> <application>

Application parameters allow:

  • User_key - API key
  • App_id - from app_id/app_key pair or Client ID for OAuth and OpenID Connect (OIDC) authentication modes
  • Application internal id

2.15.4. Creating or updating applications

Use the following command to create new applications if they do not exist, or to update existing applications: 

3scale application apply [opts] <remote> <application>

Application parameters allow:

  • User_key - API key
  • App_id - from app_id/app_key pair or Client ID for OAuth and OIDC authentication modes
  • Application internal id

  • account optional argument is required when application is not found and needs to be created. It can be one of the following:

    • Account id
    • username, email, or user_id of the administrator user of the 3scale account
    • provider_key
  • name cannot be used as unique identifier because application name is not unique in 3scale.
  • Resume a suspended application by --resume flag.
  • Suspends an application - changes the state to suspended by the --suspend flag.

Use the following options while updating applications: 

OPTIONS
       --account=<value>              Application's account. Required when
                                      creating
       --application-key=<value>      App Key(s) or Client Secret (for OAuth
                                      and OpenID Connect authentication
                                      modes) of the application to be
                                      created. Only used when application
                                      does not exist.
       --description=<value>          Application description
       --name=<value>                 Application name
       --plan=<value>                 Application's plan. Required when
                                      creating
       --redirect-url=<value>         OpenID Connect redirect url
       --resume                       Resume a suspended application
       --service=<value>              Application's service. Required when
                                      creating
       --suspend                      Suspends an application (changes the
                                      state to suspended)
       --user-key=<value>             User Key (API Key) of the application
                                      to be created.

2.15.5. Deleting applications

The following command deletes an application: 

3scale application delete [opts] <remote> <application>

Application parameters allow:

  • User_key - API key
  • App_id - from app_id/app_key pair or Client ID for OAuth and OIDC authentication modes
  • Application internal id

2.16. Troubleshooting SSL issues

This section explains how to resolve issues with Secure Sockets Layer/Transport Layer Security (SSL/TLS).

2.16.1. Installing trusted certificates

If you are experiencing issues related to self-signed SSL certificates, you can download and use remote host certificates as described in this section. For example, typical errors include SSL certificate problem: self signed certificate or self signed certificate in certificate chain.

Procedure

  1. Download the remote host certificate using openssl. For example: 

    $ 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. Ensure that the certificate is working correctly using curl. For example: 

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

    If the certificate is working correctly, you will no longer get the SSL error.

  3. Add the SSL_CERT_FILE environment variable to your 3scale commands. For example: 

    $ docker run --env "SSL_CERT_FILE=/tmp/self-signed-cert.pem" -v $PWD/self-signed-cert.pem:/tmp/self-signed-cert.pem egistry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.7 3scale service list https://{ACCESS_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME}

    This example uses a Docker volume to mount the certificate file in the container. It assumes that the file is available in the current $PWD folder.

    An alternative approach would be to create your own toolbox image using the 3scale toolbox image as the base image and then install your own trusted certificate store.

Additional resources