Referência

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

A interface de linha de comando (CLI) apigee-remote-service-cli ajuda você a provisionar e gerenciar o adaptador da Apigee para Envoy.

Como vincular comandos

A vinculação associa um serviço implantado na malha do Istio a um produto da API da Apigee. A CLI permite criar, remover, listar e verificar vinculações.

Listar vinculações

Lista todos os produtos de API que estão vinculados ao serviço remoto.

Uso

Para a Apigee híbrida:

apigee-remote-service-cli bindings list -o [organization] -e [environment] -t [token] -r [runtime]

Parâmetros

Parâmetros Tipo Descrição
-c, --config String (Obrigatório) O caminho do arquivo de configuração do serviço remoto da Apigee.
Dica: essa sinalização permite omitir a maioria dos outros parâmetros de comando, porque a CLI é capaz de extraí-los diretamente do arquivo de configuração. Consulte Como usar a opção --config.
-e, --env String (Obrigatório) Um ambiente na organização.
-h, --help Exibe a ajuda dos parâmetros de comando.
--insecure Permite conexões de servidor não seguras ao usar SSL.
--legacy Defina essa sinalização se você estiver usando o Apigee Cloud.s Ela define os URLs de gerenciamento e ambiente de execução para o Edge Cloud.
--opdk Defina essa sinalização se você estiver usando a Apigee para nuvem privada.
-o, --org String (Obrigatório) Uma organização da Apigee. Você precisa ser um administrador da organização.
-p, --password String (Obrigatório apenas para autenticação básica. Não disponível para Apigee híbrida.) Sua senha da Apigee. Também é possível especificar a senha em um arquivo .netrc. Se fizer isso, você não precisará inserir sua senha na linha de comando. Consulte também Como usar o .netrc para credenciais.
-r, --runtime String Um URL que inclui o hostAlias de um host virtual definido na configuração híbrida. O URL precisa começar com https://. Por exemplo: https://apitest.apigee-hybrid-docs.net
-t, --token String (Obrigatório) Um token de acesso.
-u, --username String (Obrigatório apenas para autenticação básica. Não disponível para Apigee híbrida.) Nome de usuário da Apigee, normalmente um endereço de e-mail. Também é possível especificar o nome de usuário em um arquivo .netrc. Se fizer isso, você não precisará inserir seu nome de usuário na linha de comando. Consulte também Como usar o .netrc para credenciais.
-v, --verbose (Opcional) Gera uma saída detalhada.

Exemplo

apigee-remote-service-cli bindings list -o myorg -e test -c config.yaml \
-r $RUNTIME -t $TOKEN
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:

Verificar uma vinculação

Esse comando está obsoleto. Na versão 1.4, os apps de desenvolvedores não exigem mais uma associação com produtos de API usados com destinos de serviço remotos.

Comando de ajuda

A ajuda on-line está disponível para todos os comandos apigee-remote-service-cli. Basta digitar:

apigee-remote-service-cli help

Para receber ajuda sobre qualquer comando. Digite:

apigee-remote-service-cli [command] help

Exemplo:

apigee-remote-service-cli provision help

Comando de provisionamento

O comando apigee-remote-service-cli provision instala um proxy na sua organização do Apigee Edge, configura um certificado e gera as credenciais necessárias para configurar o adaptador da Apigee para Envoy.

Uso

Para a Apigee híbrida:

apigee-remote-service-cli provision  -o $ORG -e $ENV -r $RUNTIME -t $TOKEN

Parâmetros

Parâmetros Tipo Descrição
--analytics-sa String Use essa sinalização para especificar o caminho para um arquivo de chave da conta de serviço do Google Cloud, em que a conta de serviço tem o papel Apigee Analytics Agent. O SA é usado pelo adaptador para fazer o upload direto dos dados de análise para a Apigee. Se você estiver usando a Apigee híbrida, essa opção permite instalar o ambiente de execução híbrido em um cluster e o adaptador em outro cluster. Essa sinalização está disponível apenas para instalações da Apigee híbrida e da Apigee no Google Cloud.
-c, --config String Caminho para o arquivo de configuração do serviço remoto da Apigee. Consulte também Como usar a opção --config.
-e, --environment String (Obrigatório) Um ambiente na organização.
-f, --force-proxy-install (Opcional) Força o proxy remote-service a ser reinstalado se já estiver instalado na sua organização.
-h, --help Exibe a ajuda dos parâmetros de comando.
-k, --key String Especifica a chave retornada do comando apigee-remote-service-cli provision.
--legacy Edge da Apigee (define o URL de gerenciamento e ambiente de execução)
-m, --management String (Obrigatório se você estiver na nuvem privada da Apigee) Seu URL base de gerenciamento da Apigee. Padrão: https://api.enterprise.apigee.com
-n, --namespace String Emite a configuração como um ConfigMap do Envoy no namespace especificado. Padrão: apigee
--opdk String Defina essa sinalização se você estiver usando a Apigee para nuvem privada.
-o, --organization String

(Obrigatório) Sua organização da Apigee.

-p, --password String (Obrigatório apenas para autenticação básica. Não disponível para Apigee híbrida.) Sua senha da Apigee. Também é possível especificar a senha em um arquivo .netrc. Se fizer isso, você não precisará inserir sua senha na linha de comando. Consulte também Como usar o .netrc para credenciais.
--rotate-int int Se n for maior que 0, gere uma nova chave privada e mantenha n chaves públicas (somente Apigee híbrida)
-r, --runtime String Um URL que inclui o hostAlias de um host virtual definido na configuração híbrida. O URL precisa começar com https://. Por exemplo: https://apitest.apigee-hybrid-docs.net
-s, --secret String Especifica o secret retornado do comando apigee-remote-service-cli provision.
--strength int (Opcional) Especifica a força da criptografia dos certificados SSL usados no provisionamento do adaptador. Padrão 2048
-t, --token String Token OAuth ou SAML da Apigee.
-u, --username String (Obrigatório apenas para autenticação básica. Não disponível para Apigee híbrida.) Nome de usuário da Apigee, normalmente um endereço de e-mail. Também é possível especificar o nome de usuário em um arquivo .netrc. Consulte também Como usar .netrc para credenciais.
-v, --verbose (Opcional) Gera uma saída detalhada.
--virtual-hosts String Modifica os hosts virtuais padrão.
--years int (Opcional) O número de anos para o certificado SSL usado no provisionamento expirar. Padrão: 1

Exemplo

Capture a resposta ao comando provision em um arquivo, que é usado como entrada para outras operações do adaptador da Apigee do Envoy.

Exemplo da Apigee híbrida:

apigee-remote-service-cli provision --organization $ORG --environment $ENV --runtime $RUNTIME \
--namespace $NAMESPACE --token $TOKEN > config.yaml

Comandos de amostra

Criar um arquivo de configuração de amostra

Cria arquivos de configuração de amostra para implantações nativas do Envoy ou do Istio.

Uso

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

Descrição

O comando requer um arquivo config.yaml válido gerado por meio do provisionamento. Por padrão, os arquivos de amostra são gravados em um diretório chamado ./samples. O comando cria esse diretório para você.

Se você estiver usando o Envoy nativo, o comando usará o host do serviço de destino e o nome desejado no cluster dele. Ele também define a conexão SSL personalizada do proxy Envoy como o cluster do serviço remoto, se uma pasta contendo tls.key e tls.crt for especificada em --tls.

Se você estiver usando o Istio, em que o proxy Envoy funciona como um arquivo secundário, se o destino não for especificado, o exemplo de httpbin será gerado. Caso contrário, você será responsável por preparar os arquivos de configuração relacionados à implantação dos serviços de destino.

Parâmetros

Parâmetros Tipo Descrição
-c, --config String (Obrigatório) Caminho para o arquivo de configuração do serviço remoto da Apigee.
Dica: essa sinalização permite omitir a maioria dos outros parâmetros de comando, porque a CLI é capaz de extraí-los diretamente do arquivo de configuração. Consulte Como usar a opção --config.
-f, --force Força a substituição do diretório atual.
-h, --help Exibe a ajuda dos parâmetros de comando.
--host O host do serviço de destino (padrão "httpbin.org")
-n, --name O nome do serviço de destino (padrão é "httpbin")
--out O diretório em que os arquivos de configuração de amostra serão criados. Padrão: ./samples
-t, --template

O nome do modelo. Se você estiver fazendo uma implantação do Istio (somente Apigee híbrida), selecione uma das opções do Istio disponíveis. Use a opção nativa para implantações nativas do Envoy. Veja a seguir as opções disponíveis:

  • istio-1.6 (padrão)
  • istio-1.7
  • native
--tls O diretório em que serão armazenados os arquivos crt e de chave TLS.

Exemplo

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

Listar opções de modelo disponíveis

Lista as opções disponíveis para usar com o parâmetro --templates.

Uso

apigee-remote-service-cli samples templates

Parâmetros

Nenhuma.

Exemplo

apigee-remote-service-cli samples templates
Supported templates (native is deprecated):
  envoy-1.14
  envoy-1.15
  envoy-1.16
  istio-1.5
  istio-1.6
  istio-1.7
  istio-1.8
  native

Comandos de token

É possível usar um token JWT para fazer chamadas de proxy de API autenticadas, em vez de usar uma chave de API. Os comandos de token permitem criar, inspecionar e fazer a rotação de tokens JWT para essa finalidade.

Criar um token JWT

É possível usar um token JWT para fazer chamadas de proxy de API autenticadas a um destino de serviço remoto. Consulte também Como usar a autenticação baseada em JWT.

Uso

Para a Apigee híbrida:
apigee-remote-service-cli token create -c [config_file] --id [consumer_key] --secret [consumer_secret] -r [runtime] -o [org] -e [env]

Parâmetros

Parâmetros Tipo Descrição
-c, --config String (Obrigatório) O caminho do arquivo de configuração do serviço remoto da Apigee.
Dica: essa sinalização permite omitir a maioria dos outros parâmetros de comando, porque a CLI é capaz de extraí-los diretamente do arquivo de configuração. Consulte Como usar a opção --config.
-e, --env String (Obrigatório) Um ambiente na organização.
-h, --help Exibe a ajuda dos parâmetros de comando.
--insecure Permite conexões de servidor não seguras ao usar SSL.
-o, --org String (Obrigatório) Uma organização da Apigee. Você precisa ser um administrador da organização.
-r, --runtime String Um URL que inclui o hostAlias de um host virtual definido na configuração híbrida. O URL precisa começar com https://. Por exemplo: https://apitest.apigee-hybrid-docs.net
-v, --verbose (Opcional) Gera uma saída detalhada.

Exemplo

./apigee-remote-service-cli token create -o $ORG -e $ENV -i YUmlZAcBKNsTAelJqPZFl3sh58ObATX9 \
-s icTARgaKHqvUH1dq -c config.yaml -r $RUNTIME -t $TOKEN

Saída

Em caso de êxito, você verá uma saída de token JST semelhante a esta:
eyJraWQiOiIxIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.eyJhY2Nlc3NfdG9rZW4iOiJ0a2tlVzVKQTY2a0pZYTB4bFV1cVBsUW1BMU43IiwiYXVkIjoiaXN0aW8iLCJuYmYiOjE1MzAxMzg1OTEsImFwaV9wcm9kdWN0X2xpc3QiOlsiaXN0aW8tcHJvZHVjdCJdLCJhcHBsaWNhdGlvbl9uYW1lIjoiaXN0aW8tYXBwIiwiZGV2ZWxvcGVyX2VtYWlsIjoicFluZ2Zsb3lkQGdvb2dsZS5jb20iLCJpc3MiOiJodHRwczovL2FwaWdlZXNlYXJjaC10ZXN0LmFwaWdlZS5uZXQvaXN0aW8tYXV0aC90b2tlbiIsImV4cCI6MTUzMDEzOTQ5MSwiaWF0IjoxNTMwMTM4NTkxLCJqdGkiOiIxODgzMzViZi0wMmE4LTRjZGUsOGFkOS0yMWJmNDZjNmRjZDkiLCJjbGllbnRfaWQiOiJZVW1sWkFjQktOc1RBZWxKcVBZRmwzc2g1OE9iQVRYOSJ9.AL7pKSTmond-NSPRNNHVbIzTdAnZjOXcjQ-BbOJ_8lsQvF7PuiOUrGIhY5XTcJusisKgbCdtIxBl8Wq1EiQ_fKnUc3JYYOqzpTB5bGoFy0Yqbfu96dneuWyzgZnoQBkqwZkbQTIg7WNTGx1TJX-UTePvBPxAefiAbaEUcigX9tTsXPoRJZOTrm7IOeKpxpB_gQYkxQtV1_NbERxjTPyMbHdMWal9_xRVzSt7mpTGudMN9OR-VtQ1uXA67GOqhZWcOzq57qImOiCMbaoKnKUADevyWjX_VscN5ZZUtzQUQhTrmv8aR69-uVhMIPKp9juMyYKaYn2IsYZEeCWfhfV45Q

Inspecionar um token JWT

É possível inspecionar um token JWT com esse comando. Consulte também Inspecionar um token.

Uso

Para a Apigee híbrida:
apigee-remote-service-cli token inspect -o [organization] -e [environment] -f [token_file] --runtime [host_alias]

Parâmetros

Parâmetros Tipo Descrição
-c, --config String (Obrigatório) O caminho do arquivo de configuração do serviço remoto da Apigee.
Dica: essa sinalização permite omitir a maioria dos outros parâmetros de comando, porque a CLI é capaz de extraí-los diretamente do arquivo de configuração. Consulte Como usar a opção --config.
-e, --env String (Obrigatório) Um ambiente na organização.
-h, --help Exibe a ajuda dos parâmetros de comando.
--insecure Permite conexões de servidor não seguras ao usar SSL.
-o, --org String (Obrigatório) Uma organização da Apigee. Você precisa ser um administrador da organização.
-r, --runtime String Um URL que inclui o hostAlias de um host virtual definido na configuração híbrida. O URL precisa começar com https://. Por exemplo: https://apitest.apigee-hybrid-docs.net
-v, --verbose (Opcional) Gera uma saída detalhada.

Exemplo

apigee-remote-service-cli token inspect -c config.yaml <<< $TOKEN

Saída

Em caso de êxito, você verá uma saída semelhante a esta:
{
	"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.

Fazer a rotação de um token JWT

Em algum momento depois de gerar um JWT inicial, talvez seja necessário alterar o par de chaves pública/privada armazenado pela Apigee no mapa de chave-valor (KVM, na sigla em inglês) criptografado. Esse processo de geração de um novo par de chaves é chamado de rotação de chaves. Quando você faz a rotação, um novo par de chaves privada/pública é gerado e armazenado na KVM "istio" na organização/ambiente da Apigee. Além disso, a chave pública antiga é mantida com seu valor de ID de chave original.

Uso

Para a Apigee híbrida

apigee-remote-service-cli token rotate-cert -o [organization] -e [environment] -t [token] -r [runtime] -k [provision_key] -s [provision_secret] --kid [new_key_id]

Parâmetros

Parâmetros Tipo Descrição
-c, --config String (Obrigatório) O caminho do arquivo de configuração do serviço remoto da Apigee.
Dica: essa sinalização permite omitir a maioria dos outros parâmetros de comando, porque a CLI é capaz de extraí-los diretamente do arquivo de configuração. Consulte Como usar a opção --config.
-e, --env String (Obrigatório) Um ambiente na organização.
-h, --help Exibe a ajuda dos parâmetros de comando.
--insecure Permite conexões de servidor não seguras ao usar SSL.
--truncate int Número de certificados que serão mantidos em jwks (padrão 2)
-o, --org String (Obrigatório) Uma organização da Apigee. Você precisa ser um administrador da organização.
-r, --runtime String Um URL que inclui o hostAlias de um host virtual definido na configuração híbrida. O URL precisa começar com https://. Por exemplo: https://apitest.apigee-hybrid-docs.net
-v, --verbose (Opcional) Gera uma saída detalhada.

Exemplo

./apigee-remote-service-cli token create -o $ORG -e $ENV -i YUmlZAcBKNsTAelJqPZFl3sh58ObATX9 \
-s icTARgaKHqvUH1dq -c config.yaml -r $RUNTIME -t $TOKEN

Saída

certificate successfully rotated

Como usar .netrc para credenciais

apigee-remote-service-cli extrai automaticamente o username e o password (para autenticação básica, quando necessário) de um arquivo .netrc no seu diretório principal, se você estiver na nuvem pública do Edge e tiver uma entrada para a máquina api.enterprise.apigee.com. Se você estiver na nuvem privada da Apigee, o valor da máquina será o mesmo que seu URL management. Por exemplo: http://192.162.55.100. Por exemplo, na nuvem pública do Edge:
machine api.enterprise.apigee.com
login jdoe@google.com
password abc123
Por exemplo, na nuvem privada do Edge:
machine http://192.162.55.100
login jdoe@google.com
password abc123

Comando de versão

Imprima a versão da CLI.

apigee-remote-service-cli version

Como usar a opção de comando --config

A opção --config especifica a localização do arquivo de configuração gerado pelo comando provision. Uma vantagem útil dessa opção é a possibilidade de ignorar a maioria dos outros parâmetros de comando, que a CLI extrai do arquivo de configuração. As opções incluem:
  • organização
  • ambiente
  • runtime
  • management
  • insecure
  • namespace
  • legacy
  • opdk

Por exemplo, execute o comando provision da seguinte maneira:

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

Arquivo de configuração

Nesta seção, mostramos um exemplo de arquivo de configuração com todas as opções disponíveis.

global:
  temp_dir: /tmp/apigee-istio
  keep_alive_max_connection_age: 1m
  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
  jwt_provider_key: https://org-test.apigee.net/remote-service/token