Reference

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.

Binding commands

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

Note: In the Create Product UI, you can specify one or more services with a product. Doing so is equivalent to creating the binding using the CLI.

Add a binding

Adds a remote target binding to an API product.

Usage

For Apigee hybrid:

apigee-remote-service-cli bindings add [service_name] [product_name]  -o [organization] -e [environment] -t [token]

Parameters

Parameters	Type	Description
`-c, --config`	String	(Required) The path to the Apigee Remote Service config file. Tip: When you specify this option, you can omit most other command parameters. 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 Cloud. It sets the management and runtime URLs for Edge Cloud.
`--opdk`		Set this flag if you are using Apigee 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	Apigee runtime base URL (required for hybrid or opdk).
`-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 Obtaining an OAuth 2.0 access token and SAML overview.
`-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

Parameters

Parameters	Type	Description
`-c, --config`	String	(Required) The path to the Apigee Remote Service config file. Tip: When you specify this option, you can omit most other command parameters. 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 Cloud. It sets the management and runtime URLs for Edge Cloud.
`--opdk`		Set this flag if you are using Apigee 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	Apigee runtime base URL (required for hybrid or opdk).
`-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 Obtaining an OAuth 2.0 access token and SAML overview.
`-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.

Note: You can also remove a Remote Service for Envoy binding by removing the service name from the product in the UI.

Usage

For Apigee hybrid:

apigee-remote-service-cli bindings remove [service_name] [product_name]  -o [organization] -e [environment] -t [token]

Parameters

Parameters	Type	Description
`-c, --config`	String	(Required) The path to the Apigee Remote Service config file. Tip: When you specify this option, you can omit most other command parameters. 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 Cloud. It sets the management and runtime URLs for Edge Cloud.
`--opdk`		Set this flag if you are using Apigee 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	Apigee runtime base URL (required for hybrid or opdk).
`-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 Obtaining an OAuth 2.0 access token and SAML overview.
`-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

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

Usage

Parameters

Parameters	Type	Description
`-c, --config`	String	Path to Apigee Remote Service config file. Tip: When you specify this option, you can omit most other command parameters. See 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. UPGRADE NOTE: If you are upgrading to v1.0-beta.4 or a later version, you must include the `--force-proxy-install` flag to replace the existing remote service proxy deployed on Apigee.
`-h, --help`		Displays help for the command parameters.
`-k, --key`	String	Specifies the key returned from the `apigee-remote-service-cli provision` command.
`--legacy`		Apigee Edge (sets management and runtime URL)
`-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.
`--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	Apigee runtime base URL (required for hybrid or opdk)
`-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.
`--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.

Apigee hybrid example:

apigee-remote-service-cli provision --organization $ORG --environment $ENV --runtime $RUNTIME --namespace $NAMESPACE --token $TOKEN > 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 Apigee hybrid:

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: When you specify this option, you can omit most other command parameters. 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	Apigee runtime base URL (required only for hybrid or opdk).
`-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 Apigee hybrid:

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: When you specify this option, you can omit most other command parameters. 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	Apigee runtime base URL (required only for hybrid or opdk).
`-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 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

Parameters

Parameters	Type	Description
`-c, --config`	String	(Required) The path to the Apigee Remote Service config file. Tip: When you specify this option, you can omit most other command parameters. 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	Apigee runtime base URL (required for hybrid or opdk).
`-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 Apigee 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).

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

Reference

Binding commands

Add a binding

Usage

Parameters

Example

List bindings

Usage

Parameters

Example

Remove a binding

Usage

Parameters

Example

Help command

Provision command

Usage

Parameters

Example

Token commands

Create a JWT token

Usage

Parameters

Example

Output

Inspect a JWT token

Usage

Parameters

Example

Output

Rotate a JWT token

Usage

Parameters

Example

Output

Using .netrc for credentials

Version command

Using the --config command option

Configuration file

Using the `--config` command option