Como usar o Docker para o Edge Microgateway

Você está lendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X. info

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 da 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, faça o seguinte:

  • Configure o Edge Microgateway para sua organização/ambiente da Apigee:

    edgemicro configure -o your_org -e your_env -u your_username

    Para mais detalhes sobre a configuração, consulte Parte 1: configurar o Edge Microgateway.

  • Depois de realizar as etapas de configuração, localize o arquivo de configuração. O local padrão é:

    $HOME/.edgemicro/your_org-your_env-config.yaml

    em que your_org e your_env são a organização e o ambiente que você usou ao executar o comando edgemicro config. Você vai 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, crie (ou tenha criado) as entidades do Apigee Edge necessárias para fazer chamadas autenticadas de proxy de API. Essas entidades incluem um proxy compatível com o Edge Microgateway, um produto de API, um desenvolvedor e um app de desenvolvedor. Para instruções completas, consulte Criar entidades no Apigee Edge.

Executar o Edge Microgateway como um contêiner do Docker

  1. Faça o download da imagem Docker para o Edge Microgateway:

    docker pull gcr.io/apigee-microgateway/edgemicro:latest

  2. Antes de continuar, verifique se você realizou todas as etapas na seção Pré-requisitos.

  3. Execute o comando a seguir 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 e your_env são a organização e o ambiente que você usou ao executar o comando edgemicro config.

    Não se esqueça de colocar crases (`) ao redor do comando. Exemplo:

    export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/docs-test-config.yaml`

  4. 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 Publica todas as portas expostas no host. Consulte também a referência de execução do Docker.
    -p Mapeie explicitamente uma única porta ou um intervalo de portas. Consulte também a referência de execução do Docker.
    -d Executar no modo separado. 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 TLS no contêiner do Docker, exponha a porta 8443 se você montar o diretório de arquivos de registro. Consulte 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 e edgemicro.pid serão criados. Não é possível modificar a raiz do nome do arquivo edgemicro. 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 usada para configurar o Edge Microgateway.
    EDGEMICRO_ENV O nome do ambiente da Apigee usado 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 de registro é enviada. Consulte 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/edgemicro

    1. Para 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

    Especificar opções de saída de arquivo de registros

    O parâmetro de configuração do Edge Microgateway to_console permite enviar informações de registro para a saída padrão em vez de um arquivo de registro. Se você seguir as etapas para executar o Edge Microgateway em um contêiner do Docker, por padrão, o contêiner vai redirecionar stdout e a saída de erro para um arquivo localizado no contêiner no local: ${APIGEE_ROOT}/logs/edgemicro.log.

    Para impedir que as informações de registro sejam enviadas ao edgemicro.log, use a variável LOG_CONSOLE_OUTPUT_TO_FILE ao executar o contêiner.

    A tabela a seguir descreve o comportamento da saída de registros ao usar LOG_CONSOLE_OUTPUT_TO_FILE com to_console:

    to_console: true

    LOG_CONSOLE_OUTPUT_TO_FILE=false

    • Nenhum registro será enviado ao arquivo de registros do Edge Microgateway, conforme descrito em Gerenciar arquivos de registros.
    • 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 ao arquivo de registros do Edge Microgateway, conforme descrito em Gerenciar arquivos de registros.
    • 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 registros do Edge Microgateway, conforme descrito em Gerenciar arquivos de registros.
    • Os registros serão enviados para o arquivo edgemicro.log.

    Testar uma chamada de API

    Depois de iniciar o Edge Microgateway no contêiner, é possível fazer chamadas de API para ele. Por exemplo, se o caminho base da API for /hello:

    http://localhost:8000/hello

    Exemplo de resposta:

    {"error":"missing_authorization","error_description":"Missing Authorization header"}

    Se você vir essa resposta, significa que o Edge Microgateway processou a chamada de API com êxito. 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 de desenvolvedor que você criou antes. Na página "App do desenvolvedor", mostre e copie a chave do consumidor. Esse valor é a chave de API. Você vai 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 cliente que você copiou do app de desenvolvedor é a chave de API. Por padrão, o Edge Microgateway espera que você transmita a chave em um cabeçalho chamado x-api-key, assim:

    curl -i http://localhost:8000/hello -H "x-api-key:apikey"

    Exemplo:

    curl -i http://localhost:8000/hello -H "x-api-key:PydUKRDGIXRqF2xh4usn1FLHbhGKVIz"

    Se quiser saber mais sobre como fazer chamadas de API autenticadas pelo Edge Microgateway com chaves de API e tokens OAuth, consulte Parte 4: proteger o Edge Microgateway.

    Como interromper o Edge Microgateway

    Use o seguinte comando do Docker para interromper o Edge Microgateway:

    docker stop edgemicro

    Reiniciar o Edge Microgateway

    Depois de interromper o Edge Microgateway, reinicie-o com este comando do Docker:

    docker start edgemicro

    Como usar 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 do Edge Microgateway para usar TLS em solicitações de entrada (direção norte) e configurar o Edge Microgateway como 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, disponibilize os arquivos de certificado nesse ponto de montagem e consulte-os no arquivo de configuração do Edge Microgateway. Esse arquivo de configuração geralmente está localizado no diretório $HOME/.edgemicro e é chamado de your_org-your_env-config.yaml. Exemplo:

    ...
edgemicro:
  ssl:
   key: /opt/apigee/.edgemicro/southbound/tls.key
   cert: /opt/apigee/.edgemicro/southbound/tls.crt
...

    Usar uma CA que não é confiável para o Node.js

    Se você estiver usando uma autoridade de certificação (CA) que não é confiável por padrão pelo Node.js (como é o caso de um certificado autoassinado), use o parâmetro NODE_EXTRA_CA_CERTS ao executar o contêiner.

    Defina esse parâmetro como o caminho para um arquivo que contenha um ou mais certificados confiáveis no formato PEM. Para saber como esse parâmetro é usado, consulte os exemplos Como configurar o TLS de saída e Como configurar o TLS de entrada.

    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 Microgateway como um contêiner do Docker.

    Desativar a validação TLS

    Embora não seja recomendado, em alguns casos, talvez você queira desativar a validação de TLS para o Edge Microgateway em execução em um contêiner. A capacidade de desativar o TLS não é integrada ao contêiner do Docker do Edge Microgateway por padrão. Para realizar a tarefa, você precisa criar uma imagem Docker personalizada para o Edge Microgateway. A seguir estão instruções gerais para criar a imagem personalizada e desativar a validação TLS.

    1. Clone ou faça o download do repositório de origem do Edge Microgateway em https://github.com/apigee-internal/microgateway.

    2. cd para o diretório microgateway/kubernetes/docker/edgemicro no diretório do código-fonte.

      Exemplo:

      cd $HOME/git/microgateway/kubernetes/docker/edgemicro

    3. Abra o arquivo entrypoint.sh e modifique o código para aceitar a variável de ambiente NODE_TLS_REJECT_UNAUTHORIZED. Depois, ao executar o contêiner, você vai especificar um valor para essa variável.

    4. Crie o contêiner do Docker:

      docker build -t edgemicro .

    5. 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 de saída

    Nesta seção, explicamos como configurar uma conexão TLS de entrada no servidor do Edge Microgateway. O TLS de saída permite que os clientes usem HTTPS ao fazer chamadas de API para o Edge Microgateway. O exemplo abaixo usa certificados autoassinados.

    1. Etapas iniciais de configuração

    1. Localize o arquivo openssl.cnf no seu sistema. Por exemplo, /etc/ssl/openssl.cnf.
    2. Abra o arquivo opensssl.cnf para edição.

    3. Verifique se os req_extensions estão presentes no arquivo de configuração. Por exemplo, você precisa ter informações semelhantes às seguintes no arquivo:

      [ req ]
...
req_extensions          = v3_req
...

[ v3_req ]
extendedKeyUsage = serverAuth, clientAuth, codeSigning, emailProtection
basicConstraints = CA:FALSE
keyUsage = nonRepudiation, digitalSignature, keyEncipherment

    4. 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

    5. Siga as etapas na seção Pré-requisitos para inicializar e configurar o Edge Microgateway, se ainda não tiver feito isso. Ao concluir, você terá criado um proxy baseado no Edge Microgateway, um produto de API, um desenvolvedor e um app de desenvolvedor. Além disso, você terá executado o comando edgemicro configure e recebido uma chave e um secret.

    2. Gerar certificados autoassinados

    Em seguida, gere os certificados e as chaves necessárias para estabelecer o TLS:

    1. cd para o diretório $HOME/.edgemicro.

    2. Crie o seguinte script bash. Você pode dar o nome que quiser. 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

    3. No arquivo bash, verifique se o caminho para o arquivo openssl.cnf está correto.

    4. Execute o arquivo bash. Você vai precisar informar os dados do certificado. Use localhost para o nome comum.

    5. 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

    1. Abra o arquivo de configuração do Edge Micro em um editor. Exemplo:

      vi $HOME/.edgemicro/myorg-test-config.yaml

    2. Edite a estrofe edgemicro da seguinte maneira. Observe que você está fazendo mudanças nos atributos port e ssl:

      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:
...

    3. Execute o comando a seguir 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 e your_env são a organização e o ambiente que você usou ao executar o comando edgemicro config.

      Não se esqueça de colocar crases (`) ao redor do comando. Exemplo:

      export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/docs-test-config.yaml`

    Consulte também Executar o Edge Microgateway como um contêiner do Docker.

    4. Executar o contêiner

    1. Execute o comando a seguir 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

    2. Observe os seguintes parâmetros usados no comando, que são diferentes do comando básico descrito em Executar o Edge Microgateway como um contêiner do Docker.

      • O elemento port é definido como 8443.
      • Uma montagem de volume é usada para montar os arquivos de chave e certificado.
      • A variável NODE_EXTRA_CA_CERTS é usada para adicionar uma CA personalizada (conforme necessário no caso de certificados autoassinados).

    5. Testar a configuração de TLS

    1. Execute o seguinte comando cURL para testar a configuração. Substitua o basepath e a chave de API no comando. No exemplo a seguir, presumimos que você está no diretório em que rootca.pem está localizado e que o proxy criado tem o caminho base /hello:

      curl -v https://localhost:8443/hello --cacert rootca.pem \
-H "x-api-key: Az82fdnfONVCOOE4NKhajxAboDgA3FAo"

    2. A saída detalhada do cURL mostra cada etapa do handshake TLS. Se você receber uma resposta HTTP 200, a configuração foi concluída:

      *   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 de saída

    Esta seção explica como configurar uma conexão TLS sul (de 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

    1. Localize o arquivo openssl.cnf no seu sistema. Por exemplo, /etc/ssl/openssl.cnf.
    2. Abra o arquivo opensssl.cnf para edição.

    3. Verifique se os req_extensions estão presentes no arquivo de configuração. Por exemplo, você precisa ter informações semelhantes às seguintes no arquivo:

      [ req ]
...
req_extensions          = v3_req
...

[ v3_req ]
extendedKeyUsage = serverAuth, clientAuth, codeSigning, emailProtection
basicConstraints = CA:FALSE
keyUsage = nonRepudiation, digitalSignature, keyEncipherment

    4. 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

    5. Execute o comando edgemicro configure:

      edgemicro configure -o your_org -e your_env -u your_username

      Para mais detalhes sobre a configuração, consulte Parte 1: configurar o Edge Microgateway.

    6. Copie as credenciais de chave e secret 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 do Node.js

    1. cd para o diretório .edgemicro.

    2. Crie o seguinte script bash. Você pode dar o nome que quiser. 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

    3. No arquivo bash, verifique se o caminho para o arquivo openssl.cnf está correto.

    4. Execute o arquivo bash. Você vai precisar informar os dados do certificado. Use hellworld para o nome comum.

    5. Verifique se os seguintes arquivos foram criados:

      • rootca.key
      • rootca.pem
      • tls.key
      • tls.csr
      • rootca.srl
      • tls.crt

    6. 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);

    7. Crie um arquivo package.json no mesmo diretório que server.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"
  }
}

    8. Execute npm install para receber as dependências.

    9. Crie um Dockerfile no mesmo diretório de server.js, em que WORKDIR é o caminho para a raiz do seu app Node.js:

      FROM node:8-alpine
WORKDIR path-to-your-node-app
COPY package*.json ./

RUN npm install
COPY . .
EXPOSE 9443
CMD [ "npm", "start" ]

    10. Compile a imagem Docker:

      docker build -t helloworld .

    11. Inicie o app de exemplo:

      docker run -P -p 9443:9443 --name helloworld helloworld

    3. Criar entidades na Apigee Edge

    1. Crie um proxy baseado no Edge Microgateway com estas configurações. Para mais informações, consulte Criar um proxy de API compatível com o Edge Microgateway no Edge.

      • Nome do proxy: edgemicro_local
      • Revisão: 1
      • Caminho base: /local
      • Destino: https://helloworld:9443

    2. Crie um produto de API. Para mais detalhes, consulte Criar um produto.

    3. Crie um desenvolvedor. Para mais detalhes, consulte Criar um desenvolvedor.

    4. Crie um app de desenvolvedor. Para mais detalhes, consulte Criar um app de desenvolvedor.

    4. Executar o contêiner

    1. Abra o arquivo de configuração do Edge Micro em um editor. Exemplo:

      vi $HOME/.edgemicro/myorg-test-config.yaml

    2. Edite a estrofe edgemicro da seguinte maneira. Observe que você está fazendo mudanças nos atributos port e ssl:

      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:
...

    3. Execute o comando a seguir 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 e your_env são a organização e o ambiente que você usou ao executar o comando edgemicro config.

      Não se esqueça de colocar crases (`) ao redor do comando. Exemplo:

      export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/docs-test-config.yaml`

    4. 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

    1. Execute o seguinte comando cURL para testar a configuração. Substitua o basepath usado no proxy compatível com microrrede e a chave de API obtida do app para desenvolvedores criado no Apigee Edge. Exemplo:

      curl https://localhost:8443/local -k -H "x-api-key: xxxx" -v

      Você vai receber 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"}

    2. Execute o Edge Microgateway novamente, 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

    3. Execute o seguinte comando cURL. Substitua o basepath e a chave de API como antes. Exemplo:

      curl https://localhost:8443/local -k -H "x-api-key: xxxx" -v

    4. Verifique a saída. Se a operação for bem-sucedida, você vai 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

    Adicionar um plug-in personalizado

    É possível adicionar novos recursos e funcionalidades ao microrrecurso escrevendo plug-ins personalizados. Com os plug-ins personalizados, você interage de forma programática com as solicitações e respostas que fluem pelo microrgateway.

    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ê saiba escrever e configurar plug-ins para uma configuração padrão do Edge Microgateway. Caso contrário, consulte Desenvolver plug-ins personalizados.

    Opção A: ativar o diretório de plug-ins em um volume

    (Adicionado na v.2.5.27) As etapas para adicionar plug-ins por uma montagem de volume são semelhantes às etapas necessárias para adicionar qualquer plug-in personalizado ao Edge Microgateway. Ao executar o contêiner do Docker, é possível montar 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 volume 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.

    1. Parar o Edge Microgateway:

      edgemicro stop

    2. Crie um diretório para seus plug-ins personalizados. Por exemplo, crie

      $HOME/edgemicro/custom/plugins

    3. Adicione o diretório de plug-ins personalizados ao arquivo de configuração do Edge Microgateway. Exemplo:

        plugins:
    dir: $HOME/edgemicro/custom/plugins
    sequence:
      - oauth
      - response-uppercase
  ````

    4. Escreva e teste seu plug-in de acordo com as instruções em Escrever um plug-in simples. Coloque 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

    5. Execute o contêiner do Docker com um comando semelhante ao seguinte, em que você usa a opção -v para montar 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 (onde o plug-in personalizado está localizado) é mapeado para o ponto de montagem do contêiner /opt/apigee/plugins:

      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

    6. 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 contêiner.

    1. Empacotar seus plug-ins

    1. Escreva e teste seu plug-in de acordo com as instruções em Escrever um plug-in simples.

    2. Coloque o código do plug-in na estrutura de diretórios adequada. Os diretórios de plug-ins precisam seguir uma estrutura definida. O exemplo a seguir mostra a estrutura que você precisa seguir, em que response-uppercase e request-headers são os nomes das pastas que contêm o código do plug-in personalizado. Esses nomes são apenas exemplos, e os nomes das suas pastas podem ser diferentes:

      plugin
  |
  |-- plugins
    |
    |- response-uppercase
    |     |- index.js
    |     |- package.json
    |- request-headers
    |     | - index.js
          | - package.json

    3. cd na pasta plugin.

    4. Na pasta plugin, compacte toda a pasta plugins:

      zip -r plugins.zip plugins/

    2. Criar uma imagem Docker

    Em seguida, crie um Dockerfile para adicionar o código do plug-in a uma imagem do Edge Microgateway.

    1. No mesmo diretório em que o arquivo ZIP está localizado, crie um arquivo chamado Dockerfile.

    2. Adicione o código a seguir 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"]

    3. 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, é preciso adicioná-los ao arquivo de configuração do Edge Microgateway.

    1. 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

    2. 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 de plug-ins, que no exemplo abaixo é response-uppercase. 

      edgemicro:
  ...
  plugins:
    dir: /opt/apigee/plugins
    sequence:
      - oauth
      - response-uppercase

    4. Iniciar o microgateway

    Por fim, inicie o microgateway no contêiner.

    1. Execute o comando a seguir 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 e your_env são a organização e o ambiente que você usou ao executar o comando edgemicro config.

      Não se esqueça de colocar crases (`) ao redor do comando. Exemplo:

      export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/docs-test-config.yaml`

    2. 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

    3. Chame sua 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!