Como usar o Docker para o Edge Microgateway

Esta é a documentação do Apigee Edge.
Acesse Documentação da Apigee X.
informações

Neste tópico, explicamos como executar o Edge Microgateway em um contêiner do Docker. Etapas neste tópico pressupõem um conhecimento básico sobre o Docker, os comandos do Docker e o Edge Microgateway instalação e configuração. Para Para mais informações, acesse a documentação do Docker e o Edge Microgateway.

Pré-requisitos

Antes de executar o Edge Microgateway em um contêiner do Docker, faça o seguinte: tarefas:

  • 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 a Parte 1: configurar o Edge Microgateway.

  • Depois de concluir as etapas de configuração, encontre o arquivo . O local padrão é este:

    $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 quando executou o comando edgemicro config. Você precisará esse arquivo ao iniciar o Edge Microgateway em um contêiner do Docker.

  • Verifique se você tem as credenciais de chave e segredo que foram retornadas quando você executou o 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, é preciso criar (ou que criaram) as entidades da Apigee Edge necessárias para fazer chamadas de proxy de API autenticadas. Essas entidades incluem um servidor com reconhecimento proxy, um produto de API, um desenvolvedor e um app do desenvolvedor. Para instruções completas, consulte Crie entidades no Apigee Edge.

Executar o Edge Micro como um contêiner do Docker

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

    docker pull gcr.io/apigee-microgateway/edgemicro:latest
  2. Antes de prosseguir para as próximas etapas, verifique se você realizou todas as etapas a 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 executou o comando edgemicro config.

    Lembre-se de colocar acentos graves (`) ao redor do comando. Exemplo:

    export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/docs-test-config.yaml`
  4. Executar o Edge Microgateway como um contêiner. O comando define diversas variáveis de ambiente que são usados pelo ambiente de execução do contêiner para iniciar o Edge Microgateway:

    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 SERVICE_NAME=edgemicro \
    --security-opt=no-new-privileges \
    --cap-drop=ALL \
    gcr.io/apigee-microgateway/edgemicro:latest

    Parâmetros

    Parâmetro Descrição
    -P Publicar todas as portas expostas no host. Consulte também a referência de execução do Docker.
    -p Mapeie explicitamente uma porta ou um 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, exponha a porta 8443 se montar o diretório do arquivo de registro. Consulte também VOLUME [sistemas de arquivos compartilhados]. Consulte também Como usar TLS no contêiner do Docker.
    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 contendo o arquivo de configuração do Edge Microgateway codificado em base64.
    SERVICE_NAME Se você estiver no Kubernetes, esse parâmetro será preenchido automaticamente. Caso contrário, você pode definir como quiser. Se você não especificar nada, o serviço for definido como default.
    DEBUG Defina como * para ativar a depuração.
    HTTP_PROXY HTTPS_PROXY Usar quando o Edge Microgateway estiver sendo executados atrás de um firewall e o gateway não consegue se comunicar com a Apigee Borda Para mais informações, consulte Como configurar o Edge Microgateway por um firewall da empresa.

    Por exemplo: HTTP_PROXY=http://10.203.0.1:5187/

    NO_PROXY Uma lista de domínios delimitados por vírgulas para os quais o Edge Microgateway não pode servir como proxy. Para mais informações, consulte Como configurar o Edge Microgateway por um firewall da empresa.

    Por exemplo: localhost,127.0.0.1,localaddress,.localdomain.com

    NODE_EXTRA_CA_CERTS (Opcional) Use este parâmetro se estiver usando uma CA não confiável por padrão pelo Node.js. Defina o valor desse parâmetro como o caminho para um arquivo que contém um ou mais certificados confiáveis no formato PEM. Para detalhes, consulte Certificados TLS.
    --security-opt (Opcional) Define as opções de segurança desejadas do Docker. Consulte Configuração de segurança na documentação do Docker.
    --cap-drop (Opcional) Define limites de recursos do Linux permitidos no contêiner. Consulte Privilégios de ambiente de execução e recursos do Linux na documentação do Docker.

    Exemplo:

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

Como 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 de base da 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 processou corretamente 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 criado anteriormente. No console do Página do app, mostre e copie a chave do cliente. 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ê copiado de "App do desenvolvedor" é a chave de API. Por padrão, o Edge Microgateway espera que você transmita a chave em um cabeçalho com o nome x-api-key, desta forma:

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 comando do Docker a seguir para interromper o Edge Microgateway:

docker stop edgemicro

Como reiniciar o Edge Microgateway

Depois de parar 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 do Edge Microgateway para usar o TLS para solicitações recebidas (direção norte-americana). É possível configurar Microgateway para ser um cliente TLS para solicitações enviadas para endpoints de destino (direção para o sul).

Onde colocar 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 tornar arquivos de certificado disponíveis nesse ponto de montagem e referenciá-los no Arquivo de configuração do Edge Microgateway. Esse arquivo de configuração geralmente fica localizado no diretório $HOME/.edgemicro com o nome your_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 AC não confiável para o Node.js

Se você estiver usando uma autoridade certificadora (CA) não confiável por padrão Node.js (como no 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 em formato PEM. Para saber como esse parâmetro é usado, consulte a exemplos Como configurar o TLS no sentido norte e Como configurar o TLS no sentido norte.

Exemplo:

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.

Como desativar a validação TLS

Embora não seja recomendado, em alguns casos, você pode desativar a validação TLS para o Edge Microgateway em execução em um contêiner. A capacidade de desativar o TLS não é integrado ao contêiner do Docker do Edge Microgateway por padrão. Para realizar tarefa, crie uma imagem do Docker personalizada para o Edge Microgateway. Abaixo sã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 https://github.com/apigee-internal/microgateway:

  2. cd ao 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 o NODE_TLS_REJECT_UNAUTHORIZED variável de ambiente. Mais tarde, ao executar o contêiner, você especificará um valor para 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:

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 no sentido norte

Nesta seção, explicamos como configurar uma conexão TLS no sentido norte (recebida) no Edge Microgateway servidor. Com o TLS na direção norte, os clientes podem usar 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 o req_extensions está presente no arquivo de configuração. Por exemplo, deve ter informações semelhantes às seguintes em seu 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 de 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 terminar, você criar um proxy com reconhecimento do Edge Microgateway, um produto de API, um e um app do desenvolvedor. Além disso, você deve ter executado 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:

  1. cd ao diretório $HOME/.edgemicro.
  2. 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
    
  3. No arquivo bash, verifique se o caminho para o arquivo openssl.cnf está correto.

  4. Execute o arquivo bash. As informações do certificado serão solicitadas. Certifique-se de usar localhost como 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 alterações aos 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 executou o comando edgemicro config.

    Lembre-se de colocar acentos graves (`) 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

  1. Use o comando a seguir para executar o contêiner do Docker com o Edge Microgateway:

    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: mas diferem dos modelos descrito em Executar o Edge Micro 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 AC personalizada (conforme necessário no caso de certificados autoassinados).

5. Testar a configuração do TLS

  1. Execute o comando cURL a seguir para testar a configuração. Substituto o caminho de 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 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 da Handshake de TLS. Se você receber uma resposta HTTP 200, a configuração estará 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 no sentido sul

Esta seção explica como configurar uma conexão TLS no sentido sul (de saída) entre o servidor 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 o req_extensions está presente no arquivo de configuração. Por exemplo, deve ter informações semelhantes às seguintes em seu 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 de 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 a Parte 1: configurar o Edge Microgateway.

  6. Copie as credenciais da chave e do secret que foram retornadas edgemicro configure: Você 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

  1. cd ao diretório .edgemicro.

  2. 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
    
  3. No arquivo bash, verifique se o caminho para o arquivo openssl.cnf está correto.

  4. Execute o arquivo bash. As informações do certificado serão solicitadas. Certifique-se de usar hellworld como 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 novo Dockerfile no mesmo diretório que server.js, em que WORKDIR. é o caminho para a raiz do seu aplicativo 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 no Apigee Edge

  1. Crie um proxy com reconhecimento do Edge Microgateway com estas 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 de base: /local
    • Destino: https://helloworld:9443
  2. Criar um produto de API. Para mais detalhes, consulte Criar um produto.

  3. Crie um desenvolvedor. Veja mais detalhes em Criar um desenvolvedor.

  4. Criar um app do desenvolvedor. Veja mais detalhes em Criar um app do 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 alterações aos 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 executou o comando edgemicro config.

    Lembre-se de colocar acentos graves (`) 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.

    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 do TLS

  1. Execute o comando cURL a seguir para testar a configuração. Substituto o caminho de base usado no proxy com reconhecimento de microgateway e o Chave de API recebida do app do desenvolvedor que você criou no Apigee Edge. Exemplo:

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

    Você vai encontrar 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.

    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 comando cURL a seguir. Substituto o caminho de base 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 tudo der certo, 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
    

Como adicionar um plug-in personalizado

É possível adicionar novos recursos ao microgateway escrevendo recursos personalizados plug-ins. Os plug-ins personalizados permitem que você interaja de maneira programática com as solicitações e as respostas que fluem pelo microgateway.

Você tem duas opções para implantar plug-ins em um Edge Microgateway em execução em um contêiner do Docker:

O restante desta seção pressupõe que você já sabe programar 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 meio de uma montagem de volume são semelhantes às etapas necessárias para adicionar qualquer plug-in personalizado ao Edge Microgateway. Quando você executa o contêiner do Docker, pode montar o diretório de plug-ins no sistema (o volume) no ponto de montagem do contêiner, que é /opt/apigee/plugins. Depois especifique o diretório do 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.

  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-in personalizado ao arquivo de configuração do Edge Microgateway. Exemplo:

      plugins:
        dir: $HOME/edgemicro/custom/plugins
        sequence:
          - oauth
          - response-uppercase
      ````
    
  4. Crie e teste seu plug-in, de acordo com as instruções em Criar um plug-in simples. Não se esqueça de 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ê use a opção -v para ativar o diretório de plug-ins no volume do Docker. Na Com o 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 /opt/apigee/plugins do contêiner:

    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

Nesta opção, você cria os plug-ins no seu contêiner.

1. Empacotar plug-ins

  1. Crie e teste seu plug-in, de acordo com as instruções em Criar 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 de pastas contendo código de 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
    
  3. cd para a pasta plugin.

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

    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.

  1. No mesmo diretório em que o arquivo ZIP está localizado, crie um novo arquivo com o nome Dockerfile.
  2. Adicione o código abaixo ao arquivo 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, é necessário adicioná-los ao Edge Microgateway de configuração do Terraform.

  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 deve 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. 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 executou o comando edgemicro config.

    Lembre-se de colocar acentos graves (`) ao redor do comando. Exemplo:

    export EDGEMICRO_CONFIG=`base64 $HOME/.edgemicro/docs-test-config.yaml`
  2. Executar o Edge Microgateway como um contêiner. O comando define diversas variáveis de ambiente que são usados 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 a API para testar o plug-in:

    Teste se o código do plug-in é executado chamando sua API e verificando se o é a esperada:

    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!