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

CLI Reference

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