Ingress

Um objeto da API (do inglês "Application Programming Interface") que gerencia o acesso externo aos serviços em um cluster, normalmente HTTP.

Um Ingress pode fornecer balanceamento de carga, terminação SSL e hospedagem virtual baseada em nomes.

Terminologia

Para fins de clareza, este guia define os seguintes termos:

• Nó: Uma máquina de trabalho no Kubernetes, parte de um cluster.
• Cluster: Um conjunto de nós que executam aplicações em contêiner gerenciado pelo Kubernetes. Para este exemplo, e nas instalações mais comuns do Kubernetes, os nós no cluster não fazem parte da Internet pública.
• Roteador de borda: Um roteador que impõe a política de firewall para o seu cluster. Isso pode ser um gateway gerenciado por um provedor de nuvem ou um hardware físico.
• Rede do cluster: Um conjunto de links, lógicos ou físicos, que facilitam a comunicação dentro de um cluster de acordo com o modelo de rede do Kubernetes.
• Serviço: Um objeto serviço do Kubernetes que identifica um conjunto de Pods usando seletores de label. Salvo indicação em contrário, assume-se que os Serviços tenham IPs virtuais apenas roteáveis dentro da rede de cluster.

O que é o Ingress?

O Ingress expõe rotas HTTP e HTTPS de fora do cluster para um serviço dentro do cluster. O roteamento do tráfego é controlado por regras definidas no recurso Ingress.

Aqui está um exemplo simples em que o Ingress envia todo o seu tráfego para um serviço:

Um Ingress pode ser configurado para fornecer URLs acessíveis externamente aos serviços, balanceamento de carga de tráfego, terminação SSL/TLS e oferecer hospedagem virtual baseada em nome. Um controlador Ingress é responsável por atender o Ingress, geralmente com um balanceador de carga, embora também possa configurar seu roteador de borda ou frontends adicionais para ajudar a lidar com o tráfego.

Um Ingress não expõe portas ou protocolos arbitrários. Normalmente se usa um serviço do tipo Service.Type=NodePort ou Service.Type=LoadBalancer para expor serviços à Internet que não sejam HTTP e HTTPS.

Pré-requisitos

Você deve ter um controlador Ingress para satisfazer um Ingress. Apenas a criação de um recurso Ingress não tem efeito.

Você pode precisar instalar um controlador Ingress, como ingress-nginx. Você pode escolher entre vários controladores Ingress.

Idealmente, todos os controladores Ingress devem se encaixar na especificação de referência. Na realidade, os vários controladores Ingress operam de forma ligeiramente diferente.

O recurso Ingress

Um exemplo mínimo do recurso Ingress:

service/networking/minimal-ingress.yaml

apiVersion: networking.k8s.io/v1 kind: Ingress metadata:   name: minimal-ingress   annotations:     nginx.ingress.kubernetes.io/rewrite-target: / spec:   ingressClassName: nginx-example   rules:   - http:       paths:       - path: /testpath         pathType: Prefix         backend:           service:             name: test             port:               number: 80 

Um Ingress precisa dos campos apiVersion, kind, metadata e spec. O nome de um objeto Ingress deve ser um nome de subdomínio DNS válido. Para obter informações gerais sobre como trabalhar com arquivos de configuração, consulte como instalar aplicações, como configurar contêineres e como gerenciar recursos. O Ingress frequentemente usa anotações para configurar opções dependendo do controlador Ingress. Um exemplo deste uso é a anotação rewrite-target. Diferentes controladores Ingress suportam diferentes anotações. Revise a documentação do seu controlador Ingress escolhido para saber quais anotações são suportadas.

A especificação Ingress tem todas as informações necessárias para configurar um balanceador de carga ou servidor proxy. Mais importante ainda, ele contém uma lista de regras correspondentes a todas as solicitações recebidas. O recurso Ingress suporta apenas regras para direcionar o tráfego HTTP(S).

Se o ingressClassName for omitido, uma classe Ingress padrão deve ser definida.

Existem alguns controladores Ingress que funcionam sem a definição de uma IngressClass padrão. Por exemplo, o controlador Ingress-NGINX pode ser configurado com uma flag --watch-ingress-without-class. No entanto, recomenda-se especificar a IngressClass padrão, conforme mostrado abaixo.

Regras do Ingress

Cada regra HTTP contém as seguintes informações:

• Um host opcional. Neste exemplo, nenhum host é especificado, portanto, a regra se aplica a todo o tráfego HTTP de entrada através do endereço IP especificado. Se um host for fornecido (por exemplo, foo.bar.com), as regras se aplicam a esse host.
• Uma lista de caminhos (por exemplo, /testpath), cada um com um backend associado definido com um service.name e um service.port.name ou service.port.number. Tanto o host quanto o caminho devem corresponder ao conteúdo de uma solicitação recebida antes que o balanceador de carga direcione o tráfego para o serviço referenciado.
• Um backend é uma combinação de nomes de serviço e porta, conforme descrito na documentação de Services ou um backend de recursos personalizados por meio de um CRD. As solicitações HTTP e HTTPS para o Ingress que correspondem ao host e ao caminho da regra são enviadas para o backend listado.

Um defaultBackend geralmente é configurado em um controlador Ingress para atender a quaisquer solicitações que não correspondam a um caminho na especificação.

DefaultBackend

Um Ingress sem regras envia todo o tráfego para um único backend padrão e .spec.defaultBackend é o backend que deve lidar com as solicitações nesse caso. O defaultBackend é convencionalmente uma opção de configuração do controlador Ingress e não é especificado em seus recursos Ingress. Se nenhum .spec.rules for especificado, o .spec.defaultBackend deve ser especificado. Se o defaultBackend não for definido, o tratamento de solicitações que não correspondem a nenhuma das regras ficará a cargo do controlador de Ingress (consulte a documentação do seu controlador de Ingress para descobrir como ele lida com esse caso).

Se nenhum dos hosts ou caminhos corresponder à solicitação HTTP nos objetos Ingress, o tráfego será roteado para o seu backend padrão.

Resource backends

Um Resource backend é um ObjectRef para outro recurso Kubernetes dentro do mesmo namespace que o objeto Ingress. Um Resource é uma configuração mutuamente exclusiva com o serviço, e a validação irá falhar se ambos forem especificados. Um uso comum para um Resource backend é inserir dados em um backend de armazenamento de objetos com ativos estáticos.

service/networking/ingress-resource-backend.yaml

apiVersion: networking.k8s.io/v1 kind: Ingress metadata:   name: ingress-resource-backend spec:   defaultBackend:     resource:       apiGroup: k8s.example.com       kind: StorageBucket       name: static-assets   rules:     - http:         paths:           - path: /icons             pathType: ImplementationSpecific             backend:               resource:                 apiGroup: k8s.example.com                 kind: StorageBucket                 name: icon-assets 

Depois de criar o Ingress acima, você pode visualizá-lo com o seguinte comando:

kubectl describe ingress ingress-resource-backend 

Name:             ingress-resource-backend Namespace:        default Address: Default backend:  APIGroup: k8s.example.com, Kind: StorageBucket, Name: static-assets Rules:   Host        Path  Backends   ----        ----  --------   *               /icons   APIGroup: k8s.example.com, Kind: StorageBucket, Name: icon-assets Annotations:  <none> Events:       <none> 

Tipos de path HTTP

Cada caminho no Ingress deve ter um tipo de caminho correspondente. Os caminhos que não incluem um pathType explícito falharão na validação. Existem três tipos de caminho suportados:

• ImplementationSpecific: Com esse tipo de caminho, a correspondência depende da IngressClass. As implementações podem tratar isso como um pathType separado ou tratá-lo de forma idêntica aos tipos de caminho Prefix ou Exact.
• Exact: Corresponde exatamente ao caminho da URL podendo ser case-sensitive.
• Prefix: Corresponde com base em um prefixo de caminho de URL dividido por /. A correspondência faz distinção entre maiúsculas e minúsculas e é feita em um caminho, elemento por elemento. Um elemento de caminho refere-se à lista de labels no caminho dividido pelo separador /. Uma solicitação é uma correspondência para o caminho p se cada p for um prefixo elementar de p do caminho da solicitação.

Exemplos

Várias correspondências

Em alguns casos, vários caminhos dentro de uma entrada corresponderão a uma solicitação. Nesses casos, a precedência será dada primeiro ao caminho correspondente mais longo. Se dois caminhos ainda estiverem iguais, a precedência será dada aos caminhos com um tipo de caminho exato sobre o tipo de caminho de prefixo.

Hostname curingas

Os hosts podem ter correspondências precisas (por exemplo, “foo.bar.com”) ou um curinga (por exemplo, “*.foo.com”). Correspondências precisas exigem que o cabeçalho do host HTTP corresponda ao campo host. As correspondências curinga exigem que o cabeçalho do host HTTP seja igual ao sufixo da regra curinga.

service/networking/ingress-wildcard-host.yaml

apiVersion: networking.k8s.io/v1 kind: Ingress metadata:   name: ingress-wildcard-host spec:   rules:   - host: "foo.bar.com"     http:       paths:       - pathType: Prefix         path: "/bar"         backend:           service:             name: service1             port:               number: 80   - host: "*.foo.com"     http:       paths:       - pathType: Prefix         path: "/foo"         backend:           service:             name: service2             port:               number: 80 

Classe Ingress

Os Ingress podem ser implementados por diferentes controladores, muitas vezes com diferentes configurações. Cada Ingress deve especificar uma classe, uma referência a um recurso IngressClass que contém uma configuração adicional, incluindo o nome do controlador que deve implementar a classe.

service/networking/external-lb.yaml

apiVersion: networking.k8s.io/v1 kind: IngressClass metadata:   name: external-lb spec:   controller: example.com/ingress-controller   parameters:     apiGroup: k8s.example.com     kind: IngressParameters     name: external-lb 

O campo .spec.parameters de uma classe Ingress permite que você faça referência a outro recurso que fornece a configuração relacionada a essa classe Ingress.

O tipo específico de parâmetros a serem usados depende do controlador Ingress que você especificar no campo .spec.controller da classe Ingress.

Escopo da classe Ingress

Dependendo do seu controlador Ingress, os parâmetros definidos em todo o cluster ou apenas para um namespace poderão ser utilizados.

• Cluster
• Namespaced

--- apiVersion: networking.k8s.io/v1 kind: IngressClass metadata:   name: external-lb-1 spec:   controller: example.com/ingress-controller   parameters:     # Os parâmetros para esta classe Ingress são especificados em um     # ClusterIngressParameter (grupo de API k8s.example.net) nomeado     # "external-config-1". Esta definição diz ao Kubernetes para     # procurar um recurso de parâmetro com escopo de cluster.         scope: Cluster     apiGroup: k8s.example.net     kind: ClusterIngressParameter     name: external-config-1 

--- apiVersion: networking.k8s.io/v1 kind: IngressClass metadata:   name: external-lb-2 spec:   controller: example.com/ingress-controller   parameters:     # The parameters for this IngressClass are specified in an     # IngressParameter (API group k8s.example.com) named "external-config",     # that's in the "external-configuration" namespace.     scope: Namespace     apiGroup: k8s.example.com     kind: IngressParameter     namespace: external-configuration     name: external-config 

Anotação obsoleta

Antes que o recurso IngressClass e o campo ingressClassName fossem adicionados no Kubernetes 1.18, as classes Ingress foram especificadas com uma anotação kubernetes.io/ingress.class no Ingress. Esta anotação nunca foi formalmente definida, mas foi amplamente apoiada pelos controladores Ingress.

O campo ingressClassName mais recente no Ingress é um substituto para essa anotação, mas não é um equivalente direto. Embora a anotação tenha sido geralmente usada para fazer referência ao nome do controlador Ingress que deve implementar o Ingress, o campo é uma referência a um recurso IngressClass que contém a configuração Ingress adicional, incluindo o nome do controlador Ingress.

Classe Ingress Padrão

Você pode marcar uma classe Ingress específica como padrão para o seu cluster. Definir a anotação ingressclass.kubernetes.io/is-default-class como true em um recurso IngressClass garantirá que novos Ingress sem um campo ingressClassName especificado sejam atribuídos a esta ingressClassName padrão.

service/networking/default-ingressclass.yaml

apiVersion: networking.k8s.io/v1 kind: IngressClass metadata:   labels:     app.kubernetes.io/component: controller   name: nginx-example   annotations:     ingressclass.kubernetes.io/is-default-class: "true" spec:   controller: k8s.io/ingress-nginx 

Tipos de Ingress

Ingress fornecidos por um único serviço

No Kubernetes existem conceitos que permitem expor um único serviço (veja alternativas). Você também pode fazer isso com um Ingress especificando um backend padrão sem regras.

service/networking/test-ingress.yaml

apiVersion: networking.k8s.io/v1 kind: Ingress metadata:   name: test-ingress spec:   defaultBackend:     service:       name: test       port:         number: 80 

Se você criá-lo usando kubectl apply -f, você deve ser capaz de visualizar o estado do Ingress que você adicionou:

kubectl get ingress test-ingress 

NAME           CLASS         HOSTS   ADDRESS         PORTS   AGE test-ingress   external-lb   *       203.0.113.123   80      59s 

Onde 203.0.113.123 é o IP alocado pelo controlador Ingress para satisfazer o Ingress.

Simples fanout

Uma configuração de fanout roteia o tráfego de um único endereço IP para mais de um serviço, com base na URI HTTP que está sendo solicitada. Um Ingress permite que você mantenha o número de balanceadores de carga no mínimo. Por exemplo, uma configuração como:

exigiria um Ingress como:

service/networking/simple-fanout-example.yaml

apiVersion: networking.k8s.io/v1 kind: Ingress metadata:   name: simple-fanout-example spec:   rules:   - host: foo.bar.com     http:       paths:       - path: /foo         pathType: Prefix         backend:           service:             name: service1             port:               number: 4200       - path: /bar         pathType: Prefix         backend:           service:             name: service2             port:               number: 8080 

Quando você cria o Ingress com kubectl apply -f:

kubectl describe ingress simple-fanout-example 

Name:             simple-fanout-example Namespace:        default Address:          178.91.123.132 Default backend:  default-http-backend:80 (10.8.2.3:8080) Rules:   Host         Path  Backends   ----         ----  --------   foo.bar.com                /foo   service1:4200 (10.8.0.90:4200)                /bar   service2:8080 (10.8.0.91:8080) Events:   Type     Reason  Age                From                     Message   ----     ------  ----               ----                     -------   Normal   ADD     22s                loadbalancer-controller  default/test 

O controlador Ingress fornece um balanceador de carga específico de implementação que satisfaz o Ingress, desde que os serviços (service1, service2) existam. Quando tiver feito isso, você pode ver o endereço do balanceador de carga no campo Address.

Hospedagem virtual baseada em nome

Os hosts virtuais baseados em nomes suportam o roteamento de tráfego HTTP para vários nomes de host no mesmo endereço IP.

O Ingress a seguir diz ao balanceador de carga de apoio para rotear solicitações com base no Host header.

service/networking/name-virtual-host-ingress.yaml

apiVersion: networking.k8s.io/v1 kind: Ingress metadata:   name: name-virtual-host-ingress spec:   rules:   - host: foo.bar.com     http:       paths:       - pathType: Prefix         path: "/"         backend:           service:             name: service1             port:               number: 80   - host: bar.foo.com     http:       paths:       - pathType: Prefix         path: "/"         backend:           service:             name: service2             port:               number: 80 

Se você criar um recurso de Ingress sem nenhum host definido nas regras, qualquer tráfego da web para o endereço IP do seu controlador de Ingress pode ser correspondido sem que seja necessário um host virtual baseado em nome.

Por exemplo, o Ingress a seguir roteia o tráfego solicitado para first.bar.com para service1, second.bar.com para service2 e qualquer tráfego cujo cabeçalho de host de solicitação não corresponda a first.bar.com e second.bar.com para service3.

service/networking/name-virtual-host-ingress-no-third-host.yaml

apiVersion: networking.k8s.io/v1 kind: Ingress metadata:   name: name-virtual-host-ingress-no-third-host spec:   rules:   - host: first.bar.com     http:       paths:       - pathType: Prefix         path: "/"         backend:           service:             name: service1             port:               number: 80   - host: second.bar.com     http:       paths:       - pathType: Prefix         path: "/"         backend:           service:             name: service2             port:               number: 80   - http:       paths:       - pathType: Prefix         path: "/"         backend:           service:             name: service3             port:               number: 80 

TLS

Você pode configurar o uso de TLS no Ingress especificando um Secret que contém uma chave privada e um certificado TLS. O recurso Ingress suporta apenas uma única porta TLS, 443, e assume a terminação TLS no ponto de entrada (o tráfego para o Serviço e seus Pods não está criptografado o que é inseguro). Se a seção de configuração TLS em um Ingress especificar hosts diferentes, eles serão multiplexados na mesma porta de acordo com o nome do host especificado através da extensão SNI TLS (desde que o controlador Ingress suporte SNI). O objeto Secret do tipo TLS deve conter chaves chamadas tls.crt e tls.key que contêm o certificado e a chave privada a ser usada para TLS.

Por exemplo:

apiVersion: v1 kind: Secret metadata:   name: testsecret-tls   namespace: default data:   tls.crt: base64 encoded cert   tls.key: base64 encoded key type: kubernetes.io/tls 

Fazer referência a esse segredo em um Ingress diz ao controlador Ingress para proteger o canal do cliente para o balanceador de carga usando TLS. Você precisa ter certeza de que o objeto Secret do tipo TLS que você criou é originário de um certificado que contém um Nome Comum (Common Name, CN), também conhecido como Nome de Domínio Totalmente Qualificado (Fully Qualified Domain Name, FQDN), tal como https-example.foo.com.

service/networking/tls-example-ingress.yaml

apiVersion: networking.k8s.io/v1 kind: Ingress metadata:   name: tls-example-ingress spec:   tls:   - hosts:       - https-example.foo.com     secretName: testsecret-tls   rules:   - host: https-example.foo.com     http:       paths:       - path: /         pathType: Prefix         backend:           service:             name: service1             port:               number: 80 

Balanceador de carga

Um controlador Ingress é inicializado com algumas configurações de política de balanceamento de carga que se aplicam a todos os Ingress, como o algoritmo de balanceamento de carga, esquema de peso de backend e outros. Conceitos mais avançados de balanceamento de carga (por exemplo, sessões persistentes, pesos dinâmicos) ainda não estão expostos através do Ingress. Em vez disso, você pode obter esses recursos através do balanceador de carga usado para um serviço.

Também vale a pena notar que, embora as verificações de integridade não sejam expostas diretamente através do Ingress, existem conceitos paralelos no Kubernetes, como readiness probes, que permitem alcançar o mesmo resultado final. Revise a documentação específica do controlador para ver como eles lidam com as verificações de integridade (por exemplo: nginx ou GCE).

Atualizando um Ingress

Para atualizar um Ingress existente para adicionar um novo Host, você pode atualizá-lo editando o recurso:

kubectl describe ingress test 

Name:             test Namespace:        default Address:          178.91.123.132 Default backend:  default-http-backend:80 (10.8.2.3:8080) Rules:   Host         Path  Backends   ----         ----  --------   foo.bar.com                /foo   service1:80 (10.8.0.90:80) Annotations:   nginx.ingress.kubernetes.io/rewrite-target:  / Events:   Type     Reason  Age                From                     Message   ----     ------  ----               ----                     -------   Normal   ADD     35s                loadbalancer-controller  default/test 

kubectl edit ingress test 

Isso abre um editor com a configuração existente no formato YAML. Para incluir o novo host modifique:

spec:   rules:   - host: foo.bar.com     http:       paths:       - backend:           service:             name: service1             port:               number: 80         path: /foo         pathType: Prefix   - host: bar.baz.com     http:       paths:       - backend:           service:             name: service2             port:               number: 80         path: /foo         pathType: Prefix .. 

Depois de salvar suas alterações, o kubectl atualizará o recurso no servidor API, que diz ao controlador Ingress para reconfigurar o balanceador de carga.

Verifique isso:

kubectl describe ingress test 

Name:             test Namespace:        default Address:          178.91.123.132 Default backend:  default-http-backend:80 (10.8.2.3:8080) Rules:   Host         Path  Backends   ----         ----  --------   foo.bar.com                /foo   service1:80 (10.8.0.90:80)   bar.baz.com                /foo   service2:80 (10.8.0.91:80) Annotations:   nginx.ingress.kubernetes.io/rewrite-target:  / Events:   Type     Reason  Age                From                     Message   ----     ------  ----               ----                     -------   Normal   ADD     45s                loadbalancer-controller  default/test 

Você pode alcançar o mesmo resultado invocando kubectl replace -f em um arquivo Ingress YAML modificado.

Falha nas zonas de disponibilidade

Técnicas para distribuir o tráfego entre domínios de falha diferem entre os provedores de nuvem. Verifique a documentação do controlador Ingress para obter detalhes relevantes.

Alternativas

Você pode expor um serviço de várias maneiras que não envolve diretamente o recurso Ingress:

• Use Service.Type=LoadBalancer
• Use Service.Type=NodePort

Próximos passos

• Aprenda sobre a API Ingress
• Aprenda sobre controladores Ingress
• Configure o Ingress no Minikube usando o NGINX Controller