Chapter 5. The 3scale toolbox

The 3scale toolbox is a Ruby client that enables you to manage 3scale products 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:

5.1. Installing the toolbox

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

5.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 Ecosystem Catalog: 

    $ 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-rhel8:3scale2.13

  3. Verify the installation: 

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

Additional resources

5.2. Supported toolbox commands

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

Note

The update command has been removed and replaced by the copy command.

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

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

5.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-rhel8:3scale2.13 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.

5.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-rhel8:3scale2.13 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

5.5. Copying service settings only

You can bulk copy 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 removed and replaced by the copy command.

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

$ podman run registry.redhat.io/3scale-amp2/toolbox-rhel8:3scale2.13 3scale copy [opts] service --source=https://{ACCESS_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME} --destination=https://{DEST_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME} {SERVICE_ID} {DEST_ID}

5.6. OpenAPI Authentication

By implementing OpenAPI authentication with the 3scale toolbox, you can ensure that only authorized users have access to your APIs, safeguard sensitive data, and efficiently manage API usage. This approach will reinforces your API infrastructure and fosters trust among developers and consumers.

Note

Only one top-level security requirement is supported; operation-level security requirements are not supported.

Supported security schemes: apiKey and oauth2 with any flow type.

For the apiKey security scheme type:

  • The credentials location is read from the OpenAPI in field of the security scheme object.
  • Auth user key is read from the OpenAPI name field of the security scheme object.

Partial example of OpenAPI 3.0.2 with apiKey security requirement:

openapi: "3.0.2"
security:
  - petstore_api_key: []
components:
  securitySchemes:
    petstore_api_key:
      type: apiKey
      name: api_key
      in: header
      ...

For the oauth2 security scheme type:

  • The credentials location is hard-coded to headers.
  • OpenID Connect Issuer Type defaults to rest. You can be override this using the --oidc-issuer-type=<value> command option.
  • OpenID Connect Issuer is not read from OpenAPI. Since 3scale requires that the issuer URL must include a client secret, the issue must be set using this --oidc-issuer-endpoint=<value> command option.
  • OIDC AUTHORIZATION FLOW is read from the flows field of the security scheme object.

Partial example of OpenAPI 3.0.2 with oauth2 security requirement:

openapi: "3.0.2"
security:
    - petstore_oauth:
      - write:pets
      - read:pets
  components:
    securitySchemes:
      petstore_oauth:
        type: oauth2
        flows:
          clientCredentials:
            tokenUrl: http://example.org/api/oauth/dialog
            scopes:
              write:pets: modify pets in your account
              read:pets: read your pets
              ...

When OpenAPI does not specify any security requirements:

  • The product is considered as an Open API.
  • The default_credentials 3scale policy is added. Note: This is also called as anonymous_policy.
  • You require the command --default-credentials-userkey. Note: The command fails if is not provided.

Additional resources

5.7. 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-rhel8:3scale2.13 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 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.

The following additional rules apply when importing OpenAPI definitions:

  • Definitions are validated as OpenAPI 2.0 or OpenAPI 3.0.
  • All mapping rules from the OpenAPI definition are imported. You can view these in API > Integration.
  • All mapping rules in the 3scale product are replaced.
  • 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.
  • To replace methods, the method names must be identical to the methods defined in the OpenAPI definition operation.operationId by using exact pattern matching.
Note

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 provides a way to specify security for your API using its security schemes and security requirements features. For more information, see the official Swagger Authentication and Authorization documentation.

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.

5.8. Importing a 3scale backend from an OpenAPI definition

You can use the toolbox import command to import an OpenAPI definition and create a 3scale backend API. The command line option --backend enables this feature. 3scale uses the OpenAPI definition to create and store a backend and its private base URL, as well as its mapping rules and methods.

Prerequisites

  • A user account with administrator privileges for a 3scale 2.13 On-Premises instance.
  • An OAS document that defines your API.

Procedure

  • Use the following format to run the import command to create a backend: 

    $ 3scale import openapi -d <remote> --backend <OAS>
  • Replace <remote> with the URL for the 3scale instance in which to create the backend. Use this format: http[s]://<authentication>@3scale_domain

  • Replace <OAS> with the /path/to/your/oasdoc.yaml.

    Table 5.1. Additional OpenAPI definition options

    OptionsDescription

    -o --output=<value>

    The output format. Can be either JSON or YAML.

    --override-private-base-url=<value>

    3scale reads the backend’s private endpoint from the OpenAPI definition’s servers[0].url field. To override the setting in that field, specify this option and replace <value> with the private base URL of your choice. When the OpenAPI definition does not specify a value in the servers[0].url field and you do not specify the this option in the import command, execution fails.

    --prefix-matching

    Use prefix matching instead of strict matching on mapping rules derived from OpenAPI operations.

    --skip-openapi-validation

    Skip OpenAPI schema validation.

    -t --target_system_name=<value>

    Target system name is a unique key in your tenant. System name can be inferred from the OpenAPI definition, however you can override that with your own name by using this parameter.

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

5.9.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-rhel8:3scale2.13 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-rhel8:3scale2.13.

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:

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

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

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

5.10. Creating application plans

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

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

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

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

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

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

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

5.10.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-rhel8:3scale2.13 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

5.10.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-rhel8:3scale2.13 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.

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

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

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

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

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

5.12. Creating methods

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

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

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

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

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

5.13. Creating services

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

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

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

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

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

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

5.14. Creating ActiveDocs

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

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

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

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

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

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

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

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

5.15.3. Exporting proxy configurations

Use the proxy-config export command, for example, if you have a self-managed APIcast gateway not connected to your 3scale instance. In this scenario, inject the 3scale configuration manually or by using the APICast deployment and configuration options. In both cases, you must provide the 3scale configuration.

The following command exports a configuration that you can inject into the APIcast gateway: 

3scale proxy-config export <remote>

You can specify the following options when exporting a proxy configuration for the provider account that will be used as a 3scale configuration file: 

Options for proxy-config
--environment=<value>      Gateway environment. Must be 'sandbox' or
                           'production' (default: sandbox)
-o --output=<value>        Output format. One of: json|yaml

5.15.4. Deploying proxy configurations

The following deploy command promotes your APIcast configuration to the staging environment in 3scale or to a production environment if you are using Service Mesh. 

3scale proxy deploy <remote> <service>

You can specify the following option when using the deploy command to promote your APIcast configuration to the staging environment: 

-o --output=<value>        Output format. One of: json|yaml

5.15.5. Updating proxy configurations

The following update command updates your APIcast configuration. 

3scale proxy update <remote> <service>

You can specify the following options when using the update command to update your APIcast configuration: 

-o --output=<value>           Output format. One of: json|yaml
-p --param=<value>            APIcast configuration parameters. Format:
                              [--param key=value]. Multiple options allowed.

5.15.6. Showing proxy configurations

The following show command fetches your undeployed APIcast configuration. 

3scale proxy show <remote> <service>

You can specify the following options when using the show command to fetch your undeployed APIcast configuration: 

-o --output=<value>           Output format. One of: json|yaml

5.15.7. Deploying proxy configurations (Deprecated)

Note

In 3scale 2.12, support for the proxy-config deploy command is deprecated.

Use the the following commands:

  • proxy deploy
  • proxy update
  • proxy show

For more information, see Deploying proxy configurations.

The following deploy command promotes your APIcast configuration to the staging environment in 3scale or to a production environment if you are using Service Mesh. 

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

You can specify the following option when using the deploy command to promote your APIcast configuration to the staging environment: 

-o --output=<value>        Output format. One of: json|yaml

Additional resources

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

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

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

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

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

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

5.18. Exporting products

You can export a 3scale product definition in .yaml format so that you can import that product into a 3scale instance that has no connectivity with the source 3scale instance. You must set up a 3scale product before you can export that product. See Creating new products to test API calls.

When two 3scale instances have network connectivity, use the toolbox 3scale copy command when you want to use the same 3scale product in both 3scale instances.

Description

When you export a 3scale product, the toolbox serializes the product definition in .yaml format that adheres to the Product and Backend custom resource definitions (CRDs). For more information, see Using the 3scale operator to configure and provision 3scale. Along with the basic information for the product, the output .yaml includes:

  • Backends that are linked to the product.
  • Metrics, methods and mapping rules for linked backends.
  • Limits and pricing rules defined in application plans.
  • Metrics and methods that are referenced by limits and pricing rules.

Exporting a product is a read-only operation. In other words, it is safe to repeatedly export a product. The toolbox does not change the product being exported. If you want to, you can modify the .yaml output before you import it into another 3scale instance.

Exporting a 3scale product is intended for the following situations:

  • There is no connectivity between the source and destination 3scale instances. For example, there might be severe network restrictions that prevent running the toolbox 3scale copy command when you want to use the same product in more than one 3scale instance.
  • You want to use Git or some other source control system to maintain 3scale product definitions in .yaml format.

The 3scale toolbox export and import commands might also be useful for backing up and restoring product definitions.

Format

Use this format for running the export command: 

$ 3scale product export [-f output-file] <remote> <product>

The export command can send output to stdout or to a file. The default is stdout. To send output to a file, specify the -f or --file option with the name of a .yaml file.

Replace <remote> with a 3scale provider account alias or URL that is associated with the 3scale instance from which you are exporting the product. For more information about specifying this, see Managing remote access credentials.

Replace <product> with the system name or 3scale ID of the product that you want to export. This product must be associated with the 3scale provider account that you specified. You can find a product’s system name in the 3scale GUI on the product’s Overview page. To obtain a product’s 3scale ID, run the toolbox 3scale services show command.

Example

The following command exports the petstore product from the 3scale instance associated with the my-3scale-1 provider account and outputs it to the petstore-product.yaml file: 

$ 3scale product export -f petstore-product.yaml my-3scale-1 petstore

Following is a serialization example for the Default API product: 

apiVersion: v1
kind: List
items:
- apiVersion: capabilities.3scale.net/v1beta1
  kind: Product
  metadata:
    annotations:
      3scale_toolbox_created_at: '2021-02-17T10:59:23Z'
      3scale_toolbox_version: 0.17.1
    name: api.xysnalcj
  spec:
    name: Default API
    systemName: api
    description: ''
    mappingRules:
    - httpMethod: GET
      pattern: "/v2"
      metricMethodRef: hits
      increment: 1
      last: false
    metrics:
      hits:
        friendlyName: Hits
        unit: hit
        description: Number of API hits
    methods:
      servicemethod01:
        friendlyName: servicemethod01
        description: ''
    policies:
    - name: apicast
      version: builtin
      configuration: {}
      enabled: true
    applicationPlans:
      basic:
        name: Basic
        appsRequireApproval: false
        trialPeriod: 0
        setupFee: 0.0
        custom: false
        state: published
        costMonth: 0.0
        pricingRules:
        - from: 1
          to: 1000
          pricePerUnit: 1.0
          metricMethodRef:
            systemName: hits
        limits:
        - period: hour
          value: 1222222
          metricMethodRef:
            systemName: hits
            backend: backend_01
    backendUsages:
      backend_01:
        path: "/v1/pets"
      backend_02:
        path: "/v1/cats"
    deployment:
      apicastSelfManaged:
        authentication:
          oidc:
            issuerType: rest
            issuerEndpoint: https://hello:test@example.com/auth/realms/3scale-api-consumers
            jwtClaimWithClientID: azp
            jwtClaimWithClientIDType: plain
            authenticationFlow:
              standardFlowEnabled: false
              implicitFlowEnabled: true
              serviceAccountsEnabled: false
              directAccessGrantsEnabled: true
            credentials: query
            security:
              hostHeader: ''
              secretToken: some_secret
            gatewayResponse:
              errorStatusAuthFailed: 403
              errorHeadersAuthFailed: text/plain; charset=us-ascii
              errorAuthFailed: Authentication failed
              errorStatusAuthMissing: 403
              errorHeadersAuthMissing: text/plain; charset=us-ascii
              errorAuthMissing: Authentication parameters missing
              errorStatusNoMatch: 404
              errorHeadersNoMatch: text/plain; charset=us-ascii
              errorNoMatch: No Mapping Rule matched
              errorStatusLimitsExceeded: 429
              errorHeadersLimitsExceeded: text/plain; charset=us-ascii
              errorLimitsExceeded: Usage limit exceeded
        stagingPublicBaseURL: http://staging.example.com:80
        productionPublicBaseURL: http://example.com:80
- apiVersion: capabilities.3scale.net/v1beta1
  kind: Backend
  metadata:
    annotations:
      3scale_toolbox_created_at: '2021-02-17T10:59:34Z'
      3scale_toolbox_version: 0.17.1
    name: backend.01.pcjwxbdu
  spec:
    name: Backend 01
    systemName: backend_01
    privateBaseURL: https://b1.example.com:443
    description: new desc
    mappingRules:
    - httpMethod: GET
      pattern: "/v1/pets"
      metricMethodRef: hits
      increment: 1
      last: false
    metrics:
      hits:
        friendlyName: Hits
        unit: hit
        description: Number of API hits
    methods:
      mybackendmethod01:
        friendlyName: mybackendmethod01
        description: ''
- apiVersion: capabilities.3scale.net/v1beta1
  kind: Backend
  metadata:
    annotations:
      3scale_toolbox_created_at: '2021-02-17T10:59:34Z'
      3scale_toolbox_version: 0.17.1
    name: backend.02.tiedgjsk
  spec:
    name: Backend 02
    systemName: backend_02
    privateBaseURL: https://b2.example.com:443
    description: ''
    mappingRules:
    - httpMethod: GET
      pattern: "/v1/cats"
      metricMethodRef: hits
      increment: 1
      last: false
    metrics:
      hits:
        friendlyName: Hits
        unit: hit
        description: Number of API hits
    methods:
      backend02_method01:
        friendlyName: backend02_method01
        description: ''

Exporting and piping to Product CRs

When you run the export command you can pipe the output to create a product custom resource (CR). Which 3scale instance contains this CR depends on the following:

  • If the threescale-provider-account secret is defined, the 3scale operator creates the product CR in the 3scale instance identified by that secret.
  • If the threescale-provider-account secret is not defined, then if there is a 3scale instance installed in the namespace that the new product CR would be in, the 3scale operator creates the product CR in that namespace.
  • If the threescale-provider-account secret is not defined, and if the namespace that the new product CR would be in does not contain a 3scale instance, then the 3scale operator marks the product CR with a failed status.

Suppose that you run the following command in a namespace that contains a threescale-provider-account secret. The toolbox pipes the petstore CR to the 3scale instance identified in the threescale-provider-account secret: 

$ 3scale product export my-3scale-1 petstore | oc apply -f -

Additional resources

5.19. Importing products

To use the same 3scale product in more than one 3scale instance when the source and destination 3scale instances do not have network connectivity, export a 3scale product from one 3scale instance and import it into another 3scale instance. To import a product, run the toolbox 3scale product import command.

When two 3scale instances have network connectivity, use the toolbox 3scale copy command when you want to use the same 3scale product in both 3scale instances.

Description

When you import a 3scale product, the toolbox expects a serialized product definition in .yaml format that adheres to the Product and Backend custom resource definitions (CRDs). You can obtain this .yaml content by running the toolbox 3scale product export command or by manually creating the .yaml formatted product definition.

If you exported the product, the imported definition contains what was exported, which can include:

  • Backends that are linked to the product.
  • Metrics, methods and mapping rules for linked backends.
  • Limits and pricing rules defined in application plans.
  • Metrics and methods that are referenced by limits and pricing rules.

If you want to, you can modify exported .yaml output before you import it into another 3scale instance.

The import command is idempotent. You can run it any number of times to import the same product and the resulting 3scale configuration remains the same. If there is an error during the import process, it is safe to re-run the command. If the import process cannot find the product in the 3scale instance, it creates the product. It also creates any metric, method, or backend that is defined in the .yaml definition and that it cannot find in the 3scale instance.

Importing a 3scale product is intended for the following situations:

  • There is no connectivity between the source and destination 3scale instances. For example, there might be severe network restrictions that prevent running the toolbox 3scale copy command when you want to use the same product in more than one 3scale instance.
  • You want to use Git or some other source control system to maintain 3scale product definitions in .yaml format.

The 3scale toolbox export and import commands might also be useful for backing up and restoring product definitions.

Format

Use this format for running the import command: 

3scale product import [<options>] <remote>

The import command takes .yaml input from stdin or from a file. The default is stdin.

You can specify these options:

  • -f or --file followed by a file name obtains input from the .yaml file that you specify. This file must contain a 3scale product definition that adheres to the 3scale Product and Backend CRDs.
  • -o or --output followed by json or yaml outputs the report that lists what was imported in the format that you specify. The default output format is json.

Replace <remote> with a 3scale provider account alias or URL associated with the 3scale instance into which you want to import the product. For more information about specifying this, see Managing remote access credentials.

Example

The following command imports the product that is defined in petstore-product.yaml into the 3scale instance associated with the my-3scale-2 provider account. By default, the report of what was imported is in .json format. 

3scale product import -f petstore-product.yaml my-3scale-2

The import command outputs a report that lists the imported items, for example: 

api:
  product_id: 2555417888846
  backends:
    backend_01:
      backend_id: 73310
      missing_metrics_created: 1
      missing_methods_created: 1
      missing_mapping_rules_created: 1
    backend_02:
      backend_id: 73311
      missing_metrics_created: 0
      missing_methods_created: 2
      missing_mapping_rules_created: 1
  missing_methods_created: 1
  missing_metrics_created: 1
  missing_mapping_rules_created: 2
  missing_application_plans_created: 2
  application_plans:
    basic:
      application_plan_id: 2357356246461
      missing_limits_created: 7
      missing_pricing_rules_created: 7
    unlimited:
      application_plan_id: 2357356246462
      missing_limits_created: 1
      missing_pricing_rules_created: 0

An example of a serialized product definition is at the end of Exporting products.

5.20. Export and import a product policy chain

You can export or import your product’s policy chain to or from yaml or json content. In a command line, reference the product by its id or system value. You must set up a 3scale product before you can export or import a product’s policy chain. See: Creating new products to test API calls.

Features of the export command

  • The command is a read-only operation for remote products.
  • The command will write its output by default to the standard output stdout. The -f flag can be used to write the command’s output to a file.
  • Command output formats are in either json or yaml. Note that the default format is yaml.

Help options for the export product policy chain

NAME
    export - export product policy chain
USAGE
    3scale policies export [opts] <remote>
    <product>
DESCRIPTION
    export product policy chain
OPTIONS
    -f --file=<value>             Write to file instead of stdout
    -o --output=<value>           Output format. One of: json|yaml

Command format

  • The following is the format of the command to export the policy chain to a file in yaml: 

    $ 3scale policies export -f policies.yaml -o yaml remote_name product_name

Features of the the import command:

  • The command will read input from standard input or stdin. When -f FILE flag is set, input will be read from a file. When -u URL flag is set, input will be read from the URL.
  • The imported content can be either yaml or json. You do not need to specify the format because the toolbox automatically detects it.
  • The existing policy chain is overwritten with the newly imported one. SET semantics are then implemented.
  • All content validation is delegated to the 3scale API.

Help options for the import product policy chain

NAME
    import - import product policy chain
USAGE
    3scale policies import [opts] <remote>
    <product>
DESCRIPTION
    import product policy chain
OPTIONS
    -f --file=<value>             Read from file
    -u --url=<value>              Read from url

Command format

  • The following is the format of the command to import the policy chain from a file: 

    $ 3scale policies import -f plan.yaml remote_name product_name

  • The following is the format of the command to import the policy chain from a URI: 

    $ 3scale policies import -f http[s]://domain/resource/path.yaml remote_name product_name

5.21. 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 replaced. Only missing metrics and methods are created, while mapping rules are entirely replaced with the new ones.

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: these are copied and replaced.

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 value for --target_system_name: 

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

5.22. 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 metrics and methods are created, while mapping rules are entirely replaced with the new ones.

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: these are copied and replaced.
  • 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 value for --target_system_name: 

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

5.23. Troubleshooting issues with SSL and TLS

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

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. If the certificate is not working correctly, try running the curl command with the -k option (or its long form, --insecure). This indicates that you want to proceed even for server connections that are otherwise considered insecure.

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