Chapter 5. The 3scale API Management toolbox Important The 3scale toolbox CLI is a deprecated component. It is no longer the focus of active enhancements. While it remains available, anticipate its future decommissioning. Use the 3scale Application Capabilities operator for your provisioning and automation needs. 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: Installing the toolbox Supported toolbox commands Importing services Copying services Copying service settings only OpenAPI authentication Importing OpenAPI definitions Importing a 3scale API Management backend from an OpenAPI definition Managing remote access credentials Creating application plans Creating metrics Creating methods Creating services Creating ActiveDocs Listing proxy configurations Copying a policy registry Listing applications Exporting products Importing products Export and import a product policy chain Copying API backends 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 API Management 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: USD podman login registry.redhat.io Username: USD{REGISTRY-SERVICE-ACCOUNT-USERNAME} Password: USD{REGISTRY-SERVICE-ACCOUNT-PASSWORD} Login Succeeded! Pull the toolbox container image: USD podman pull registry.redhat.io/3scale-amp2/toolbox-rhel9:3scale2.15 Verify the installation: USD podman run registry.redhat.io/3scale-amp2/toolbox-rhel9:3scale2.15 3scale help Additional resources Instructions on getting the image in the Red Hat Ecosystem Catalog Instructions for installing the 3scale API Management toolbox on Kubernetes Note: You must use the correct image name and the oc command instead of kubectl on OpenShift. 5.2. Supported toolbox commands Use the 3scale toolbox to manage your API from the command line tool (CLI). Note The update command has been removed and replaced by the copy command. The following commands are supported: 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 USD podman run -v USDPWD/examples/import_example.csv:/tmp/import_example.csv registry.redhat.io/3scale-amp2/toolbox-rhel9:3scale2.15 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 USDPWD 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 USD podman run registry.redhat.io/3scale-amp2/toolbox-rhel9:3scale2.15 3scale copy service {SERVICE_ID} --source=https://{ACCESS_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME} --destination=https://{DEST_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME} --target_system_name={NEW_NAME} Note If the service to be copied has custom policies, make sure that their respective custom policy definitions already exist in the destination where the service is to be copied. To learn more about copying custom policy definitions check out the Copying a policy registry 5.5. Copying service settings only You can bulk copy the service and proxy settings, metrics, methods, application plans, application plan limits, as well as mapping rules from a service to another existing service. You need the following information: The service id you want to copy: {SERVICE_ID} The service id of the destination: {DEST_ID} A 3scale admin account: {3SCALE_ADMIN} The domain your 3scale instance is running on: {DOMAIN_NAME} If you are using hosted APICast this is 3scale.net The access key of your account: {ACCESS_KEY} The access key of the destination account: {DEST_KEY} Additionally, you can use the optional flags: The -f flag to remove existing target service mapping rules before copying. The -r flag to copy only mapping rules to target service. Note The update command has been removed and replaced by the copy command. The following example command does a bulk copy from one service to another existing service: USD podman run registry.redhat.io/3scale-amp2/toolbox-rhel9:3scale2.15 3scale copy [opts] service --source=https://{ACCESS_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME} --destination=https://{DEST_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME} {SERVICE_ID} {DEST_ID} 5.6. OpenAPI Authentication By implementing OpenAPI authentication with the 3scale toolbox, you can ensure that only authorized users have access to your APIs, safeguard sensitive data, and efficiently manage API usage. This approach will reinforces your API infrastructure and fosters trust among developers and consumers. Note Only one top-level security requirement is supported; operation-level security requirements are not supported. Supported security schemes: apiKey and oauth2 with any flow type. For the apiKey security scheme type: The credentials location is read from the OpenAPI in field of the security scheme object. Auth user key is read from the OpenAPI name field of the security scheme object. Partial example of OpenAPI 3.0.2 with apiKey security requirement: openapi: "3.0.2" security: - petstore_api_key: [] components: securitySchemes: petstore_api_key: type: apiKey name: api_key in: header ... For the oauth2 security scheme type: The credentials location is hard-coded to headers . OpenID Connect Issuer Type defaults to rest . You can be override this using the --oidc-issuer-type=<value> command option. OpenID Connect Issuer is not read from OpenAPI. Since 3scale requires that the issuer URL must include a client secret, the issue must be set using this --oidc-issuer-endpoint=<value> command option. OIDC AUTHORIZATION FLOW is read from the flows field of the security scheme object. Partial example of OpenAPI 3.0.2 with oauth2 security requirement: openapi: "3.0.2" security: - petstore_oauth: - write:pets - read:pets components: securitySchemes: petstore_oauth: type: oauth2 flows: clientCredentials: tokenUrl: http://example.org/api/oauth/dialog scopes: write:pets: modify pets in your account read:pets: read your pets ... When OpenAPI does not specify any security requirements: The product is considered as an Open API . The default_credentials 3scale policy is added. Note: This is also called as anonymous_policy . You require the command --default-credentials-userkey . Note: The command fails if is not provided. Additional resources Security Scheme Object 5.7. Importing OpenAPI definitions To create a new service or to update an existing service, you can import the OpenAPI definition from a local file or a URL. The default service name for the import is specified by the info.title in the OpenAPI definition. However, you can override this service name using --target_system_name=<NEW NAME> . This will update the service name if it already exists, or create a new service name if it does not. The import openapi command has the following format: USD 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 USD podman run -v USDPWD/my-test-api.json:/tmp/my-test-api.json registry.redhat.io/3scale-amp2/toolbox-rhel9:3scale2.15 3scale import openapi [opts] -d=https://{DEST_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME} /tmp/my-test-api.json Command options The import openapi command options include: -d --destination=<value> 3scale target instance in format: http[s]://<authentication>@3scale_domain . -t --target_system_name=<value> 3scale target system name. --backend-api-secret-token=<value> Custom secret token sent by the API gateway to the backend API. --backend-api-host-header=<value> Custom host header sent by the API gateway to the backend API. For more options, see the 3scale import openapi --help command. OpenAPI import rules The supported security schemes are apiKey and oauth2 with any OAuth flow type. The OpenAPI specification must be one of the following: Filename in the available path. URL from where toolbox can download the content. The supported schemes are http and https . Read from stdin standard input stream. This is controlled by setting the - value. The following additional rules apply when importing OpenAPI definitions: Definitions are validated as OpenAPI 2.0 or OpenAPI 3.0. All mapping rules from the OpenAPI definition are imported. You can view these in API > Integration . All mapping rules in the 3scale product are replaced. Only methods included in the OpenAPI definition are modified. All methods that were present only in the OpenAPI definition are attached to the Hits metric. To replace methods, the method names must be identical to the methods defined in the OpenAPI definition operation.operationId by using exact pattern matching. Note The toolbox will add a default_credentials policy, which is also known as an anonymous_policy , if it is not already in the policy chain. The default_credentials policy will be configured with the userkey provided in an optional parameter --default-credentials-userkey . OpenAPI 3.0 provides a way to specify security for your API using its security schemes and security requirements features. For more information, see the official Swagger Authentication and Authorization documentation. OpenAPI 3.0 limitations The following limitations apply when importing OpenAPI 3.0 definitions: Only the first server.url element in the servers list is parsed as a private URL. The server.url element's path component will be used as the OpenAPI's basePath property. The toolbox will not parse servers in the path item and servers in the operation objects. Multiple flows in the security scheme object not supported. 5.8. Importing a 3scale API Management backend from an OpenAPI definition You can use the toolbox import command to import an OpenAPI definition and create a 3scale backend API. The command line option --backend enables this feature. 3scale uses the OpenAPI definition to create and store a backend and its private base URL, as well as its mapping rules and methods. Prerequisites A user account with administrator privileges for a 3scale 2.15 On-Premises instance. An OAS document that defines your API. Procedure Use the following format to run the import command to create a backend: USD 3scale import openapi -d <remote> --backend <OAS> Replace <remote> with the URL for the 3scale instance in which to create the backend. Use this format: http[s]://<authentication>@3scale_domain Replace <OAS> with the /path/to/your/oasdoc.yaml . Table 5.1. Additional OpenAPI definition options Options Description -o --output=<value> The output format. Can be either JSON or YAML. --override-private-base-url=<value> 3scale reads the backend's private endpoint from the OpenAPI definition's servers[0].url field. To override the setting in that field, specify this option and replace <value> with the private base URL of your choice. When the OpenAPI definition does not specify a value in the servers[0].url field, and you do not specify this option in the import command, execution fails. --prefix-matching Use prefix matching instead of strict matching on mapping rules derived from OpenAPI operations. --skip-openapi-validation Skip OpenAPI schema validation. -t --target_system_name=<value> Target system name is a unique key in your tenant. System name can be inferred from the OpenAPI definition, however you can override that with your own name by using this parameter. 5.9. Managing remote access credentials To facilitate working with remote 3scale instances, you can use the 3scale toolbox to define the remote URL addresses and authentication details to access those remote instances in a configuration file. You can then refer to these remotes using a short name in any toolbox command. The default location for the configuration file is USDHOME/.3scalerc.yaml . However, you can specify another location using the THREESCALE_CLI_CONFIG environment variable or the --config-file <config_file> toolbox option. When adding remote access credentials, you can specify an access_token or a provider_key : http[s]://<access_token>@<3scale-instance-domain> http[s]://<provider_key>@<3scale-instance-domain> 5.9.1. Adding remote access credentials The following example command adds a remote 3scale instance with the short <name> at <url> : USD 3scale remote add [--config-file <config_file>] <name> <url> Example USD podman run --name toolbox-container registry.redhat.io/3scale-amp2/toolbox-rhel9:3scale2.15 3scale remote add instance_a https://123456789@example_a.net USD 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: USD 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-rhel9:3scale2.15 . Warning Storing secrets for toolbox in a container is a potential security risk, for example when distributing the container with secrets to other users or using the container for automation. Use secured volumes in Podman or secrets in OpenShift. Additional resources For more details on using Podman, see: Building, running, and managing Linux containers on Red Hat Enterprise Linux 8 5.9.2. Listing remote access credentials The following example command shows how to list remote access credentials: USD 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 USD podman run <toolbox_image_with_remotes_added> 3scale remote list instance_a https://example_a.net 123456789 instance_b https://example_b.net 987654321 5.9.3. Removing remote access credentials The following example command shows how to remove remote access credentials: USD 3scale remote remove [--config-file <config_file>] <name> This command removes the remote 3scale instance with the short <name> : Example USD podman run <toolbox_image_with_remote_added> 3scale remote remove instance_a 5.9.4. Renaming remote access credentials The following example command shows how to rename remote access credentials: USD 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 USD podman run <toolbox_image_with_remote_added> 3scale remote rename instance_a instance_b 5.10. Creating application plans Use the 3scale toolbox to create, update, list, delete, show, or export/import application plans in your Developer Portal. 5.10.1. Creating a new application plan Use the following steps to create a new application plan: You have to provide the application plan name. To override the system-name , use the optional parameter. If an application plan with the same name already exists, you will see an error message. Set as default the application plan by using the --default flag. Create a published application plan by using the --publish flag. By default, it will be hidden . Create a disabled application plan by using the --disabled flag. By default, it will be enabled . Note The service positional argument is a service reference and can be either service id or service system_name . The toolbox uses either one. The following command creates a new application plan: USD 3scale application-plan create [opts] <remote> <service> <plan-name> Use the following options while creating application plans: 5.10.2. Creating or updating application plans Use the following steps to create a new application plan if it does not exist, or to update an existing one: Update the default application plan by using the --default flag. Update the published application plan by using the --publish flag. Update the hidden application plan by using the --hide flag. Update the disabled application plan by using the --disabled flag. Update the enabled application plan by using the --enabled flag. Note The service positional argument is a service reference and can be either service id or service system_name . The toolbox uses either one. The plan positional argument is a plan reference and can be either plan id or plan system_name . The toolbox uses either one. The following command updates the application plan: USD 3scale application-plan create [opts] <remote> <service> <plan> Use the following options while updating application plans: 5.10.3. Listing application plans The following command lists the application plan: USD 3scale application-plan list [opts] <remote> <service> Use the following options while listing application plans: 5.10.4. Showing application plans The following command shows the application plan: USD 3scale application-plan show [opts] <remote> <service> <plan> Use the following options while showing application plans: 5.10.5. Deleting application plans The following command deletes the application plan: USD 3scale application-plan delete [opts] <remote> <service> <plan> Use the following options while deleting application plans: 5.10.6. Exporting/importing application plans You can export or import a single application plan to or from yaml content. Note the following: Limits defined in the application plan are included. Pricing rules defined in the application plan are included. Metrics/methods referenced by limits and pricing rules are included. Features defined in the application plan are included. Service can be referenced by id or system_name . Application Plan can be referenced by id or system_name . 5.10.6.1. Exporting an application plan to a file The following command exports the application plan: USD 3scale application-plan export [opts] <remote> <service_system_name> <plan_system_name> Example USD podman run -u root -v USDPWD:/tmp registry.redhat.io/3scale-amp2/toolbox-rhel9:3scale2.15 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 USDPWD folder. Note Specific to the export command: Read only operation on remote service and application plan. Command output can be stdout or file. If not specified by -f option, by default, yaml content will be written on stdout . Use the following options while exporting application plans: 5.10.6.2. Importing an application plan from a file The following command imports the application plan: USD 3scale application-plan import [opts] <remote> <service_system_name> Example USD podman run -v USDPWD/plan.yaml:/tmp/plan.yaml registry.redhat.io/3scale-amp2/toolbox-rhel9:3scale2.15 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 USDPWD folder. 5.10.6.3. Importing an application plan from a URL USD 3scale application-plan import -f http[s]://domain/resource/path.yaml remote_name service_name Note Specific to import command: Command input content can be stdin , file or URL format. If not specified by -f option, by default, yaml content will be read from stdin . If application plan cannot be found in remote service, it will be created. Optional param -p , --plan to override remote target application plan id or system_name . If not specified by -p option, by default, application plan will be referenced by plan attribute system_name from yaml content. Any metric or method from yaml content that cannot be found in remote service, will be created. Use the following options while importing application plans: 5.11. Creating metrics Use the 3scale toolbox to create, update, list, and delete metrics in your Developer Portal. Use the following steps for creating metrics: You have to provide the metric name. To override the system-name , use the optional parameter. If metrics with the same name already exist, you will see an error message. Create a disabled metric by using the --disabled flag. By default, it will be enabled . Note The service positional argument is a service reference and can be either service id or service system_name . The toolbox uses either one. The following command creates metrics: USD 3scale metric create [opts] <remote> <service> <metric-name> Use the following options while creating metrics: 5.11.1. Creating or updating metrics Use the following steps to create new metrics if they do not exist, or to update an existing one: If metrics with the same name already exist, you will see an error message. Update a disabled metric by using the --disabled flag. Update to enabled metric by using the --enabled flag. Note The service positional argument is a service reference and can be either service id or service system_name . The toolbox uses either one. The metric positional argument is a metric reference and can be either metric id or metric system_name . The toolbox uses either one. The following commmand updates metrics: USD 3scale metric apply [opts] <remote> <service> <metric> Use the following options while updating metrics: 5.11.2. Listing metrics The following command lists metrics: USD 3scale metric list [opts] <remote> <service> Use the following options while listing metrics: 5.11.3. Deleting metrics The following command deletes metrics: USD 3scale metric delete [opts] <remote> <service> <metric> Use the following options while deleting metrics: 5.12. Creating methods Use the 3scale toolbox to create, apply, list, and delete methods in your Developer Portal. 5.12.1. Creating methods Use the following steps for creating methods: You have to provide the method name. To override the system-name , use the optional parameter. If a method with the same name already exists, you will see an error message. Create a disabled method by --disabled flag. By default, it will be enabled . Note The service positional argument is a service reference and can be either service id or service system_name . The toolbox uses either one. The following command creates a method: USD 3scale method create [opts] <remote> <service> <method-name> Use the following options while creating methods: 5.12.2. Creating or updating methods Use the steps below for creating new methods if they do not exist, or to update existing ones: If a method with the same name already exists, the command will return an error message. Update to disabled method by using --disabled flag . Update to enabled method by using --enabled flag . Note The service positional argument is a service reference and can be either service id or service system_name . The toolbox uses either one. The method positional argument is a method reference and can be either method id or method system_name . The toolbox uses either one. The following command updates a method: USD 3scale method apply [opts] <remote> <service> <method> Use the following options while updating methods: 5.12.3. Listing methods The following command lists methods: USD 3scale method list [opts] <remote> <service> Use the following options while listing methods: 5.12.4. Deleting methods The following command deletes methods: USD 3scale method delete [opts] <remote> <service> <metric> Use the following options while deleting methods: 5.13. Creating services Use the 3scale toolbox to create, apply, list, show, or delete services in your Developer Portal. 5.13.1. Creating a new service The following command creates a new service: USD 3scale service create [options] <remote> <service-name> Use the following options while creating services: 5.13.2. Creating or updating services Use the following to create new services if they do not exist, or to update an existing one: Note service-id_or_system-name positional argument is a service reference. It can be either service id , or service system_name . Toolbox will automatically figure this out. This command is idempotent . The following command updates services: USD 3scale service apply <remote> <service-id_or_system-name> Use the following options while updating services: 5.13.3. Listing services The following command lists services: USD 3scale service list <remote> Use the following options while listing services: 5.13.4. Showing services The following command shows services: USD 3scale service show <remote> <service-id_or_system-name> Use the following options while showing services: 5.13.5. Deleting services The following command deletes services: USD 3scale service delete <remote> <service-id_or_system-name> Use the following options while deleting services: 5.14. Creating ActiveDocs Use the 3scale toolbox to create, update, list, or delete ActiveDocs in your Developer Portal. 5.14.1. Creating new ActiveDocs To create a new ActiveDocs from your API definition compliant with the OpenAPI specification: Add your API definition to 3scale, optionally giving it a name: USD 3scale activedocs create <remote> <activedocs-name> <specification> The OpenAPI specification for the ActiveDocs is required and must be one of the following values: Filename in the available path. URL from where toolbox can download the content. The supported schemes are http and https . Read from stdin standard input stream. This is controlled by setting the - value. Use the following options while creating ActiveDocs: Publish the definition in your Developer Portal. 5.14.2. Creating or updating ActiveDocs Use the following command to create new ActiveDocs if they do not exist, or to update existing ActiveDocs with a new API definition: USD 3scale activedocs apply <remote> <activedocs_id_or_system_name> Use the following options while updating ActiveDocs: Note The behavior of activedocs apply --skip-swagger-validations changed in 3scale 2.8. You may need to update existing scripts using activedocs apply . Previously, if you did not specify this option in each activedocs apply command, validation was not skipped. Now, --skip-swagger-validations is true by default. 5.14.3. Listing ActiveDocs Use the following command to get information about all ActiveDocs in the Developer Portal, including: id name system name description published (which means it can be shown in the developer portal) creation date latest updated date The following command lists all defined ActiveDocs: USD 3scale activedocs list <remote> Use the following options while listing ActiveDocs: 5.14.4. Deleting ActiveDocs The following command removes ActiveDocs: USD 3scale activedocs delete <remote> <activedocs-id_or-system-name> Use the following options while deleting ActiveDocs: 5.15. Listing proxy configurations Use the 3scale toolbox to list, show, promote all defined proxy configurations in your Developer Portal. The following command lists proxy configurations: USD 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 USDHOME/.3scalerc.yaml -h --help Print help for this command -k --insecure Proceed and operate even for server connections otherwise considered insecure -v --version Print the version of this command --verbose Verbose mode 5.15.1. Showing proxy configurations The following command shows proxy configurations: USD 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 USDHOME/.3scalerc.yaml -h --help Print help for this command -k --insecure Proceed and operate even for server connections otherwise considered insecure -v --version Print the version of this command --verbose Verbose mode 5.15.2. Promoting proxy configurations The following command promotes the latest staging proxy configuration to the production environment: USD 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 USDHOME/.3scalerc.yaml -h --help Print help for this command -k --insecure Proceed and operate even for server connections otherwise considered insecure -v --version Print the version of this command --verbose Verbose mode 5.15.3. Exporting proxy configurations Use the proxy-config export command, for example, if you have a self-managed APIcast gateway not connected to your 3scale instance. In this scenario, inject the 3scale configuration manually or by using the APICast deployment and configuration options . In both cases, you must provide the 3scale configuration. The following command exports a configuration that you can inject into the APIcast gateway: USD 3scale proxy-config export <remote> You can specify the following options when exporting a proxy configuration for the provider account that will be used as a 3scale configuration file : Options for proxy-config --environment=<value> Gateway environment. Must be 'sandbox' or 'production' (default: sandbox) -o --output=<value> Output format. One of: json|yaml 5.15.4. Deploying proxy configurations The following deploy command promotes your APIcast configuration to the staging environment in 3scale or to a production environment if you are using Service Mesh. USD 3scale proxy deploy <remote> <service> You can specify the following option when using the deploy command to promote your APIcast configuration to the staging environment: -o --output=<value> Output format. One of: json|yaml 5.15.5. Updating proxy configurations The following update command updates your APIcast configuration. USD 3scale proxy update <remote> <service> You can specify the following options when using the update command to update your APIcast configuration: -o --output=<value> Output format. One of: json|yaml -p --param=<value> APIcast configuration parameters. Format: [--param key=value]. Multiple options allowed. 5.15.6. Showing proxy configurations The following show command fetches your undeployed APIcast configuration. USD 3scale proxy show <remote> <service> You can specify the following options when using the show command to fetch your undeployed APIcast configuration: USD -o --output=<value> Output format. One of: json|yaml 5.15.7. Deploying proxy configurations (Deprecated) Note In 3scale 2.12, support for the proxy-config deploy command is deprecated. Use the the following commands: proxy deploy proxy update proxy show For more information, see Deploying proxy configurations . The following deploy command promotes your APIcast configuration to the staging environment in 3scale or to a production environment if you are using Service Mesh. USD 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: USD -o --output=<value> Output format. One of: json|yaml Additional resources Remotes 5.16. Copying a policy registry Use the toolbox command to copy a policy registry from a 3scale source account to a target account when: Missing custom policies are being created in target account. Matching custom policies are being updated in target account. This copy command is idempotent. Note Missing custom policies are defined as custom policies that exist in source account and do not exist in an account tenant. Matching custom policies are defined as custom policies that exists in both source and target account. The following command copies a policy registry: USD 3scale policy-registry copy [opts] <source_remote> <target_remote> 5.17. Listing applications Use the 3scale toolbox to list, create, show, apply, or delete applications Developer Portal. The following command lists applications: USD 3scale application list [opts] <remote> Use the following options while listing applications: 5.17.1. Creating applications Use the create command to create one application linked to a given 3scale account and application plan. The required positional parameters are as follows: <service> reference. It can be either service id , or service system_name . <account> reference. It can be one of the following: Account id username , email , or user_id of the admin user of the account provider_key <application plan> reference. It can be either plan id , or plan system_name . <name> application name. The following command creates applications: USD 3scale application create [opts] <remote> <account> <service> <application-plan> <name> Use the following options while creating applications: 5.17.2. Showing applications The following command shows applications: USD 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 5.17.3. Creating or updating applications Use the following command to create new applications if they do not exist, or to update existing applications: USD 3scale application apply [opts] <remote> <application> Application parameters allow: User_key - API key App_id - from app_id/app_key pair or Client ID for OAuth and OIDC authentication modes Application internal id account optional argument is required when application is not found and needs to be created. It can be one of the following: Account id username , email , or user_id of the administrator user of the 3scale account provider_key name cannot be used as unique identifier because application name is not unique in 3scale. Resume a suspended application by --resume flag. Suspends an application - changes the state to suspended by the --suspend flag. Use the following options while updating applications: 5.17.4. Deleting applications The following command deletes an application: USD 3scale application delete [opts] <remote> <application> Application parameters allow: User_key - API key App_id - from app_id/app_key pair or Client ID for OAuth and OIDC authentication modes Application internal id 5.18. Exporting products You can export a 3scale product definition in yaml format so that you can import that product into a 3scale instance that has no connectivity with the source 3scale instance. You must set up a 3scale product before you can export that product. See Creating new products to test API calls . When two 3scale instances have network connectivity, use the toolbox 3scale copy command when you want to use the same 3scale product in both 3scale instances. Description When you export a 3scale product, the toolbox serializes the product definition in yaml format that adheres to the Product and Backend custom resource definitions (CRDs). For more information, see Using the 3scale API Management operator to configure and provision 3scale . Along with the basic information for the product, the output yaml includes: Backends that are linked to the product. Metrics, methods and mapping rules for linked backends. Limits and pricing rules defined in application plans. Metrics and methods that are referenced by limits and pricing rules. Exporting a product is a read-only operation. In other words, it is safe to repeatedly export a product. The toolbox does not change the product being exported. If you want to, you can modify the yaml output before you import it into another 3scale instance. Exporting a 3scale product is intended for the following situations: There is no connectivity between the source and destination 3scale instances. For example, there might be severe network restrictions that prevent running the toolbox 3scale copy command when you want to use the same product in more than one 3scale instance. You want to use Git or some other source control system to maintain 3scale product definitions in yaml format. The 3scale toolbox export and import commands might also be useful for backing up and restoring product definitions. Format Use this format for running the export command: USD 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 Admin Portal 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: USD 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: USD 3scale product export my-3scale-1 petstore | oc apply -f - Additional resources Using the 3scale operator to configure and provision 3scale How the 3scale API Management operator identifies the tenant that a custom resource links to 5.19. Importing products To use the same 3scale product in more than one 3scale instance when the source and destination 3scale instances do not have network connectivity, export a 3scale product from one 3scale instance and import it into another 3scale instance. To import a product, run the toolbox 3scale product import command. When two 3scale instances have network connectivity, use the toolbox 3scale copy command when you want to use the same 3scale product in both 3scale instances. Description When you import a 3scale product, the toolbox expects a serialized product definition in .yaml format that adheres to the Product and Backend custom resource definitions (CRDs). You can obtain this .yaml content by running the toolbox 3scale product export command or by manually creating the .yaml formatted product definition. If you exported the product, the imported definition contains what was exported, which can include: Backends that are linked to the product. Metrics, methods and mapping rules for linked backends. Limits and pricing rules defined in application plans. Metrics and methods that are referenced by limits and pricing rules. If you want to, you can modify exported .yaml output before you import it into another 3scale instance. The import command is idempotent. You can run it any number of times to import the same product and the resulting 3scale configuration remains the same. If there is an error during the import process, it is safe to re-run the command. If the import process cannot find the product in the 3scale instance, it creates the product. It also creates any metric, method, or backend that is defined in the .yaml definition and that it cannot find in the 3scale instance. Importing a 3scale product is intended for the following situations: There is no connectivity between the source and destination 3scale instances. For example, there might be severe network restrictions that prevent running the toolbox 3scale copy command when you want to use the same product in more than one 3scale instance. You want to use Git or some other source control system to maintain 3scale product definitions in .yaml format. The 3scale toolbox export and import commands might also be useful for backing up and restoring product definitions. Format Use this format for running the import command: The import command takes .yaml input from stdin or from a file. The default is stdin . You can specify these options: -f or --file followed by a file name obtains input from the .yaml file that you specify. This file must contain a 3scale product definition that adheres to the 3scale Product and Backend CRDs. -o or --output followed by json or yaml outputs the report that lists what was imported in the format that you specify. The default output format is json . Replace <remote> with a 3scale provider account alias or URL associated with the 3scale instance into which you want to import the product. For more information about specifying this, see Managing remote access credentials . Example The following command imports the product that is defined in petstore-product.yaml into the 3scale instance associated with the my-3scale-2 provider account. By default, the report of what was imported is in .json format. The import command outputs a report that lists the imported items, for example: api: product_id: 2555417888846 backends: backend_01: backend_id: 73310 missing_metrics_created: 1 missing_methods_created: 1 missing_mapping_rules_created: 1 backend_02: backend_id: 73311 missing_metrics_created: 0 missing_methods_created: 2 missing_mapping_rules_created: 1 missing_methods_created: 1 missing_metrics_created: 1 missing_mapping_rules_created: 2 missing_application_plans_created: 2 application_plans: basic: application_plan_id: 2357356246461 missing_limits_created: 7 missing_pricing_rules_created: 7 unlimited: application_plan_id: 2357356246462 missing_limits_created: 1 missing_pricing_rules_created: 0 An example of a serialized product definition is at the end of Exporting products . 5.20. Export and import a product policy chain You can export or import your product's policy chain to or from yaml or json content. In a command line, reference the product by its id or system value. You must set up a 3scale product before you can export or import a product's policy chain. See: Creating new products to test API calls . Features of the export command The command is a read-only operation for remote products. The command will write its output by default to the standard output stdout . The -f flag can be used to write the command's output to a file. Command output formats are in either json or yaml . Note that the default format is yaml . Help options for the export product policy chain Command format The following is the format of the command to export the policy chain to a file in yaml : Features of the the import command: The command will read input from standard input or stdin . When -f FILE flag is set, input will be read from a file. When -u URL flag is set, input will be read from the URL. The imported content can be either yaml or json . You do not need to specify the format because the toolbox automatically detects it. The existing policy chain is overwritten with the newly imported one. SET semantics are then implemented. All content validation is delegated to the 3scale API. Help options for the import product policy chain Command format The following is the format of the command to import the policy chain from a file: The following is the format of the command to import the policy chain from a URI: 5.21. Copying API backends Create a copy of the specified source API backend on the specified 3scale system. The target system is first searched by the source backend system name by default: If a backend with the selected system name is not found, it is created. If a backend with the selected system name is found, it is replaced. Only missing metrics and methods are created, while mapping rules are entirely replaced with the new ones. You can override the system name using the --target_system_name option. Copied components The following API backend components are copied: Metrics Methods Mapping rules: these are copied and replaced. Procedure Enter the following command to copy an API backend: The specified 3scale instance can be a remote name or a URL. Note You can copy a single API backend only per command. You can copy multiple backends using multiple commands. You can copy the same backend multiple times by specifying a different --target_system_name name . Use following options when copying API backends: The following example command shows you how to copy an API backend multiple times by specifying a different value for --target_system_name : USD podman run registry.redhat.io/3scale-amp2/toolbox-rhel9:3scale2.15 3scale backend copy [-t target_system_name] -s 3scale1 -d 3scale2 api_backend_01 5.22. Copying API products Create a copy of the specified source API product on the target 3scale system. By default, the source API product system name first searches the target system: If a product with the selected system-name is not found, it is created. If a product with the selected system-name is found, it is updated. Only missing metrics and methods are created, while mapping rules are entirely replaced with the new ones. You can override the system name using the --target_system_name option. Copied components The following API product components are copied: Configuration and settings Metrics and methods Mapping rules: these are copied and replaced. Application plans, pricing rules, and limits Application usage rules Policies Backends ActiveDocs Procedure Enter the following command to copy an API product: The specified 3scale instance can be a remote name or a URL. Note You can copy a single API product only per command. You can copy multiple products using multiple commands. You can copy the same product multiple times by specifying a different --target_system_name name . Use following options when copying API products: The following example command shows you how to copy an API product multiple times by specifying a different value for --target_system_name : USD podman run registry.redhat.io/3scale-amp2/toolbox-rhel9:3scale2.15 3scale product copy [-t target_system_name] -s 3scale1 -d 3scale2 my_api_product_01 5.23. Troubleshooting issues with SSL and TLS This section explains how to resolve issues with Secure Sockets Layer/Transport Layer Security (SSL/TLS). If you are experiencing issues related to self-signed SSL certificates, you can download and use remote host certificates as described in this section. For example, typical errors include SSL certificate problem: self signed certificate or self signed certificate in certificate chain . Procedure Download the remote host certificate using openssl . For example: USD 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: USD 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 your 3scale commands. For example: USD podman run --env "SSL_CERT_FILE=/tmp/self-signed-cert.pem" -v USDPWD/self-signed-cert.pem:/tmp/self-signed-cert.pem registry.redhat.io/3scale-amp2/toolbox-rhel9:3scale2.15 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 USDPWD folder. An alternative approach would be to create your own toolbox image using the 3scale toolbox image as the base image and then install your own trusted certificate store. Additional resources Red Hat Certificate System documentation Building, running, and managing Linux containers on Red Hat Enterprise Linux 8

Commands:
podman login registry.redhat.io Username: USD{REGISTRY-SERVICE-ACCOUNT-USERNAME} Password: USD{REGISTRY-SERVICE-ACCOUNT-PASSWORD} Login Succeeded!
podman pull registry.redhat.io/3scale-amp2/toolbox-rhel9:3scale2.15
podman run registry.redhat.io/3scale-amp2/toolbox-rhel9:3scale2.15 3scale help
COMMANDS account account super command activedocs activedocs super command application application super command application-plan application-plan super command backend backend super command copy copy super command help print help import import super command method method super command metric metric super command policy-registry policy-registry super command product product super command proxy-config proxy-config super command remote remotes super command service services super command OPTIONS -c --config-file=<value> 3scale toolbox configuration file (default: USDHOME/.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
service_name,endpoint_name,endpoint_http_method,endpoint_path,auth_mode,endpoint_system_name,type
podman run -v USDPWD/examples/import_example.csv:/tmp/import_example.csv registry.redhat.io/3scale-amp2/toolbox-rhel9:3scale2.15 3scale import csv --destination=https://{ACCESS_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME} --file=/tmp/import_example.csv
podman run registry.redhat.io/3scale-amp2/toolbox-rhel9:3scale2.15 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}
podman run registry.redhat.io/3scale-amp2/toolbox-rhel9:3scale2.15 3scale copy [opts] service --source=https://{ACCESS_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME} --destination=https://{DEST_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME} {SERVICE_ID} {DEST_ID}
openapi: "3.0.2" security: - petstore_api_key: [] components: securitySchemes: petstore_api_key: type: apiKey name: api_key in: header
openapi: "3.0.2" security: - petstore_oauth: - write:pets - read:pets components: securitySchemes: petstore_oauth: type: oauth2 flows: clientCredentials: tokenUrl: http://example.org/api/oauth/dialog scopes: write:pets: modify pets in your account read:pets: read your pets
3scale import openapi [opts] -d <destination> <specification>
podman run -v USDPWD/my-test-api.json:/tmp/my-test-api.json registry.redhat.io/3scale-amp2/toolbox-rhel9:3scale2.15 3scale import openapi [opts] -d=https://{DEST_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME} /tmp/my-test-api.json
3scale import openapi -d <remote> --backend <OAS>
3scale remote add [--config-file <config_file>] <name> <url>
podman run --name toolbox-container registry.redhat.io/3scale-amp2/toolbox-rhel9:3scale2.15 3scale remote add instance_a https://123456789@example_a.net podman commit toolbox-container toolbox
podman run toolbox 3scale remote list instance_a https://example_a.net 123456789
3scale remote list [--config-file <config_file>]
podman run <toolbox_image_with_remotes_added> 3scale remote list instance_a https://example_a.net 123456789 instance_b https://example_b.net 987654321
3scale remote remove [--config-file <config_file>] <name>
podman run <toolbox_image_with_remote_added> 3scale remote remove instance_a
3scale remote rename [--config-file <config_file>] <old_name> <new_name>
podman run <toolbox_image_with_remote_added> 3scale remote rename instance_a instance_b
3scale application-plan create [opts] <remote> <service> <plan-name>
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 USDHOME/.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
3scale application-plan create [opts] <remote> <service> <plan>
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 USDHOME/.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
3scale application-plan list [opts] <remote> <service>
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 USDHOME/.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
3scale application-plan show [opts] <remote> <service> <plan>
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 USDHOME/.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
3scale application-plan delete [opts] <remote> <service> <plan>
Options for application-plan -c --config-file=<value> 3scale toolbox configuration file: defaults to USDHOME/.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
3scale application-plan export [opts] <remote> <service_system_name> <plan_system_name>
podman run -u root -v USDPWD:/tmp registry.redhat.io/3scale-amp2/toolbox-rhel9:3scale2.15 3scale application-plan export --file=/tmp/plan.yaml remote_name service_name plan_name
Options -f --file=<value> Write to file instead of stdout Options for application-plan -c --config-file=<value> 3scale toolbox configuration file: defaults to USDHOME/.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
3scale application-plan import [opts] <remote> <service_system_name>
podman run -v USDPWD/plan.yaml:/tmp/plan.yaml registry.redhat.io/3scale-amp2/toolbox-rhel9:3scale2.15 3scale application-plan import --file=/tmp/plan.yaml remote_name service_name
3scale application-plan import -f http[s]://domain/resource/path.yaml remote_name service_name
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 USDHOME/.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
3scale metric create [opts] <remote> <service> <metric-name>
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 USDHOME/.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
3scale metric apply [opts] <remote> <service> <metric>
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 USDHOME/.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
3scale metric list [opts] <remote> <service>
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 USDHOME/.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
3scale metric delete [opts] <remote> <service> <metric>
Options for metric -c --config-file=<value> 3scale toolbox configuration file: defaults to USDHOME/.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
3scale method create [opts] <remote> <service> <method-name>
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 USDHOME/.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
3scale method apply [opts] <remote> <service> <method>
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 USDHOME/.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
3scale method list [opts] <remote> <service>
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 USDHOME/.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
3scale method delete [opts] <remote> <service> <metric>
Options for method -c --config-file=<value> 3scale toolbox configuration file: defaults to USDHOME/.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
3scale service create [options] <remote> <service-name>
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 USDHOME/.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
3scale service apply <remote> <service-id_or_system-name>
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 USDHOME/.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
3scale service list <remote>
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 USDHOME/.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
3scale service show <remote> <service-id_or_system-name>
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 USDHOME/.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
3scale service delete <remote> <service-id_or_system-name>
Options for services -c --config-file=<value> 3scale toolbox configuration file: defaults to USDHOME/.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
3scale activedocs create <remote> <activedocs-name> <specification>
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 USDHOME/.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
3scale activedocs apply <remote> <activedocs_id_or_system_name>
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 USDHOME/.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
3scale activedocs list <remote>
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 USDHOME/.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
3scale activedocs delete <remote> <activedocs-id_or-system-name>
Options for ActiveDocs -c --config-file=<value> 3scale toolbox configuration file: defaults to USDHOME/.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
3scale proxy-config list <remote> <service> <environment>
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 USDHOME/.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
3scale proxy-config show <remote> <service> <environment>
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 USDHOME/.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
3scale proxy-config promote <remote> <service>
Options for proxy-config -c --config-file=<value> 3scale toolbox configuration file: defaults to USDHOME/.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
3scale proxy-config export <remote>
Options for proxy-config --environment=<value> Gateway environment. Must be 'sandbox' or 'production' (default: sandbox) -o --output=<value> Output format. One of: json|yaml
3scale proxy deploy <remote> <service>
-o --output=<value> Output format. One of: json|yaml
3scale proxy update <remote> <service>
-o --output=<value> Output format. One of: json|yaml -p --param=<value> APIcast configuration parameters. Format: [--param key=value]. Multiple options allowed.
3scale proxy show <remote> <service>
-o --output=<value> Output format. One of: json|yaml
3scale proxy-config deploy <remote> <service>
-o --output=<value> Output format. One of: json|yaml
3scale policy-registry copy [opts] <source_remote> <target_remote>
Option for policy-registry -c --config-file=<value> 3scale toolbox configuration file: defaults to USDHOME/.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
3scale application list [opts] <remote>
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 USDHOME/.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
3scale application create [opts] <remote> <account> <service> <application-plan> <name>
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 USDHOME/.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
3scale application show [opts] <remote> <application>
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 USDHOME/.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
3scale application apply [opts] <remote> <application>
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 USDHOME/.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.
3scale application delete [opts] <remote> <application>
3scale product export [-f output-file] <remote> <product>
3scale product export -f petstore-product.yaml my-3scale-1 petstore
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: ''
3scale product export my-3scale-1 petstore | oc apply -f -
3scale product import [<options>] <remote>
3scale product import -f petstore-product.yaml my-3scale-2
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
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
3scale policies export -f policies.yaml -o yaml remote_name product_name
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
3scale policies import -f plan.yaml remote_name product_name
3scale policies import -f http[s]://domain/resource/path.yaml remote_name product_name
3scale backend copy [opts] -s <source_remote> -d <target_remote> <source_backend>
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.
podman run registry.redhat.io/3scale-amp2/toolbox-rhel9:3scale2.15 3scale backend copy [-t target_system_name] -s 3scale1 -d 3scale2 api_backend_01
3scale product copy [opts] -s <source_remote> -d <target_remote> <source_product>
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.
podman run registry.redhat.io/3scale-amp2/toolbox-rhel9:3scale2.15 3scale product copy [-t target_system_name] -s 3scale1 -d 3scale2 my_api_product_01
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
SSL_CERT_FILE=self-signed-cert.pem curl -v https://self-signed.badssl.com
podman run --env "SSL_CERT_FILE=/tmp/self-signed-cert.pem" -v USDPWD/self-signed-cert.pem:/tmp/self-signed-cert.pem registry.redhat.io/3scale-amp2/toolbox-rhel9:3scale2.15 3scale service list https://{ACCESS_KEY}@{3SCALE_ADMIN}-admin.{DOMAIN_NAME}