Como criar um API Gateway Usando o Ambassador no Kubernetes da DigitalOcean

O autor escolheu a Free and Open Source Fund para receber uma doação como parte do programa Write for DOnations.

Introdução

O Ambassador é um API Gateway para aplicações nativas em nuvem que roteia o tráfego entre serviços heterogêneos e mantém fluxos de trabalho descentralizados. Ele atua como um único ponto de entrada e suporta tarefas como descoberta de serviço, gerenciamento de configuração, regras de roteamento e limitação de taxas de acesso. Ele também oferece grande flexibilidade e facilidade de configuração para seus serviços.

O Envoy é um proxy de serviço de código aberto projetado para aplicações nativas em nuvem. No Kubernetes, o Ambassador pode ser usado para instalar e gerenciar a configuração do Envoy. O Ambassador suporta alterações na configuração com tempo zero de inatividade e integração com outros recursos, como autenticação, descoberta de serviços e service meshes.

Neste tutorial, você configurará um Ambassador API Gateway em um cluster Kubernetes usando o Helm e o configurará para rotear o tráfego de entrada para vários serviços com base nas regras de roteamento. Você configurará essas regras para rotear o tráfego com base no nome do host ou no caminho para os serviços relevantes.

Pré-requisitos

Antes de começar este guia, você precisará do seguinte:

  • Um cluster Kubernetes na DigitalOcean com o kubectl configurado. Para criar um cluster Kubernetes na DigitalOcean, veja nosso guia Kubernetes Quickstart.

  • O gerenciador de pacotes Helm instalado em sua máquina local e o Tiller instalado em seu cluster. Complete os passos 1 e 2 do tutorial How To Install Software on Kubernetes Clusters with the Helm Package Manager

  • Um nome de domíno totalmente qualificado com pelo menos dois registros A configurados. Ao longo deste tutorial iremos utilizar svc1.seu-domínio, svc2.seu-domínio e svc3.seu-domínio. Você pode seguir o guia DNS Quickstart para configurar seus registros na DigitalOcean.

Passo 1 — Instalando o Ambassador

Nesta seção, você instalará o Ambassador no seu cluster Kubernetes. O Ambassador pode ser instalado usando um chart do Helm ou passando um arquivo de configuração YAML para o comando kubectl.

Nota: O Kubernetes na DigitalOcean tem o RBAC ativado por padrão, portanto, ao usar um arquivo de configuração YAML para instalação, é necessário garantir que você use o RBAC ativado. Você pode encontrar mais detalhes sobre o deployment do Ambassador no Kubernetes via YAML na documentação do Ambassador

Para os propósitos deste tutorial, você usará um chart do Helm para instalar o Ambassador no seu cluster. Após seguir os pré-requisitos, você terá o Helm instalado em seu cluster.

Para começar, execute o seguinte comando para instalar o Ambassador via Helm:

  • helm upgrade --install --wait ambassador stable/ambassador

Você verá uma saída semelhante à seguinte:

OutputRelease "ambassador" does not exist. Installing it now. NAME:   ambassador LAST DEPLOYED: Tue Jun 18 02:15:00 2019 NAMESPACE: default STATUS: DEPLOYED  RESOURCES: ==> v1/Deployment NAME        READY  UP-TO-DATE  AVAILABLE  AGE ambassador  3/3    3           3          2m39s  ==> v1/Pod(related) NAME                         READY  STATUS   RESTARTS  AGE ambassador-7d55c468cb-4gpq9  1/1    Running  0         2m38s ambassador-7d55c468cb-jr9zr  1/1    Running  0         2m38s ambassador-7d55c468cb-zhm7l  1/1    Running  0         2m38s  ==> v1/Service NAME               TYPE          CLUSTER-IP      EXTERNAL-IP    PORT(S)                     AGE ambassador         LoadBalancer  10.245.183.114  139.59.52.164  80:30001/TCP,443:31557/TCP  2m40s ambassador-admins  ClusterIP     10.245.46.43    <none>         8877/TCP                    2m41s  ==> v1/ServiceAccount NAME        SECRETS  AGE ambassador  1        2m43s  ==> v1beta1/ClusterRole NAME        AGE ambassador  2m41s  ==> v1beta1/ClusterRoleBinding NAME        AGE ambassador  2m41s  ==> v1beta1/CustomResourceDefinition NAME                                          AGE authservices.getambassador.io                 2m42s consulresolvers.getambassador.io              2m41s kubernetesendpointresolvers.getambassador.io  2m42s kubernetesserviceresolvers.getambassador.io   2m43s mappings.getambassador.io                     2m41s modules.getambassador.io                      2m41s ratelimitservices.getambassador.io            2m42s tcpmappings.getambassador.io                  2m41s tlscontexts.getambassador.io                  2m42s tracingservices.getambassador.io              2m43s  . . . 

Isso criará um deployment do Ambassador, um serviço e um balanceador de carga do Ambassador com os seus nodes do cluster Kubernetes conectados. Você precisará do IP do balanceador de carga para mapeá-lo para os registros A do seu domínio

Para obter o endereço IP do balanceador de carga do seu Ambassador, execute o seguinte:

  • kubectl get svc --namespace default ambassador

Você verá uma saída semelhante a:

OutputNAME         TYPE           CLUSTER-IP       EXTERNAL-IP     PORT(S)                      AGE ambassador   LoadBalancer   IP-do-seu-cluster   seu-endereço-IP   80:30001/TCP,443:31557/TCP   8m4s 

Observe o IP externo seu-endereço-IP neste passo e mapeie os domínios (através de seu provedor de domínio) svc1.seu-domínio, svc2.seu-domínio e svc3.seu-domínio para apontar para este endereço IP.

Você pode ativar o HTTPS com o seu balanceador de carga na DigitalOcean usando os passos fornecidos em Como configurar a terminação SSL. É recomendável configurar a terminação TLS por meio do balanceador de carga. Outra maneira de configurar a terminação TLS é usar o Suporte TLS do Ambassador

Você instalou o Ambassador no seu cluster Kubernetes usando o Helm, que criou um deployment do Ambassador com três réplicas no namespace padrão. Isso também criou um balanceador de carga com um IP público para rotear todo o tráfego em direção ao API Gateway. Em seguida, você criará deployments do Kubernetes para três serviços diferentes que você usará para testar esse API Gateway.

Passo 2 — Configurando Deployments de Servidor Web

Nesta seção, você criará três deployments para executar três containers de servidor web diferentes. Você criará arquivos YAML com definições de deployments do Kubernetes para os três diferentes containers de servidores web e fará o deploy usando o kubectl.

Abra seu editor de texto preferido para criar seu primeiro deployment para um servidor web Nginx:

  • nano svc1-deploy.yaml

Digite a seguinte configuração yaml no seu arquivo:

svc1-deploy.yaml

apiVersion: extensions/v1beta1 kind: Deployment metadata:   name: svc1 spec:   replicas: 1   selector:     matchLabels:       app: nginx       name: svc1   strategy:     type: RollingUpdate   template:     metadata:       labels:         app: nginx         name: svc1     spec:       containers:       - name: nginx         image: nginx:latest         ports:         - name: http           containerPort: 80 

Aqui você definiu um Deployment do Kubernetes com a imagem de container nginx:latest a ser deployada com 1 réplica, chamada svc1. O Deployment é definido para expor o cluster na porta 80.

Salve e feche o arquivo.

Em seguida, execute o seguinte comando para aplicar esta configuração:

  • kubectl apply -f svc1-deploy.yaml

Você verá a saída confirmando a criação:

Outputdeployment.extensions/svc1 created 

Agora, crie um segundo deployment de servidor web. Abra um arquivo chamado svc2-deploy.yaml com:

  • nano svc2-deploy.yaml

Digite a seguinte configuração YAML no arquivo:

svc2-deploy.yaml

apiVersion: extensions/v1beta1 kind: Deployment metadata:   name: svc2 spec:   replicas: 1   selector:     matchLabels:       app: httpd       name: svc2   strategy:     type: RollingUpdate   template:     metadata:       labels:         app: httpd         name: svc2     spec:       containers:       - name: httpd         image: httpd:latest         ports:         - name: http           containerPort: 80 

Aqui você definiu um Deployment do Kubernetes com a imagem de container httpd a ser deployada com 1 réplica, chamada svc2.

Salve e feche o arquivo.

Execute o seguinte comando para aplicar esta configuração:

  • kubectl apply -f svc2-deploy.yaml

Você verá esta saída:

Outputdeployment.extensions/svc2 created 

Finalmente, para o terceiro deployment, abra e crie o arquivo svc3-deploy.yaml:

  • nano svc3-deploy.yaml

Adicione as seguintes linhas ao arquivo:

svc3-deploy.yaml

apiVersion: extensions/v1beta1 kind: Deployment metadata:   name: svc3 spec:   replicas: 1   selector:     matchLabels:       app: httpbin       name: svc3   strategy:     type: RollingUpdate   template:     metadata:       labels:         app: httpbin         name: svc3     spec:       containers:       - name: httpbin         image: kennethreitz/httpbin:latest         ports:         - name: http           containerPort: 80 

Aqui você definiu um Deployment do Kubernetes com a imagem de container httpbin a ser deployada com 1 réplica, chamada svc3.

Salve e feche o arquivo.

Por fim, execute o seguinte comando para aplicar:

  • kubectl apply -f svc3-deploy.yaml

E você verá a seguinte saída:

Outputdeployment.extensions/svc3 created 

Você fez o deploy de três containers de servidor web usando deployments do Kubernetes. No próximo passo, você irá expor esses deployments ao tráfego da Internet.

Passo 3 — Expondo Apps Usando Serviços com as Anotações do Ambassador

Nesta seção, você irá expor suas aplicações web à Internet, criando os Serviços Kubernetes com Anotações do Ambassador para configurar regras para rotear o tráfego para eles. Annotations ou Anotações no Kubernetes são uma maneira de adicionar metadados aos objetos. O Ambassador usa esses valores de anotação dos serviços para configurar suas regras de roteamento.

Como lembrete, você precisa ter seus domínios (por exemplo: svc1.seu-domínio, svc2.seu-domínio e svc3.seu-domínio) mapeados para o IP público do balanceador de carga em seus registros DNS.

Defina um serviço Kubernetes para o deployment do svc1 com anotações do Ambassador, criando e abrindo este arquivo:

  • nano svc1-service.yaml

Nota: O nome do mapeamento deve ser exclusivo para cada bloco de anotação do Ambassador. O mapeamento atua como um identificador para cada bloco de anotação e, se repetido, ele irá sobrepor o bloco de anotação mais antigo.

svc1-service.yaml

apiVersion: v1 kind: Service metadata:   name: svc1   annotations:     getambassador.io/config: |       ---       apiVersion: ambassador/v1       kind: Mapping       name: svc1-service_mapping       host: svc1.seu-domínio       prefix: /       service: svc1:80 spec:   selector:     app: nginx     name: svc1   ports:   - name: http     protocol: TCP     port: 80 

Neste código YAML, você definiu um serviço Kubernetes svc1 usando anotações do Ambassador para mapear o nome do host svc1.seu-domínio para este serviço.

Salve e saia do arquivo svc1-service.yaml e execute o seguinte para aplicar esta configuração:

  • kubectl apply -f svc1-service.yaml

Você verá esta saída:

Outputservice/svc1 created 

Crie seu segundo serviço Kubernetes para o deployment do svc2 com anotações do Ambassador. Este é outro exemplo de roteamento baseado em host com o Ambassador:

  • svc2-service.yaml

Adicione a seguinte configuração ao arquivo:

svc2-service.yaml

apiVersion: v1 kind: Service metadata:   name: svc2   annotations:     getambassador.io/config: |       ---       apiVersion: ambassador/v1       kind: Mapping       name: svc2-service_mapping       host: svc2.seu-domínio       prefix: /       service: svc2:80 spec:   selector:     app: httpd     name: svc2   ports:   - name: http     protocol: TCP     port: 80 

Salve isso como svc2-service.yaml. Aqui, você definiu outro serviço Kubernetes usando anotações do Ambassador para rotear o tráfego para svc2 quando qualquer solicitação é recebida pelo Ambassador com o valor do cabeçalho host como svc2.seu-domínio. Portanto, esse roteamento baseado em host permitirá que você envie uma solicitação ao subdomínio svc2.seu-domínio, que encaminhará o tráfego para o serviço svc2 e servirá sua solicitação a partir do servidor web httpd.

Para criar este serviço, execute o seguinte:

  • kubectl apply -f svc2-service.yaml

Você verá a seguinte saída:

Outputservice/svc2 created 

Crie um terceiro serviço Kubernetes para seu deployment svc3 e sirva-o através do caminho svc2.seu-domínio/bin. Isso configurará o roteamento baseado em caminho para o Ambassador:

svc3-service.yaml

apiVersion: v1 kind: Service metadata:   name: svc3 spec:   selector:     app: httpbin     name: svc3   ports:   - name: http     protocol: TCP     port: 80 

Salve isso como svc3-service.yaml e execute o seguinte para aplicar a configuração:

  • kubectl apply -f svc3-service.yaml

Sua saída será:

Outputservice/svc3 created 

Edite svc2-service.yaml para acrescentar o segundo bloco de anotação do Ambassador para rotear o /bin para o serviço svc3:

  • nano svc2-service.yaml

svc2-service.yaml

apiVersion: v1 kind: Service metadata:   name: svc2   annotations:     getambassador.io/config: |       ---       apiVersion: ambassador/v1       kind: Mapping       name: svc2-service_mapping       host: svc2.seu-domínio       prefix: /       service: svc2:80       ---       apiVersion: ambassador/v1       kind: Mapping       name: svc3-service_mapping       host: svc2.seu-domínio       prefix: /bin       service: svc3:80 spec:   selector:     app: httpd     name: svc2   ports:   - name: http     protocol: TCP     port: 80 

Você adicionou o segundo bloco de anotação do Ambassador para configurar os caminhos que começam com /bin para mapear para o seu serviço Kubernetes svc3. Para rotear solicitações de svc2.seu-domínio/bin para svc3, você adicionou o segundo bloco de anotação aqui com o valor do host svc2.seu-domínio, que é o mesmo para os dois blocos. Portanto, o roteamento baseado em caminho permitirá que você envie uma solicitação ao svc2.seu-domínio/bin, que será recebido pelo serviço svc3 e servido pela aplicação httpbin neste tutorial.

Agora execute o seguinte para aplicar as alterações:

  • kubectl apply -f svc2-service.yaml

Você verá esta saída:

Outputservice/svc2 configured 

Você criou os Serviços Kubernetes para os três deployments e adicionou regras de roteamento com base no host e no caminho com as anotações do Ambassador. Em seguida, você adicionará configuração avançada a esses serviços para configurar o roteamento, o redirecionamento e cabeçalhos personalizados.

Passo 4 — Configurações Avançadas do Ambassador para Roteamento

Nesta seção, você irá configurar os serviços com mais anotações do Ambassador para modificar cabeçalhos e configurar redirecionamento.

Faça um curl no domínio svc1.seu-domínio e verifique os cabeçalhos de resposta:

  • curl -I svc1.seu-domínio

Sua saída será semelhante à seguinte:

OutputHTTP/1.1 200 OK server: envoy date: Mon, 17 Jun 2019 21:41:00 GMT content-type: text/html content-length: 612 last-modified: Tue, 21 May 2019 14:23:57 GMT etag: "5ce409fd-264" accept-ranges: bytes x-envoy-upstream-service-time: 0 

Esta saída mostra os cabeçalhos recebidos do serviço roteado usando o Ambassador. Você adicionará cabeçalhos personalizados à sua resposta de serviço usando as anotações do Ambassador e validará a saída para os novos cabeçalhos adicionados.

Para adicionar cabeçalhos personalizados à sua resposta de serviço, remova o cabeçalho x-envoy-upstream-service-time da resposta e adicione um novo cabeçalho de resposta x-geo-location: Brazil para o svc1. (Você pode alterar este cabeçalho conforme seus requisitos.)

Edite o arquivo svc1-service.yaml:

  • nano svc1-service.yaml

Atualize a anotação com as seguintes linhas destacadas:

svc1-service.yaml

apiVersion: v1 kind: Service metadata:   name: svc1   annotations:     getambassador.io/config: |       ---       apiVersion: ambassador/v1       kind: Mapping       name: svc1-service_mapping       host: svc1.example.com       prefix: /       remove_response_headers:       - x-envoy-upstream-service-time       add_response_headers:         x-geo-location: Brazil       service: svc1:80 spec:   selector:     app: nginx     name: svc1   ports:   - name: http     protocol: TCP     port: 80 

Aqui você modificou o serviço svc1 para remover x-envoy-upstream-service-time e adicionou o cabeçalho x-geo-location: Brazil na resposta HTTP.

Aplique as alterações que você fez:

  • kubectl apply -f svc1-service.yaml

Você verá a seguinte saída:

Outputservice/svc1 configured 

Agora execute curl para validar os cabeçalhos atualizados na resposta do serviço:

  • curl -I svc1.seu-domínio

A saída será semelhante a esta:

OutputHTTP/1.1 200 OK server: envoy date: Mon, 17 Jun 2019 21:45:26 GMT content-type: text/html content-length: 612 last-modified: Tue, 21 May 2019 14:23:57 GMT etag: "5ce409fd-264" accept-ranges: bytes x-geo-location: Brazil 

Agora edite o svc3-service.yaml para redirecionar solicitações para o seu nome de host svc3.seu-domínio para o caminho svc2.seu-domínio/bin:

  • nano svc3-service.yaml

Acrescente o bloco de anotação do Ambassador, conforme mostrado no YAML a seguir, e salve-o:

svc3-service.yaml

apiVersion: v1 kind: Service metadata:   name: svc3   annotations:     getambassador.io/config: |       ---       apiVersion: ambassador/v1       kind:  Mapping       name:  redirect_mapping       host: svc3.seu-domínio       prefix: /       service: svc2.seu-domínio       host_redirect: true       path_redirect: /bin spec:   selector:     app: httpbin     name: svc3   ports:   - name: http     protocol: TCP     port: 80 

Você adicionou host_redirect: true para configurar uma resposta de redirecionamento 301 de svc3 para svc2.seu-domínio/bin para o nome de host svc3.seu-domínio . O parâmetro host_redirect envia uma resposta de redirecionamento 301 para o cliente. Se não estiver definido, as requisições receberão respostas 200 HTTP em vez de respostas 301 HTTP.

Agora execute o seguinte comando para aplicar essas alterações:

  • kubectl apply -f svc3-service.yaml

Você verá uma saída semelhante a:

Outputservice/svc3 configured 

Agora você pode verificar a resposta para svc3.seu-domínio usando curl:

  • curl -I svc3.seu-domínio

Sua saída será semelhante à seguinte:

OutputHTTP/1.1 301 Moved Permanently location: http://svc2.seu-domínio/bin date: Mon, 17 Jun 2019 21:52:05 GMT server: envoy transfer-encoding: chunked 

A saída é um cabeçalho HTTP para a resposta da solicitação ao serviço svc3.seu-domínio mostrando que a configuração de host_redirect: true na anotação do serviço forneceu corretamente o código de status HTTP: 301 Moved Permanently.

Você configurou o serviço com anotações do Ambassador para modificar cabeçalhos HTTP e configurar redirecionamentos. Em seguida, você adicionará a configuração global ao serviço Ambassador API Gateway.

Passo 5 — Definindo Configurações Globais do Ambassador

Nesta seção, você editará o serviço Ambassador para adicionar a configuração global de compactação GZIP. A compactação GZIP compactará o tamanho dos assets HTTP e reduzirá os requisitos de largura de banda da rede, levando a tempos de resposta mais rápidos para os clientes web. Essa configuração afeta todo o tráfego que está sendo roteado pelo Ambassador API Gateway. Da mesma forma, você pode configurar outros módulos globais com o Ambassador, que permitem ativar comportamentos especiais para o serviço em nível global. Essas configurações globais podem ser aplicadas usando anotações do serviço Ambassador. Você pode consultar a documentação da Configuração Global do Ambassador para obter mais informações.

O seguinte comando kubectl edit abrirá o editor padrão, que é o vim. Para usar o nano, por exemplo, você pode definir a variável de ambiente KUBE_EDITOR como nano:

  • export KUBE_EDITOR="nano"

Edite o serviço Ambassador:

  • kubectl edit service ambassador

Agora adicione as linhas destacadas a um novo bloco de anotação para compactação GZIP:

Editing Ambassador Service

apiVersion: v1 kind: Service metadata:   annotations:     getambassador.io/config: |       ---       apiVersion: ambassador/v1       kind: Module       name: ambassador       config:         service_port: 8080       ---       apiVersion: ambassador/v0       kind:  Module       name:  ambassador       config:         gzip:           memory_level: 5           min_content_length: 256           compression_level: BEST           compression_strategy: DEFAULT           content_type:           - application/javascript           - application/json           - text/html           - text/plain           disable_on_etag_header: false           remove_accept_encoding_header: false   creationTimestamp: "2019-06-17T20:45:04Z"   labels:     app.kubernetes.io/instance: ambassador     app.kubernetes.io/managed-by: Tiller     app.kubernetes.io/name: ambassador     helm.sh/chart: ambassador-2.8.2   name: ambassador   namespace: default   resourceVersion: "2153"   . . . 

Você adicionou o bloco de anotação do Ambassador ao seu serviço Ambassador e configurou o GZIP globalmente para o API Gateway. Aqui você incluiu a configuração para controlar a quantidade de memória interna usada com memory_level, que pode ser um valor de 1 a 9. O compression_level configurado como BEST garante uma taxa de compactação mais alta, com o custo de uma latência mais alta. Com o min_content_length, você configurou o comprimento mínimo de resposta para 256 bytes. Para o content_type, você incluiu especificamente um conjunto de tipos de mídia (anteriormente MIME-types) que produz compactação. Finalmente, você adicionou as duas configurações finais como false para permitir a compactação.

Você pode ler mais sobre a compactação GZIP na página sobre GZIP do Envoy.

Quaisquer alterações neste serviço se aplicam como configurações globais para o API Gateway.

Depois de sair do editor, você verá uma saída semelhante à seguinte:

Outputservice/ambassador edited 

Verifique o svc1.seu-domínio usando o curl para ver o cabeçalho content-encoding tendo o valor gzip:

  • curl --compressed -i http://svc1.example.com

A saída será semelhante a esta:

OutputHTTP/1.1 200 OK server: envoy date: Mon, 17 Jun 2019 22:25:35 GMT content-type: text/html last-modified: Tue, 21 May 2019 14:23:57 GMT accept-ranges: bytes x-geo-location: Brazil vary: Accept-Encoding content-encoding: gzip transfer-encoding: chunked  <!DOCTYPE html> <html> <head> <title>Welcome to nginx!</title> <style>     body {         width: 35em;         margin: 0 auto;         font-family: Tahoma, Verdana, Arial, sans-serif;     } </style> </head> <body> <h1>Welcome to nginx!</h1> <p>If you see this page, the nginx web server is successfully installed and working. Further configuration is required.</p>  <p>For online documentation and support please refer to <a href="http://nginx.org/">nginx.org</a>.<br/> Commercial support is available at <a href="http://nginx.com/">nginx.com</a>.</p>  <p><em>Thank you for using nginx.</em></p> </body> </html> 

Aqui você pode ver a página HTML padrão do Nginx com seu cabeçalho de resposta, mostrando que o content-encoding da resposta recebida é compactação gzip.

Você adicionou a configuração global ao Ambassador para habilitar a configuração GZIP para respostas de tipos de conteúdo selecionados no API Gateway.

Conclusão

Você configurou com êxito um API Gateway para seu cluster Kubernetes usando o Ambassador. Agora você pode expor suas aplicações usando roteamento baseado em host e caminho, com cabeçalhos personalizados e a compactação GZIP global.

Para obter mais informações sobre as anotações do Ambassador e parâmetros de configuração, leia a documentação oficial do Ambassador.