Executar um gateway de API privada do Jitterbit no Docker
Introdução
Esta seção fornece exemplos de diferentes maneiras de executar um gateway de API privada no Docker usando a imagem Docker do Jitterbit.
Pré-requisitos
Antes de começar, você precisa do seguinte:
-
Docker instalado e em execução.
-
Uma conta Harmony, com seu nome de usuário, senha e ID da organização.
-
Uma API do API Manager válida na organização associada ao gateway de API privada.
-
Se executar atrás de um proxy de encaminhamento, configure o firewall do host para permitir exceções do servidor proxy.
-
(Opcional) Para geração automática de certificados TLS, um domínio de gateway personalizado registrado e seu nome de domínio totalmente qualificado (FQDN) no formato
mygateway.mydomain.com.
Iniciar e configurar interativamente
Execute o seguinte para iniciar o contêiner e responda aos prompts (que segue as etapas de configuração de instalação do Linux):
docker run --interactive --tty --name=jb-gateway \
--hostname=jb-gateway -p 80:80 -p 443:443 \
jitterbit/private-gateway
Iniciar e configurar interativamente com rede bridge
Execute o seguinte para criar uma rede bridge e iniciar o contêiner conectado a essa rede, depois responda aos prompts:
docker network create -d bridge jitterbit
docker run --interactive -tty --name=jb-gateway \
--hostname=jb-gateway -p 80:80 -p 443:443 \
--network=jitterbit \
jitterbit/private-gateway
Uma rede bridge oferece as seguintes vantagens:
-
Descoberta de Contêiner: Permite comunicação direta usando nomes de contêiner, evitando dependência de endereços IP. Isso simplifica a comunicação entre contêineres e permite que agentes privados se comuniquem livremente com gateways privados.
-
Melhor Isolamento: Oferece isolamento aprimorado, reduzindo o risco de interações acidentais entre contêineres não relacionados.
-
Configurações Personalizadas: Permite configurações de rede específicas, como personalização de sub-rede e gateway.
-
Segmentação de Rede: Facilita a segmentação do tráfego de rede, garantindo que contêineres em diferentes redes bridge não interfiram entre si.
-
Políticas de Rede: Permite a aplicação de regras de rede ou políticas distintas, oferecendo controle aprimorado sobre as comunicações de contêiner.
Cuidado
Se configurar um ambiente multi-gateway em contêiner atrás de um balanceador de carga de aplicação (ALB) como AWS ALB, todos os contêineres de gateway devem estar no mesmo host.
Dica
Use a mesma rede para executar seus agentes privados baseados em Docker.
Iniciar sem supervisão com rede bridge e configurar com variáveis de ambiente
Execute o seguinte para criar uma rede bridge e iniciar o contêiner em modo destacado, com valores fornecidos por variáveis de ambiente:
docker network create -d bridge jitterbit
docker run --detach --name=jb-gateway \
--hostname=jb-gateway -p 80:80 -p 443:443 \
--network=jitterbit \
--env "HARMONY_USERNAME=<USERNAME>" \
--env "HARMONY_PASSWORD=<PASSWORD>" \
--env "ORGANIZATION_ID=<ORG_ID>" \
--env "SERVICE_URL=<SERVICE_URL>" \
--env "PROXY_ENABLED=true|false" \
--env "PROXY_HOSTNAME=<PROXY_HOSTNAME>"
--env "PROXY_USERNAME=<PROXY_SERVER_USERNAME>" \
--env "PROXY_PASSWORD=<PROXY_SERVER_PASSWORD>" \
--env "LETS_ENCRYPT_ENABLED=true|false" \
--env "LETS_ENCRYPT_DOMAIN=<DOMAIN>" \
--env "LETS_ENCRYPT_EMAIL=<EMAIL>" \
--env "MAX_DOMAIN_PARTS=<MAX_DOMAIN_PARTS>" \
jitterbit/private-gateway
Defina os valores das variáveis da seguinte forma:
| Variável | Descrição | Exemplo |
|---|---|---|
HARMONY_USERNAME |
Login da conta Harmony. | name@example.com |
HARMONY_PASSWORD |
Senha da conta Harmony, em texto simples ou codificada com base64. |
P@5$w0rdUEA1Cg== (codificada em base64) |
ORGANIZATION_ID |
Número do ID da organização Harmony. | 12345 |
SERVICE_URL |
URL do serviço Jitterbit para sua região:
|
https://services.jitterbit.eu/apis |
PROXY_ENABLED |
Ativar proxy (true ou false). |
true |
PROXY_HOSTNAME |
Hostname e porta do proxy. | host.docker.internal:12121 |
PROXY_USERNAME |
Nome de usuário do servidor proxy. | $(PROXY_SERVER_USERNAME) |
PROXY_PASSWORD |
Senha do servidor proxy, em texto simples ou codificada com base64. |
$(PROXY_SERVER_PASSWORD) |
LETS_ENCRYPT_ENABLED |
Ativar Let's Encrypt (true ou false). |
true |
LETS_ENCRYPT_DOMAIN |
Nome de domínio do Let's Encrypt. Se o nome de domínio contiver caracteres multibyte, insira sua forma Punycode. | gateway.mydomain.com |
LETS_ENCRYPT_EMAIL |
Email da conta Let's Encrypt. | youremail@<mydomain>.com |
MAX_DOMAIN_PARTS |
Número máximo de níveis de subdomínio suportados em um nome de domínio totalmente qualificado (FQDN) personalizado. Disponível desde a versão 12.9. O gateway suporta até 10 níveis de subdomínio por padrão. O aumento além do padrão de 10 exige que a chave MaxDomainParts já exista em gatewayconfig.yaml; consulte a nota abaixo. |
15 |
Importante
A chave MaxDomainParts já deve existir em gatewayconfig.yaml antes que a variável de ambiente MAX_DOMAIN_PARTS tenha efeito. O script de inicialização do gateway apenas atualiza o valor de uma chave MaxDomainParts existente; ele não adiciona a chave automaticamente. Para adicionar a chave a um contêiner em execução:
-
Abra uma sessão de shell no contêiner:
docker exec -it jb-gateway bash -
Adicione a chave
MaxDomainPartsa/usr/local/openresty/nginx/conf/onpremise/gatewayconfig.yaml. Por exemplo:MaxDomainParts: 15 -
Interrompa o contêiner e inicie um novo usando o mesmo comando
docker runcomMAX_DOMAIN_PARTSdefinido com o mesmo valor.
Inicialização e configuração automática com arquivo de variáveis de ambiente
Siga estas etapas para iniciar o contêiner em modo desanexado com variáveis de ambiente definidas em um arquivo:
-
No diretório onde o Docker é executado, crie um subdiretório
conf. Nele, crie um arquivogateway.confcontendo as seguintes variáveis de ambiente:conf/gateway.conf## # Jitterbit Private API Gateway Docker configuration # For more information, see https://docs.jitterbit.com/api-gateways/private/docker/ ## ## Jitterbit API Gateway Configuration # # Your Harmony account username. (Usually your email address.) HARMONY_USERNAME= # Your Harmony account password. # IMPORTANT: Follow your shell's quoting and escape rules for passwords with special characters. # Example: 'P@5$w0rD' HARMONY_PASSWORD= # Your Harmony account organization ID. # Example: 12345 ORGANIZATION_ID= # The Jitterbit service URL for your Harmony account region, one of the following: # - For NA: https://services.jitterbit.net/apis # - For EMEA: https://services.jitterbit.eu/apis # - For APAC: https://services.jitterbit.cc/apis SERVICE_URL= # Since private API gateway version 12.9, maximum number of subdomain levels supported in a custom fully qualified domain name (FQDN). # If not specified, the gateway supports up to 10 subdomain levels by default. # Requires the MaxDomainParts key to already exist in gatewayconfig.yaml; see the note under "Unattended start with bridge network and configure with environment variables". # MAX_DOMAIN_PARTS= ## Proxy Configuration (Optional) # # When true, enable proxy. PROXY_ENABLED=false ## When PROXY_ENABLED=true, uncomment and set the following: # # Proxy server URL, as http://your_proxy_server:port # PROXY_HOSTNAME= # Proxy server username # PROXY_USERNAME= # Proxy server password # PROXY_PASSWORD= ## Let's Encrypt certificates # When true, enable automatic generation of TLS certificate. # IMPORTANT: You must first create a DNS record pointing to the public IP address of your server. LETS_ENCRYPT_ENABLED=true # Fully-qualified domain name of your server, matching the A record or CNAME of the DNS record. # Example: gateway.mydomain.com # If the domain name contains multibyte characters, enter its Punycode form. LETS_ENCRYPT_DOMAIN= # Used by Lets Encrypt to issue the certificate. (Usually your email address.) LETS_ENCRYPT_EMAIL=Segurança de senha
Desde a versão 11.51 do gateway de API privado, os valores de
HARMONY_PASSWORDePROXY_PASSWORDpodem ser fornecidos como strings codificadas em base64. Sejam em texto simples ou codificados em base64, esses valores são mascarados (com***) no log de saída. -
Defina os valores das variáveis como no exemplo anterior.
-
Execute o seguinte comando:
docker run --detach --name=jb-gateway -p 80:80 -p 443:443 \ -v "$(pwd)/conf:/conf" \ jitterbit/private-gateway -
(Opcional) Teste o gateway.
Teste
Você pode testar um gateway de API privado do Docker em execução usando uma verificação de integridade ou o utilitário de autoteste.
Verificação de integridade
Para garantir que um gateway de API privado funcione conforme esperado, primeiro teste a URL de serviço de uma API do API Manager usando o gateway na nuvem e, em seguida, teste a URL do gateway de API privado para o mesmo endpoint:
-
No API Manager da organização associada ao gateway de API privado, crie e publique uma API.
-
Usando uma ferramenta de teste de API ou comando, faça uma solicitação HTTPS GET para a URL de serviço da API.
Por exemplo, para nome de organização
JBExample, ID de organização123456, prefixo de URL de ambientedevelopment, número de versão de API 1 e raiz de serviçohealthProbe, a URL de serviço da API seriahttps://JBExample123456.jitterbit.net/development/v1/healthProbena região NA. -
Faça a chamada novamente, mas substitua seu nome e ID de organização e o nome de domínio da região Harmony (
jitterbit.net,jitterbit.ccoujitterbit.eu) pelo subdomínio e domínio do seu gateway.Usando o exemplo anterior com um domínio de gateway de
mysubdomain.example.com, resulta em uma URL de gateway de API privado dehttps://mysubdomain.example.com/development/v1/healthProbe.
Utilitário de autoteste
O utilitário de autoteste integrado do gateway executa uma série de testes automáticos que incluem importar um projeto e uma API integrados e, em seguida, chamar a API através do gateway para garantir a configuração adequada.
A API é criada com a opção SSL only ativada, significando que o acesso à URL do gateway de API privado será testado apenas sobre HTTPS. Para permitir acesso sobre HTTP, você pode desativar a opção SSL only na configuração de API depois que a API de teste for criada.
Uma URL de API deve estar disponível em sua assinatura para que o autoteste seja bem-sucedido.
Para executar o utilitário de autoteste, siga estas etapas:
-
Abra uma sessão de shell em um contêiner em execução:
docker exec -it jitterbit-gateway bash -
Execute o utilitário de autoteste:
/usr/bin/jitterbit-api-gateway-config --test