Você está vendo a documentação do Apigee Edge.
Acesse a
documentação da Apigee X. informações
Neste tópico, explicamos como executar o Edge Microgateway em um contêiner do Docker. As etapas abordadas neste tópico pressupõem um conhecimento básico do Docker, dos comandos do Docker e da configuração e configuração do Edge Microgateway. Para mais informações, consulte a documentação do Docker e do Edge Microgateway.
Pré-requisitos
Antes de executar o Edge Microgateway em um contêiner do Docker, é preciso realizar as seguintes tarefas:
Configure o Edge Microgateway para seu ambiente/organização da Apigee:
edgemicro configure -o your_org -e your_env -u your_username
Para mais detalhes sobre a configuração, consulte a Parte 1: configurar o Edge Microgateway.
Após executar as etapas de configuração, localize o arquivo de configuração. O local padrão é este:
$HOME/.edgemicro/your_org-your_env-config.yaml
em que
your_org
eyour_env
são a organização e o ambiente usados ao executar o comandoedgemicro config
. Você precisará desse arquivo ao iniciar o Edge Microgateway em um contêiner do Docker.Verifique se você tem as credenciais de chave e secret que foram retornadas quando você executou o comando
edgemicro config
. Exemplo:The following credentials are required to start edge micro key: d9c34e1aff68ed969273c016699eabf48780e4f652242e72fc88a43e21252cb0 secret: 3bc95a71c86a3c8ce04537fbcb788158731t51dfc6cdec13b7c05aa0bd969430
Antes de iniciar o Edge Microgateway em um contêiner do Docker, você precisa criar ou criar as entidades do Apigee Edge necessárias para fazer chamadas de proxy de API autenticadas. Essas entidades incluem um proxy com reconhecimento do Edge Microgateway, um produto da API, um desenvolvedor e um app de desenvolvedor. Para instruções completas, consulte Criar entidades no Apigee Edge.
Executar o Edge Micro como um contêiner do Docker
Faça o download da imagem do Docker para o Edge Microgateway:
docker pull gcr.io/apigee-microgateway/edgemicro:latest
Antes de prosseguir para as próximas etapas, verifique se você realizou todas as etapas da seção Pré-requisitos.
Execute o seguinte comando para codificar em base64 o arquivo de configuração do Edge Microgateway localizado em
$HOME/.edgemicro
:export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/your_org-your_env-config.yaml`
em que
your_org
eyour_env
são a organização e o ambiente usados ao executar o comandoedgemicro config
.Lembre-se de colocar crases (`) ao redor do comando. Exemplo:
export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/docs-test-config.yaml`
Execute o Edge Microgateway como um contêiner. O comando define várias variáveis de ambiente usadas pelo ambiente de execução do contêiner para iniciar o Edge Microgateway:
chown -R 100:101 ~/.edgemicro/ \ docker run -P -p 8000:8000 -d --name edgemicro \ -v /var/tmp:/opt/apigee/logs \ -e EDGEMICRO_PROCESSES=1 \ -e EDGEMICRO_ORG=your_org \ -e EDGEMICRO_ENV=your_env \ -e EDGEMICRO_KEY=your_key \ -e EDGEMICRO_SECRET=your_secret \ -e "EDGEMICRO_CONFIG=$EDGEMICRO_CONFIG" \ -e "LOG_CONSOLE_OUTPUT_TO_FILE=false" \ -e SERVICE_NAME=edgemicro \ --security-opt=no-new-privileges \ --cap-drop=ALL \ gcr.io/apigee-microgateway/edgemicro:latest
Parâmetros
<tr> <td><code>SERVICE_NAME</code></td> <td>If you are on Kubernetes, this parameter is auto-populated. Otherwise, you can set it to anything you wish. If you specify nothing, the service name is set to <code>default</code>.</td> </tr> <tr> <tr> <td><code>DEBUG</code></td> <td>Set to <code>*</code> to enable debugging. </td> </tr> <tr> <td><code>HTTP_PROXY</code> <code>HTTPS_PROXY</code></td> <td>Use when Edge Microgateway is running behind a firewall and the gateway cannot communicate with Apigee Edge. For more information, see <a href="operation-and-configuration-reference-edge-microgateway#settingupedgemicrogatewaybehindacompanyfirewall">Setting up Edge Microgateway behind a company firewall</a>. <p>For example: <code>HTTP_PROXY=http://10.203.0.1:5187/</code></p></td> </tr> <tr> <td><code>NO_PROXY</code></td> <td>A comma delimited list of domains that Edge Microgateway should not proxy to. For more information, see <a href="operation-and-configuration-reference-edge-microgateway#settingupedgemicrogatewaybehindacompanyfirewall">Setting up Edge Microgateway behind a company firewall</a>. <p>For example: <code>localhost,127.0.0.1,localaddress,.localdomain.com</code></p></td> </tr> <tr> <tr> <tr> <td><code>NODE_EXTRA_CA_CERTS</code></td> <td>(Optional) Use this parameter if you are using a CA that's not trusted by default by Node.js. Set the value of this parameter to the path to a file containing one or more trusted certificates in PEM format. For details, see <a href="#tls_certificates">TLS certificates</a>.</td> </tr> <tr> <td><code>--security-opt</code></td> <td>(Optional) Sets desired Docker security options. See <a href="https://docs.docker.com/engine/reference/run/#security-configuration">Security configuration</a> in the Docker documentation.</td> </tr> <tr> <td><code>--cap-drop</code></td> <td>(Optional) Sets limits on Linux capabilities permitted in the container. See <a href="https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities">Runtime privilege and Linux capabilities</a> in the Docker documentation.</td> </tr> </tbody>
Parâmetro Descrição -P
Publique todas as portas expostas no host. Consulte também a referência de execução do Docker. -p
Mapear explicitamente uma única porta ou intervalo de portas. Consulte também a referência de execução do Docker. -d
Executar no modo independente. Consulte também a referência de execução do Docker. -v, -- volume
Especifica uma montagem de volume. Se você configurar o Edge Microgateway para usar o TLS no contêiner do Docker, precisará expor a porta 8443 se ativar o diretório do arquivo de registros. Veja também VOLUME [sistemas de arquivos compartilhados]. Consulte também Como usar TLS no contêiner do Docker. -w, -- workdir
(Opcional) Especifica o caminho para o diretório em que os arquivos edgemicro.sock
eedgemicro.pid
precisam ser criados. Não é possível modificar a raiz do nome de arquivoedgemicro
. O padrão é o caminho do diretório de trabalho atual.Exemplo:
docker run -P -p 8000:8000 -d -w /tmp --name edgemicro
...EDGEMICRO_ORG
O nome da organização da Apigee que você usou para configurar o Edge Microgateway. EDGEMICRO_ENV
O nome do ambiente da Apigee que você usou para configurar o Edge Microgateway. EDGEMICRO_PROCESSES
O número de processos a serem iniciados. EDGEMICRO_KEY
A chave retornada quando você configurou o Edge Microgateway. EDGEMICRO_SECRET
O secret retornado quando você configurou o Edge Microgateway. EDGEMICRO_CONFIG
Uma variável que contém o arquivo de configuração do Edge Microgateway codificado em base64. LOG_CONSOLE_OUTPUT_TO_FILE
(Booleano) Permite especificar para onde a saída do registro é enviada. Consulte Como especificar opções de arquivo de registro. Exemplo:
chown -R 100:101 ~/.edgemicro/
docker run -P -p 8000:8000 -d --name edgemicro
-v /var/tmp:/opt/apigee/logs
-e EDGEMICRO_PROCESS=1
-e EDGEMICRO_ORG=docs
-e EDGEMICRO_ENV=test
-e EDGEMICRO_KEY=d9c34e1aff68ed969273b016699eabf48780e4f652242e72fc88a23e21252cb0
-e EDGEMICRO_SECRET=3bc95a71c86a3c8ce04137fbcb788158731t51dfc6cdec13b7c05aa0bd969430
-e "EDGEMICRO_CONFIG=$EDGEMICRO_CONFIG"
-e SERVICE_NAME=edgemicro
--security-opt=no-new-privileges
--cap-drop=ALL
gcr.io/apigee-microgateway/edgemicroPara verificar se o contêiner está em execução:
docker ps
A resposta será semelhante a esta:
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 8b92e082ea9c edgemicro "/tmp/entrypoint.sh" 12 minutes ago Up 12 minutes 0.0.0.0:8000->8000/tcp, 0.0.0.0:32775->8443/tcp edgemicro
Como especificar opções de saída do arquivo de registros
Com o parâmetro de configuração to_console do Edge Microgateway, é possível enviar informações de registro para a saída padrão, e não para um arquivo de registros. Se você seguir as etapas para executar o Edge Microgateway em um contêiner do Docker, o contêiner por padrão redirecionará stdout e saída de erro para um arquivo localizado no contêiner no local:
${APIGEE_ROOT}/logs/edgemicro.log
.Para evitar que informações de registro sejam enviadas para
edgemicro.log
, use a variávelLOG_CONSOLE_OUTPUT_TO_FILE
ao executar o contêiner.A tabela a seguir descreve o comportamento de saída do registro quando você usa
LOG_CONSOLE_OUTPUT_TO_FILE
comto_console
:to_console: true
LOG_CONSOLE_OUTPUT_TO_FILE=false
- Nenhum registro será enviado para o arquivo de registros do Edge Microgateway, conforme descrito em Como gerenciar arquivos de registro.
- Os registros não serão enviados para o arquivo
edgemicro.log
.
to_console: true
LOG_CONSOLE_OUTPUT_TO_FILE=true
- Nenhum registro será enviado para o arquivo de registros do Edge Microgateway, conforme descrito em Como gerenciar arquivos de registro.
- Os registros serão enviados para o arquivo
edgemicro.log
.
to_console: false
LOG_CONSOLE_OUTPUT_TO_FILE=true
- Os registros serão enviados para o arquivo de registro do Edge Microgateway, conforme descrito em Como gerenciar arquivos de registro.
- Os registros serão enviados para o arquivo
edgemicro.log
.
Como testar uma chamada de API
Depois de iniciar o Edge Microgateway no contêiner, você poderá fazer chamadas de API para ele. Por exemplo, se o caminho base da sua API for
/hello
:http://localhost:8000/hello
Exemplo de resposta:
{"error":"missing_authorization","error_description":"Missing Authorization header"}
Se você receber essa resposta, significa que o Edge Microgateway lidou com a chamada de API. No entanto, por padrão, o Edge Microgateway exige uma chave de API para autenticação. Na próxima seção, você vai testar a API com uma chave de API válida.
Testar uma API com uma chave de API válida
Na interface do Edge, navegue até o app do desenvolvedor que você criou anteriormente. Na página "App do desenvolvedor", mostre e copie a chave do cliente. Esse valor é a chave de API. Você usará essa chave para fazer chamadas de API autenticadas.
Chame a API com o cabeçalho
x-api-key
da seguinte maneira. O valor da chave do consumidor que você copiou do app do desenvolvedor é a chave de API. Por padrão, o Edge Microgateway espera que você transmita a chave em um cabeçalho chamadox-api-key
, como este:curl -i http://localhost:8000/hello -H "x-api-key:apikey"
Exemplo:
curl -i http://localhost:8000/hello -H "x-api-key:PydUKRDGIXRqF2xh4usn1FLHbhGKVIz"
Se você quiser saber mais sobre como fazer chamadas de API autenticadas pelo Edge Microgateway com chaves de API e tokens OAuth, consulte a Parte 4: Secure Edge Microgateway.
Como interromper o Edge Microgateway
Use o seguinte comando do Docker para interromper o Edge Microgateway:
docker stop edgemicro
Reiniciando o Edge Microgateway
Depois de interromper o Edge Microgateway, reinicie-o com este comando do Docker:
docker start edgemicro
Como usar o TLS no contêiner do Docker
Nesta seção, explicamos como configurar o TLS para o Edge Microgateway em execução em um contêiner do Docker. É possível configurar o servidor Edge Microgateway para usar TLS para solicitações de entrada (direção norte-americana) e configurar o Edge Microgateway para ser um cliente TLS para solicitações de saída para endpoints de destino (direção sul).
Onde colocar os arquivos de certificado
O contêiner do Docker que executa o Edge Microgateway tem um ponto de montagem em
/opt/apigee/.edgemicro
. Ao configurar o Edge Microgateway para usar certificados TLS, é possível disponibilizar os arquivos de certificado nesse ponto de montagem e consultá-los no arquivo de configuração do Edge Microgateway. Esse arquivo de configuração geralmente fica no diretório$HOME/.edgemicro
e é chamado deyour_org-your_env-config.yaml
. Exemplo:... edgemicro: ssl: key: /opt/apigee/.edgemicro/southbound/tls.key cert: /opt/apigee/.edgemicro/southbound/tls.crt ...
Como usar uma CA em que o Node.js não confia
Se você estiver usando uma autoridade de certificação (CA, na sigla em inglês) na qual o Node.js não confia por padrão (como o caso de um certificado autoassinado), considere usar o parâmetro
NODE_EXTRA_CA_CERTS
ao executar o contêiner.Defina esse parâmetro como o caminho para um arquivo que contém um ou mais certificados confiáveis no formato PEM. Para saber como esse parâmetro é usado, consulte os exemplos Como configurar o TLS para o norte e Como configurar o TLS para o sul.
Exemplo:
chown -R 100:101 ~/.edgemicro/ \ docker run -P -p 8443:8443 -d --name edgemicro \ -v $HOME/.edgemicro:/opt/apigee/.edgemicro \ -v $HOME/.edgemicro:/opt/apigee/logs \ -e NODE_EXTRA_CA_CERTS=/opt/apigee/.edgemicro/rootca.pem \ -e EDGEMICRO_PORT=8443 \ -e EDGEMICRO_ORG=docs \ -e EDGEMICRO_ENV=test \ -e EDGEMICRO_KEY=ac36574905fb54fdae65fc5433e831bec2680efb98220a355f2e917e52973c \ -e EDGEMICRO_SECRET=aac81dff6c326eaa222d53c15c8841fa78ea863bf4472568c9ce2d80a3bc56 \ -e "EDGEMICRO_CONFIG=$EDGEMICRO_CONFIG" \ --link helloworld:helloworld gcr.io/apigee-microgateway/edgemicro
Consulte também Executar o Edge Micro como um contêiner do Docker.
Desativando a validação TLS
Embora não seja recomendado, em alguns casos, convém desativar a validação TLS para o Edge Microgateway em execução em um contêiner. Por padrão, o recurso de desativar o TLS não é integrado ao contêiner Docker do Edge Microgateway. Para realizar a tarefa, você precisa criar uma imagem personalizada do Docker para o Edge Microgateway. Veja abaixo as instruções gerais para criar a imagem personalizada e desativar a validação TLS.
Clone ou faça o download do repositório de origem do Edge Microgateway em
https://github.com/apigee-internal/microgateway
.cd
para o diretóriomicrogateway/kubernetes/docker/edgemicro
no diretório do código-fonte.Exemplo:
cd $HOME/git/microgateway/kubernetes/docker/edgemicro
Abra o arquivo
entrypoint.sh
e modifique o código para aceitar a variável de ambienteNODE_TLS_REJECT_UNAUTHORIZED
. Mais tarde, ao executar o contêiner, especifique um valor para essa variável.Crie o contêiner do Docker:
docker build -t edgemicro .
Ao executar o contêiner, especifique a opção
-e NODE_TLS_REJECT_UNAUTHORIZED = 1
. Exemplo:
chown -R 100:101 ~/.edgemicro/ \ docker run -P -p 8443:8443 -d --name edgemicro \ -v $HOME/.edgemicro:/opt/apigee/.edgemicro \ -v $HOME/.edgemicro:/opt/apigee/logs \ -e NODE_TLS_REJECT_UNAUTHORIZED = 1 \ -e EDGEMICRO_PORT=8443 \ -e EDGEMICRO_ORG=docs \ -e EDGEMICRO_ENV=test \ -e EDGEMICRO_KEY=ac36574905fb54fdae65fc5433e831bec2680efb98220a355f2e917e52973c \ -e EDGEMICRO_SECRET=aac81dff6c326eaa222d53c15c8841fa78ea863bf4472568c9ce2d80a3bc56 \ -e "EDGEMICRO_CONFIG=$EDGEMICRO_CONFIG" \ --link helloworld:helloworld gcr.io/apigee-microgateway/edgemicro
Exemplo: como configurar o TLS para o norte
Nesta seção, explicamos como configurar uma conexão TLS no sentido norte (entrada) no servidor Edge Microgateway. Com o TLS no sentido norte, os clientes podem usar HTTPS ao fazer chamadas de API para o Edge Microgateway. O exemplo abaixo usa certificados autoassinados.
1. Etapas de configuração inicial
- Localize o arquivo
openssl.cnf
no sistema. Por exemplo,/etc/ssl/openssl.cnf
. - Abra o arquivo
opensssl.cnf
para edição. Verifique se os
req_extensions
estão presentes no arquivo de configuração. Por exemplo, o arquivo precisa ter informações semelhantes às seguintes:[ req ] ... req_extensions = v3_req ... [ v3_req ] extendedKeyUsage = serverAuth, clientAuth, codeSigning, emailProtection basicConstraints = CA:FALSE keyUsage = nonRepudiation, digitalSignature, keyEncipherment
Adicione a seguinte estrofe a
openssl.cnf
para gerar os atributos SNI corretos:[ alt_names ] DNS.1 = www.example.com DNS.2 = example.com DNS.3 = localhost DNS.4 = localhost.localdomain DNS.5 = 127.0.0.1 DNS.6 = ::1 DNS.7 = fe80::1
Exemplo de arquivo
opensssl.cnf
:[ req ] distinguished_name = req_distinguished_name attributes = req_attributes req_extensions = v3_req [ v3_req ] extendedKeyUsage = serverAuth, clientAuth, codeSigning, emailProtection basicConstraints = CA:FALSE keyUsage = nonRepudiation, digitalSignature, keyEncipherment [ req_distinguished_name ] countryName = Country Name (2 letter code) countryName_min = 2 countryName_max = 2 stateOrProvinceName = State or Province Name (full name) localityName = Locality Name (eg, city) 0.organizationName = Organization Name (eg, company) organizationalUnitName = Organizational Unit Name (eg, section) commonName = Common Name (eg, fully qualified host name) commonName_max = 64 emailAddress = Email Address emailAddress_max = 64 [ req_attributes ] challengePassword = A challenge password challengePassword_min = 4 challengePassword_max = 20 [ alt_names ] DNS.1 = www.example.com DNS.2 = example.com DNS.3 = localhost DNS.4 = localhost.localdomain DNS.5 = 127.0.0.1 DNS.6 = ::1 DNS.7 = fe80::1
Siga as etapas da seção Pré-requisitos para inicializar e configurar o Edge Microgateway, se ainda não tiver feito isso. Depois de concluído, você terá criado um proxy com reconhecimento do Edge Microgateway, um produto de API, um desenvolvedor e um app para desenvolvedores. Além disso, você já executou o comando
edgemicro configure
e recebeu uma chave e um secret.
2. Gerar certificados autoassinados
Em seguida, gere os certificados e as chaves necessários para estabelecer o TLS:
cd
para o diretório$HOME/.edgemicro
.Crie o script bash a seguir. Você pode dar o nome que quiser a ela. Por exemplo:
keygen.sh
.#!/bin/bash # generate ca openssl genrsa -out rootca.key 2048 openssl req -x509 -new -nodes -key rootca.key -sha256 -days 1024 -out rootca.pem # generate key openssl genrsa -out tls.key 2048 openssl req -new -key tls.key -out tls.csr # sign cert openssl x509 -req -in tls.csr -CA rootca.pem -CAkey rootca.key -CAcreateserial -out tls.crt -days 1024 -sha256 -extensions 'v3_req' -extfile path/openssl.cnf
No arquivo bash, verifique se o caminho para o arquivo
openssl.cnf
está correto.Execute o arquivo bash. As informações do certificado serão solicitadas. Use
localhost
como o nome comum.Verifique se os seguintes arquivos foram criados:
rootca.key
rootca.pem
tls.key
tls.csr
rootca.srl
tls.crt
3. Editar o arquivo de configuração do Edge Microgateway
Abra o arquivo de configuração do Edge Micro em um editor. Exemplo:
vi $HOME/.edgemicro/myorg-test-config.yaml
Edite a estrofe
edgemicro
da seguinte maneira. Observe que você está fazendo mudanças nos atributosport
essl
:edge_config: ... edgemicro: port: 8443 max_connections: 1000 config_change_poll_interval: 600 ssl: key: /opt/apigee/.edgemicro/tls.key cert: /opt/apigee/.edgemicro/tls.crt passphrase: admin123 rejectUnauthorized: true requestCert: false logging: ...
Execute o seguinte comando para codificar em base64 o arquivo de configuração do Edge Microgateway localizado em
$HOME/.edgemicro
:export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/your_org-your_env-config.yaml`
em que
your_org
eyour_env
são a organização e o ambiente usados ao executar o comandoedgemicro config
.Lembre-se de colocar crases (`) ao redor do comando. Exemplo:
export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/docs-test-config.yaml`
Consulte também Executar o Edge Micro como um contêiner do Docker.
4. Executar o contêiner
Execute o seguinte comando para executar o contêiner do Docker com o Edge Microgateway:
chown -R 100:101 ~/.edgemicro/ \ docker run -P -p 8443:8443 -d --name edgemicro \ -v path_to_your_edgemicro_dir:/opt/apigee/.edgemicro \ -v path_to_your_logs_dir:/opt/apigee/logs \ -e NODE_EXTRA_CA_CERTS=/opt/apigee/.edgemicro/rootca.pem \ -e EDGEMICRO_PORT=8443 \ -e EDGEMICRO_ORG=$EDGEMICRO_ORG \ -e EDGEMICRO_ENV=$EDGEMICRO_ENV \ -e EDGEMICRO_KEY=$EDGEMICRO_KEY \ -e EDGEMICRO_SECRET=$EDGEMICRO_SECRET \ -e "EDGEMICRO_CONFIG=$EDGEMICRO_CONFIG" \ gcr.io/apigee-microgateway/edgemicro:latest
Observe os parâmetros a seguir usados no comando. Eles são diferentes do comando básico descrito em Executar o Edge Micro como um contêiner do Docker.
- O
port
está definido como8443
. - Uma montagem de volume é usada para montar os arquivos de chave e de certificado.
- A variável
NODE_EXTRA_CA_CERTS
é usada para adicionar uma CA personalizada, conforme necessário no caso de certificados autoassinados.
- O
5. Testar a configuração de TLS
Execute o comando cURL a seguir para testar a configuração. Substitua o caminho base e a chave de API no comando. O exemplo a seguir pressupõe que você esteja no diretório em que
rootca.pem
está localizado e que o proxy que você criou tem o caminho de base/hello
:curl -v https://localhost:8443/hello --cacert rootca.pem \ -H "x-api-key: Az82fdnfONVCOOE4NKhajxAboDgA3FAo"
A saída de cURL detalhada mostra cada etapa do handhaking do TLS. Se você receber uma resposta HTTP 200, significa que a configuração foi bem-sucedida:
* Trying ::1...ey:Az82fdnfONVCOOE4NKhajxAboDgA3FAo" * TCP_NODELAY set * Connected to localhost (::1) port 8443 (#0) * ALPN, offering h2 * ALPN, offering http/1.1 * Cipher selection: ALL:!EXPORT:!EXPORT40:!EXPORT56:!aNULL:!LOW:!RC4:@STRENGTH * successfully set certificate verify locations: * CAfile: rootca.pem CApath: none * TLSv1.2 (OUT), TLS handshake, Client hello (1): * TLSv1.2 (IN), TLS handshake, Server hello (2): * TLSv1.2 (IN), TLS handshake, Certificate (11): * TLSv1.2 (IN), TLS handshake, Server key exchange (12): * TLSv1.2 (IN), TLS handshake, Server finished (14): * TLSv1.2 (OUT), TLS handshake, Client key exchange (16): * TLSv1.2 (OUT), TLS change cipher, Client hello (1): * TLSv1.2 (OUT), TLS handshake, Finished (20): * TLSv1.2 (IN), TLS change cipher, Client hello (1): * TLSv1.2 (IN), TLS handshake, Finished (20): * SSL connection using TLSv1.2 / ECDHE-RSA-AES128-GCM-SHA256 * ALPN, server accepted to use http/1.1 * Server certificate: * subject: C=US; ST=CO; L=Boulder; O=Docs; OU=Docs; CN=localhost; emailAddress=docs@apigee.com * start date: Dec 14 22:35:28 2018 GMT * expire date: Oct 3 22:35:28 2021 GMT * common name: localhost (matched) * issuer: C=US; ST=CO; L=Boulder; O=Docs; OU=Docs; CN=localhost; emailAddress=docs@apigee.com * SSL certificate verify ok. > GET /hello HTTP/1.1 > Host: localhost:8443 > User-Agent: curl/7.54.0 > Accept: */* > x-api-key:Az82fdnfaONVCOE4NKhajxAboDA3FAo > < HTTP/1.1 200 OK < x-powered-by: Apigee < access-control-allow-origin: * < x-frame-options: ALLOW-FROM RESOURCE-URL < x-xss-protection: 1 < x-content-type-options: nosniff < content-type: text/plain; charset=utf-8 < etag: W/"d-GHB1ZrJKk/wdVTdB/jgBsw" < date: Fri, 14 Dec 2018 22:43:13 GMT < via: 1.1 google < alt-svc: clear < x-response-time: 1325 < Connection: keep-alive < Transfer-Encoding: chunked < * Connection #0 to host localhost left intact Hello, Guest!
Exemplo: como configurar o TLS para o sul
Nesta seção, explicamos como configurar uma conexão TLS no sentido sul (saída) entre o servidor do Edge Microgateway e um aplicativo de destino de back-end. O exemplo abaixo usa certificados autoassinados.
1. Etapas iniciais de configuração
- Localize o arquivo
openssl.cnf
no sistema. Por exemplo,/etc/ssl/openssl.cnf
. - Abra o arquivo
opensssl.cnf
para edição. Verifique se os
req_extensions
estão presentes no arquivo de configuração. Por exemplo, o arquivo precisa ter informações semelhantes às seguintes:[ req ] ... req_extensions = v3_req ... [ v3_req ] extendedKeyUsage = serverAuth, clientAuth, codeSigning, emailProtection basicConstraints = CA:FALSE keyUsage = nonRepudiation, digitalSignature, keyEncipherment
Adicione a seguinte estrofe a
openssl.cnf
para gerar os atributos SNI corretos:[ alt_names ] DNS.1 = helloworld DNS.2 = localhost DNS.3 = localhost.localdomain DNS.4 = 127.0.0.1 DNS.5 = ::1 DNS.6 = fe80::1
Exemplo de arquivo
opensssl.cnf
:[ req ] distinguished_name = req_distinguished_name attributes = req_attributes req_extensions = v3_req [ v3_req ] extendedKeyUsage = serverAuth, clientAuth, codeSigning, emailProtection basicConstraints = CA:FALSE keyUsage = nonRepudiation, digitalSignature, keyEncipherment [ req_distinguished_name ] countryName = Country Name (2 letter code) countryName_min = 2 countryName_max = 2 stateOrProvinceName = State or Province Name (full name) localityName = Locality Name (eg, city) 0.organizationName = Organization Name (eg, company) organizationalUnitName = Organizational Unit Name (eg, section) commonName = Common Name (eg, fully qualified host name) commonName_max = 64 emailAddress = Email Address emailAddress_max = 64 [ req_attributes ] challengePassword = A challenge password challengePassword_min = 4 challengePassword_max = 20 [ alt_names ] DNS.1 = helloworld DNS.2 = localhost DNS.3 = localhost.localdomain DNS.4 = 127.0.0.1 DNS.5 = ::1 DNS.6 = fe80::1
Execute o comando
edgemicro configure
:edgemicro configure -o your_org -e your_env -u your_username
Para mais detalhes sobre a configuração, consulte a Parte 1: configurar o Edge Microgateway.
Copie as credenciais de chave e secret que foram retornadas de
edgemicro configure
. Você vai precisar desses valores para executar o contêiner. Exemplo:The following credentials are required to start edge micro key: d9c34e1aff68ed969273c016699eabf48780e4f652242e72fc88a43e21252cb0 secret: 3bc95a71c86a3c8ce04537fbcb788158731t51dfc6cdec13b7c05aa0bd969430
2. Criar um aplicativo de destino Node.js
cd
para o diretório.edgemicro
.Crie o script bash a seguir. Você pode dar o nome que quiser a ela. Por exemplo:
keygen.sh
.#!/bin/bash # generate ca openssl genrsa -out rootca.key 2048 openssl req -x509 -new -nodes -key rootca.key -sha256 -days 1024 -out rootca.pem # generate key openssl genrsa -out tls.key 2048 openssl req -new -key tls.key -out tls.csr # sign cert openssl x509 -req -in tls.csr -CA rootca.pem -CAkey rootca.key -CAcreateserial -out tls.crt -days 1024 -sha256 -extensions 'v3_req' -extfile path/openssl.cnf
No arquivo bash, verifique se o caminho para o arquivo
openssl.cnf
está correto.Execute o arquivo bash. As informações do certificado serão solicitadas. Use
hellworld
como o nome comum.Verifique se os seguintes arquivos foram criados:
rootca.key
rootca.pem
tls.key
tls.csr
rootca.srl
tls.crt
Crie um novo arquivo chamado
server.js
.'use strict'; const express = require('express'); const https = require('https'); const fs = require('fs'); const options = { key: fs.readFileSync("tls.key"), cert: fs.readFileSync("tls.crt") }; // Constants const PORT = 9443; const HOST = '0.0.0.0'; // App const app = express(); app.get('/', (req, res) => { res.send('Hello world\n'); }); https.createServer(options, app).listen(PORT);
Crie um arquivo
package.json
no mesmo diretório queserver.js
. Exemplo:{ "name": "helloworld", "version": "1.0.0", "description": "", "main": "server.js", "scripts": { "test": "echo \"Error: no test specified\" && exit 1", "start": "node server.js" }, "author": "", "license": "ISC", "dependencies": { "express": "^4.16.4", "fs": "0.0.1-security", "https": "^1.0.0" } }
Execute
npm install
para receber as dependências.Crie um novo Dockerfile no mesmo diretório que
server.js
, em queWORKDIR
é o caminho para a raiz do aplicativo em Node.js:FROM node:8-alpine WORKDIR path-to-your-node-app COPY package*.json ./ RUN npm install COPY . . EXPOSE 9443 CMD [ "npm", "start" ]
Crie a imagem Docker:
docker build -t helloworld .
Inicie o app de exemplo:
docker run -P -p 9443:9443 --name helloworld helloworld
3. Criar entidades no Apigee Edge
Crie um proxy com reconhecimento do Edge Microgateway com essas configurações. Para mais informações, consulte Criar um proxy de API com reconhecimento do Edge Microgateway no Edge.
- Nome do proxy:
edgemicro_local
- Revisão:
1
- Caminho base:
/local
- Destino:
https://helloworld:9443
- Nome do proxy:
Criar um produto de API. Confira mais detalhes em Criar um produto.
Criar um desenvolvedor. Para mais detalhes, consulte Criar um desenvolvedor.
Crie um app do desenvolvedor. Para mais detalhes, consulte Criar um app do desenvolvedor.
4. Executar o contêiner
Abra o arquivo de configuração do Edge Micro em um editor. Exemplo:
vi $HOME/.edgemicro/myorg-test-config.yaml
Edite a estrofe
edgemicro
da seguinte maneira. Observe que você está fazendo mudanças nos atributosport
essl
:edge_config: ... edgemicro: port: 8443 max_connections: 1000 config_change_poll_interval: 600 ssl: key: /opt/apigee/.edgemicro/tls.key cert: /opt/apigee/.edgemicro/tls.crt passphrase: admin123 rejectUnauthorized: true requestCert: false logging: ...
Execute o seguinte comando para codificar em base64 o arquivo de configuração do Edge Microgateway localizado em
$HOME/.edgemicro
:export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/your_org-your_env-config.yaml`
em que
your_org
eyour_env
são a organização e o ambiente usados ao executar o comandoedgemicro config
.Lembre-se de colocar crases (`) ao redor do comando. Exemplo:
export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/docs-test-config.yaml`
Execute o comando a seguir para iniciar o Edge Microgateway no contêiner do Docker.
chown -R 100:101 ~/.edgemicro/ \ docker run -P -p 8443:8443 -d --name edgemicro \ -v path_to_your_edgemicro_dir:/opt/apigee/.edgemicro \ -v path_to_your_logs_dir:/opt/apigee/logs \ -e EDGEMICRO_PORT=8443 \ -e EDGEMICRO_ORG=$EDGEMICRO_ORG \ -e EDGEMICRO_ENV=$EDGEMICRO_ENV \ -e EDGEMICRO_KEY=$EDGEMICRO_KEY \ -e EDGEMICRO_SECRET=$EDGEMICRO_SECRET \ -e "EDGEMICRO_CONFIG=$EDGEMICRO_CONFIG" \ --link helloworld:helloworld gcr.io/apigee-microgateway/edgemicro
5. Testar a configuração de TLS
Execute o comando cURL a seguir para testar a configuração. Substitua o caminho base usado no proxy com reconhecimento de microgateway e a chave de API recebida do app de desenvolvedor que você criou no Apigee Edge. Exemplo:
curl https://localhost:8443/local -k -H "x-api-key: xxxx" -v
Você verá este erro:
... * subject: C=CA; ST=Ontario; L=Toronto; O=Google Canada; OU=Google Cloud Platform; CN=edgemicro; emailAddress=srinandans@google.com * start date: Dec 10 02:12:22 2018 GMT * expire date: Sep 29 02:12:22 2021 GMT * issuer: C=CA; ST=Ontario; L=Toronto; O=Google Canada; OU=Google Cloud Platform; CN=edgemicro; emailAddress=srinandans@google.com * SSL certificate verify result: unable to get local issuer certificate (20), continuing anyway. > GET /local HTTP/1.1 > Host: localhost:8443 > User-Agent: curl/7.54.0 > Accept: */* > x-api-key: 9fVC65pFj8LrmlPmVyxFjx4KgAHTxqSd > < HTTP/1.1 502 Bad Gateway < Date: Wed, 12 Dec 2018 05:25:01 GMT < Connection: keep-alive < Content-Length: 93 < * Connection #0 to host localhost left intact {"message":"unable to verify the first certificate","code":"UNABLE_TO_VERIFY_LEAF_SIGNATURE"}
Execute novamente o Edge Microgateway, mas desta vez adicione a variável
NODE_EXTRA_CA_CERTS
.chown -R 100:101 ~/.edgemicro/ \ docker run -P -p 8443:8443 -d --name edgemicro \ -v path_to_your_edgemicro_dir:/opt/apigee/.edgemicro \ -v path_to_your_logs_dir:/opt/apigee/logs \ -e NODE_EXTRA_CA_CERTS=/opt/apigee/.edgemicro/rootca.pem \ -e EDGEMICRO_PORT=8443 \ -e EDGEMICRO_ORG=$EDGEMICRO_ORG \ -e EDGEMICRO_ENV=$EDGEMICRO_ENV \ -e EDGEMICRO_KEY=$EDGEMICRO_KEY \ -e EDGEMICRO_SECRET=$EDGEMICRO_SECRET \ -e "EDGEMICRO_CONFIG=$EDGEMICRO_CONFIG" \ --link helloworld:helloworld gcr.io/apigee-microgateway/edgemicro
Execute o comando cURL a seguir. Substitua o caminho base e a chave de API como antes. Exemplo:
curl https://localhost:8443/local -k -H "x-api-key: xxxx" -v
Verifique a saída. Em caso de êxito, você receberá uma resposta de status HTTP 200:
... > GET /local HTTP/1.1 > Host: localhost:8443 > User-Agent: curl/7.54.0 > Accept: */* > x-api-key: 9fVC65pFj8LrmlPmVyxFjx4KgAHTxqSd > < HTTP/1.1 200 OK < x-powered-by: Express < content-type: text/html; charset=utf-8 < etag: W/"c-M6tWOb/Y57lesdjQuHeB1P/qTV0" < date: Wed, 12 Dec 2018 05:49:28 GMT < x-response-time: 421 < Connection: keep-alive < Transfer-Encoding: chunked < Hello world
Como adicionar um plug-in personalizado
É possível adicionar novos recursos ao microgateway escrevendo plug-ins personalizados. Com os plug-ins personalizados, é possível interagir de maneira programática com as solicitações e as respostas que fluem pelo microgateway.
Há duas opções para implantar plug-ins em uma instância do Edge Microgateway em execução em um contêiner do Docker:
O restante desta seção pressupõe que você esteja familiarizado com a criação e a configuração de plug-ins para uma configuração padrão do Edge Microgateway. Caso contrário, consulte Desenvolver plug-ins personalizados.
Opção A: montar o diretório de plug-ins em um volume
(Adicionado na v.2.5.27) As etapas para adicionar plug-ins por meio de uma montagem de volume são semelhantes às necessárias para adicionar qualquer plug-in personalizado ao Edge Microgateway. Ao executar o contêiner do Docker, é possível ativar o diretório de plug-ins no sistema local (o volume) no ponto de montagem do contêiner, que é
/opt/apigee/plugins
. Em seguida, especifique o diretório de volumes local no arquivo de configuração do Edge Microgateway.As etapas a seguir ilustram como usar um ponto de montagem do Docker para incluir plug-ins personalizados.
Interromper o Edge Microgateway:
edgemicro stop
Crie um diretório para seus plug-ins personalizados. Por exemplo, crie
$HOME/edgemicro/custom/plugins
Adicione o diretório do plug-in personalizado ao arquivo de configuração do Edge Microgateway. Exemplo:
plugins: dir: $HOME/edgemicro/custom/plugins sequence: - oauth - response-uppercase ````
Crie e teste o plug-in de acordo com as instruções em Criar um plug-in simples. Certifique-se de colocar o código do plug-in na estrutura de diretórios adequada. Exemplo:
custom | |-- plugins | |- response-uppercase | |- index.js | |- package.json |- request-headers | | - index.js | - package.json
Execute o contêiner do Docker com um comando semelhante ao seguinte, em que você usa a opção
-v
para ativar o diretório de plug-ins no volume do Docker. No comando de exemplo a seguir, o diretório de plug-ins$HOME/edgemicro/custom/plugins
, em que o plug-in personalizado está localizado, é mapeado para o ponto de montagem/opt/apigee/plugins
do contêiner:chown -R 100:101 ~/.edgemicro/ \ docker run -P -p 8000:8000 -d --name edgemicro \ -v /var/tmp:/opt/apigee/logs \ -v $HOME/edgemicro/custom/plugins:/opt/apigee/plugins \ -e EDGEMICRO_PROCESSES=1 \ -e EDGEMICRO_ORG=jdoe \ -e EDGEMICRO_ENV=test \ -e EDGEMICRO_KEY=39c4b561100cd7f258768d1072f3e1d7c17b5f36a18fe89972bb5c9ce7e58fb \ -e EDGEMICRO_SECRET=f5f9e239a38b4e6cc99c2aa067716a84aebdcff9580a7925fc500e402b1a5fa \ -e "EDGEMICRO_CONFIG=$EDGEMICRO_CONFIG" \ -e SERVICE_NAME=edgemicro \ --security-opt=no-new-privileges \ --cap-drop=ALL gcr.io/apigee-microgateway/edgemicro:latest
Chame a API para testar o plug-in.
Para mais informações, consulte VOLUME [sistemas de arquivos compartilhados].
Opção B: criar os plug-ins no contêiner
Nessa opção, você cria os plug-ins no seu contêiner.
1. Empacotar seus plug-ins
Crie e teste o plug-in de acordo com as instruções em Criar um plug-in simples.
Coloque o código do plug-in na estrutura de diretórios adequada. Os diretórios do plug-in precisam seguir uma estrutura definida. O exemplo abaixo mostra a estrutura que você precisa seguir, em que
response-uppercase
erequest-headers
são os nomes das pastas que contêm o código do plug-in personalizado. Esses nomes são apenas exemplos. Os nomes das pastas podem ser diferentes:plugin | |-- plugins | |- response-uppercase | |- index.js | |- package.json |- request-headers | | - index.js | - package.json
cd
para a pastaplugin
.Na pasta
plugin
, compacte toda a pastaplugins
:zip -r plugins.zip plugins/
2. Criar uma imagem do Docker
Em seguida, crie um Dockerfile para adicionar o código do plug-in a uma imagem do Edge Microgateway.
- No mesmo diretório em que o arquivo ZIP está localizado, crie um novo arquivo chamado
Dockerfile
. Adicione o código abaixo a
Dockerfile
e salve o arquivo:USER root RUN apk update && \ apk upgrade && \ apk add zipapk add zip && \ mkdir /opt/apigee/customplugins && \ chown apigee:apigee /opt/apigee/customplugins COPY plugins.zip /opt/apigee/customplugins RUN su - apigee -c "unzip /opt/apigee/customplugins/plugins.zip -d /opt/apigee/customplugins" EXPOSE 8000 EXPOSE 8443 USER apigee ENTRYPOINT ["entrypoint"]
Crie uma nova imagem Docker do Edge Microgateway com seus plug-ins:
docker build -t image-name .
Exemplo:
docker build -t edgemicroplugins .
3. Atualizar a configuração do Edge Microgateway
Agora que os plug-ins estão empacotados, eles precisam ser adicionados ao arquivo de configuração do Edge Microgateway.
Abra o arquivo de configuração do Edge Microgateway em um editor:
$HOME/.edgemicro/org-env-config.yaml
Exemplo:
vi $HOME/.edgemicro/myorg-test-config.yaml
Adicione o diretório do plug-in ao arquivo de configuração. No exemplo a seguir, o atributo
dir
especifica o local do código do plug-in (que você especificou no Dockerfile). Você também precisa especificar o nome do diretório do plug-in, que no exemplo abaixo éresponse-uppercase
.edgemicro: ... plugins: dir: /opt/apigee/plugins sequence: - oauth - response-uppercase
4. Inicie o microgateway
Por fim, inicie o microgateway no contêiner.
Execute o seguinte comando para codificar em base64 o arquivo de configuração do Edge Microgateway localizado em
$HOME/.edgemicro
:export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/your_org-your_env-config.yaml`
em que
your_org
eyour_env
são a organização e o ambiente usados ao executar o comandoedgemicro config
.Lembre-se de colocar crases (`) ao redor do comando. Exemplo:
export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/docs-test-config.yaml`
Execute o Edge Microgateway como um contêiner. O comando define várias variáveis de ambiente usadas pelo ambiente de execução do contêiner para iniciar o Edge Microgateway:
docker run -P -p 8000:8000 -d --name edgemicroplugins \ -e EDGEMICRO_PLUGIN_DIR=/opt/apigee/customplugins/plugins \ -e EDGEMICRO_ORG=your_org \ -e EDGEMICRO_ENV=your_env \ -e EDGEMICRO_KEY=your_key \ -e EDGEMICRO_SECRET=your_secret \ -e "EDGEMICRO_CONFIG=$EDGEMICRO_CONFIG" \ -e SERVICE_NAME=edgemicroplugins image_name
Exemplo:
docker run -P -p 8000:8000 -d --name edgemicroplugins \ -e EDGEMICRO_PLUGIN_DIR=/opt/apigee/customplugins/plugins \ -e EDGEMICRO_ORG=docs \ -e EDGEMICRO_ENV=test \ -e EDGEMICRO_KEY=d9c34e1aff68ed969273b016699eabf48780e4f652242e72fc88a23e21252cb0 \ -e EDGEMICRO_SECRET=3bc95a71c86a3c8ce04137fbcb788158731t51dfc6cdec13b7c05aa0bd969430 \ -e "EDGEMICRO_CONFIG=$EDGEMICRO_CONFIG" \ -e SERVICE_NAME=edgemicroplugins edgemicroplugins
Chame a API para testar o plug-in:
Teste se o código do plug-in é executado chamando a API e verificando se a saída está conforme o esperado:
curl -i http://localhost:8000/hello -H "x-api-key:apikey"
Por exemplo, o plug-in
response-uppercase
pode retornar uma resposta como esta:curl -i http://localhost:8000/hello -H "x-api-key:PydUKRDGIXRqF2xh4usn1FLHbhGKVIz" HELLO, WORLD!