SupportConsoleDevelopersStart a trialContact

Chapter 3. The 3scale toolbox

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

Within 3scale documentation, there is information about the installation of the 3scale toolbox, supported toolbox commands, services, plans, troubleshooting issues with SSL and TLS, etc. Refer to one of the sections below for more details:

3.1. Installing the toolbox

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

3.1.1. Installing the toolbox container image

This section explains how to install the toolbox container image.

Prerequisites

Procedure

  1. Log in to the Red Hat container registry: 

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

  2. Pull the toolbox container image: 

    $ podman pull registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.8

  3. Verify the installation: 

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

3.1.2. Installing unsupported toolbox versions

Procedure

Additional resources

3.2. 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. The use of deprecated commands is not supported.

The following commands are supported: 

COMMANDS
    account              account super command
    activedocs           activedocs super command
    application          application super command
    application-plan     application-plan super command
    backend              backend super command
    copy                 copy super command
    help                 print help
    import               import super command
    method               method super command
    metric               metric super command
    policy-registry      policy-registry super command
    product              product super command
    proxy-config         proxy-config super command
    remote               remotes super command
    service              services super command
    update               [DEPRECATED] 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

3.3. Importing services

Import services from a CSV file by specifying the following fields in the order specified below. 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

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

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

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

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

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

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

3.6. Importing OpenAPI definitions

To create a new service or to update an existing service, you can import the OpenAPI definition from a local file or a URL. The default service name for the import is specified by the info.title in the OpenAPI definition. However, you can override this service name using --target_system_name=<NEW NAME>. This will update the service name if it already exists, or create a new service name if it does not.

The import openapi command has the following format: 

3scale import openapi [opts] -d=<destination> <specification>

The OpenAPI <specification> can be one of the following:

  • /path/to/your/definition/file.[json|yaml|yml]
  • http[s]://domain/resource/path.[json|yaml|yml]

Example

$ podman run registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.8 3scale import openapi [opts] -d=https://{DEST_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME}  my-test-api.json

Command options

The import openapi command options include:

-d --destination=<value>
3scale target instance in format: http[s]://<authentication>@3scale_domain.
-t --target_system_name=<value>
3scale target system name.
--backend-api-secret-token=<value>
Custom secret token sent by the API gateway to the backend API.
--backend-api-host-header=<value>
Custom host header sent by the API gateway to the backend API.

For more options, see the 3scale import openapi --help command.

OpenAPI import rules

The following rules apply when importing OpenAPI definitions:

  • Definitions are validated as OpenAPI 2.0 or OpenAPI 3.0.
  • All mapping rules in the 3scale service are deleted.
  • 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. You can view these in API > Integration.
  • The supported security schemes are apiKey and oauth2 with any OAuth flow type.

  • The OpenAPI specification must be one of the following:

    • Filename in the available path.
    • URL from where toolbox can download the content. The supported schemes are http and https.
    • Read from stdin standard input stream. This is controlled by setting the - value.
Note

While there is no security requirement in the specification, the service is considered as an OpenAPI. The 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 an optional parameter --default-credentials-userkey.

OpenAPI 3.0 limitations

The following limitations apply when importing OpenAPI 3.0 definitions:

  • Only the first server.url element in the servers list is parsed as a private URL. The server.url element’s path component will be used as the OpenAPI’s basePath property.
  • The toolbox will not parse servers in the path item and servers in the operation objects.
  • Multiple flows in the security scheme object not supported.

3.7. Managing remote access credentials

To facilitate working with remote 3scale instances, you can use the 3scale toolbox to define the remote URL addresses and authentication details to access those remote instances in a configuration file. You can then refer to these remotes using a short name in any toolbox command.

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

When adding remote access credentials, you can specify an access_token or a provider_key:

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

3.7.1. Adding remote access credentials

The following example command adds a remote 3scale instance with the short <name> at <url>: 

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

Example

$ podman run --name toolbox-container registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.8 3scale remote add instance_a https://123456789@example_a.net

$ podman commit toolbox-container toolbox

This example creates the remote instance and commits the container to create a new image. You can then run the new image with the remote information included. For example, the following command uses the new image to show the newly added remote: 

$ podman run toolbox 3scale remote list
instance_a https://example_a.net 123456789

Other toolbox commands can then use the newly created image to access the added remotes. This example uses an image named toolbox instead of registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.8.

Warning

Storing secrets for toolbox in a container is a potential security risk, for example when distributing the container with secrets to other users or using the container for automation. Use secured volumes in Podman or secrets in OpenShift.

Additional resources

For more details on using Podman, see:

3.7.2. Listing remote access credentials

The following example command shows how to list remote access credentials: 

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

This command shows the list of added remote 3scale instances in the following format: <name> <URL> <authentication-key>:

Example

$ podman run <toolbox_image_with_remotes_added> 3scale remote list
instance_a https://example_a.net 123456789
instance_b https://example_b.net 987654321

3.7.3. Removing remote access credentials

The following example command shows how to remove remote access credentials: 

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

This command removes the remote 3scale instance with the short <name>:

Example

$ podman run <toolbox_image_with_remote_added> 3scale remote remove instance_a

3.7.4. Renaming remote access credentials

The following example command shows how to rename remote access credentials: 

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

This command renames the remote 3scale instance with the short <old_name> to <new_name>:

Example

$ podman run <toolbox_image_with_remote_added> 3scale remote rename instance_a instance_b

3.8. Creating application plans

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

3.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
       --default                      Make the default application plan
       --disabled                     Disable all methods and metrics in
                                      the application plan
    -o --output=<value>               Output format on stdout:
                                      one of json|yaml
    -p --published                    Publish the application plan
       --setup-fee=<value>            Set-up fee
    -t --system-name=<value>          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:
                                      defaults to $HOME/.3scalerc.yaml
    -h --help                         Print help for this command
    -k --insecure                     Proceed and operate even for server
                                      connections otherwise considered
                                      insecure
    -v --version                      Print the version of this command
       --verbose                      Verbose mode

3.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                      Make the default application plan
       --disabled                     Disable all methods and metrics in
                                      the application plan
       --enabled                      Enable the application plan
       --hide                         Hide the application plan
    -n --name=<value>                 Set the plan name
    -o --output=<value>               Output format on stdout:
                                      one of json|yaml
    -p --publish                      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:
                                      defaults to $HOME/.3scalerc.yaml
    -h --help                         Print help for this command
    -k --insecure                     Proceed and operate even for server
                                      connections otherwise considered
                                      insecure
    -v --version                      Print the version of this command
       --verbose                      Verbose mode

3.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
    -o --output=<value>           Output format on stdout:
                                  one of json|yaml

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

3.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
    -o --output=<value>           Output format on stdout:
                                  one of json|yaml

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

3.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:
                                  defaults to $HOME/.3scalerc.yaml
    -h --help                     Print help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Print the version of this command
       --verbose                  Verbose mode

3.8.6. Exporting/importing 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.

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

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

This example uses a Podman 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:
                                  defaults to $HOME/.3scalerc.yaml
    -h --help                     Print help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Print the version of this command
       --verbose                  Verbose mode

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

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

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

3.8.6.3. Importing an application plan from a 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:
                                       defaults to $HOME/.3scalerc.yaml
    -h --help                          Print help for this command
    -k --insecure                      Proceed and operate even for server
                                       connections otherwise considered
                                       insecure
    -v --version                       Print the version of this command
       --verbose                       Verbose mode

3.9. Creating metrics

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

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>      Set a metric description
       --disabled                 Disable this metric in all application
                                  plans
    -o --output=<value>           Output format on stdout:
                                  one of json|yaml
    -t --system-name=<value>      Set the application plan system name
       --unit=<value>             Metric unit: default hit

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

3.9.1. 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>      Set a metric description
       --disabled                 Disable this metric in all application
                                  plans
       --enabled                  Enable this metric in all application
                                  plans
    -n --name=<value>             This will set the metric name
       --unit=<value>             Metric unit: default hit
    -o --output=<value>           Output format on stdout:
                                  one of json|yaml

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

3.9.2. Listing metrics

The following command lists metrics: 

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

Use the following options while listing metrics: 

Options
    -o --output=<value>           Output format on stdout:
                                  one of json|yaml

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

3.9.3. 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:
                                  defaults to $HOME/.3scalerc.yaml
    -h --help                     Print help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Print the version of this command
       --verbose                  Verbose mode

3.10. Creating methods

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

3.10.1. Creating methods

Use the following steps for 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: 

Options
       --description=<value>      Set a method description
       --disabled                 Disable this method in all
                                  application plans
    -o --output=<value>           Output format on stdout:
                                  one of json|yaml
    -t --system-name=<value>      Set the method system name

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

3.10.2. Creating or updating methods

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

  • If a method with the same name already exists, the command will return an error message.
  • 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>      Set a method description
       --disabled                 Disable this method in all
                                  application plans
       --enabled                  Enable this method in all
                                  application plans
    -n --name=<value>             Set the method name
    -o --output=<value>           Output format on stdout:
                                  one of json|yaml

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

3.10.3. Listing methods

The following command lists methods: 

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

Use the following options while listing methods: 

Options
    -o --output=<value>           Output format on stdout:
                                  one of json|yaml

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

3.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:
                                  defaults to $HOME/.3scalerc.yaml
    -h --help                     Print help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Print the version of this command
       --verbose                  Verbose mode

3.11. Creating services

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

3.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
    -o --output=<value>                  Output format on stdout:
                                         one of json|yaml
    -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:
                                         defaults to $HOME/.3scalerc.yaml
    -h --help                            Print help for this command
    -k --insecure                        Proceed and operate even for
                                         server connections otherwise
                                         considered insecure
    -v --version                         Print the version of this command
       --verbose                         Verbose mode

3.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
    -o --output=<value>                  Output format on stdout:
                                         one of json|yaml

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

3.11.3. Listing services

The following command lists services: 

3scale service list <remote>

Use the following options while listing services: 

Options
    -o --output=<value>           Output format on stdout:
                                  one of json|yaml

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

3.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
    -o --output=<value>           Output format on stdout:
                                  one of json|yaml

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

3.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:
                                  defaults to $HOME/.3scalerc.yaml
    -h --help                     Print help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Print the version of this command
       --verbose                  Verbose mode

3.12. Creating ActiveDocs

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

3.12.1. Creating new ActiveDocs

To create a new ActiveDocs from your API definition compliant with the OpenAPI specification:

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

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

    The OpenAPI specification for the ActiveDocs is required and must be one of the following values:

    • Filename in the available path.
    • URL from where toolbox can download the content. The supported schemes are http and https.

    • Read from stdin standard input stream. This is controlled by setting the - value.

      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
    -o --output=<value>             Output format on stdout: one
                                    of json|yaml
    -p --published                  Specify to publish the
                                    ActiveDocs on the Developer
                                    Portal. Otherwise it is hidden.
    -s --system-name=<value>        Specify the system-name of
                                    the ActiveDocs
       --skip-swagger-validations   Specify to skip validation
                                    of the Swagger specification
Options for ActiveDocs
    -c --config-file=<value>        toolbox configuration file.
                                    Defaults to $HOME/.3scalerc.yaml
    -h --help                       Print help for this command
    -k --insecure                   Proceed and operate even for
                                    server connections otherwise
                                    considered insecure
    -v --version                    Print the version of this command
       --verbose                    Verbose mode
  2. Publish the definition in your Developer Portal.

3.12.2. Creating or updating ActiveDocs

Use the following command to create new ActiveDocs 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 to hide the ActiveDocs
                                        on the Developer Portal
 -i --service-id=<value>                Specify the Service ID associated
                                        to the ActiveDocs
 -o --output=<value>                    Output format on stdout:
                                        one of json|yaml
    --openapi-spec=<value>              Specify the Swagger specification.
                                        Can be a file, a URL or '-' to read
                                        from stdin. This is a mandatory
                                        option when applying the ActiveDoc
                                        for the first time.
 -p --publish                           Specify to publish the ActiveDocs
                                        on the Developer Portal. Otherwise
                                        it is hidden
 -s --name=<value>                      Specify the name of the ActiveDocs
    --skip-swagger-validations=<value>  Specify whether to skip validation
                                        of the Swagger specification: true
                                        or false. Defaults to true.

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

The behavior of activedocs apply --skip-swagger-validations changed in 3scale 2.8. You may need to update existing scripts using activedocs apply. Previously, if you did not specify this option in each activedocs apply command, validation was not skipped. Now, --skip-swagger-validations is true by default.

3.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
    -o --output=<value>           Output format on stdout:
                                  one of json|yaml
    -s --service-ref=<value>      Filter the ActiveDocs by service
                                  reference
Options for ActiveDocs
    -c --config-file=<value>      3scale toolbox configuration file:
                                  defaults to $HOME/.3scalerc.yaml
    -h --help                     Print help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Print the version of this command
       --verbose                  Verbose mode

3.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:
                                  defaults to $HOME/.3scalerc.yaml
    -h --help                     Print help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Print the version of this command
       --verbose                  Verbose mode

3.13. Listing proxy configurations

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

The following command lists proxy configurations: 

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

Use the following options while listing proxy configurations: 

Options
    -o --output=<value>           Output format on stdout:
                                  one of json|yaml

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

3.13.1. 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
       --config-version=<value>   Specify the proxy configuration version.
                                  If not specified, defaults to latest
    -o --output=<value>           Output format on stdout:
                                  one of json|yaml

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

3.13.2. 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:
                                  defaults to $HOME/.3scalerc.yaml
    -h --help                     Print help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Print the version of this command
       --verbose                  Verbose mode

3.14. Copying a policy registry

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:
                                  defaults to $HOME/.3scalerc.yaml
    -h --help                     Print help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Print the version of this command
       --verbose                  Verbose mode

3.15. Listing applications

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

The following command lists applications: 

3scale application list [opts] <remote>

Use the following options while listing applications: 

OPTIONS
       --account=<value>          Filter by account
    -o --output=<value>           Output format on stdout:
                                  one of json|yaml
       --plan=<value>             Filter by application plan. Service
                                  option required.
       --service=<value>          Filter by service

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

3.15.1. 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 created.
       --description=<value>        Application description
    -o --output=<value>             Output format on stdout:
                                    one of json|yaml
       --redirect-url=<value>       OpenID Connect redirect url
       --user-key=<value>           User Key (API Key) of the application
                                    to be created.

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

3.15.2. 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 
OPTIONS
    -o --output=<value>           Output format on stdout:
                                  one of json|yaml

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

3.15.3. 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
    -o --output=<value>            Output format on stdout:
                                   one of json|yaml
       --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.

OPTIONS FOR APPLICATION
    -c --config-file=<value>      3scale toolbox configuration file:
                                  defaults to $HOME/.3scalerc.yaml
    -h --help                     Show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Print the version of this command
       --verbose                  Verbose mode.

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

3.16. Copying API backends

Create a copy of the specified source API backend on the specified 3scale system. The target system is first searched by the source backend system name by default:

  • If a backend with the selected system name is not found, it is created.
  • If a backend with the selected system name is found, it is updated. Only missing components are created, for example, metrics, methods, or mapping rules.

You can override the system name using the --target_system_name option.

Copied components

The following API backend components are copied:

  • Metrics
  • Methods
  • Mapping rules

Procedure

  • Enter the following command to copy an API backend: 

    3scale backend copy [opts] -s <source_remote> -d <target_remote> <source_backend>

    The specified 3scale instance can be a remote name or a URL.

    Note

    You can copy a single API backend only per command. You can copy multiple backends using multiple commands. You can copy the same backend multiple times by specifying a different --target_system_name name.

Use following options when copying API backends: 

Options
    -d --destination=<value>             3scale target instance: URL or
                                         remote name (required).
    -s --source=<value>                  3scale source instance: URL or
                                         remote name (required).
    -t --target_system_name=<value>      Target system name: defaults to
                                         source system name.

+ The following example command shows you how to copy an API backend multiple times by specifying a different --target_system_name name:

+ 

$ podman run registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.8 3scale backend copy [-t target_system_name] -s 3scale1 -d 3scale2 api_backend_01

3.16.1. Copying API products

Create a copy of the specified source API product on the target 3scale system. By default, the source API product system name first searches the target system:

  • If a product with the selected system-name is not found, it is created.
  • If a product with the selected system-name is found, it is updated. Only missing components are created; for example, metrics, methods, mapping rules, and other configurations.

You can override the system name using the --target_system_name option.

Copied components

The following API product components are copied:

  • Configuration and settings
  • Metrics and methods
  • Mapping rules
  • Application plans, pricing rules, and limits
  • Application usage rules
  • Policies
  • Backends
  • ActiveDocs

Procedure

  • Enter the following command to copy an API product: 

    3scale product copy [opts] -s <source_remote> -d <target_remote> <source_product>

    The specified 3scale instance can be a remote name or a URL.

    Note

    You can copy a single API product only per command. You can copy multiple products using multiple commands. You can copy the same product multiple times by specifying a different --target_system_name name.

Use following options when copying API products: 

Options
    -d --destination=<value>             3scale target instance: URL or
                                         remote name (required).
    -s --source=<value>                  3scale source instance: URL or
                                         remote name (required).
    -t --target_system_name=<value>      Target system name: defaults to
                                         source system name.

+ The following example command shows you how to copy an API product multiple times by specifying a different --target_system_name name:

+ 

$ podman run registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.8 3scale product copy [-t target_system_name] -s 3scale1 -d 3scale2 my_api_product_01

3.17. Troubleshooting issues with SSL and TLS

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

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

    $ podman 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.8 3scale service list https://{ACCESS_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME}

    This example uses a Podman 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

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.