One place for hosting & domains

      Ambassador

      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:

      Output

      Release "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:

      Output

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

      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:

      Output

      deployment.extensions/svc1 created

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

      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:

      Output

      deployment.extensions/svc2 created

      Finalmente, para o terceiro deployment, abra e crie o arquivo 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:

      Output

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

      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:

      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:

      Output

      service/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:

      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:

      Output

      service/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á:

      Output

      service/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:

      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:

      Output

      service/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:

      Output

      HTTP/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:

      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:

      Output

      service/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:

      Output

      HTTP/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:

      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:

      Output

      service/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:

      Output

      HTTP/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:

      Output

      service/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:

      Output

      HTTP/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.



      Source link

      How To Create an API Gateway Using Ambassador on DigitalOcean Kubernetes


      The author selected the Free and Open Source Fund to receive a donation as part of the Write for DOnations program.

      Introduction

      Ambassador is an API Gateway for cloud-native applications that routes traffic between heterogeneous services and maintains decentralized workflows. It acts as a single entry point and supports tasks like service discovery, configuration management, routing rules, and rate limiting. It provides great flexibility and ease of configuration for your services.

      Envoy is an open source service proxy designed for cloud-native applications. In Kubernetes, Ambassador can be used to install and manage Envoy configuration. Ambassador supports zero downtime configuration changes and integration with other features like authentication, service discovery, and services meshes.

      In this tutorial, you’ll set up an Ambassador API Gateway on a Kubernetes cluster using Helm and configure it for routing incoming traffic to various services based on routing rules. You’ll configure these rules to route the traffic based on hostname or path to the relevant services.

      Prerequisites

      Before you begin this guide you’ll need the following:

      Step 1 — Installing Ambassador

      In this section, you will install Ambassador on your Kubernetes cluster. Ambassador can be installed using a Helm chart or by passing a YAML configuration file to the kubectl command.

      Note: DigitalOcean Kubernetes has RBAC enabled by default, so when using a YAML configuration file for installation you need to ensure that you use the RBAC enabled one. You can find further details about deploying Amabassador to Kubernetes via YAML in Ambassador’s documentation.

      For the purposes of this tutorial, you’ll use a Helm chart to install Ambassador to your cluster. Having followed the prerequisites, you’ll have Helm installed to your cluster.

      To begin, run the following command to install Ambassador via Helm:

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

      You’ll see output similar to the following:

      Output

      Release "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 . . .

      This will create an Ambassador deployment, service, and a Load Balancer with your Kubernetes cluster nodes attached. You’ll need the Load Balancer’s IP to map it to your domain’s A records.

      To get the IP address of your Ambassador Load Balancer, run the following:

      • kubectl get svc --namespace default ambassador

      You’ll see output similar to:

      Output

      NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE ambassador LoadBalancer your_cluster_IP your-IP-address 80:30001/TCP,443:31557/TCP 8m4s

      Note the external IP your-IP-address in this step and map the domains (via your domain provider) svc1.your-domain, svc2.your-domain, and svc3.your-domain to point to this IP address.

      You can enable HTTPS with your DigitalOcean Load Balancer using the steps given at How to Configure SSL Termination. It is recommended to configure TLS termination via the Load Balancer. Another way of configuring TLS termination is using Ambassador’s TLS Support

      You’ve installed Ambassador on your Kubernetes cluster using Helm which created an Ambassador deployment with three replicas in the default namespace. This also created a Load Balancer with a public IP to route all traffic toward the API Gateway. Next you’ll create Kubernetes deployments for three different services that you’ll be using to test this API Gateway.

      Step 2 — Setting Up Web Server Deployments

      In this section, you’ll create three deployments to run three different web server containers. You’ll create YAML files with definitions of Kubernetes deployments for the three different web server containers and deploy them using kubectl.

      Open your preferred text editor to create your first deployment for an Nginx web server:

      Enter the following yaml configuration in your file:

      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
      

      Here you have defined a Kubernetes Deployment with the nginx:latest container image to be deployed with 1 replica, called svc1. The Deployment is defined to expose in-cluster at port 80.

      Save and close the file.

      Then run the following command to apply this configuration:

      • kubectl apply -f svc1-deploy.yaml

      You’ll see output confirming creation:

      Output

      deployment.extensions/svc1 created

      Now, create a second web server deployment. Open a file called svc2-deploy.yaml with:

      Enter the following YAML configuration in the file:

      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
      

      Here you have defined a Kubernetes Deployment with the httpd container image to be deployed with 1 replica, called svc2.

      Save and close the file.

      Run the following command to apply this configuration:

      • kubectl apply -f svc2-deploy.yaml

      You’ll see this output:

      Output

      deployment.extensions/svc2 created

      Finally for the third deployment, open and create the svc3-deploy.yaml file:

      Add the following lines to the file:

      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
      

      Here you have defined a Kubernetes Deployment with the httpbin container image to be deployed with 1 replica, called svc3.

      Save and close the file.

      Finally, run the following command to apply:

      • kubectl apply -f svc3-deploy.yaml

      And you’ll see the following output:

      Output

      deployment.extensions/svc3 created

      You’ve deployed three web server containers using Kubernetes deployments. In the next step, you will be exposing these deployments to internet traffic.

      Step 3 — Exposing Apps Using Services with Ambassador Annotations

      In this section, you will expose your web apps to the internet creating Kubernetes Services with Ambassador annotations to configure rules to route traffic to them. Annotations in Kubernetes are a way to add metadata to objects. Ambassador uses these annotation values from services to configure its routing rules.

      As a reminder you need to have your domains (for example: svc1.your-domain, svc2.your-domain, and svc3.your-domain) mapped to the Load Balancer’s public IP in your DNS records.

      Define a Kubernetes service for the svc1 deployment with Ambassador annotations by creating and opening this file:

      Note: The mapping name should be unique for every Ambassador annotation block. The mapping acts as an identifier for every annotation block and if repeated it will overlap the older annotation block.

      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.your-domain
            prefix: /
            service: svc1:80
      spec:
        selector:
          app: nginx
          name: svc1
        ports:
        - name: http
          protocol: TCP
          port: 80
      

      In this YAML code, you have defined a Kubernetes service svc1 with Ambassador annotations to map hostname svc1.your-domain to this service.

      Save and exit svc1-service.yaml, and then execute the following to apply this configuration:

      • kubectl apply -f svc1-service.yaml

      You’ll see this output:

      Output

      service/svc1 created

      Create your second Kubernetes service for svc2 deployment with Ambassador annotations. This is another example of host-based routing with Ambassador:

      Add the following configuration to the file:

      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.your-domain
            prefix: /
            service: svc2:80
      spec:
        selector:
          app: httpd
          name: svc2
        ports:
        - name: http
          protocol: TCP
          port: 80
      

      Save this as svc2-service.yaml. Here, you’ve defined another Kubernetes service with Ambassador annotations to route traffic to svc2 when any request is received by Ambassador with the host header value as svc2.your-domain. Therefore this host-based routing will allow you to send a request to the subdomain svc2.your-domain, which will route the traffic to the service svc2 and serve your request from httpd web server.

      To create this service, execute the following:

      • kubectl apply -f svc2-service.yaml

      You’ll see the following output:

      Output

      service/svc2 created

      Create a third Kubernetes service for your svc3 deployment and serve it via the path svc2.your-domain/bin. This will configure path-based routing for Ambassador:

      svc3-service.yaml

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

      Save this as svc3-service.yaml and run the following to apply the configuration:

      • kubectl apply -f svc3-service.yaml

      Your output will be:

      Output

      service/svc3 created

      Edit svc2-service.yaml to append the second Ambassador annotation block to route /bin to svc3 service:

      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.your-domain
            prefix: /
            service: svc2:80
            ---
            apiVersion: ambassador/v1
            kind: Mapping
            name: svc3-service_mapping
            host: svc2.your-domain
            prefix: /bin
            service: svc3:80
      spec:
        selector:
          app: httpd
          name: svc2
        ports:
        - name: http
          protocol: TCP
          port: 80
      

      You’ve added the second Ambassador annotation block to configure paths beginning with /bin to map to your svc3 Kubernetes service. In order to route requests for svc2.your-domain/bin to svc3, you have added the second annotation block here as the host value svc2.your-domain, which is the same for both of the blocks. Therefore path-based routing will allow you to send a request to svc2.your-domain/bin, which will be received by service svc3 and served by the httpbin application in this tutorial

      Now run the following to apply the changes:

      • kubectl apply -f svc2-service.yaml

      You’ll see this output:

      Output

      service/svc2 configured

      You have created Kubernetes Services for the three deployments and added host-based and path-based routing rules with Ambassador annotations. Next, you’ll add advanced configuration to these services to configure routing, redirection, and custom headers.

      Step 4 — Advanced Ambassador Configurations for Routing

      In this section, you will configure the services with further Ambassador annotations to modify headers and configure redirection.

      curl the domain svc1.your-domain and check the response headers:

      Your output will be similar to the following:

      Output

      HTTP/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

      This output shows the headers received from the service routed using Ambassador. You’ll add custom headers to your service response using Ambassador annotations and validate the output for new added headers.

      To add custom headers to your service response, remove the header x-envoy-upstream-service-time from the response and add a new response header x-geo-location: India for svc1. (You may change this header as per your requirements.)

      Edit the file svc1-service.yaml:

      Update the annotation with the following highlighted lines:

      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: India
            service: svc1:80
      spec:
        selector:
          app: nginx
          name: svc1
        ports:
        - name: http
          protocol: TCP
          port: 80
      

      Here you have modified the svc1 service to remove x-envoy-upstream-service-time and added the x-geo-location: India header in the HTTP response.

      Apply the changes you have made:

      • kubectl apply -f svc1-service.yaml

      You will see the following output:

      Output

      service/svc1 configured

      Now run curl to validate the updated headers in the service response:

      The output will be similar to this:

      Output

      HTTP/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: India

      Now edit svc3-service.yaml to redirect requests for your hostname svc3.your-domain to path svc2.your-domain/bin:

      Append the Ambassador annotation block as shown in the following YAML and save it:

      svc3-service.yaml

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

      You’ve added host_redirect: true to configure a 301 redirection response for svc3 to svc2.your-domain/bin for hostname svc3.your-domain. The host_redirect parameter sends a 301 redirection response to the client. If not set, the requests will receive 200 HTTP responses rather than 301 HTTP responses.

      Now run the following command to apply these changes:

      • kubectl apply -f svc3-service.yaml

      You will see similar output to:

      Output

      service/svc3 configured

      You can now check the response for svc3.your-domain using curl:

      Your output will be similar to the following:

      Output

      HTTP/1.1 301 Moved Permanently location: http://svc2.your-domain/bin date: Mon, 17 Jun 2019 21:52:05 GMT server: envoy transfer-encoding: chunked

      The output is a HTTP header for the request’s response to the service svc3.your-domainshowing that the configuration of host_redirect: true in your service annotation has correctly provided the HTTP status code: 301 Moved Permanently.

      You’ve configured the service with Ambassador annotations to modify HTTP headers and configure redirections. Next you will be adding global configuration to the Ambassador API Gateway service.

      Step 5 — Setting Up Ambassador Global Configurations

      In this section, you will edit the Ambassador service to add global GZIP compression configuration. GZIP compression will compress the HTTP assets size and reduce network bandwidth requirements leading to faster response times for the web clients. This configuration affects all the traffic being routed out through the Ambassador API Gateway. Similarly, you can configure other global modules with Ambassador, which let you enable special behaviors for Ambassador at a global level. These global configurations can be applied using annotations to the Ambassador service. You can refer to Ambassador’s Global Configuration documentation for further information.

      The following kubectl edit command will open the default editor, which is vim. To use nano, for example, you can set the environment variable KUBE_EDITOR to nano:

      • export KUBE_EDITOR="nano"

      Edit the Ambassador service:

      • kubectl edit service ambassador

      Now add the highlighted lines to a new annotation block for GZIP compression:

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

      You’ve added the Ambassador annotation block to your Ambassador service and configured GZIP globally for the API Gateway. Here you have included configuration to control the amount of internal memory used with memory_level, which can be a value from 1 to 9. The compression_level set at BEST ensures a higher compression rate at the cost of higher latency. With min_content_length you have configured the minimum response length to 256 bytes. For content_type you’ve specifically included a set of media types (formerly MIME-types) that yield compression. Finally you added the final two configurations as false to allow for compression.

      You can read more about GZIP compression on Envoy’s GZIP page.

      Any changes in this service apply as global configurations for the API Gateway.

      Once you have exited the editor you’ll see output similar to the following:

      Output

      service/ambassador edited

      Check svc1.your-domain using curl for the content-encoding header having value gzip:

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

      The output will be similar to this:

      Output

      HTTP/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: India 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>

      Here you can see the default HTML page of Nginx with its response header showing that content-encoding of the received response is gzip compressed.

      You’ve added global configuration to Ambassador to enable GZIP configuration for selected content type responses across the API Gateway.

      Conclusion

      You have successfully set up an API Gateway for your Kubernetes cluster using Ambassador. You are now able to expose your apps using host- and path-based routing, custom headers, and global GZIP compression.

      For further information about the Ambassador annotations and configuration parameters, read Ambassador’s official documentation.



      Source link