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