Menu Close
Settings Close

Language and Page Formatting Options

Chapter 2. Using the 3scale toolbox

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

2.1. Installing the toolbox

The officially supported methods of installing the 3scale toolbox are:

  • Red Hat Enterprise Linux using yum or rpm
  • 3scale toolbox container image

2.1.1. Installing the toolbox on RHEL

You can install the toolbox on Red Hat Enterprise Linux using yum or rpm.

Prerequisites

You must enable access to the following repositories:

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

For example:

$ sudo subscription-manager repos --enable=rhel-7-server-3scale-amp-2.6-rpms --enable rhel-server-rhscl-7-rpms

Procedure

  1. Install the toolbox:

    $ yum install 3scale-toolbox
  2. Verify the installation:

    $ 3scale help

2.1.2. Installing the toolbox container image

Prerequisites

  • See the Red Hat Container Catalog page for the 3scale-amp26/toolbox image.
  • You must have a Red Hat registry service account.
  • You must have Docker installed and the daemon running.

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-amp26/toolbox
  3. Verify the installation:

    $ docker run --rm registry.redhat.io/3scale-amp26/toolbox:latest 3scale help

Additional resources

2.1.3. Installing unsupported toolbox versions

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

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

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

Import the services by running:

$ 3scale import csv --destination=https://{ACCESS_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME} --file=examples/import_example.csv

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

  • service id you want to copy: {SERVICE_ID}
  • 3scale admin account: {3SCALE_ADMIN}
  • domain your 3scale instance is running on: {DOMAIN_NAME} (if you are using hosted APICast this is 3scale.net)
  • access key of your account: {ACCESS_KEY}
  • access key of the destination account if you are copying to a different account: {DEST_KEY}
  • name for the new service: {NEW_NAME}
$ 3scale copy service {SERVICE_ID} --source=https://{ACCESS_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME} --destination=https://{DEST_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME} --target_system_name={NEW_NAME}
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 Section 2.14, “Copying a policy registry (custom policies)”

2.5. Copying service settings only

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

You will need the following information:

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

And can use the following optional flags:

  • -f remove existing target service mapping rules before copying
  • -r copy only mapping rules to target service
Note
  • The update command has been deprecated and replaced by the copy command.

    • Red Hat discourages the use of deprecated features.
$ 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 service are deleted.
  • In order to be replaced, all method names must be identical to methods defined in the OpenAPI definition (operation.operationId) by using exact pattern matching.
  • Only methods included in the OpenAPI definition are modified.
  • All methods that were present only in the OpenAPI definition are attached to the Hits metric.
  • All mapping rules from the OpenAPI definition are imported.

    • View these in API > Integration.
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.

$ 3scale import openapi [opts] --destination=https://{DEST_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME}

2.6.1. Optional flags

-d --destination=<value>
3scale target instance. 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

$ 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

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

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

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 example creates a new application plan:

Example

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 example updates the application plan:

Example

3scale application-plan apply [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 example lists the application plan:

Example

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 example shows the application plan:

Example

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 example deletes the application plan:

Example

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 example exports the application plan:

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

Example

3scale application-plan export -f plan.yaml remote_name service_name plan_name

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 example imports the application plan:

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

Example

3scale application-plan import -f plan.yaml remote_name service_name

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 example creates metrics:

Example

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 example updates metrics:

Example

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 example lists metrics:

Example

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 example deletes metrics:

Example

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 example creates a method:

Example

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 example updates a method:

Example

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 example lists methods:

Example

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 example deletes methods:

Example

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 example creates a new service:

Example

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 example updates services:

Example

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 example lists services:

Example

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 example shows services:

Example

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 example deletes services:

Example

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:

    Example

    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
  1. Publish the definition in your Developer Portal.

2.12.2. Creating or updating ActiveDocs

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

Example

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

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 example lists all defined ActiveDocs:

Example

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 example removes ActiveDocs:

Example

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 example lists proxy configurations:

Example

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 example shows proxy configurations:

Example

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 example promotes the latest staging proxy configuration to the production environment:

Example

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 example copies a policy registry:

Example

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 example lists applications:

Example

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 example creates applications:

Example

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 example shows applications:

Example

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 to create new applications if they do not exist, or to update existing applications:

Example

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 example deletes an application:

Example

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

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

  1. Download the remote certificate using openssl

    $ echo | openssl s_client -showcerts -servername self-signed.badssl.com -connect self-signed.badssl.com:443 2>/dev/null | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > self-signed-cert.pem
  2. Make sure it works by using it with curl

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

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

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

    $ SSL_CERT_FILE=self-signed-cert.pem 3scale import csv