Google is committed to advancing racial equity for Black communities. See how.

Reference

The apigee-remote-service-cli Command Line Interface (CLI) helps you provision and manage Apigee Adapter for Envoy.

Binding commands

Binding associates a service deployed to the Istio mesh with an Apigee API product. The CLI lets you create, remove, list, and verify bindings.

Add a binding

Adds a remote service target binding to an API product.

Usage

For Edge Public Cloud:

apigee-remote-service-cli bindings add [service_name] [product_name]  -o [organization] -e [environment] -u [username] -p [password] -c [config]

For Edge Private Cloud:

apigee-remote-service-cli bindings add [service_name] [product_name]  -o [organization] -e [environment] -u [username] -p [password] -r [runtime] -c [config]

Where:

  • target_name is the name of a remote service target to bind to the product.
  • product_name is the name of a product to bind the service to.

Flags

Parameters Type Description
-c, --config String (Required) 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, --env String (Required) An environment in your organization.
-h, --help Displays help for the command parameters.
--insecure Allow insecure server connections when using SSL
--legacy Set this flag if you are using Apigee Edge Cloud. It sets the management and runtime URLs for Edge Cloud.
--mfa Apigee multi-factor authorization token (used with --legacy only)
--opdk Set this flag if you are using Apigee Edge for Private Cloud.
-o, --org String (Required) An Apigee organization. You must be an org administrator.
-p, --password String (Required for basic authentication only) Your Apigee password. You can optionally specify the password in a .netrc file. If you do so, then you are not required to provide your password on the command line. See also Using .netrc for credentials.
-r, --runtime String (Private Cloud only) Specifies the runtime URL for your Private Cloud instance.
-t, --token String (Required for OAuth token authentication only) An OAuth or SAML token that you generate from your Apigee account information. For information on generating tokens, see Using get_token and Access the management API with SAML.
-u, --username String (Required for basic authentication only) Your Apigee username (typically an email address). You can optionally specify the username in a .netrc file. If you do so, then you are not required to provide your username on the command line. See also Using .netrc for credentials.
-v, --verbose (Optional) Produces verbose output.

Example

./apigee-remote-service-cli bindings add httpbin.org envoy-test -o myorg -e test -u user@example.com -c config.yaml -p xxxxxx
product envoy-test is now bound to: httpbin.org

List bindings

List all API products that are bound to the Remote Service.

Usage

For Edge Public Cloud:

apigee-remote-service-cli bindings list -o [organization] -e [environment] -u [username] -p [password]

For Edge Private Cloud:

apigee-remote-service-cli bindings list -o [organization] -e [environment] -u [username] -p [password] -r [runtime] 

Parameters

Parameters Type Description
-c, --config String (Required) 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, --env String (Required) An environment in your organization.
-h, --help Displays help for the command parameters.
--insecure Allow insecure server connections when using SSL
--legacy Set this flag if you are using Apigee Edge Cloud. It sets the management and runtime URLs for Edge Cloud.
--mfa Apigee multi-factor authorization token (used with --legacy only)
--opdk Set this flag if you are using Apigee Edge for Private Cloud.
-o, --org String (Required) An Apigee organization. You must be an org administrator.
-p, --password String (Required for basic authentication only) Your Apigee password. You can optionally specify the password in a .netrc file. If you do so, then you are not required to provide your password on the command line. See also Using .netrc for credentials.
-r, --runtime String (Private Cloud only) Specifies the runtime URL for your Private Cloud instance.
-t, --token String (Required for OAuth token authentication only) An OAuth or SAML token that you generate from your Apigee account information. For information on generating tokens, see Using get_token and Access the management API with SAML.
-u, --username String (Required for basic authentication only) Your Apigee username (typically an email address). You can optionally specify the username in a .netrc file. If you do so, then you are not required to provide your username on the command line. See also Using .netrc for credentials.
-v, --verbose (Optional) Produces verbose output.

Example

apigee-remote-service-cli bindings list -o myorg -e test -u user@example.com -c config.yaml -p abc123
PI 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:

Remove a binding

Remove the binding of Remote Service for Envoy from an API product.

Usage

For Edge Public Cloud:

apigee-remote-service-cli bindings remove [service_name] [product_name]  -o [organization] -e [environment] -u [username] -p [password] -c [config]

For Edge Private Cloud:

apigee-remote-service-cli bindings remove [service_name] [product_name]  -o [organization] -e [environment] -u [username] -p [password] -r [runtime] -c [config]

Where:

  • target_name is the name of a remote service target to unbind from the product.
  • product_name is the name of a product from which to unbind the target.

Parameters

Parameters Type Description
-c, --config String (Required) 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, --env String (Required) An environment in your organization.
-h, --help Displays help for the command parameters.
--insecure Allow insecure server connections when using SSL
--legacy Set this flag if you are using Apigee Edge Cloud. It sets the management and runtime URLs for Edge Cloud.
--mfa Apigee multi-factor authorization token (used with --legacy only)
--opdk Set this flag if you are using Apigee Edge for Private Cloud.
-o, --org String (Required) An Apigee organization. You must be an org administrator.
-p, --password String (Required for basic authentication only) Your Apigee password. You can optionally specify the password in a .netrc file. If you do so, then you are not required to provide your password on the command line. See also Using .netrc for credentials.
-r, --runtime String (Private Cloud only) Specifies the runtime URL for your Private Cloud instance.
-t, --token String (Required for OAuth token authentication only) An OAuth or SAML token that you generate from your Apigee account information. For information on generating tokens, see Using get_token and Access the management API with SAML.
-u, --username String (Required for basic authentication only) Your Apigee username (typically an email address). You can optionally specify the username in a .netrc file. If you do so, then you are not required to provide your username on the command line. See also Using .netrc for credentials.
-v, --verbose (Optional) Produces verbose output.

Example

./apigee-remote-service-cli bindings remove httpbin.org envoy-test -o myorg -e test -u user@example.com -c config.yaml -p xxxxxx
product envoy-test is no longer bound to: httpbin.org

Verify a binding

Verify that the specifed bound API product and its associated developer apps also have a remote service product associated with them. If you do not specify an API product name, then the command checks all bound products.

Usage

For Edge Public Cloud:

apigee-remote-service-cli bindings verify [product_name]  -o [organization] -e [environment] -u [username] -p [password] -c [config]

For Edge Private Cloud:

apigee-remote-service-cli bindings verify [product_name]  -o [organization] -e [environment] -u [username] -p [password] -r [runtime] -c [config]

Where product_name is optional. If you do not specify a product name, all bound products are checked.

Parameters

Parameters Type Description
-c, --config String (Required) 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, --env String (Required) An environment in your organization.
-h, --help Displays help for the command parameters.
--insecure Allow insecure server connections when using SSL
--legacy Set this flag if you are using Apigee Edge Cloud. It sets the management and runtime URLs for Edge Cloud.
--mfa Apigee multi-factor authorization token (used with --legacy only)
--opdk Set this flag if you are using Apigee Edge for Private Cloud.
-o, --org String (Required) An Apigee organization. You must be an org administrator.
-r, --runtime String (Private Cloud only) Specifies the runtime URL for your Private Cloud instance.
-t, --token String (Required for OAuth token authentication only) An OAuth or SAML token that you generate from your Apigee account information. For information on generating tokens, see Using get_token and Access the management API with SAML.
-v, --verbose (Optional) Produces verbose output.

Example

./apigee-remote-service-cli bindings verify my-product -o myorg -e test -u user@example.com -c config.yaml -p xxxxxx
  app my-app associated with product my-product is verified

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 a proxy in your Apigee Edge organization, sets up a certificate, and generates credentials that you'll need to configure the Apigee Adapter for Envoy.

Usage

If you are on Edge Public Cloud:

apigee-remote-service-cli provision -o $ORG -e $ENV -u $USERNAME -p $PASSWORD

If you are on Edge Private Cloud:

apigee-remote-service-cli provision --opdk -o $ORG -e $ENV -u $USERNAME --management $MGMT_SERVER_URL -- runtime $RUNTIME_URL -p $PASSWORD

Parameters

Parameters Type Description
--analytics-sa String This flag is only available for Apigee hybrid and Apigee on Google Cloud installations.

Use this flag to specify the path to a Google Cloud service account key file, where the service account has the Apigee Analytics Agent role. The SA is used by the adapter to directly upload analytics data to Apigee. If you are using Apigee hybrid, this option allows you to install the hybrid runtime in one cluster and the adapter in another cluster.

-c, --config String Path to Apigee Remote Service config file. See also Using the --config option.
-e, --environment String (Required) An environment in your organization.
-f, --force-proxy-install (Optional) Forces the remote-service proxy to be re-installed if it is already installed in your org.
-h, --help Displays help for the command parameters.
-k, --key String Specifies the key returned from the apigee-remote-service-cli provision command.
--legacy Set this flag if you are using Apigee Edge Cloud. It sets the management and runtime URLs for Edge Cloud.
--mfa Apigee multi-factor authorization token (used with --legacy only)
-m, --management String (Required if you are on Apigee Private Cloud) Your Apigee management base URL. Default: https://api.enterprise.apigee.com
-n, --namespace String Emit configuration as an Envoy ConfigMap in the specified namespace. Default: apigee
--opdk String Apigee OPDK.
-o, --organization String (Required) Your Apigee organization. You must be an org administrator.
-p, --password String (Required for basic authentication only) Your Apigee password. You can optionally specify the password in a .netrc file. If you do so, then you are not required to provide your password on the command line. See also Using .netrc for credentials.
--rotate-int int If n > 0, generate new private key and keep n public keys (hybrid only)
-r, --runtime String (Private Cloud only) Specifies the runtime URL for your Private Cloud instance.
-s, --secret String Specifies the secret returned from the apigee-remote-service-cli provision command.
--strength int (Optional) Specifies the encryption strength for SSL certificates used in provisioning the adapter. Default 2048
-t, --token String (Hybrid only) Apigee OAuth or SAML token.
-u, --username String (Required for basic authentication only) Your Apigee username (typically an email address). You can optionally specify the username in a .netrc file. See also Using .netrc for credentials.
-v, --verbose (Optional) Produces verbose output.
--virtual-hosts String Overrides the default virtual hosts, which are default,secure. Use this option if you have virtual hosts specified for your Edge organization-environment other than these defaults. See the Edge documentation to learn about virtual hosts.
--years int (Optional) The number of years before the SSL certificate used in the provisioning expires. Default: 1

Example

Be sure to capture the output of the provision command in a file, which is used as input for other Apigee Adapter for Envoy operations.

Edge Public Cloud example:

apigee-remote-service-cli provision --legacy --mfa $MFA --username $USER --password $PASSWORD --organization $ORG --environment $ENV > config.yaml

Samples command

Creates sample configuration files for native Envoy or Istio deployments.

Usage

apigee-remote-service-cli samples create [flags]

Description

The command requires a valid config.yaml file 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 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 Type Description
-c, --config String (Required) 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 Force the existing directory to be overwritten.
-h, --help Displays help for the command parameters.
--host The target service host (default "httpbin.org")
-n, --name The target service name (default "httpbin")
--out Th directory in which to create the sample config files. Default: ./samples
-t, --template

The template name. If you're doing an Istio deployment (hybrid only), select one of the available Istio options. Use the native option for native Envoy deployments. Available options are:

  • istio-1.6 (Default)
  • istio-1.7
  • native
--tls The directory in which to store the TLS key and crt files.

Example

apigee-remote-service-cli samples create -c ./config.yaml

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

For Edge Public Cloud:
apigee-remote-service-cli token create -c [config_file] --id [consumer_key] --secret [consumer_secret] -o [org] -e [env]
For Edge Private Cloud:
apigee-remote-service-cli token create -c [config_file] --id [consumer_key] --secret [consumer_secret] -r [runtime] -o [org] -e [env]

Parameters

Parameters Type Description
-c, --config String (Required) 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, --env String (Required) An environment in your organization.
-h, --help Displays help for the command parameters.
--insecure Allow insecure server connections when using SSL.
-o, --org String (Required) An Apigee organization. You must be an org administrator.
-r, --runtime String (Private Cloud only) Specifies the runtime URL for your Private Cloud instance.
-v, --verbose (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

For Edge Public Cloud:
apigee-remote-service-cli token inspect -o [organization] -e [environment] -f [token_file]
For Edge Private Cloud:
apigee-remote-service-cli token inspect -o [organization] -e [environment] -f [token_file] --runtime [host_alias]

Parameters

Parameters Type Description
-c, --config String (Required) 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, --env String (Required) An environment in your organization.
-h, --help Displays help for the command parameters.
--insecure Allow insecure server connections when using SSL.
-o, --org String (Required) An Apigee organization. You must be an org administrator.
-r, --runtime String (Private Cloud only) Specifies the runtime URL for your Private Cloud instance.
-v, --verbose (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 Edge 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 Edge organization/environment. In addition, the old public key is retained along with its original key ID value.

Usage

If you are on Edge Public Cloud:
apigee-remote-service-cli token rotate-cert -c [config_file] -o [organization] -e [environment] -k [provision_key] -s [provision_secret] --kid [new_key_id]
If you are on Edge Private Cloud:
apigee-remote-service-cli token rotate-cert -o [organization] -e [environment] -u [username] -p [password] -k [provision_key] -s [provision_secret] --kid [new_key_id]

Parameters

Parameters Type Description
-c, --config String (Required) 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, --env String (Required) An environment in your organization.
-h, --help Displays help for the command parameters.
--insecure Allow insecure server connections when using SSL
--truncate int Number of certs to keep in jwks (default 2)
-o, --org String (Required) An Apigee organization. You must be an org administrator.
-r, --runtime String (Private Cloud only) Specifies the runtime URL for your Private Cloud instance.
-v, --verbose (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

Using .netrc for credentials

apigee-remote-service-cli automatically picks up the username and password (for basic authentication where needed) from a .netrc file in your home directory if you are on Edge Public Cloud and have an entry for the machine api.enterprise.apigee.com. If you are on Apigee Private Cloud, the machine value is the same as your management URL (for example: http://192.162.55.100). For example on Edge Public Cloud:
machine api.enterprise.apigee.com
login jdoe@google.com
password abc123
For example on Edge Private Cloud:
machine http://192.162.55.100
login jdoe@google.com
password abc123

Version command

Print the CLI version.

apigee-remote-service-cli version

Using the --config command option

The --config option specifies the location of the config file generated by the provision command. A helplful benefit of this option is that it allows you to skip most other command parameters, which the CLI pulls from the config file. These options include:
  • organization
  • environment
  • runtime
  • management
  • insecure
  • namespace
  • legacy
  • opdk

For example, you could execute the provision command like this:

apigee-remote-service-cli provision --config='old-config.yaml' > new-config.yaml

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
  allow_unverified_ssl_cert: false
products:
  refresh_rate: 2m
analytics:
  legacy_endpoint: false
  file_limit: 1024
  send_channel_size: 10
  collection_interval: 10s
  fluentd_endpoint: apigee-udca-myorg-test.apigee.svc.cluster.local:20001
  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
auth:
  api_key_claim: claim
  api_key_cache_duration: 30m
  api_key_header: x-api-key
  api_target_header: :authority
  reject_unauthorized: true
  jwks_poll_interval: 0s