This page applies to Apigee and Apigee hybrid.
View Apigee Edge documentation.
The apigee-remote-service-cli
Command Line Interface (CLI) helps you
provision and manage Apigee Adapter for Envoy.
Simplify CLI commands with the ‑‑config
option
The ‑‑config
option specifies the location
of the config.yaml
file generated by the provision
command. A helpful benefit of this option is that it
allows you to skip most other command parameters because the CLI pulls them directly from the config.yaml
file.
Note that any command-line parameters specified override values in the config.yaml
file.
- organization
- environment
- runtime
- management
- insecure
- namespace
- legacy
- opdk
You can use this option when upgrading the adapter; however, you must still include the
--force-proxy-install
flag in that case.
For example, you could execute the provision
command like this:
apigee-remote-service-cli provision --config='old-config.yaml' > new-config.yaml
Note that if you do not change any values in the old config file, you don't have to save a new one, because it will be identical to the original.
List bindings command
List all API products that are bound to the Remote Service.
Usage
apigee-remote-service-cli bindings list [flags]
Parameters
Parameters | Presence | Used with products | Description |
---|---|---|---|
-c,
|
Optional | All | (String) The path to the Apigee Remote Service config file. Tip: This flag allows you to omit most other command parameters, because the CLI is able to pull them directly from the config file. See Using the ‑‑config option.
|
-e,
|
Optional if --config is present; required otherwise. |
All | (String) An environment in your organization. |
-h,
|
Optional | All | Displays help for the command parameters. |
‑‑insecure
|
Optional | All | Allow insecure server connections when using SSL. |
‑‑legacy
|
N/A | Edge Public Cloud only | This parameter does not apply for Apigee installations. |
-m,
|
N/A | Edge Private Cloud only | This parameter does not apply for Apigee installations. |
‑‑mfa
| N/A | Edge Public Cloud only | This parameter does not apply for Apigee installations. |
‑‑opdk
| N/A | Edge Private Cloud only | This parameter does not apply for Apigee installations. |
-o,
|
Optional if --config is present; required otherwise. |
All | (String) An Apigee organization. You must be an org administrator. |
-p,
|
N/A (Basic Auth Only) |
Edge Public and Private Cloud only | This parameter does not apply for Apigee installations. |
-r,
|
Optional if --config is present; required otherwise. |
Apigee hybrid only | (String) Specifies the runtime URL for your Private Cloud or Apigee hybrid instance.
The URL must start with https:// . For example: https://apitest.example.net
|
|
N/A | Edge Private Cloud only | This parameter does not apply for Apigee installations. |
-t,
|
Required (OAuth token auth only) |
All | (String) An OAuth or SAML token that you generate from your Apigee account information. Overrides any other provided credentials. |
-u,
|
N/A (Basic Auth Only) |
Edge Public and Private Cloud only | This parameter does not apply for Apigee installations. |
-v,
|
Optional | All | (Optional) Produces verbose output. |
Example
apigee-remote-service-cli bindings list -o myorg -e test --token $TOKEN \ -c config.yaml
Example output
API Products ============ Bound ----- envoy-test: Quota: 5 requests every 1 minute Target bindings: httpbin.org Paths: httpbin: Quota: 5 requests every 1 minute Target bindings: httpbin.org Paths: /httpbin / Unbound ------- product-1: Quota: 100 requests every 1 hour product-2: Quota: 1000 requests every 1 month product-3: product-4:
Help command
Online help is provided for all apigee-remote-service-cli
commands. Just type:
apigee-remote-service-cli help
For help on any command, type:
apigee-remote-service-cli [command] help
For example:
apigee-remote-service-cli provision help
Provision command
The apigee-remote-service-cli provision
command installs two API proxies in your Apigee
Edge organization, sets up a certificate, and generates credentials that you'll need to
configure the Apigee Adapter for Envoy.
Usage
apigee-remote-service-cli provision [flags]
Parameters
Parameters | Presence | Used with products | Description |
---|---|---|---|
‑‑analytics-sa
|
Optional | Apigee hybrid and Apigee only |
(String) Use this flag to specify the path to a Google Cloud service account key file, where
the service account has the |
-c,
|
Optional | All | (String) The path to the Apigee Remote Service config file. Tip: This flag allows you to omit most other command parameters, because the CLI is able to pull them directly from the config file. See Using the --config option.
|
-e,
|
Optional if --config is present; required otherwise. |
All | (String) An environment in your organization. |
-f, ‑‑force-proxy-install
|
Optional | All | (Optional) Forces the remote-service proxy to be re-installed if it is
already installed in your org.
|
-h,
|
Optional | All | Displays help for the command parameters. |
‑‑insecure
|
Optional | All | Allow insecure server connections when using SSL. |
‑‑legacy
|
N/A | Edge Public Cloud only | This parameter does not apply for Apigee installations. |
-m,
|
N/A | Edge Private Cloud only | This parameter does not apply for Apigee installations. |
‑‑mfa
| N/A | Edge Public Cloud only | This parameter does not apply for Apigee installations. |
-n, ‑‑namespace
|
Optional if --config is present; defaults to apigee .
|
For Kubernetes deployments only | (String) Emit configuration as an Envoy ConfigMap in the specified namespace. Default: apigee
|
‑‑opdk
| N/A | Edge Private Cloud only | This parameter does not apply for Apigee installations. |
-o,
|
Optional if --config is present; required otherwise. |
All | (String) An Apigee organization. You must be an org administrator to provision. |
-p,
|
N/A (Basic Auth Only) |
Edge Public and Private Cloud only | This parameter does not apply for Apigee installations. |
‑‑rotate
|
Optional | Apigee hybrid only | (Integer) If n > 0, generate new private key and keep n public keys (hybrid only) |
-r,
|
Optional if --config is present; required otherwise. |
Apigee hybrid only | (String) Specifies the runtime URL for your Apigee hybrid instance.
The URL must start with https:// . For example: https://apitest.example.net
|
|
N/A | Edge Private Cloud only | This parameter does not apply for Apigee installations. |
-t,
|
Required (OAuth token auth only) |
All | (String) An OAuth or SAML token that you generate from your Apigee account information. Overrides any other provided credentials. |
-u,
|
N/A (Basic Auth Only) |
Edge Public and Private Cloud only | This parameter does not apply for Apigee installations. |
-v,
|
Optional | All | (Optional) Produces verbose output. |
‑‑virtual-hosts
|
N/A | Edge Private Cloud only | This parameter does not apply for Apigee installations. |
Example
As the following example shows, it's important to capture the output of the provision
command in a file, which is used
as input for other Apigee Adapter for Envoy operations.
Example:
apigee-remote-service-cli provision --legacy --mfa $MFA --username $USER --password $PASSWORD \ --organization $ORG --environment $ENV > config.yaml
Samples command
Creates and lists sample configuration files.
Create sample configuration files
Creates sample configuration files for native Envoy and Istio deployments.
Usage
apigee-remote-service-cli samples create [flags]
Description
This command requires a valid config.yaml
file as input. This input file is the file that was
generated through provisioning.
By default, the sample files are output to a directory named ./samples
. The command
creates this directory for you.
If you're using native Envoy, the command takes the target service host and the desired name for
its cluster. It also sets a custom SSL connection from the Envoy proxy to the remote service
cluster if a folder containing tls.key
and tls.crt
is provided via --tls
.
If you're using Istio, where the Envoy proxy acts as a sidecar, if the target is unspecified,
the httpbin
example will be generated. Otherwise, you are responsible for preparing
configuration files related to deployment of your target services.
Parameters
Parameters | Presence | Used with products | Description |
---|---|---|---|
‑‑adapter‑host
|
Used for Envoy templates only | All | (String) The adapter hostname (default: localhost )
|
-c, ‑‑config
|
Required | All | (String) Path to Apigee Remote Service config file. Tip: This flag allows you to omit most other command parameters, because the CLI is able to pull them directly from the config file. See Using the --config option.
|
-f, ‑‑force
|
Optional | All | Force the existing directory to be overwritten. |
-h, ‑‑help
|
Optional | All | Displays help for the command parameters. |
‑‑host |
Used for Envoy templates only | All | (String) The target service host (default httpbin.org )
|
-n, ‑‑name |
Optional | All | (String) The target service name (default httpbin.org )
|
‑‑out
|
Optional | All | (String) The directory in which to create the sample config files. Default: ./samples
|
‑‑tag
|
Used for Istio templates only | All | (String) The version tag of the Envoy Adapter image. Default: Current release version |
-t, ‑‑template
|
Optional | All | (String) The Envoy or Istio template name. To see the available list of templates, execute the command
apigee-remote-service samples templates . Default: istio-1.9 . The default
works for all 1.9+ versions of Istio.
|
‑‑tls
|
Optional, for Envoy templates only | All | (String) The directory containing tls.key and tls.crt files
used for the adapter service.
|
Example
apigee-remote-service-cli samples create -c ./config.yaml
List available template options
Lists the templates available to use with the --templates
parameter for the samples
command.
Usage
apigee-remote-service-cli samples templates
Parameters
None.
Example
apigee-remote-service-cli samples templates
Supported templates (native is deprecated): envoy-1.15 envoy-1.16 envoy-1.17 istio-1.7 istio-1.8 istio-1.9
Token commands
You can use a JWT token to make authenticated API proxy calls instead of using an API key. The token commands let you create, inspect, and rotate JWT tokens for this purpose.
Create a JWT token
You can use a JWT token to make authenticated API proxy calls to a remote service target. See also Using JWT based authentication.Usage
apigee-remote-service-cli token create [flags]
Parameters
Parameters | Presence | Used with products | Description |
---|---|---|---|
-c,
|
Required | All | (String) The path to the Apigee Remote Service config file. Tip: This flag allows you to omit most other command parameters, because the CLI is able to pull them directly from the config file. See Using the --config option.
|
-e,
|
Optional if --config is present; required otherwise. |
All | (String) An environment in your organization. |
-h,
|
Optional | All | Displays help for the command parameters. |
--i, --id
|
Required | All | (String) The Key credential found in the Apigee developer app as described in How to obtain an API key. |
‑‑insecure
|
Optional | All | Allow insecure server connections when using SSL. |
‑‑legacy
|
N/A | Edge Public Cloud only | This parameter does not apply for Apigee installations. |
‑‑opdk
| N/A | Edge Private Cloud only | This parameter does not apply for Apigee installations. |
-o,
|
Optional if --config is present; required otherwise. |
All | (String) An Apigee organization. You must be an org administrator. |
-r,
|
Optional if --config is present; required otherwise. |
Apigee hybrid only | (String) Specifies the runtime URL for your Private Cloud or Apigee hybrid instance.
The URL must start with https:// . For example: https://apitest.example.net
|
--s, ‑‑secret
|
Required | All | (String) The Secret credential found in the Apigee developer app as described in How to obtain an API key. |
|
N/A | Edge Private Cloud only | This parameter does not apply for Apigee installations. |
-v,
|
Optional | All | (Optional) Produces verbose output. |
Example
apigee-remote-service-cli token create -o myorg -e test -i YUmlZAcBKNsTAelJqPZFl3sh58ObATX9 \ -s icTARgaKHqvUH1dq -c config.yaml
Output
On success, you'll see a JST token output similar to the following:eyJraWQiOiIxIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJhY2Nlc3NfdG9rZW4iOiJ0a2tlVzVKQTY2a0pZYTB4bFV1cVBsUW1BMU43IiwiYXVkIjoiaXN0aW8iLCJuYmYiOjE1MzAxMzg1OTEsImFwaV9wcm9kdWN0X2xpc3QiOlsiaXN0aW8tcHJvZHVjdCJdLCJhcHBsaWNhdGlvbl9uYW1lIjoiaXN0aW8tYXBwIiwiZGV2ZWxvcGVyX2VtYWlsIjoicFluZ2Zsb3lkQGdvb2dsZS5jb20iLCJpc3MiOiJodHRwczovL2FwaWdlZXNlYXJjaC10ZXN0LmFwaWdlZS5uZXQvaXN0aW8tYXV0aC90b2tlbiIsImV4cCI6MTUzMDEzOTQ5MSwiaWF0IjoxNTMwMTM4NTkxLCJqdGkiOiIxODgzMzViZi0wMmE4LTRjZGUsOGFkOS0yMWJmNDZjNmRjZDkiLCJjbGllbnRfaWQiOiJZVW1sWkFjQktOc1RBZWxKcVBZRmwzc2g1OE9iQVRYOSJ9.AL7pKSTmond-NSPRNNHVbIzTdAnZjOXcjQ-BbOJ_8lsQvF7PuiOUrGIhY5XTcJusisKgbCdtIxBl8Wq1EiQ_fKnUc3JYYOqzpTB5bGoFy0Yqbfu96dneuWyzgZnoQBkqwZkbQTIg7WNTGx1TJX-UTePvBPxAefiAbaEUcigX9tTsXPoRJZOTrm7IOeKpxpB_gQYkxQtV1_NbERxjTPyMbHdMWal9_xRVzSt7mpTGudMN9OR-VtQ1uXA67GOqhZWcOzq57qImOiCMbaoKnKUADevyWjX_VscN5ZZUtzQUQhTrmv8aR69-uVhMIPKp9juMyYKaYn2IsYZEeCWfhfV45Q
Inspect a JWT token
You can inspect a JWT token with this command. See also Inspect a token.Usage
apigee-remote-service-cli token inspect [flags]
Parameters
Parameters
Parameters | Presence | Used with products | Description |
---|---|---|---|
-c,
|
Required | All | (String) The path to the Apigee Remote Service config file. Tip: This flag allows you to omit most other command parameters, because the CLI is able to pull them directly from the config file. See Using the ‑‑config option.
|
-e,
|
Optional if --config is present; required otherwise. |
All | (String) An environment in your organization. |
-f,
|
Required | All | (String) The token file (default: use stdin )
|
-h,
|
Optional | All | Displays help for the command parameters. |
‑‑insecure
|
Optional | All | Allow insecure server connections when using SSL. |
‑‑legacy
|
N/A | Edge Public Cloud only | This parameter does not apply for Apigee installations. |
‑‑opdk
| N/A | Edge Private Cloud only | This parameter does not apply for Apigee installations. |
-o,
|
Optional if --config is present; required otherwise. |
All | (String) An Apigee organization. You must be an org administrator. |
-r,
|
Optional if --config is present; required otherwise. |
Apigee hybrid only | (String) Specifies the runtime URL for your Private Cloud or Apigee hybrid instance.
The URL must start with https:// . For example: https://apitest.example.net
|
|
N/A | Edge Private Cloud only | This parameter does not apply for Apigee installations. |
-v,
|
Optional | All | (Optional) Produces verbose output. |
Example
apigee-remote-service-cli token inspect -c config.yaml <<< $TOKEN
Output
On success, you'll see output similar to the following:{ "aud": [ "remote-service-client" ], "exp": 1591741549, "iat": 1591740649, "iss": "https://apigee-docs-test.apigee.net/remote-service/token", "jti": "99325d2e-6440-4278-9f7f-b252a1a79e53", "nbf": 1591740649, "access_token": "VfzpXzBGAQ07po0bPMKY4JgQjus", "api_product_list": [ "httpbin" ], "application_name": "httpbin", "client_id": "GYDGHy5TRpV8AejXCOlreP7dPVepA8H", "developer_email": "user@example.com", "scope": "" } verifying... token ok.
Rotate a JWT token
At some time after you initially generate a JWT, you might need to change the public/private key pair stored by Apigee in its encrypted key-value map (KVM). This process of generating a new key pair is called key rotation. When you rotate keys, a new private/public key pair is generated and stored in the "istio" KVM in your Apigee organization/environment. In addition, the old public key is retained along with its original key ID value.Usage
apigee-remote-service-cli token rotate-cert [flags]
Parameters
Parameters | Presence | Used with products | Description |
---|---|---|---|
-c,
|
Required | All | (String) The path to the Apigee Remote Service config file. Tip: This flag allows you to omit most other command parameters, because the CLI is able to pull them directly from the config file. See Using the --config option.
|
-e,
|
Optional if --config is present; required otherwise. |
All | (String) An environment in your organization. |
-h,
|
N/A | Edge Public and Private Cloud only | Displays help for the command parameters. |
--k, --key
|
N/A | Edge Public and Private Cloud only | (String) The provision key. |
‑‑insecure
|
N/A | Edge Public and Private Cloud only | Allow insecure server connections when using SSL. |
‑‑legacy
|
N/A | Edge Public Cloud only | You must set this flag if you are using Apigee Edge for Public Cloud. Sets the management and runtime URLs for Apigee Edge for Public Cloud. |
‑‑opdk
| N/A | Edge Private Cloud only | You must set this flag if you are using Apigee Edge for Private Cloud. |
-o,
|
Optional if --config is present; required otherwise. |
Edge Public and Private Cloud only | (String) An Apigee organization. You must be an org administrator. |
-r,
|
N/A | Edge Private Cloud only | (String) Specifies the runtime URL for your Private Cloud or Apigee hybrid instance.
The URL must start with https:// . For example: https://apitest.example.net
|
--s, ‑‑secret
|
Required | All | (String) The provision secret. |
|
N/A | Edge Private Cloud only | (String) Specifies client-side TLS certificate, private key, and root CA for mTLS connection. |
--t, ‑‑truncate
|
Required | All | (Integer) The number of certs to keep in JWKS (default 2). |
-v,
|
Optional | All | (Optional) Produces verbose output. |
Example
apigee-remote-service-cli token rotate-cert -c config.yaml -o myorg -e test \ -k 2e238ffa15dc5ab6a1e97868e7581f6c60ddb8575478582c256d8b7e5b2677a8 \ -s 51058077223fa7b683c3bea845c5cca138340d1d5583922b6d465f9f918a4b08
Output
certificate successfully rotated
Create an internal token
Create a JWT token for authorizing remote-service API calls.Usage
apigee-remote-service-cli token internal [flags]
Parameters
Parameters
Parameters | Presence | Used with products | Description |
---|---|---|---|
-c,
|
Required | Apigee hybrid only | (String) The path to the Apigee Remote Service config file. Tip: This flag allows you to omit most other command parameters, because the CLI is able to pull them directly from the config file. See Using the --config option.
|
-d,
|
Required | Apigee hybrid only | (String) valid time of the internal JWT from creation (default: 10m0s (10 minutes)).
|
-e,
|
Optional if --config is present; required otherwise. |
Apigee hybrid only | (String) An environment in your organization. |
-h,
|
Optional | Apigee hybrid only | Displays help for the command parameters. |
‑‑insecure
|
Optional | Apigee hybrid only | Allow insecure server connections when using SSL. |
-o,
|
Optional if --config is present; required otherwise. |
Apigee hybrid only | (String) An Apigee organization. You must be an org administrator. |
-r,
|
Optional if --config is present; required otherwise. |
Apigee hybrid only | (String) Specifies the runtime URL for your Apigee hybrid instance.
The URL must start with https:// . For example: https://apitest.example.net
|
-v,
|
Optional | Apigee hybrid only | (Optional) Produces verbose output. |
Version command
Print the CLI version.
apigee-remote-service-cli version
Configuration file
This section shows an example configuration file with all of the available options.
global: temp_dir: /tmp/apigee-istio keep_alive_max_connection_age: 10m api_address: :5000 metrics_address: :5001 tls: cert_file: tls.crt key_file: tls.key tenant: internal_api: https://istioservices.apigee.net/edgemicro remote_service_api: https://org-test.apigee.net/remote-service org_name: org env_name: env key: mykey secret: mysecret client_timeout: 30s tls: ca_file: /opt/apigee/tls/ca.crt cert_file: /opt/apigee/tls/tls.crt key_file: /opt/apigee/tls/tls.key allow_unverified_ssl_cert: false products: refresh_rate: 2m analytics: legacy_endpoint: false file_limit: 1024 send_channel_size: 10 collection_interval: 10s auth: api_key_claim: claim api_key_cache_duration: 30m api_key_header: x-api-key api_header: :authority allow_unauthorized: false jwt_provider_key: https://org-test.apigee.net/remote-token/token append_metadata_headers: true