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:
- Section 5.1, “Installing the toolbox”
- Section 5.2, “Supported toolbox commands”
- Section 5.3, “Importing services”
- Section 5.4, “Copying services”
- Section 5.5, “Copying service settings only”
- Section 5.6, “Importing OpenAPI definitions”
- Section 5.7, “Managing remote access credentials”
- Section 5.8, “Creating application plans”
- Section 5.9, “Creating metrics”
- Section 5.10, “Creating methods”
- Section 5.11, “Creating services”
- Section 5.12, “Creating ActiveDocs”
- Section 5.13, “Listing proxy configurations”
- Section 5.14, “Copying a policy registry”
- Section 5.15, “Listing applications”
- Section 5.16, “Exporting products”
- Section 5.17, “Importing products”
- Section 5.18, “Export and import a product policy chain”
- Section 5.19, “Copying API backends”
- Section 5.21, “Troubleshooting issues with SSL and TLS”
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
- See the 3scale toolbox image in the Red Hat Ecosystem Catalog.
- You must have a Red Hat registry service account.
- The examples in this topic assume that you have Podman installed.
Procedure
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!
Pull the toolbox container image:
$ podman pull registry.redhat.io/3scale-amp2/toolbox-rhel8:3scale2.11
Verify the installation:
$ podman run registry.redhat.io/3scale-amp2/toolbox-rhel8:3scale2.11 3scale help
Additional resources
- For details on installing the toolbox image with OpenShift, Podman, or Docker, see the instructions on getting the image in the Red Hat Ecosystem Catalog.
-
See also the instructions for installing the 3scale toolbox on Kubernetes. You must use the correct image name and the
oc
command instead ofkubectl
on OpenShift.
5.2. Supported toolbox commands
Use the 3scale toolbox to manage your API from the command line tool (CLI).
The update command has been deprecated and replaced by the copy command. The use of deprecated commands is not supported.
The following commands are supported:
COMMANDS account account super command activedocs activedocs super command application application super command application-plan application-plan super command backend backend super command copy copy super command help print help import import super command method method super command metric metric super command policy-registry policy-registry super command product product super command proxy-config proxy-config super command remote remotes super command service services super command update [DEPRECATED] update super command OPTIONS -c --config-file=<value> 3scale toolbox configuration file (default: $HOME/.3scalerc.yaml) -h --help show help for this command -k --insecure Proceed and operate even for server connections otherwise considered insecure -v --version Prints the version of this command --verbose Verbose mode
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.11 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.11 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}
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 and update the service and proxy settings, metrics, methods, application plans, application plan limits, as well as mapping rules from a service to another existing service.
You need the following information:
-
The service id you want to copy:
{SERVICE_ID}
-
The service id of the destination:
{DEST_ID}
-
A 3scale admin account:
{3SCALE_ADMIN}
The domain your 3scale instance is running on:
{DOMAIN_NAME}
- If you are using hosted APICast this is 3scale.net
-
The access key of your account:
{ACCESS_KEY}
-
The access key of the destination account:
{DEST_KEY}
Additionally, you can use the optional flags:
-
The
-f
flag to remove existing target service mapping rules before copying. -
The
-r
flag to copy only mapping rules to target service.
The update
command has been deprecated and replaced by the copy
command. The use of deprecated commands is not supported.
The following example command does a bulk update from one service to another existing service:
$ podman run registry.redhat.io/3scale-amp2/toolbox-rhel8:3scale2.11 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}
5.6. Importing OpenAPI definitions
To create a new service or to update an existing service, you can import the OpenAPI definition from a local file or a URL. The default service name for the import is specified by the info.title
in the OpenAPI definition. However, you can override this service name using --target_system_name=<NEW NAME>
. This will update the service name if it already exists, or create a new service name if it does not.
The import openapi
command has the following format:
3scale import openapi [opts] -d=<destination> <specification>
The OpenAPI <specification>
can be one of the following:
-
/path/to/your/definition/file.[json|yaml|yml]
-
http[s]://domain/resource/path.[json|yaml|yml]
Example
$ podman run registry.redhat.io/3scale-amp2/toolbox-rhel8:3scale2.11 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.
While there is no security requirement in the specification, the service is considered as an OpenAPI. The toolbox will add a default_credentials
policy, which is also known as an anonymous_policy
, if it is not already in the policy chain. The default_credentials
policy will be configured with the userkey provided in an optional parameter --default-credentials-userkey
.
OpenAPI 3.0 limitations
The following limitations apply when importing OpenAPI 3.0 definitions:
-
Only the first
server.url
element in theservers
list is parsed as a private URL. Theserver.url
element’spath
component will be used as the OpenAPI’sbasePath
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.7. Managing remote access credentials
To facilitate working with remote 3scale instances, you can use the 3scale toolbox to define the remote URL addresses and authentication details to access those remote instances in a configuration file. You can then refer to these remotes using a short name in any toolbox command.
The default location for the configuration file is $HOME/.3scalerc.yaml
. However, you can specify another location using the THREESCALE_CLI_CONFIG
environment variable or the --config-file <config_file>
toolbox option.
When adding remote access credentials, you can specify an access_token
or a provider_key
:
-
http[s]://<access_token>@<3scale-instance-domain>
-
http[s]://<provider_key>@<3scale-instance-domain>
5.7.1. Adding remote access credentials
The following example command adds a remote 3scale instance with the short <name>
at <url>
:
3scale remote add [--config-file <config_file>] <name> <url>
Example
$ podman run --name toolbox-container registry.redhat.io/3scale-amp2/toolbox-rhel8:3scale2.11 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.11
.
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.7.2. Listing remote access credentials
The following example command shows how to list remote access credentials:
3scale remote list [--config-file <config_file>]
This command shows the list of added remote 3scale instances in the following format: <name>
<URL>
<authentication-key>
:
Example
$ podman run <toolbox_image_with_remotes_added> 3scale remote list instance_a https://example_a.net 123456789 instance_b https://example_b.net 987654321
5.7.3. Removing remote access credentials
The following example command shows how to remove remote access credentials:
3scale remote remove [--config-file <config_file>] <name>
This command removes the remote 3scale instance with the short <name>
:
Example
$ podman run <toolbox_image_with_remote_added> 3scale remote remove instance_a
5.7.4. Renaming remote access credentials
The following example command shows how to rename remote access credentials:
3scale remote rename [--config-file <config_file>] <old_name> <new_name>
This command renames the remote 3scale instance with the short <old_name>
to <new_name>
:
Example
$ podman run <toolbox_image_with_remote_added> 3scale remote rename instance_a instance_b
5.8. Creating application plans
Use the 3scale toolbox to create, update, list, delete, show, or export/import application plans in your Developer Portal.
5.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
.
-
By default, it will be
Create a
disabled
application plan by using the--disabled
flag.-
By default, it will be
enabled
.
-
By default, it will be
The
service
positional argument is a service reference and can be either serviceid
or servicesystem_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.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.
The
service
positional argument is a service reference and can be either serviceid
or servicesystem_name
.- The toolbox uses either one.
The
plan
positional argument is a plan reference and can be either planid
or plansystem_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.8.3. Listing application plans
The following command lists the application plan:
3scale application-plan list [opts] <remote> <service>
Use the following options while listing application plans:
Options -o --output=<value> Output format on stdout: one of json|yaml Options for application-plan -c --config-file=<value> 3scale toolbox configuration file: defaults to $HOME/.3scalerc.yaml -h --help Print help for this command -k --insecure Proceed and operate even for server connections otherwise considered insecure -v --version Print the version of this command --verbose Verbose mode
5.8.4. Showing application plans
The following command shows the application plan:
3scale application-plan show [opts] <remote> <service> <plan>
Use the following options while showing application plans:
Options -o --output=<value> Output format on stdout: one of json|yaml Options for application-plan -c --config-file=<value> 3scale toolbox configuration file: defaults to $HOME/.3scalerc.yaml -h --help Print help for this command -k --insecure Proceed and operate even for server connections otherwise considered insecure -v --version Print the version of this command --verbose Verbose mode
5.8.5. Deleting application plans
The following command deletes the application plan:
3scale application-plan delete [opts] <remote> <service> <plan>
Use the following options while deleting application plans:
Options for application-plan -c --config-file=<value> 3scale toolbox configuration file: defaults to $HOME/.3scalerc.yaml -h --help Print help for this command -k --insecure Proceed and operate even for server connections otherwise considered insecure -v --version Print the version of this command --verbose Verbose mode
5.8.6. Exporting/importing application plans
You can export or import a single application plan to or from yaml
content.
Note the following:
- Limits defined in the application plan are included.
- Pricing rules defined in the application plan are included.
- Metrics/methods referenced by limits and pricing rules are included.
- Features defined in the application plan are included.
-
Service can be referenced by
id
orsystem_name
. -
Application Plan can be referenced by
id
orsystem_name
.
5.8.6.1. Exporting an application plan to a file
The following command exports the application plan:
3scale application-plan export [opts] <remote> <service_system_name> <plan_system_name>
Example
$ podman run -u root -v $PWD:/tmp registry.redhat.io/3scale-amp2/toolbox-rhel8:3scale2.11 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.
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 onstdout
.
-
If not specified by
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.8.6.2. Importing an application plan from a file
The following command imports the application plan:
3scale application-plan import [opts] <remote> <service_system_name>
Example
$ podman run -v $PWD/plan.yaml:/tmp/plan.yaml registry.redhat.io/3scale-amp2/toolbox-rhel8:3scale2.11 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.8.6.3. Importing an application plan from a URL
3scale application-plan import -f http[s]://domain/resource/path.yaml remote_name service_name
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 fromstdin
.
-
If not specified by
- If application plan cannot be found in remote service, it will be created.
Optional param
-p
,--plan
to override remote target application planid
orsystem_name
.-
If not specified by
-p
option, by default, application plan will be referenced by plan attributesystem_name
fromyaml
content.
-
If not specified by
- 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.9. Creating metrics
Use the 3scale toolbox to create, update, list, and delete metrics in your Developer Portal.
Use the following steps for creating metrics:
- You have to provide the metric name.
-
To override the
system-name
, use the optional parameter. - If metrics with the same name already exist, you will see an error message.
Create a
disabled
metric by using the--disabled
flag.-
By default, it will be
enabled
.
-
By default, it will be
The
service
positional argument is a service reference and can be either serviceid
or servicesystem_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.9.1. Creating or updating metrics
Use the following steps to create new metrics if they do not exist, or to update an existing one:
- If metrics with the same name already exist, you will see an error message.
-
Update a
disabled
metric by using the--disabled
flag. -
Update to
enabled
metric by using the--enabled
flag.
The
service
positional argument is a service reference and can be either serviceid
or servicesystem_name
.- The toolbox uses either one.
The
metric
positional argument is a metric reference and can be either metricid
or metricsystem_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.9.2. Listing metrics
The following command lists metrics:
3scale metric list [opts] <remote> <service>
Use the following options while listing metrics:
Options -o --output=<value> Output format on stdout: one of json|yaml Options for metric -c --config-file=<value> 3scale toolbox configuration file: defaults to $HOME/.3scalerc.yaml -h --help Print help for this command -k --insecure Proceed and operate even for server connections otherwise considered insecure -v --version Print the version of this command --verbose Verbose mode
5.9.3. Deleting metrics
The following command deletes metrics:
3scale metric delete [opts] <remote> <service> <metric>
Use the following options while deleting metrics:
Options for metric -c --config-file=<value> 3scale toolbox configuration file: defaults to $HOME/.3scalerc.yaml -h --help Print help for this command -k --insecure Proceed and operate even for server connections otherwise considered insecure -v --version Print the version of this command --verbose Verbose mode
5.10. Creating methods
Use the 3scale toolbox to create, apply, list, and delete methods in your Developer Portal.
5.10.1. Creating methods
Use the following steps for creating methods:
- You have to provide the method name.
-
To override the
system-name
, use the optional parameter. - If a method with the same name already exists, you will see an error message.
Create a
disabled
method by--disabled
flag.-
By default, it will be
enabled
.
-
By default, it will be
The
service
positional argument is a service reference and can be either serviceid
or servicesystem_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.10.2. Creating or updating methods
Use the steps below for creating new methods if they do not exist, or to update existing ones:
- If a method with the same name already exists, the command will return an error message.
-
Update to
disabled
method by using--disabled flag
. -
Update to
enabled
method by using--enabled flag
.
The
service
positional argument is a service reference and can be either serviceid
or servicesystem_name
.- The toolbox uses either one.
The
method
positional argument is a method reference and can be either methodid
or methodsystem_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.10.3. Listing methods
The following command lists methods:
3scale method list [opts] <remote> <service>
Use the following options while listing methods:
Options -o --output=<value> Output format on stdout: one of json|yaml Options for method -c --config-file=<value> 3scale toolbox configuration file: defaults to $HOME/.3scalerc.yaml -h --help Print help for this command -k --insecure Proceed and operate even for server connections otherwise considered insecure -v --version Print the version of this command --verbose Verbose mode
5.10.4. Deleting methods
The following command deletes methods:
3scale method delete [opts] <remote> <service> <metric>
Use the following options while deleting methods:
Options for method -c --config-file=<value> 3scale toolbox configuration file: defaults to $HOME/.3scalerc.yaml -h --help Print help for this command -k --insecure Proceed and operate even for server connections otherwise considered insecure -v --version Print the version of this command --verbose Verbose mode
5.11. Creating services
Use the 3scale toolbox to create, apply, list, show, or delete services in your Developer Portal.
5.11.1. Creating a new service
The following command creates a new service:
3scale service create [options] <remote> <service-name>
Use the following options while creating services:
Options -a --authentication-mode=<value> Specify authentication mode of the service: - '1' for API key - '2' for App Id/App Key - 'oauth' for OAuth mode - 'oidc' for OpenID Connect -d --deployment-mode=<value> Specify the deployment mode of the service --description=<value> Specify the description of the service -o --output=<value> Output format on stdout: one of json|yaml -s --system-name=<value> Specify the system-name of the service --support-email=<value> Specify the support email of the service Options for service -c --config-file=<value> 3scale toolbox configuration file: defaults to $HOME/.3scalerc.yaml -h --help Print help for this command -k --insecure Proceed and operate even for server connections otherwise considered insecure -v --version Print the version of this command --verbose Verbose mode
5.11.2. Creating or updating services
Use the following to create new services if they do not exist, or to update an existing one:
service-id_or_system-name
positional argument is a service reference.-
It can be either service
id
, or servicesystem_name
. - Toolbox will automatically figure this out.
-
It can be either service
-
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.11.3. Listing services
The following command lists services:
3scale service list <remote>
Use the following options while listing services:
Options -o --output=<value> Output format on stdout: one of json|yaml Options for services -c --config-file=<value> 3scale toolbox configuration file: defaults to $HOME/.3scalerc.yaml -h --help Print help for this command -k --insecure Proceed and operate even for server connections otherwise considered insecure -v --version Print the version of this command --verbose Verbose mode
5.11.4. Showing services
The following command shows services:
3scale service show <remote> <service-id_or_system-name>
Use the following options while showing services:
Options -o --output=<value> Output format on stdout: one of json|yaml Options for services -c --config-file=<value> 3scale toolbox configuration file: defaults to $HOME/.3scalerc.yaml -h --help Print help for this command -k --insecure Proceed and operate even for server connections otherwise considered insecure -v --version Print the version of this command --verbose Verbose mode
5.11.5. Deleting services
The following command deletes services:
3scale service delete <remote> <service-id_or_system-name>
Use the following options while deleting services:
Options for services -c --config-file=<value> 3scale toolbox configuration file: defaults to $HOME/.3scalerc.yaml -h --help Print help for this command -k --insecure Proceed and operate even for server connections otherwise considered insecure -v --version Print the version of this command --verbose Verbose mode
5.12. Creating ActiveDocs
Use the 3scale toolbox to create, update, list, or delete ActiveDocs in your Developer Portal.
5.12.1. Creating new ActiveDocs
To create a new ActiveDocs from your API definition compliant with the OpenAPI specification:
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
andhttps
. 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
- Publish the definition in your Developer Portal.
5.12.2. Creating or updating ActiveDocs
Use the following command to create new ActiveDocs if they do not exist, or to update existing ActiveDocs with a new API definition:
3scale activedocs apply <remote> <activedocs_id_or_system_name>
Use the following options while updating ActiveDocs:
Options -d --description=<value> Specify the description of the ActiveDocs --hide Specify to hide the ActiveDocs on the Developer Portal -i --service-id=<value> Specify the Service ID associated to the ActiveDocs -o --output=<value> Output format on stdout: one of json|yaml --openapi-spec=<value> Specify the Swagger specification. Can be a file, a URL or '-' to read from stdin. This is a mandatory option when applying the ActiveDoc for the first time. -p --publish Specify to publish the ActiveDocs on the Developer Portal. Otherwise it is hidden -s --name=<value> Specify the name of the ActiveDocs --skip-swagger-validations=<value> Specify whether to skip validation of the Swagger specification: true or false. Defaults to true. Options for ActiveDocs -c --config-file=<value> 3scale toolbox configuration file: defaults to $HOME/.3scalerc.yaml -h --help Print help for this command -k --insecure Proceed and operate even for server connections otherwise considered insecure -v --version Print the version of this command --verbose Verbose mode
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.12.3. Listing ActiveDocs
Use the following command to get information about all ActiveDocs in the Developer Portal, including:
- id
- name
- system name
- description
- published (which means it can be shown in the developer portal)
- creation date
- latest updated date
The following command lists all defined ActiveDocs:
3scale activedocs list <remote>
Use the following options while listing ActiveDocs:
Options -o --output=<value> Output format on stdout: one of json|yaml -s --service-ref=<value> Filter the ActiveDocs by service reference Options for ActiveDocs -c --config-file=<value> 3scale toolbox configuration file: defaults to $HOME/.3scalerc.yaml -h --help Print help for this command -k --insecure Proceed and operate even for server connections otherwise considered insecure -v --version Print the version of this command --verbose Verbose mode
5.12.4. Deleting ActiveDocs
The following command removes ActiveDocs:
3scale activedocs delete <remote> <activedocs-id_or-system-name>
Use the following options while deleting ActiveDocs:
Options for ActiveDocs -c --config-file=<value> 3scale toolbox configuration file: defaults to $HOME/.3scalerc.yaml -h --help Print help for this command -k --insecure Proceed and operate even for server connections otherwise considered insecure -v --version Print the version of this command --verbose Verbose mode
5.13. Listing proxy configurations
Use the 3scale toolbox to list, show, promote all defined proxy configurations in your Developer Portal.
The following command lists proxy configurations:
3scale proxy-config list <remote> <service> <environment>
Use the following options while listing proxy configurations:
Options -o --output=<value> Output format on stdout: one of json|yaml Options for proxy-config -c --config-file=<value> 3scale toolbox configuration file: defaults to $HOME/.3scalerc.yaml -h --help Print help for this command -k --insecure Proceed and operate even for server connections otherwise considered insecure -v --version Print the version of this command --verbose Verbose mode
5.13.1. Showing proxy configurations
The following command shows proxy configurations:
3scale proxy-config show <remote> <service> <environment>
Use the following options while showing proxy configurations:
Options --config-version=<value> Specify the proxy configuration version. If not specified, defaults to latest -o --output=<value> Output format on stdout: one of json|yaml Options for proxy-config -c --config-file=<value> 3scale toolbox configuration file: defaults to $HOME/.3scalerc.yaml -h --help Print help for this command -k --insecure Proceed and operate even for server connections otherwise considered insecure -v --version Print the version of this command --verbose Verbose mode
5.13.2. Promoting proxy configurations
The following command promotes the latest staging proxy configuration to the production environment:
3scale proxy-config promote <remote> <service>
Use the following options while promoting the latest staging proxy configurations to the production environment:
Options for proxy-config -c --config-file=<value> 3scale toolbox configuration file: defaults to $HOME/.3scalerc.yaml -h --help Print help for this command -k --insecure Proceed and operate even for server connections otherwise considered insecure -v --version Print the version of this command --verbose Verbose mode
5.13.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.13.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-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.14. Copying a policy registry
Use the toolbox command to copy a policy registry from a 3scale source account to a target account when:
- Missing custom policies are being created in target account.
- Matching custom policies are being updated in target account.
- This copy command is idempotent.
- 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.15. Listing applications
Use the 3scale toolbox to list, create, show, apply, or delete applications Developer Portal.
The following command lists applications:
3scale application list [opts] <remote>
Use the following options while listing applications:
OPTIONS --account=<value> Filter by account -o --output=<value> Output format on stdout: one of json|yaml --plan=<value> Filter by application plan. Service option required. --service=<value> Filter by service OPTIONS FOR APPLICATION -c --config-file=<value> 3scale toolbox configuration file: defaults to $HOME/.3scalerc.yaml -h --help Print help for this command -k --insecure Proceed and operate even for server connections otherwise considered insecure -v --version Print the version of this command --verbose Verbose mode
5.15.1. Creating applications
Use the create command to create one application linked to a given 3scale account and application plan.
The required positional paramaters are as follows:
-
<service>
reference. It can be either serviceid
, or servicesystem_name
. <account>
reference. It can be one of the following:-
Account
id
-
username
,email
, oruser_id
of the admin user of the account -
provider_key
-
Account
-
<application plan>
reference. It can be either planid
, or plansystem_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.15.2. Showing applications
The following command shows applications:
3scale application show [opts] <remote> <application>
Application parameters allow:
-
User_key
- API key -
App_id
- from app_id/app_key pair or Client ID for OAuth and OpenID Connect (OIDC) authentication modes -
Application internal
id
OPTIONS -o --output=<value> Output format on stdout: one of json|yaml OPTIONS FOR APPLICATION -c --config-file=<value> 3scale toolbox configuration file: defaults to $HOME/.3scalerc.yaml -h --help Print help for this command -k --insecure Proceed and operate even for server connections otherwise considered insecure -v --version Print the version of this command --verbose Verbose mode
5.15.3. Creating or updating applications
Use the following command to create new applications if they do not exist, or to update existing applications:
3scale application apply [opts] <remote> <application>
Application parameters allow:
-
User_key
- API key -
App_id
- from app_id/app_key pair or Client ID for OAuth and OIDC authentication modes -
Application internal
id
account
optional argument is required when application is not found and needs to be created. It can be one of the following:-
Account
id
-
username
,email
, oruser_id
of the administrator user of the 3scale account -
provider_key
-
Account
-
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.15.4. Deleting applications
The following command deletes an application:
3scale application delete [opts] <remote> <application>
Application parameters allow:
-
User_key
- API key -
App_id
- from app_id/app_key pair or Client ID for OAuth and OIDC authentication modes -
Application internal
id
5.16. 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). 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 -
For details, see How the 3scale operator identifies the tenant that a custom resource links to.
5.17. 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 3scaleProduct
andBackend
CRDs. -
-o
or--output
followed byjson
oryaml
outputs the report that lists what was imported in the format that you specify. The default output format isjson
.
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.18. 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
oryaml
. Note that the default format isyaml
.
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
orjson
. 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.19. 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.
NoteYou 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.11 3scale backend copy [-t target_system_name] -s 3scale1 -d 3scale2 api_backend_01
5.20. 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.
NoteYou 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.11 3scale product copy [-t target_system_name] -s 3scale1 -d 3scale2 my_api_product_01
5.21. 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
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
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.Add the
SSL_CERT_FILE
environment variable to your3scale
commands. For example:$ podman run --env "SSL_CERT_FILE=/tmp/self-signed-cert.pem" -v $PWD/self-signed-cert.pem:/tmp/self-signed-cert.pem egistry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.11 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
- For more details on SSL certificates, see the Red Hat Certificate System documentation.
- For more details on Podman, see Building, running, and managing Linux containers on Red Hat Enterprise Linux 8.