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