CLI Reference

You're viewing Apigee Edge documentation.
View Apigee X documentation.

Public and Private Cloud Deprecation Notice:

Support for Istio by integrating with Istio Mixer

In March this year, the Istio community announced deprecation for Istio Mixer. The Istio Mixer component is critical for the functioning of the Apigee adapter for Istio, which is why we redesigned the Istio adapter to use native Envoy filters (see envoy filter and HTTP filters) to integrate with Apigee.

Apigee announced the beta release of this feature in the API management for services that use Envoy blog post, in addition to the Apigee Adapter for Envoy overview.

Apigee recommends that you move your Istio Adapter setup to Apigee Adapter for Envoy as soon as possible. Moving to the Envoy adapter requires that you recreate your Istio Adapter setup from scratch. There is no other migration path.

The apigee-istio Command Line Interface (CLI) lets you control and manage the Apigee adapter.

Help command

Online help is provided for all apigee-istio commands. Just type:

apigee-istio help

For help on any command, type:

apigee-istio <command> help

For example:

apigee-istio provision help

Version command

Print the CLI version.

apigee-istio version

Provision command

Provisioning installs a proxy in your Apigee Edge organization, sets up a certificate, and generates credentials that you'll need to configure the Apigee adapter.

Usage

If you are on Edge Public Cloud:

apigee-istio provision -o [organization] -e [environment] -u [username] -p [password]

If you are on Edge Private Cloud:

apigee-istio provision -o [organization] -e [environment] -u [username] --managementBase [mgmt server url] -p [password]

Parameters

Parameters	Type	Description
`-o, --org`	String	(Required) Your Apigee organization. You must be an org administrator.
`-e, --env`	String	(Required) An environment in your organization.
`-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.
`-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.
`-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.
`-f, --forceProxyInstall`		(Optional) Forces the `istio-auth` proxy to be re-installed if it is already installed in your org.
`-h, --help`		Displays help for the command parameters.
`-k, --key`	String	(Required only when `--verifyOnly` is used) Specifies the key returned from the `apigee-istio provision` command, because `--verifyOnly` does not regenerate the key.
`-s, --secret`	String	(Required only when `--verifyOnly` is used) Specifies the secret returned from the `apigee-istio provision` command, because `--verifyOnly` does not regenerate the secret.
`--verifyOnly`		(Optional) Causes the command to execute without actually provisioning anything on Apigee Edge.
`-m, --managementBase`	String	(Required if you are on Apigee Private Cloud) Your Apigee management base URL. Default: `https://api.enterprise.apigee.com`
`-n, --netrc`	String	(Optional) Specifies the path to your `.netrc` file. Default: `$HOME/.netrc`. See also Using .netrc for credentials
`-r, --routerBase`	String	(Optional) Specifies the virtual host alias for your organization-environment. Default: `apigee.net`. See the Edge documentation to learn about virtual hosts.
`--strength`	int	(Optional) Specifies the encryption strength for SSL certificates used in provisioning the adapter. Default 2048
`-v, --verbose`		(Optional) Produces verbose output.
`--virtualHosts`	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

Examples

If you are on Edge Public Cloud:

apigee-istio provision -o docs -e test -u jdoe@example.com -p abc123

If you are on Edge Private Cloud:

apigee-istio provision -o docs -e test -u jdoe@example.com --managementBase http://192.162.55.100:8080

Output

On success, you'll see output similar to the following:

verifying internal proxy...
  ok: https://edgemicroservices.apigee.net/edgemicro/analytics/organization/myorg/environment/myenv
  ok: https://edgemicroservices.apigee.net/edgemicro/quotas/organization/myorg/environment/myenv
verifying customer proxy...
  ok: https://myorg-myenv.apigee.net/istio-auth/certs
  ok: https://myorg-myenv.apigee.net/istio-auth/products
  ok: https://myorg-myenv.apigee.net/istio-auth/verifyApiKey

# istio handler configuration for apigee adapter
apiVersion: config.istio.io/v1alpha2
kind: apigee
metadata:
  name: apigee-handler
  namespace: istio-system
spec:
  apigee_base: https://edgemicroservices.apigee.net/edgemicro
  customer_base: https://myorg-myenv.apigee.net/istio-auth
  org_name: myorg
  env_name: myenv
  key: 06a40b65005d03ea24c0d53de69ab795590b0c332526e97fed549471bdea00b9
  secret: 93550179f344150c6474956994e0943b3e93a3c90c64035f378dc05c98389633

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.

Add a binding

Bind an Istio service to an API product.

Usage

If you are on Edge Public Cloud:

apigee-istio bindings add [service_name] [product_name]  -o [organization] -e [environment] -u [username] -p [password]

If you are on Edge Private Cloud:

apigee-istio bindings add [service_name] [product_name]  -o [organization] -e [environment] -u [username] -p [password] --managementBase [mgmt server url] --routerBase [host alias]

Parameters

Parameters	Type	Description
`-o, --org`	String	(Required) An Apigee organization. You must be an org administrator.
`-e, --env`	String	(Required) An environment in your organization.
`-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.
`-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.
`-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.
`-m, --managementBase`	String	(Required if you are on Apigee Private Cloud) Your Apigee management base URL. Default: `https://api.enterprise.apigee.com`
`service_name`	String	(Required) The identifier for the service that you are binding. For example: `helloworld.default.svc.cluster.local`
`product_name`	String	(Required) The name of the API product to bind to. For example: `hello-istio-product`.
`-r, --routerBase`	String	(Optional) Specifies the virtual host alias for your organization-environment. Default: `apigee.net`. See the Edge documentation to learn about virtual hosts.
`-n, --netrc`	String	(Optional) Specifies the path to your `.netrc` file. Default: `$HOME/.netrc`. See also Using .netrc for credentials
`-v, --verbose`		(Optional) Produces verbose output.
`-h, --help`		Displays help for the command parameters.

Example

apigee-istio bindings add helloworld.default.svc.cluster.local hello-istio-product -o myorg -e test

Output

On success, you'll see output similar to the following:

product hello-istio-product is now bound to: helloworld.default.svc.cluster.local

List bindings

List all Istio service bindings.

Usage

If you are on Edge Public Cloud:

apigee-istio bindings list -o [organization] -e [environment] -u [username] -p [password]

If you are on Edge Private Cloud:

apigee-istio bindings list -o [organization] -e [environment] -u [username] -p [password] --managementBase [mgmt server url] --routerBase [host alias]

Parameters

Parameters	Type	Description
`-o, --org`	String	(Required) An Apigee organization. You must be an org administrator.
`-e, --env`	String	(Required) An environment in your organization.
`-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.
`-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.
`-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.
`-m, --managementBase`	String	(Required if you are on Apigee Private Cloud) Your Apigee management base URL. Default: `https://api.enterprise.apigee.com`
`-r, --routerBase`	String	(Optional) Specifies the virtual host alias for your organization-environment. Default: `apigee.net`. See the Edge documentation to learn about virtual hosts.
`-n, --netrc`	String	(Optional) Specifies the path to your `.netrc` file. Default: `$HOME/.netrc`. See also Using .netrc for credentials
`-v, --verbose`		(Optional) Produces verbose output.
`-h, --help`		Displays help for the command parameters.

Example

apigee-istio bindings list -o myorg -e test

Output

On success, you'll see output similar to the following, listing bound and unbound products in your organization:

API Products
============
Bound
-----
hello-istio-product:
  Quota: 5 requests every 1 minute
  Service bindings:
    helloworld.default.svc.cluster.local
  Paths:
    /

Unbound
-------
Generic Product:
streetcarts_product:
users:
  Quota: 50 requests every 1 minute
jdoe:

Remove binding

Remove the binding of an Istio service from an API product.

Usage

If you are on Edge Public Cloud:

apigee-istio bindings remove [service_name] [product_name] -o [organization] -e [environment] -u [username] -p [password]

If you are on Edge Private Cloud:

apigee-istio bindings remove [service_name] [product_name]  -o [organization] -e [environment] -u [username] -p [password] --managementBase [mgmt server url] --routerBase [host alias]

Parameters

Parameters	Type	Description
`-o, --org`	String	(Required) An Apigee organization. You must be an org administrator.
`-e, --env`	String	(Required) An environment in your organization.
`-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.
`-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.
`-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.
`-m, --managementBase`	String	(Required if you are on Apigee Private Cloud) Your Apigee management base URL. Default: `https://api.enterprise.apigee.com`
`service_name`	String	(Required) The identifier for the service that you are removing. For example: `helloworld.default.svc.cluster.local`
`product_name`	String	(Required) The name of the API product for which to remove the binding. For example: `hello-istio-product`.
`-r, --routerBase`	String	(Optional) Specifies the virtual host alias for your organization-environment. Default: `apigee.net`. See the Edge documentation to learn about virtual hosts.
`-n, --netrc`	String	(Optional) Specifies the path to your `.netrc` file. Default: `$HOME/.netrc`. See also Using .netrc for credentials
`-v, --verbose`		(Optional) Produces verbose output.
`-h, --help`		Displays help for the command parameters.

Example

apigee-istio bindings remove helloworld.default.svc.cluster.local hello-istio-product -o myorg -e test

Output

On success, you'll see output similar to the following:

product hello-istio-product is no longer bound to: helloworld.default.svc.cluster.local

Token commands

The token commands let you create, inspect, and rotate JWT tokens. See also Using JWT-based authentication.

Create a JWT token

You can use the token to make authenticated API calls to a service running in the Istio mesh that is bound to an API product. See also Using JWT-based authentication.

Usage

If you are on Edge Public Cloud:

apigee-istio token create -o [organization] -e [environment] -u [username] -p [password] -i [consumer_key] -s [consumer_secret]

If you are on Edge Private Cloud:

apigee-istio token create -o [organization] -e [environment] -u [username] -p [password] -i [consumer_key] -s [consumer_secret] --managementBase [mgmt server url] --routerBase [host alias]

Parameters

Parameters	Type	Description
`-o, --org`	String	(Required) An Apigee organization. You must be an org administrator.
`-e, --env`	String	(Required) An environment in your organization.
`-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.
`-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.
`-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.
`-m, --managementBase`	String	(Required if you are on Apigee Private Cloud) Your Apigee management base URL. Default: `https://api.enterprise.apigee.com`
`-i, --id`	String	(Required) The consumer key from the Developer App you created on Apigee Edge, as explained in Get an API key`.`
`-s, --secret`	String	(Required) The consumer secret from the Developer App you created on Apigee Edge, as explained in Get an API key`.`
`-r, --routerBase`	String	(Optional) Specifies the virtual host alias for your organization-environment. Default: `apigee.net`. See the Edge documentation to learn about virtual hosts.
`-n, --netrc`	String	(Optional) Specifies the path to your `.netrc` file. Default: `$HOME/.netrc`. See also Using .netrc for credentials.
`-v, --verbose`		(Optional) Produce verbose output.
`-h, --help`		Displays help for the command parameters.

Example

apigee-istio token create -o myorg -e test -i YUmlZAcBKNsTAelJqPZFl3sh58ObATX9 -s icTARgaKHqvUH1dq

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 Using JWT-based authentication.

Usage

If you are on Edge Public Cloud:

apigee-istio token inspect -o [organization] -e [environment] -u [username] -p [password] -f [token_file]

If you are on Edge Private Cloud:

apigee-istio token inspect -o [organization] -e [environment] -u [username] -p [password] -f [token_file] --managementBase [mgmt server url] --routerBase [host alias]

Parameters

Parameters	Type	Description
`-f, --file`	String	A file containing the token. Or, you can use standard input.
`-o, --org`	String	(Required) An Apigee organization. You must be an org administrator.
`-e, --env`	String	(Required) An environment in your organization.
`-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.
`-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.
`-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.
`-m, --managementBase`	String	(Required if you are on Apigee Private Cloud) Apigee management base. Default: `https://api.enterprise.apigee.com`
`-r, --routerBase`	String	(Optional) Specifies the virtual host alias for your organization-environment. Default: `apigee.net`. See the Edge documentation to learn about virtual hosts.
`-n, --netrc`	String	(Optional) Specifies the path to your .netrc file. Default: `$HOME/.netrc`. See also Using .netrc for credentials.
`-v, --verbose`		(Optional) Produces verbose output.
`-h, --help`		Displays help for the command parameters.

Example

apigee-istio token inspect -o myorg -e test -u jdoe@google.com -p abc123 -f ./mytoken

Output

On success, you'll see output similar to the following:

{
        "access_token": "eeiZQz07tdTot6VeZfv7HEv1BlSQ",
        "api_product_list": [
                "istio-product"
        ],
        "application_name": "istio-app",
        "aud": "istio",
        "client_id": "YUmlZAcBKNsTAelKqPYFl3sh58ObATX9",
        "developer_email": "jdoe@google.com",
        "exp": 1530150142,
        "iat": 1530339242,
        "iss": "https://apigeesearch-test.apigee.net/istio-auth/token",
        "jti": "e8a0eb3f-395a-4f90-8446-b1b015986cb1",
        "nbf": 1530339242
}

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-istio token rotate-cert -o [organization] -e [environment] -u [username] -p [password] -k [provision_key] -s [provision_secret] --kid [new_key_id]

If you are on Edge Private Cloud:

apigee-istio token rotate-cert -o [organization] -e [environment] -u [username] -p [password] -k [provision_key] -s [provision_secret] --kid [new_key_id] --managementBase [mgmt server url] --routerBase [host alias]

Parameters

Parameters	Type	Description
`-k, --key`	String	(Required) The secret value you obtained when you provisioned the Apigee adapter.
`--kid`	String	(Optional) The new key id (default "1")
`-s, --secret`	String	(Required) The secret value you obtained when you provisioned the Apigee adapter.
`--strength`	int	(Optional) Specifies the encryption strength for SSL certificates used in provisioning the adapter. Default 2048
`--years`	int	(Optional) The number of years before the SSL certificate used in the provisioning expires. Default: 1
`-o, --org`	String	(Required) An Apigee organization. You must be an org administrator.
`-e, --env`	String	(Required) An environment in your organization.
`-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.
`-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.
`-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.
`-m, --managementBase`	String	(Required if you are on Apigee Private Cloud) Apigee management base. Default: `https://api.enterprise.apigee.com`
`-r, --routerBase`	String	(Optional) Specifies the virtual host alias for your organization-environment. Default: `apigee.net`. See the Edge documentation to learn about virtual hosts.
`-n, --netrc`	String	(Optional) Specifies the path to your .netrc file. Default: `$HOME/.netrc`. See also Using .netrc for credentials
`-v, --verbose`		(Optional) Produces verbose output.
`-h, --help`		Displays help for the command parameters.

Example

apigee-istio token rotate-cert -o myorg -e test -u jdoe@google.com -k 2e238ffa15dc5ab6a1e97868e7581f6c60ddb8575478582c256d8b7e5b2677a8 -s 51058077223fa7b683c3bea845c5cca138340d1d5583922b6d465f9f918a4b08 --kid 2

Output

certificate successfully rotated

Using .netrc for credentials

apigee-istio 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 managementBase 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