Chapter 2. Using the 3scale toolbox
The 3scale toolbox is a Ruby client that enables you to manage 3scale products from the command line.
The 3scale toolbox does not support all API as a Product (APIaaP) features. For more details, see the Known issues in the 3scale Release Notes.
2.1. Installing the toolbox
The officially supported method of installing the 3scale toolbox is using the 3scale toolbox container image.
2.1.1. Installing the toolbox container image
Prerequisites
- See the 3scale toolbox image in the Red Hat Container Catalog.
- You must have a Red Hat registry service account.
- The examples in this topic assume that you have Docker installed and the daemon running.
Procedure
Log in to the Red Hat container registry:
$ docker login registry.redhat.io Username: ${REGISTRY-SERVICE-ACCOUNT-USERNAME} Password: ${REGISTRY-SERVICE-ACCOUNT-PASSWORD} Login Succeeded!Pull the toolbox container image:
$ docker pull registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.7
Verify the installation:
$ docker run registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.7 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 Container Catalog.
-
See also the instructions for installing the 3scale toolbox on Kubernetes. You must use the correct image name and the
occommand instead ofkubectlon OpenShift.
2.1.2. Installing unsupported toolbox versions
Procedure
-
You can install unsupported toolbox versions on Fedora Linux, Ubuntu Linux, Windows, or macOS by downloading and installing the latest
.rpm,.deb,.msior.pkgfile from GitHub.
2.2. Using 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. Red Hat discourages the use of deprecated features.
The following commands are supported:
COMMANDS
account account super command
activedocs activedocs super command
application application super command
application-plan application-plan super command
copy copy super command
help show help
import import super command
method method super command
metric metric super command
policy-registry policy-registry super command
proxy-config proxy-config super command
remote remotes super command
service services super command
update [DEPRECTATED] update super command
OPTIONS
-c --config-file=<value> 3scale toolbox configuration file
(default: $HOME/.3scalerc.yaml)
-h --help show help for this command
-k --insecure Proceed and operate even for server
connections otherwise considered insecure
-v --version Prints the version of this command
--verbose Verbose mode2.3. Importing services
Import services from a CSV file by specifying the following fields in this order (you also need to include these headers in your CSV file):
service_name,endpoint_name,endpoint_http_method,endpoint_path,auth_mode,endpoint_system_name,type
You need the following information:
-
A 3scale admin account:
{3SCALE_ADMIN} The domain your 3scale instance is running on:
{DOMAIN_NAME}- If you are using hosted APICast this is 3scale.net
-
The access key of your account:
{ACCESS_KEY} -
The CSV file of services, for example:
examples/import_example.csv
Import the services by running:
Example
$ docker run -v $PWD/examples/import_example.csv:/tmp/import_example.csv registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.7 3scale import csv --destination=https://{ACCESS_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME} --file=/tmp/import_example.csv
This example uses a Docker volume to mount the resource file in the container. It assumes that the file is available in the current $PWD folder.
2.4. Copying services
Create a new service based on an existing one from the same account or from another account. When you copy a service, the relevant ActiveDocs are also copied.
You need the following information:
-
The service id you want to copy:
{SERVICE_ID} -
A 3scale admin account:
{3SCALE_ADMIN} The domain your 3scale instance is running on:
{DOMAIN_NAME}- If you are using hosted APICast this is 3scale.net
-
The access key of your account:
{ACCESS_KEY} -
The access key of the destination account if you are copying to a different account:
{DEST_KEY} -
The name for the new service:
{NEW_NAME}
Example
$ docker run registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.7 3scale copy service {SERVICE_ID} --source=https://{ACCESS_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME} --destination=https://{DEST_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME} --target_system_name={NEW_NAME}
If the service to be copied has custom policies, make sure that their respective custom policy definitions already exist in the destination where the service is to be copied. To learn more about copying custom policy definitions check out the Copying a policy registry.
2.5. Copying service settings only
You can bulk copy and update the service and proxy settings, metrics, methods, application plans, application plan limits, as well as mapping rules from a service to another existing service.
You need the following information:
-
The service id you want to copy:
{SERVICE_ID} -
The service id of the destination:
{DEST_ID} -
A 3scale admin account:
{3SCALE_ADMIN} The domain your 3scale instance is running on:
{DOMAIN_NAME}- If you are using hosted APICast this is 3scale.net
-
The access key of your account:
{ACCESS_KEY} -
The access key of the destination account:
{DEST_KEY}
Additionally, you can use the optional flags:
-
The
-fflag to remove existing target service mapping rules before copying. -
The
-rflag 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:
Example
$ docker run registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.7 3scale update [opts] service --source=https://{ACCESS_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME} --destination=https://{DEST_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME} {SERVICE_ID} {DEST_ID}
2.6. Importing OpenAPI definitions
To create a new service or to update an existing service, use the definitions from a local file or access credentials. If that service name already exists, it will be updated. Conversely, if the service name does not exist, it will be created.
The default service name for the import is taken from info.title in the OpenAPI definition. You can override this service name using --target_system_name=<NEW NAME>. If that service name already exists, it will be updated. Conversely, if the service name does not exist, it will be created.
The following rules apply to every import:
- Definitions are validated as OpenAPI 2.0.
- All mapping rules in the 3scale product are deleted.
-
In order to be replaced, all method names must be identical to methods defined in the OpenAPI definition (
operation.operationId) by using exact pattern matching. - Only methods included in the OpenAPI definition are modified.
-
All methods that were present only in the OpenAPI definition are attached to the
Hitsmetric. All mapping rules from the OpenAPI definition are imported.
- View these in API > Integration.
While there is no security requirement in swagger specifications, the service is considered as an OpenAPI. Toolbox will add a default_credentials policy, which is also known as an anonymous_policy, if it is not already in the policy chain. The default_credentials policy will be configured with the userkey provided in optional parameter --default-credentials-userkey.
Example
$ docker run registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.7 3scale import openapi [opts] --destination=https://{DEST_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME}
2.6.1. Optional flags
-d --destination=<value>-
3scale target instance in format:
http[s]://<authentication>@3scale_domain. -t --target_system_name=<value>- Target system name.
2.7. Managing remote access credentials
To facilitate work with remote 3scale instances, define in a config file the remote web addresses (URLs) with authentication that you will use for accessing those instances. Refer to them by a short name in any 3scale toolbox command.
The default location for the config file is $HOME/.3scalerc.yaml but you can specify another location using the THREESCALE_CLI_CONFIG environment variable or the --config-file <config_file> option.
You can specify remotes using either an access_token or a provider_key:
-
http[s]://<access_token>@<3scale-instance-domain> -
http[s]://<provider_key>@<3scale-instance-domain>
2.7.1. Listing remote access credentials
3scale remote list [--config-file <config_file>]
Shows the list of existing remotes (name, URL and authentication key).
Example
$ docker run registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.7 3scale remote list instance_a https://example_a.net 123456789 instance_b https://example_b.net 987654321
2.7.2. Adding remote access credentials
3scale remote add [--config-file <config_file>] <name> <url>
Adds a remote with short name <name> at <url>.
Example
$ docker run registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.7 3scale remote add instance_a https://123456789@example_a.net
2.7.3. Removing remote access credentials
3scale remote remove [--config-file <config_file>] <name>
Removes the remote woth short name <name>.
Example
$ docker run registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.7 3scale remote remove instance_a
2.7.4. Renaming remote access credentials
3scale remote rename [--config-file <config_file>] <old_name> <new_name>
Renames remote with short name <old_name> to <new_name>.
Example
$ docker run registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.7 3scale remote rename instance_a instance_b
2.8. Application plans
Use the 3scale toolbox to create, update, list, delete, show, or export/import application plans in your Developer Portal.
2.8.1. Creating a new application plan
Use the following steps to create a new application plan:
- You have to provide the application plan name.
-
To override the
system-name, use the optional parameter. - If an application plan with the same name already exists, you will see an error message.
-
Set as
defaultthe application plan by using the--defaultflag. Create a
publishedapplication plan by using the--publishflag.-
By default, it will be
hidden.
-
By default, it will be
Create a
disabledapplication plan by using the--disabledflag.-
By default, it will be
enabled.
-
By default, it will be
The
servicepositional argument is a service reference and can be either serviceidor 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
-d --default This will make the default application plan
--disabled This will disable all methods and metrics in
the application plan
--end-user-required=<value> End user required: true or false
-p --published This will publish the application plan
--setup-fee=<value> Set-up fee
-t --system-name=<value> This will set application plan system name
--trial-period-days=<value> The trial period in days
Options for application-plan
-c --config-file=<value> 3scale toolbox configuration file
(default: $HOME/.3scalerc.yaml)
-h --help show help for this command
-k --insecure Proceed and operate even for server
connections otherwise considered insecure
-v --version This will print the version of this command
--verbose Verbose mode2.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
defaultapplication plan by using the--defaultflag. -
Update the
publishedapplication plan by using the--publishflag. -
Update the
hiddenapplication plan by using the--hideflag. -
Update the
disabledapplication plan by using the--disabledflag. -
Update the
enabledapplication plan by using the--enabledflag.
The
servicepositional argument is a service reference and can be either serviceidor servicesystem_name.- The toolbox uses either one.
The
planpositional argument is a plan reference and can be either planidor 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 This will make the default application plan
--disabled This will disable all methods and metrics in
the application plan
--enabled This will enable the application plan
--end-user-required=<value> End user required: true or false
--hide This will hide the application plan
-n --name=<value> This will set the plan name
-p --publish This will publish the application plan
--setup-fee=<value> Set-up fee
--trial-period-days=<value> The trial period in days
Options for application-plan
-c --config-file=<value> 3scale toolbox configuration file
(default: $HOME/.3scalerc.yaml)
-h --help show help for this command
-k --insecure Proceed and operate even for server
connections otherwise considered
insecure
-v --version This will print the version of this command
--verbose Verbose mode2.8.3. Listing application plans
The following command lists the application plan:
3scale application-plan list [opts] <remote> <service>
Use the following options while listing application plans:
Options for application-plan
-c --config-file=<value> 3scale toolbox configuration file
(default:$HOME/.3scalerc.yaml)
-h --help show help for this command
-k --insecure Proceed and operate even for server
connections otherwise considered insecure
-v --version This will print the version of this command
--verbose Verbose mode2.8.4. Showing application plans
The following command shows the application plan:
3scale application-plan show [opts] <remote> <service> <plan>
Use the following options while showing application plans:
Options for application-plan
-c --config-file=<value> 3scale toolbox configuration file
(default: $HOME/.3scalerc.yaml)
-h --help show help for this command
-k --insecure Proceed and operate even for server
connections otherwise considered insecure
-v --version This will print the version of this command
--verbose Verbose mode2.8.5. Deleting application plans
The following command deletes the application plan:
3scale application-plan delete [opts] <remote> <service> <plan>
Use the following options while deleting application plans:
Options for application-plan
-c --config-file=<value> 3scale toolbox configuration file
(default: $HOME/.3scalerc.yaml)
-h --help show help for this command
-k --insecure Proceed and operate even for server
connections otherwise considered insecure
-v --version This will print the version of this command
--verbose Verbose mode2.8.6. Export/import application plans
You can export or import a single application plan to or from yaml content.
Note the following: * Limits defined in the application plan are included. * Pricing rules defined in the application plan are included. * Metrics/methods referenced by limits and pricing rules are included. * Features defined in the application plan are included. * Service can be referenced by id or system_name. * Application Plan can be referenced by id or system_name.
2.8.6.1. Exporting an application plan to a file
The following command exports the application plan:
3scale application-plan export [opts] <remote> <service_system_name> <plan_system_name>
Example
$ docker run -u root -v $PWD:/tmp registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.7 3scale application-plan export --file=/tmp/plan.yaml remote_name service_name plan_name
This example uses a Docker volume to mount the exported file in the container for output to the current $PWD folder.
Specific to the export command:
- Read only operation on remote service and application plan.
Command output can be
stdoutor file.-
If not specified by
-foption, by default,yamlcontent 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
(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 mode2.8.6.2. Importing an application plan from a file
The following command imports the application plan:
3scale application-plan import [opts] <remote> <service_system_name>
Example
$ docker run -v $PWD/plan.yaml:/tmp/plan.yaml registry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.7 3scale application-plan import --file=/tmp/plan.yaml remote_name service_name
This example uses a Docker volume to mount the imported file in the container from the current $PWD folder.
2.8.6.3. Importing an application plan from URL
3scale application-plan import -f http[s]://domain/resource/path.yaml remote_name service_name
Specific to import command:
Command input content can be
stdin, file or URL format.-
If not specified by
-foption, by default,yamlcontent will be read fromstdin.
-
If not specified by
- If application plan cannot be found in remote service, it will be created.
Optional param
-p,--planto override remote target application planidorsystem_name.-
If not specified by
-poption, by default, application plan will be referenced by plan attributesystem_namefromyamlcontent.
-
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
(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 mode2.9. Metrics
Use the 3scale toolbox to create, update, list, and delete metrics in your Developer Portal.
2.9.1. Creating metrics
Use the following steps for creating metrics:
- You have to provide the metric name.
-
To override the
system-name, use the optional parameter. - If metrics with the same name already exist, you will see an error message.
Create a
disabledmetric by using the--disabledflag.-
By default, it will be
enabled.
-
By default, it will be
The
servicepositional argument is a service reference and can be either serviceidor 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> This will set a metric description
--disabled This will disable this metric in all application plans
-t --system-name=<value> This will set the application plan system name
--unit=<value> Metric unit: default hit
Option for metric
-c --config-file=<value> 3scale toolbox configuration file
(default: $HOME/.3scalerc.yaml)
-h --help show help for this command
-k --insecure Proceed and operate even for server
connections otherwise considered insecure
-v --version This will print the version of this command
--verbose Verbose mode2.9.2. Creating or updating metrics
Use the following steps to create new metrics if they do not exist, or to update an existing one:
- If metrics with the same name already exist, you will see an error message.
-
Update a
disabledmetric by using the--disabledflag. -
Update to
enabledmetric by using the--enabledflag.
The
servicepositional argument is a service reference and can be either serviceidor servicesystem_name.- The toolbox uses either one.
The
metricpositional argument is a metric reference and can be either metricidor 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> This will set a metric description
--disabled This will disable this metric in all application plans
--enabled This will enable this metric in all application plans
-n --name=<value> This will set the metric name
--unit=<value> Metric unit: default hit
Options for metric
-c --config-file=<value> 3scale toolbox configuration file
(default: $HOME/.3scalerc.yaml)
-h --help show help for this command
-k --insecure Proceed and operate even for server
connections otherwise considered insecure
-v --version This will print the version of this command
--verbose Verbose mode2.9.3. Listing metrics
The following command lists metrics:
3scale metric list [opts] <remote> <service>
Use the following options while listing metrics:
Options for metric
-c --config-file=<value> 3scale toolbox configuration file
(default: $HOME/.3scalerc.yaml)
-h --help show help for this command
-k --insecure Proceed and operate even for server
connections otherwise considered insecure
-v --version This will print the version of this command
--verbose Verbose mode2.9.4. Deleting metrics
The following command deletes metrics:
3scale metric delete [opts] <remote> <service> <metric>
Use the following options while deleting metrics:
Options for metric
-c --config-file=<value> 3scale toolbox configuration file
(default: $HOME/.3scalerc.yaml)
-h --help show help for this command
-k --insecure Proceed and operate even for server
connections otherwise considered insecure
-v --version This will print the version of this command
--verbose Verbose mode2.10. Methods
Use the 3scale toolbox to create, apply, list, and delete methods in your Developer Portal.
2.10.1. Creating methods
- You have to provide the method name.
-
To override the
system-name, use the optional parameter. - If a method with the same name already exists, you will see an error message.
Create a
disabledmethod by--disabledflag.-
By default, it will be
enabled.
-
By default, it will be
The
servicepositional argument is a service reference and can be either serviceidor 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:
Option
--description=<value> This will set a method description
--disabled This will disable this method in all
application plans
-t --system-name=<value> This will set the method system name
Options for method
-c --config-file=<value> 3scale toolbox configuration file (default:
$HOME/.3scalerc.yaml)
-h --help show help for this command
-k --insecure Proceed and operate even for server
connections otherwise considered insecure
-v --version This will print the version of this command
--verbose Verbose mode2.10.2. Creating or updating methods
Use the following steps for creating new methods if they do not exist, or to update an existing ones:
- If a method with the same name already exists, command will fail.
-
Update to
disabledmethod by using--disabled flag. -
Update to
enabledmethod by using--enabled flag.
The
servicepositional argument is a service reference and can be either serviceidor servicesystem_name.- The toolbox uses either one.
The
methodpositional argument is a method reference and can be either methodidor 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> This will set a method description
--disabled This will disable this method in all
application plans
--enabled This will enable this method in all
application plans
-n --name=<value> This will set the method name
Options for method
-c --config-file=<value> 3scale toolbox configuration file
(default: $HOME/.3scalerc.yaml)
-h --help This will show help for this command
-k --insecure Proceed and operate even for server
connections otherwise considered insecure
-v --version This will print the version of this command
--verbose Verbose mode2.10.3. Listing methods
The following command lists methods:
3scale method list [opts] <remote> <service>
Use the following options while listing methods:
Options for method
-c --config-file=<value> 3scale toolbox configuration file
(default: $HOME/.3scalerc.yaml)
-h --help show help for this command
-k --insecure Proceed and operate even for server
connections otherwise considered insecure
-v --version This will print the version of this command
--verbose Verbose mode2.10.4. Deleting methods
The following command deletes methods:
3scale method delete [opts] <remote> <service> <metric>
Use the following options while deleting methods:
Options for method
-c --config-file=<value> 3scale toolbox configuration file
(default: $HOME/.3scalerc.yaml)
-h --help show help for this command
-k --insecure Proceed and operate even for server
connections otherwise considered insecure
-v --version This will print the version of this command
--verbose Verbose mode2.11. Creating services
Use the 3scale toolbox to create, apply, list, show, or delete services in your Developer Portal.
2.11.1. Creating a new service
The following command creates a new service:
3scale service create [options] <remote> <service-name>
Use the following options while creating services:
Options
-a --authentication-mode=<value> Specify authentication mode of the
service ('1' for API key, '2' for
App Id / App Key, 'oauth' for OAuth
mode, 'oidc' for OpenID Connect)
-d --deployment-mode=<value> Specify the deployment mode of the
service
--description=<value> Specify the description of the
service
-s --system-name=<value> Specify the system-name of the
service
--support-email=<value> Specify the support email of the
service
Options for service
-c --config-file=<value> 3scale toolbox configuration file
(default:
$HOME/.3scalerc.yaml)
-h --help show help for this command
-k --insecure Proceed and operate even for server
connections otherwise considered
insecure
-v --version Prints the version of this command
--verbose Verbose mode2.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-namepositional 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
Options for services
-c --config-file=<value> 3scale toolbox configuration file
(default: $HOME/.3scalerc.yaml)
-h --help show help for this command
-k --insecure Proceed and operate even for server
connections otherwise considered
insecure
-v --version Prints the version of this command
--verbose Verbose mode2.11.3. Listing services
The following command lists services:
3scale service list <remote>
Use the following options while listing services:
Options for services
-c --config-file=<value> 3scale toolbox configuration file (default:
$HOME/.3scalerc.yaml)
-h --help show help for this command
-k --insecure Proceed and operate even for server
connections otherwise considered insecure
-v --version Prints the version of this command
--verbose Verbose mode2.11.4. Showing services
The following command shows services:
3scale service show <remote> <service-id_or_system-name>
Use the following options while showing services:
Options for services
-c --config-file=<value> 3scale toolbox configuration file
(default: $HOME/.3scalerc.yaml)
-h --help show help for this command
-k --insecure Proceed and operate even for server
connections otherwise considered insecure
-v --version Prints the version of this command
--verbose Verbose mode2.11.5. Deleting services
The following command deletes services:
3scale service delete <remote> <service-id_or_system-name>
Use the following options while deleting services:
Options for services
-c --config-file=<value> 3scale toolbox configuration file (default:
$HOME/.3scalerc.yaml)
-h --help show help for this command
-k --insecure Proceed and operate even for server
connections otherwise considered insecure
-v --version Prints the version of this command
--verbose Verbose mode2.12. ActiveDocs
Use the 3scale toolbox to create, update, list, or delete ActiveDocs in your Developer Portal.
2.12.1. Creating new ActiveDocs
To create a new ActiveDocs from your OpenAPI / Swagger compliant API defintion:
Add your API defintion to 3scale, optionally giving it a name:
3scale activedocs create <remote> <activedocs-name> <spec>
Use the following options while creating ActiveDocs:
Options -d --description=<value> Specify the description of the ActiveDocs -i --service-id=<value> Specify the Service ID associated to the ActiveDocs -p --published Specify it to publish the ActiveDoc on the Developer Portal. Otherwise it will be hidden -s --system-name=<value> Specify the system-name of the ActiveDocs --skip-swagger-validations Specify it to skip validation of the Swagger specification Options for ActiveDocs -c --config-file=<value> 3scale toolbox configuration file (default: $HOME/.3scalerc.yaml) -h --help show help for this command -k --insecure Proceed and operate even for server connections otherwise considered insecure -v --version Prints the version of this command --verbose Verbose mode- Publish the definition in your Developer Portal.
2.12.2. Creating or updating ActiveDocs
Use the following command to create new ActiveDoc if they do not exist, or to update existing ActiveDocs with a new API definition:
3scale activedocs apply <remote> <activedocs_id_or_system_name>
Use the following options while updating ActiveDocs:
Options
-d --description=<value> Specify the description of the
ActiveDocs
--hide Specify it to hide the ActiveDocs on
the Developer Portal
-i --service-id=<value> Specify the Service ID associated to
the ActiveDocs
--openapi-spec=<value> Specify the swagger spec. Can be a
file, an URL or '-' to read from
stdin. This option is mandatory when
applying the ActiveDoc for the first
time
-p --publish Specify it to publish the ActiveDocs
on the Developer Portal. Otherwise it
will be hidden
-s --name=<value> Specify the name of the ActiveDocs
--skip-swagger-validations Specify it to skip validation of the
Swagger specification
Options for ActiveDocs
-c --config-file=<value> 3scale toolbox configuration file
(default: $HOME/.3scalerc.yaml)
-h --help show help for this command
-k --insecure Proceed and operate even for server
connections otherwise considered
insecure
-v --version Prints the version of this command
--verbose Verbose mode2.12.3. Listing ActiveDocs
Use the following command to get information about all ActiveDocs in the developer portal, including:
- id
- name
- system name
- description
- published (which means it can be shown in the developer portal)
- creation date
- latest updated date
The following command lists all defined ActiveDocs:
3scale activedocs list <remote>
Use the following options while listing ActiveDocs:
Options for ActiveDocs
-c --config-file=<value> 3scale toolbox configuration file
(default: $HOME/.3scalerc.yaml)
-h --help show help for this command
-k --insecure Proceed and operate even for server
connections otherwise considered insecure
-v --version Prints the version of this command
--verbose Verbose mode2.12.4. Deleting ActiveDocs
The following command removes ActiveDocs:
3scale activedocs delete <remote> <activedocs-id_or-system-name>
Use the following options while deleting ActiveDocs:
Options for ActiveDocs
-c --config-file=<value> 3scale toolbox configuration file
(default: $HOME/.3scalerc.yaml)
-h --help show help for this command
-k --insecure Proceed and operate even for server
connections otherwise considered insecure
-v --version Prints the version of this command
--verbose Verbose mode2.13. Proxy configurations
Use the 3scale toolbox to list, show, promote all defined proxy configurations in your Developer Portal.
2.13.1. Listing proxy configuration
The following command lists proxy configurations:
3scale proxy-config list <remote> <service> <environment>
Use the following options while listing proxy configurations:
Options for proxy-config
-c --config-file=<value> 3scale toolbox configuration file (default:
/home/msoriano/.3scalerc.yaml)
-h --help show help for this command
-k --insecure Proceed and operate even for server
connections otherwise considered insecure
-v --version Prints the version of this command
--verbose Verbose mode2.13.2. Showing proxy configurations
The following command shows proxy configurations:
3scale proxy-config show <remote> <service> <environment>
Use the following options while showing proxy configurations:
Options for proxy-config
-c --config-file=<value> 3scale toolbox configuration file
(default: /home/msoriano/.3scalerc.yaml)
-h --help show help for this command
-k --insecure Proceed and operate even for server
connections otherwise considered
insecure
-v --version Prints the version of this command
--verbose Verbose mode2.13.3. Promoting proxy configurations
The following command promotes the latest staging proxy configuration to the production environment:
3scale proxy-config promote <remote> <service>
Use the following options while promoting the latest staging proxy configurations to the production environment:
Options for proxy-config
-c --config-file=<value> 3scale toolbox configuration file (default:
/home/msoriano/.3scalerc.yaml)
-h --help show help for this command
-k --insecure Proceed and operate even for server
connections otherwise considered insecure
-v --version Prints the version of this command
--verbose Verbose mode2.14. Copying a policy registry (custom policies)
Use the toolbox command to copy a policy registry from a 3scale source account to a target account when:
- missing custom policies are being created in target account.
- matching custom policies are being updated in target account.
- this copy command is idempotent.
- Missing custom policies are defined as custom policies that exist in source account and do not exist in an account tenant.
- Matching custom policies are defined as custom policies that exists in both source and target account.
The following command copies a policy registry:
3scale policy-registry copy [opts] <source_remote> <target_remote>
Option for policy-registry
-c --config-file=<value> 3scale toolbox configuration file (default:
$HOME/.3scalerc.yaml)
-h --help show help for this command
-k --insecure Proceed and operate even for server
connections otherwise considered insecure
-v --version Prints the version of this command
--verbose Verbose mode2.15. Applications
Use the 3scale toolbox to list, create, show, apply, or delete applications Developer Portal.
2.15.1. Listing applications
The following command lists applications:
3scale application list [opts] <remote>
Use the following options while listing applications:
OPTIONS
--account=<value> Filter by account
--plan=<value> Filter by application plan.
Service option required.
--service=<value> Filter by service2.15.2. Creating applications
Use the create command to create one application linked to a given 3scale account and application plan.
The required positional paramaters are as follows:
-
<service>reference. It can be either serviceid, or servicesystem_name. <account>reference. It can be one of the following:-
Account
id -
username,email, oruser_idof 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 to be
created.
--description=<value> Application description
--redirect-url=<value> OpenID Connect redirect url
--user-key=<value> User Key (API Key) of the application
to be created.2.15.3. Showing applications
The following command shows applications:
3scale application show [opts] <remote> <application>
Application parameters allow:
-
User_key- API key -
App_id- from app_id/app_key pair or Client ID for OAuth and OpenID Connect (OIDC) authentication modes -
Application internal
id
2.15.4. Creating or updating applications
Use the following command to create new applications if they do not exist, or to update existing applications:
3scale application apply [opts] <remote> <application>
Application parameters allow:
-
User_key- API key -
App_id- from app_id/app_key pair or Client ID for OAuth and OIDC authentication modes -
Application internal
id accountoptional 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_idof the administrator user of the 3scale account -
provider_key
-
Account
-
namecannot be used as unique identifier because application name is not unique in 3scale. -
Resume a suspended application by
--resumeflag. -
Suspends an application - changes the state to suspended by the
--suspendflag.
Use the following options while updating applications:
OPTIONS
--account=<value> Application's account. Required when
creating
--application-key=<value> App Key(s) or Client Secret (for OAuth
and OpenID Connect authentication
modes) of the application to be
created. Only used when application
does not exist.
--description=<value> Application description
--name=<value> Application name
--plan=<value> Application's plan. Required when
creating
--redirect-url=<value> OpenID Connect redirect url
--resume Resume a suspended application
--service=<value> Application's service. Required when
creating
--suspend Suspends an application (changes the
state to suspended)
--user-key=<value> User Key (API Key) of the application
to be created.2.15.5. Deleting applications
The following command deletes an application:
3scale application delete [opts] <remote> <application>
Application parameters allow:
-
User_key- API key -
App_id- from app_id/app_key pair or Client ID for OAuth and OIDC authentication modes -
Application internal
id
2.16. Troubleshooting SSL issues
This section explains how to resolve issues with Secure Sockets Layer/Transport Layer Security (SSL/TLS).
2.16.1. Installing trusted certificates
If you are experiencing issues related to self-signed SSL certificates, you can download and use remote host certificates as described in this section. For example, typical errors include SSL certificate problem: self signed certificate or self signed certificate in certificate chain.
Procedure
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.
Add the
SSL_CERT_FILEenvironment variable to your3scalecommands. For example:$ docker run --env "SSL_CERT_FILE=/tmp/self-signed-cert.pem" -v $PWD/self-signed-cert.pem:/tmp/self-signed-cert.pem egistry.redhat.io/3scale-amp2/toolbox-rhel7:3scale2.7 3scale service list https://{ACCESS_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME}This example uses a Docker volume to mount the certificate file in the container. It assumes that the file is available in the current
$PWDfolder.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 using containers, see the Red Hat
- For more details on using Docker, see https://docs.docker.com/.