Adicionar uma porta de servidor a um cabeçalho de host

Por padrão, o Traefik lida com o cabeçalho Host de uma forma compatível com a maioria dos aplicativos modernos. Não é recomendável modificar o cabeçalho Host para incluir uma porta. Antes de fazer qualquer alteração, verifique como o Traefik lida com o cabeçalho por padrão e entenda em que situações é apropriado sobrescrevê-lo.

Tratamento padrão do cabeçalho “ Host ”

Por padrão, o Traefik encaminha o cabeçalho original “ Host ” com passHostHeader: true. Ele adiciona automaticamente os seguintes cabeçalhos de encaminhamento separados, em vez de incorporar a porta no cabeçalho Host :

• X-Forwarded-Host

• X-Forwarded-Port

Substituindo o cabeçalho Host para aplicativos legados

Se seu aplicativo precisar da porta incorporada no cabeçalho Host , use o middleware de cabeçalhos do Traefik para sobrescrevê-la.

# Example (Kubernetes Middleware)
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-header
spec:
  headers:
    customRequestHeaders:
      Host: "legacy-app.example:8080"

Aplique o middleware ao seu recurso Ingress usando a anotação “Traefik Ingress”. Certifique-se de que o processamento de CRD esteja habilitado (é a configuração padrão). Para configurar o processamento de CRDs, consulte o guia “ ibm-ingress-deploy-config ConfigMap processTraefikCRDs campo ”.

Encaminhamento de solicitações recebidas por meio de um ALB privado

Por padrão, os ALBs públicos processam recursos de entrada. Para redirecionar as solicitações recebidas por meio de um ALB privado, especifique a classe private-iks-traefik no campo spec.ingressClassName do seu recurso Ingress.

spec.ingressClassName: "private-iks-traefik"

Autenticação de aplicativos com App ID

Configure o Traefik Ingress com IBM Cloud App ID para aplicar a autenticação em seus aplicativos. Para obter mais informações, consulte “Adicionando a autenticaçã App ID a aos aplicativos ”.

Definição do tamanho máximo do corpo da solicitação do cliente

Por padrão, o Traefik não impõe um limite ao tamanho do corpo da solicitação do cliente. Para definir um limite máximo, crie um Middleware de Buffering e aplique-o ao seu recurso Ingress.

O Traefik rejeita qualquer solicitação que exceda o limite configurado com uma resposta 413 “ HTTP ”.

1. Crie um recurso de middleware de buffer do Traefik. Defina maxRequestBodyBytes como o número máximo de bytes que o cliente pode enviar. O exemplo a seguir define um limite de 2 MB (2.097.152 bytes).

   # Example (Kubernetes Middleware)
   apiVersion: traefik.io/v1alpha1
   kind: Middleware
   metadata:
     name: limit
   spec:
     buffering:
       maxRequestBodyBytes: 2097152
   

2. Aplique o middleware ao seu recurso Ingress usando a anotação “Traefik Ingress”.

Ativação do armazenamento em buffer dos dados de resposta do cliente

Por padrão, o Traefik transmite as respostas diretamente, sem armazenamento em buffer. Com o Buffering Middleware, o Traefik pode armazenar respostas na memória ou gravá-las no disco antes de enviá-las ao cliente. Utilize este middleware somente quando seu aplicativo precisar dele, pois o armazenamento em buffer de respostas não é recomendado na maioria dos casos.

Para ativar o buffer de respostas, siga estas etapas:

1. Crie um recurso de middleware de buffer do Traefik. Defina maxResponseBodyBytes como o tamanho máximo da resposta em bytes e memResponseBodyBytes como o limite acima do qual a resposta é gravada no disco, em vez de ser mantida na memória. O exemplo a seguir armazena em buffer até 5 MB no total, sendo que o primeiro 1 MB fica na memória.

   # Example (Kubernetes Middleware)
   apiVersion: traefik.io/v1alpha1
   kind: Middleware
   metadata:
     name: response-buffer
   spec:
     buffering:
       maxResponseBodyBytes: 5242880    # 5 MB max response size
       memResponseBodyBytes: 1048576    # 1 MB in memory, then disk
   

2. Aplique o middleware ao seu recurso Ingress usando a anotação “Traefik Ingress”.

Ajustando os tempos limite

O Traefik oferece dois tipos de controles de tempo limite: os tempos limite entre o cliente e o ALB e os tempos limite entre o ALB e seu aplicativo de back-end. Configure-os separadamente, dependendo de onde estiver o gargalo.

Para definir os tempos limite entre o cliente e o ALB, configure os campos correspondentes em ibm-ingress-deploy-config ConfigMap:

• Para definir por quanto tempo uma solicitação recebida em HTTP ou HTTPS aguarda a resposta da instância do Traefik, use os campos httpReadTimeout e httpsReadTimeout.
• Para definir o tempo máximo antes que a resposta expire, use os campos “ httpWriteTimeout ” e “ httpsWriteTimeout ”.
• Para configurar o tempo máximo durante o qual uma conexão keepalive permanece aberta antes de ser encerrada, utilize os campos “ httpIdleTimeout ” e “ httpsIdleTimeout ”.

Para definir o tempo limite de conexão e de leitura entre o ALB e seu aplicativo back-end, use ServersTransport para configurar o transporte entre o Traefik e seus servidores HTTP.

# Example (Kubernetes ServersTransport)
apiVersion: traefik.io/v1alpha1
kind: ServersTransport
metadata:
  name: mytransport
spec:
  forwardingTimeouts:
    dialTimeout: 30s
    responseHeaderTimeout: 10s
    idleConnTimeout: 90s

Para clusters VPC, você também deve modificar o tempo limite de inatividade da conexão no serviço de balanceador de carga que expõe seu ALB público. Substitua CLUSTER_ID pelo ID do seu cluster, que você pode obter acessando ibmcloud ks cluster get --cluster CLUSTER_NAME_OR_ID. O exemplo a seguir define o tempo limite para 910 segundos:

kubectl annotate svc -n kube-system public-cr<clusterid> service.kubernetes.io/ibm-load-balancer-cloud-provider-vpc-idle-connection-timeout="910"

O Traefik aceita o valor “ 0 ” para seus tempos limite, o que desativa o tempo limite.

A anotação ibm-load-balancer-cloud-provider-vpc-idle-connection-timeout no balanceador de carga do VPC não aceita o valor zero. Você pode definir um valor de tempo limite entre 50 segundos e 7.200 segundos (2 horas). Caso precise de um prazo superior a 2 horas, abra um ticket de suporte e apresente a justificativa comercial.

Se seus clusters estiverem expostos por meio do IBM Cloud Internet Services (CIS) ou do Cloudflare com o Web Application Firewall (WAF) ou o balanceamento de carga global ativado, defina esses tempos limite para mais de 900 segundos. Para obter mais informações, consulte a documentação da Cloudflare.

Depois de criar o recurso ServersTransport , aplique-o ao seu recurso Service usando a anotação Traefik Service.

Personalização de ações em caso de erro

Para definir ações personalizadas que o ALB pode executar em caso de erros específicos do HTTP, configure o Traefik Errors Middleware. Depois de criar o middleware, aplique-o ao seu recurso Ingress usando a anotação Traefik Ingress.

Alteração das portas padrão HTTP e HTTPS

Por padrão, os ALBs ficam à escuta na porta 80 para HTTP e na porta 443 para HTTPS. Se o seu cluster exigir portas não padrão, você pode alterar esses valores para cada ALB usando os campos “ httpPort ” e “ httpsPort ” na página “ ibm-ingress-deploy-config ” ConfigMap.

Personalização do cabeçalho da solicitação

Use o middleware de cabeçalhos do Traefik para adicionar, sobrescrever ou remover campos de cabeçalho de uma solicitação do cliente antes de encaminhá-la para seu aplicativo de back-end. Isso é útil para inserir informações de contexto, como nomes de scripts, identificadores de locatário ou outros metadados de que seu aplicativo necessita.

# Example (Kubernetes Middleware)
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-header
spec:
  headers:
    customRequestHeaders:
      X-Script-Name: "test"

Depois de criar o middleware, aplique-o ao seu recurso Ingress usando a anotação Traefik Ingress.

Personalização do cabeçalho de resposta

Use o middleware de cabeçalhos do Traefik para adicionar, sobrescrever ou remover campos de cabeçalho de uma resposta antes de enviá-la ao cliente. Isso é útil para aplicar políticas de segurança, adicionar cabeçalhos CORS ou remover cabeçalhos internos antes que eles cheguem ao cliente.

# Example (Kubernetes Middleware)
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-header
spec:
  headers:
    customResponseHeaders:
      X-Custom-Response-Header: "value"

Depois de criar o middleware, aplique-o ao seu recurso Ingress usando a anotação Traefik Ingress.

Redirecionamento de solicitações não seguras

Para garantir que o acesso seja feito exclusivamente por meio de HTTPS e redirecionar permanentemente todas as solicitações recebidas em HTTP para o endpoint HTTPS, defina o campo httpsRedirect no ibm-ingress-deploy-config ConfigMap.

Ativação e desativação da Segurança de Transporte Rigorosa ( HTTP )

HTTP A Segurança de Transporte Rigorosa ( HSTS ) determina que os navegadores acessem um domínio apenas por meio de HTTPS, impedindo ataques de downgrade de protocolo. Esse recurso é opcional no Traefik. Habilite essa função utilizando o Middleware de Cabeçalhos com os campos stsSeconds, stsIncludeSubdomains e stsPreload.

# Example (Kubernetes Middleware) - produces: Strict-Transport-Security: max-age=31536000; includeSubDomains; preload
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: security-headers
spec:
  headers:
    stsSeconds: 31536000            # max-age=1 year
    stsIncludeSubdomains: true
    stsPreload: true

Aplique o middleware ao seu recurso Ingress usando a seguinte anotação do Traefik Ingress.

Modificando a forma como o ALB mapeia o URI da solicitação

Por padrão, o Traefik usa o comparador “ PathPrefix ” para rotear as solicitações. Se seu aplicativo exigir correspondência exata de caminho ou roteamento baseado em expressões regulares, substitua o comparador usando a seguinte anotação do Traefik Ingress.

traefik.ingress.kubernetes.io/router.pathmatcher: PathRegexp

Configurando a autenticação mútua

A autenticação mútua TLS ( mTLS ) exige que tanto o servidor quanto o cliente apresentem certificados válidos, proporcionando uma autenticação mais robusta do que a padrão TLS. Para exigir a autenticação por certificado do cliente no seu ALB, crie um recurso TLSOption que faça referência ao segredo do certificado da sua CA.

# Example (Kubernetes TLSOption)
apiVersion: traefik.io/v1alpha1
kind: TLSOption
metadata:
  name: mtls
  namespace: default
spec:
  minVersion: VersionTLS12
  clientAuth:
    secretNames:
      - my-ca-secret
    clientAuthType: RequireAndVerifyClientCert

Depois de criar o recurso TLSOption, aplique-o ao seu recurso Ingress usando a anotação Traefik Ingress.

Configurando o comportamento de repetição de tentativas para solicitações de upstream

Quando um servidor back-end não responde, o Traefik pode automaticamente tentar novamente a solicitação em outro servidor upstream. Configure o comportamento de repetição de tentativas usando o middleware de repetição do Traefik. Depois de criar o middleware, aplique-o ao seu recurso Ingress usando a anotação Traefik Ingress.

Limitação de taxa

A limitação de taxa protege seus aplicativos de back-end contra picos de tráfego e uso indevido, limitando o número de solicitações que o ALB processa dentro de um intervalo de tempo. Configure a limitação de taxa usando o Traefik RateLimit Middleware. Depois de criar o middleware, aplique-o ao seu recurso Ingress usando a anotação Traefik Ingress.

Reescrita de caminhos

A reescrita de caminho permite expor um caminho público URL diferente do caminho no qual seu aplicativo de back-end fica à escuta. Por exemplo, você pode redirecionar as solicitações que chegam a /app para um aplicativo de back-end que escuta em /. Utilize um dos seguintes recursos do Traefik, dependendo se você precisa de uma substituição fixa ou de uma substituição baseada em padrões:

• O recurso “ ReplacePath Middleware ” do Traefik
• O recurso “ ReplacePathRegex Middleware ” do Traefik

# Example Replace the path with /foo
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-replacepath
spec:
  replacePath:
    path: "/foo"

# Example Replace path with regex
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-replacepathregex
spec:
  replacePathRegex:
    regex: "^/foo/(.*)"
    replacement: "/bar/$1"

Aplique o middleware ao seu recurso Ingress usando a seguinte anotação do Traefik Ingress.

Roteamento de tráfego com cookies “sticky”

As sessões persistentes garantem que as solicitações de um cliente sejam sempre encaminhadas para o mesmo servidor de back-end durante toda a duração da sessão. Isso é útil para aplicativos com estado que armazenam dados de sessão localmente no servidor. Habilite as sessões persistentes configurando a anotação de cookie “sticky” do Traefik Service no seu recurso Ingress.

Criptografando o tráfego entre seu aplicativo e o ALB

Por padrão, o Traefik redireciona o tráfego para seu aplicativo back-end por meio de HTTP. Se seu aplicativo exigir conexões upstream criptografadas, use um ServersTransport recurso para configurar um TLS o entre o ALB e seu aplicativo, incluindo o certificado da CA e o nome do servidor esperado.

# Example (Kubernetes ServersTransport)
apiVersion: traefik.io/v1alpha1
kind: ServersTransport
metadata:
  name: backend-transport
spec:
  rootCAs:
    - secret: my-ca-cert
  serverName: <myapp.example.com> # must match your certificate

Aplique a anotação “ ServersTransport ” ao seu recurso de serviço utilizando a seguinte anotação do Traefik Service.

Customizando a implementação do ALB

O ibm-ingress-deploy-config ConfigMap controla as configurações no nível do ALB, como o número de réplicas, portas, nível de log, valores de tempo limite e provedor de Ingress. Use este ConfigMap para aplicar alterações de configuração a um ou mais ALBs em seu cluster sem modificar recursos Ingress individualmente.

1. Obtenha os nomes dos serviços que expõem cada ALB. Anote os nomes dos serviços, pois você os utilizará nas etapas a seguir.

   • Clusters clássicos:

       kubectl get svc -n kube-system | grep alb
       ```
   * Clusters de VPC: na saída, procure um nome de serviço que seja formatado como `public-crc204dl7w0qf6n6sp7tug`.
   
   ```sh {: pre}
       kubectl get svc -n kube-system | grep LoadBalancer
       ```
   

2. Crie um arquivo YAML para um configmap do ibm-ingress-deploy-config. Para cada ID do ALB, é possível especificar uma ou mais das configurações opcionais a seguir. Você só precisa incluir as configurações que deseja definir.

   apiVersion: v1
   kind: ConfigMap
   metadata:
     name: ibm-ingress-deploy-config
     namespace: kube-system
   data:
     <alb1-id>: '{"replicas":<number_of_replicas>, "ingressClass":"<class>", "httpsPort":"<port>", "httpPort":"<port>", "logLevel": "<TRACE|DEBUG|INFO|WARN|ERROR|FATAL|PANIC>", "ingressProvider": "<ingress|ingress-nginx>", "processTraefikCRDs": <true|false>, "traefikIngressNginxAllowExternalNameServices": <true|false>, "traefikCRDAllowCrossNamespace": <true|false>, "traefikCRDAllowExternalNameServices": <true|false>, "httpReadTimeout": <seconds>, "httpWriteTimeout": <seconds>, "httpIdleTimeout": <seconds>, "httpsReadTimeout": <seconds>, "httpsWriteTimeout": <seconds>, "httpsIdleTimeout": <seconds>, "httpsRedirect": <true|false>, "customEntryPoints": {"<name>": {"port": <port>, "protocol": "<TCP|UDP>", "readTimeout": <seconds|0>, "writeTimeout": <seconds|0>, "idleTimeout": <seconds|0>, "udpTimeout": <seconds>}}, "tolerations": [{"key":"<key>","operator":"<Equal|Exists>","value":"<value>","effect":"<NoSchedule|PreferNoSchedule|NoExecute>"}]}'
     <alb2-id>: '{"replicas":<number_of_replicas>, "ingressClass":"<class>", "httpsPort":"<port>", "httpPort":"<port>", "logLevel": "<TRACE|DEBUG|INFO|WARN|ERROR|FATAL|PANIC>", "ingressProvider": "<ingress|ingress-nginx>", "processTraefikCRDs": <true|false>, "traefikIngressNginxAllowExternalNameServices": <true|false>, "traefikCRDAllowCrossNamespace": <true|false>, "traefikCRDAllowExternalNameServices": <true|false>, "httpReadTimeout": <seconds>, "httpWriteTimeout": <seconds>, "httpIdleTimeout": <seconds>, "httpsReadTimeout": <seconds>, "httpsWriteTimeout": <seconds>, "httpsIdleTimeout": <seconds>, "httpsRedirect": <true|false>, "customEntryPoints": {"<name>": {"port": <port>, "protocol": "<TCP|UDP>", "readTimeout": <seconds|0>, "writeTimeout": <seconds|0>, "idleTimeout": <seconds|0>, "udpTimeout": <seconds>}}, "tolerations": [{"key":"<key>","operator":"<Equal|Exists>","value":"<value>","effect":"<NoSchedule|PreferNoSchedule|NoExecute>"}]}'
   

   replicas

   Por padrão, cada ALB possui duas réplicas. Aumente as capacidades de processamento de ALB, aumentando o número de pods de ALB. Para obter mais informações, consulte Aumentando o número de réplicas do pod do ALB.

   ingressClass

   Se você especificou uma classe diferente de public-iks-traefik ou private-iks-traefik no seu recurso Ingress, insira o nome da classe aqui.

   httpPort, httpsPort

   Exponha portas não padrão para o ALB do Ingress incluindo as portas HTTP ou HTTPS que você deseja abrir.

   Valores padrão: 80/443.

   logLevel

   Especifique o nível de registro. Escolha entre: TRACE, DEBUG, INFO, WARN, ERROR, FATAL, PANIC.

   Padrão: INFO.

   ingressProvider

   Especifique qual provedor do Traefik Ingress deve ser usado para este ALB. Valores válidos:

   ingress: Utiliza o controlador de entrada do próprio Traefik. Ele processa anotações específicas do Traefik nos recursos do Ingress.

   ingress-nginx: Utiliza um arquivo temporário camada de compatibilidade para o Ingress —NGINX no Traefik. Ele processa anotações criadas para o Ingress — NGINX — e imita o comportamento do Ingress — NGINX — sempre que possível. Use esse valor para facilitar a migração do Ingress ( NGINX ) para o Traefik.

   Padrão: ingress.

   processTraefikCRDs

   Quando configurado como “ true ”, o Traefik processa seus próprios recursos CRD, além dos recursos do Ingress. Os CRDs compatíveis incluem IngressRoute, Middleware e TLSOption. Para ver a lista completa, consulte a documentação do Traefik sobre CRDs.

   Padrão: true.

   traefikIngressNginxAllowExternalNameServices

   Habilita o suporte aos serviços do ExternalName para objetos do Ingress que são processados pelo provedor ingress-nginx. Essa opção se aplica apenas quando a opção “ ingressProvider ” está definida como “ ingress-nginx ”.

   Padrão: true.

   traefikCRDAllowCrossNamespace

   Permite que os recursos do IngressRoute (CRD do Traefik) façam referência a recursos em outros namespaces.

   Padrão: false.

   traefikCRDAllowExternalNameServices

   Permite que os recursos do IngressRoute (CRD do Traefik) façam referência aos serviços do ExternalName.

   Padrão: false.

   httpReadTimeout, httpsReadTimeout

   Configura o tempo limite de leitura de HTTP / HTTPS entre o ALB e o cliente. O valor deve ser um número inteiro de segundos; definir esse valor como zero desativa o tempo limite.

   Para obter mais informações, consulte a documentação do Traefik.

   httpWriteTimeout, httpsWriteTimeout

   Configura o tempo limite de gravação HTTP / HTTPS entre o ALB e o cliente. O valor deve ser um número inteiro de segundos; definir esse valor como zero desativa o tempo limite.

   Para obter mais informações, consulte a documentação do Traefik.

   httpIdleTimeout, httpsIdleTimeout

   Configura o tempo limite de inatividade (keepalive) HTTP / HTTPS entre o ALB e o cliente. O valor deve ser um número inteiro de segundos; definir esse valor como zero desativa o tempo limite.

   Para obter mais informações, consulte a documentação do Traefik.

   Se você utilizar o IBM Cloud Internet Services (CIS) ou o Cloudflare com o Web Application Firewall (WAF) ou o balanceamento de carga global, configure esse valor para mais de 900 segundos. Para obter mais informações, consulte “ Ajustando os tempos limite ”.

   httpsRedirect

   Ativa um redirecionamento permanente de todas as solicitações recebidas em HTTP para o endpoint HTTPS.

   Padrão: false.

   customEntryPoints

   Especifica pontos de entrada personalizados adicionais para o Traefik. O nome do ponto de entrada será a chave do objeto. Os seguintes nomes de pontos de entrada estão reservados e não podem ser utilizados: web, websecure, traefik, hc, http e https.

   Caso a configuração do ponto de entrada esteja inválida, nenhum dos pontos de entrada personalizados será processado!

   customEntryPoints.<name>.port

   Porta do ponto de entrada a ser utilizada. Este campo é obrigatório. Certifique-se de que não haja conflito com outras portas.

   A porta e o protocolo definidos aqui devem ser configurados manualmente no Balanceador de Carga; veja abaixo as instruções.

   customEntryPoints.<name>.protocol

   Protocolo do ponto de entrada a ser utilizado. Este campo é obrigatório. Os valores válidos são TCP e UDP.

   customEntryPoints.<name>.readTimeout

   Configura o tempo limite de leitura do ponto de entrada, entre o ALB e o cliente. O valor deve ser um número inteiro de segundos; ao defini-lo como zero, o tempo limite é desativado.

   Para obter mais informações, consulte a documentação do Traefik.

   customEntryPoints.<name>.writeTimeout

   Configura o tempo limite de gravação do ponto de entrada entre o ALB e o cliente. O valor deve ser um número inteiro de segundos; ao defini-lo como zero, o tempo limite é desativado.

   Para obter mais informações, consulte a documentação do Traefik.

   customEntryPoints.<name>.idleTimeout

   Configura o tempo limite de inatividade (keepalive) do ponto de entrada entre o ALB e o cliente. O valor deve ser um número inteiro de segundos; ao defini-lo como zero, o tempo limite é desativado.

   Para obter mais informações, consulte a documentação do Traefik.

   customEntryPoints.<name>.udpTimeout

   Configura o tempo limite de inatividade do ponto de entrada para o ouvinte UDP. Este campo só é considerado para endpoints que utilizam o protocolo UDP. O valor deve ser um número inteiro de segundos e maior que zero.

   Para obter mais informações, consulte a documentação do Traefik.

   tolerations

   Especifica tolerâncias personalizadas adicionais para os pods do ALB. Para obter mais informações, consulte “Contaminações e Tolerâncias ”.

3. Crie o configmap ibm-ingress-deploy-config em seu cluster.

   kubectl create -f ibm-ingress-deploy-config.yaml
   

4. Atualize seus ALBs para aplicar as alterações. As alterações podem levar até cinco minutos para entrarem em vigor. Se o comando for executado sem exibir nenhuma saída, a atualização foi enviada com sucesso.

   ibmcloud ks ingress alb update -c CLUSTER_NAME_OR_ID
   

5. Se você tiver especificado endereços HTTP e HTTPS fora do padrão ou portas, ou se tiver criado pontos de entrada adicionais, será necessário abrir as portas em cada serviço ALB.

   1. Para cada serviço do ALB que você localizou na etapa 1, edite o arquivo YAML.

       kubectl edit svc -n kube-system <alb_svc_name>
       ```
   2. Na seção `spec.ports`, inclua as portas que você deseja abrir. Por padrão, as portas 80 e 443 ficam abertas. Para manter a 80 e a 443 abertas, não as remova deste arquivo. Qualquer porta que não esteja especificada é encerrada. Não especifique um `nodePort`. Depois de incluir a porta e aplicar as mudanças, um `nodePort` é designado automaticamente.
   
   ```sh {: codeblock}
       ...
       ports:
       - name: port-80
         port: 80
         protocol: TCP
         targetPort: 80
       - name: port-443
         port: 443
         protocol: TCP
         targetPort: 443
       - name: <new_port>
         port: <port>
         protocol: TCP
         targetPort: <port>
       ...
       ```
   3. Salve e feche o arquivo. As suas mudanças são aplicadas automaticamente.
   
   

Customizando a classe do Ingress

Uma classe do Ingress associa um nome de classe a um tipo de controlador do Ingress, permitindo que vários controladores coexistam no mesmo cluster. Use o IngressClass recurso para definir uma classe personalizada para seus ALBs.

O Traefik processa apenas as classes de Ingress nas quais .spec.controller está definido como traefik.io/ingress-controller``.

Incluindo a autenticação do App ID em apps

Proteja seus aplicativos contra acessos não autenticados integrando IBM Cloud App ID ao seu Ingress ALB. Quando a autenticação está configurada, o ALB encaminha as solicitações por meio de um servidor de autenticação ( OAuth2-Proxy ), que valida as credenciais com o servidor de autenticação ( App ID ) antes de encaminhar o tráfego para o seu aplicativo.

1. Escolha uma instância do App ID existente ou crie uma nova.

   Uma instância do App ID pode ser usada em apenas um namespace em seu cluster. Para configurar o App ID para recursos do Ingress em diversos namespaces, repita as etapas nesta seção para especificar uma instância exclusiva do App ID para os recursos do Ingress em cada namespace.

   • Para usar uma instância existente, certifique-se de que o nome da instância do serviço contenha apenas caracteres alfanuméricos em letras minúsculas e que seu comprimento não exceda 25 caracteres. Para mudar o nome, selecione Renomear serviço no menu de mais opções na página de detalhes da instância de serviço.
   • Para provisionar uma nova instância do App ID:
     1. Substitua o Nome do serviço pelo seu próprio nome exclusivo para a instância de serviço. O nome da instância do serviço deve conter apenas caracteres alfanuméricos em letras minúsculas e não pode ter mais de 25 caracteres.
     2. Escolha a mesma região na qual seu cluster está implementado.
     3. Clique em Criar.

2. Inclua URLs de redirecionamento para seu app. Uma URL de redirecionamento é o terminal de retorno de chamada de seu app. Para evitar ataques de phishing, o IBM Cloud App ID valida a URL de solicitação com relação à lista de permissões de URLs de redirecionamento.

   1. No console de gerenciamento do App ID, navegue para Gerenciar autenticação.
   2. Na guia Provedores de identidade, certifique-se de que você tenha um Provedor de identidade selecionado. Se nenhum provedor de identidade for selecionado, você não será autenticado, mas receberá um token de acesso para acessar o aplicativo de forma anônima.
   3. Na guia Configurações de autenticação, inclua URLs de redirecionamento para o app no formato https://<hostname>/oauth2-<App_ID_service_instance_name>/callback. Todas as letras no nome da instância do serviço devem estar em minúsculas.

   Se você utilizar a função de logout do IBM Cloud App ID, acrescente /sign_out ao seu domínio no formato https://<hostname>/oauth2-<App_ID_service_instance_name>/sign_out e inclua este endereço URL na lista de URLs de redirecionamento. Para usar uma página personalizada de logout, defina whitelist_domains na seção OAuth2-Proxy ConfigMap. Chame o endpoint https://<hostname>/oauth2-<App_ID_service_instance_name>/sign_out com o parâmetro de consulta rd ou defina o cabeçalho X-Auth-Request-Redirect com o URL da sua página de logout personalizada URL. Para obter mais informações, consulte “Sair ”.

3. Ligue a instância de serviço do App ID ao seu cluster. O comando cria uma chave de serviço para a instância do serviço; alternativamente, você pode incluir a opção --key para usar as credenciais da chave de serviço já existentes. Vincule a instância do serviço ao mesmo namespace em que estão seus recursos do Ingress. Todas as letras no nome da instância do serviço devem estar em minúsculas.

   ibmcloud ks cluster service bind --cluster CLUSTER_NAME_OR_ID --namespace NAMESPACE --service APP_ID_SERVICE_INSTANCE_NAME [--key SERVICE_INSTANCE_KEY]
   

   Quando o serviço for vinculado com sucesso ao seu cluster, será criado um segredo do cluster que contém as credenciais da instância do seu serviço. O exemplo a seguir mostra a saída:

   ibmcloud ks cluster service bind --cluster mycluster --namespace mynamespace --service appid1
   Binding service instance to namespace...
   OK
   Namespace:    mynamespace
   Secret name:  binding-<service_instance_name>
   

4. Ative o complemento ALB OAuth Proxy em seu cluster. Este complemento cria e gerencia os seguintes recursos do Kubernetes: uma implantação do OAuth2-Proxy para sua instância do serviço App ID, um segredo que contém a configuração do OAuth2-Proxy e um recurso Ingress que encaminha as solicitações recebidas para a implantação do OAuth2-Proxy. O nome de cada recurso começa com oauth2-.

   1. Ative o complemento alb-oauth-proxy.

       ibmcloud ks cluster addon enable alb-oauth-proxy --cluster CLUSTER_NAME_OR_ID
       ```
   2. Verifique se o complemento ALB OAuth Proxy tem um status de `Addon Ready`. Aguarde alguns minutos e execute o comando novamente se o status for “ `Enabling` ”.
   ```sh {: pre}
       ibmcloud ks cluster addon ls --cluster CLUSTER_NAME_OR_ID
       ```
   

5. Nos recursos do Ingress para aplicativos nos quais você deseja adicionar uma autenticaçã App ID, certifique-se de que o nome do recurso não exceda 25 caracteres. Em seguida, configure o middleware “ ForwardAuth ”:

   1. Crie um recurso “ ForwardAuth Middleware ” no Traefik. O arquivo address especifica o URL do OAuth2-Proxy para sua instância do App ID, que atua como a Parte Confiável (RP) do OIDC. Todas as letras no nome da instância do serviço devem estar em minúsculas.

       apiVersion: traefik.io/v1alpha1
       kind: Middleware
       metadata:
         name: oauth-verify
         namespace: default
       spec:
         forwardAuth:
           address: "https://oauth2-<App_ID_service_instance_name>.<namespace_of_Ingress_resource>.svc.cluster.local/oauth2-<App_ID_service_instance_name>/auth"
           tls:
             insecureSkipVerify: true
       ```
       Por padrão, o Traefik valida nomes alternativos de sujeito (SANs) de IP do tipo TLS. IBM- Espera-se que os certificados fornecidos não sejam aprovados nessa validação; portanto, use a opção “ `insecureSkipVerify: true` ”. Essa configuração garante que a instância do Traefik, ou ALB, possa se comunicar com as instâncias de implantação do `oauth2-proxy`.
       {: note}
   
   2. Escolha quais tokens enviar no cabeçalho `Authorization` para o seu app. Para obter mais informações sobre ID e tokens de acesso, consulte a [Documentação do App ID](/docs/appid?topic=appid-tokens).
       * Para enviar apenas o ` `ID Token``, adicione a opção ` `authResponseHeaders` ` ao seu middleware ` ForwardAuth `:
   
           ```yaml {: codeblock}
           apiVersion: traefik.io/v1alpha1
           kind: Middleware
           metadata:
             name: oauth-verify
             namespace: default
           spec:
             forwardAuth:
               address: "https://oauth2-<App_ID_service_instance_name>.<namespace_of_Ingress_resource>.svc.cluster.local/oauth2-<App_ID_service_instance_name>/auth"
               authResponseHeaders:
                 - Authorization
               tls:
                 insecureSkipVerify: true
           ```
       * Para enviar apenas o ` `Access Token``, adicione a opção ` `authResponseHeaders` ` ao seu middleware ` ForwardAuth `:
   
           ```yaml {: codeblock}
           apiVersion: traefik.io/v1alpha1
           kind: Middleware
           metadata:
             name: oauth-verify
             namespace: default
           spec:
             forwardAuth:
               address: "https://oauth2-<App_ID_service_instance_name>.<namespace_of_Ingress_resource>.svc.cluster.local/oauth2-<App_ID_service_instance_name>/auth"
               authResponseHeaders:
                 - X-Auth-Request-Access-Token
               tls:
                 insecureSkipVerify: true
           ```
       * Para enviar tanto o ` `Access Token` ` quanto o ` `ID Token``, adicione a opção ` `authResponseHeaders` ` ao seu middleware ` ForwardAuth `:
   
           ```yaml {: codeblock}
           apiVersion: traefik.io/v1alpha1
           kind: Middleware
           metadata:
             name: oauth-verify
             namespace: default
           spec:
             forwardAuth:
               address: "https://oauth2-<App_ID_service_instance_name>.<namespace_of_Ingress_resource>.svc.cluster.local/oauth2-<App_ID_service_instance_name>/auth"
               authResponseHeaders:
                 - X-Auth-Request-Access-Token
                 - Authorization
               tls:
                 insecureSkipVerify: true
           ```
   3. Opcional: Se seu aplicativo for compatível com a [estratégia de aplicativo web](/docs/appid?topic=appid-key-concepts#term-web-strategy), além da [estratégia de API](/docs/appid?topic=appid-key-concepts#term-api-strategy) ou em vez dela, adicione o `authSigninURL` ao seu middleware ForwardAuth. Todas as letras no nome da instância do serviço devem estar em minúsculas.
   
   ```yaml {: codeblock}
       apiVersion: traefik.io/v1alpha1
       kind: Middleware
       metadata:
         name: oauth-verify
         namespace: default
       spec:
         forwardAuth:
           address: "https://oauth2-<App_ID_service_instance_name>.<namespace_of_Ingress_resource>.svc.cluster.local/oauth2-<App_ID_service_instance_name>/auth"
           authResponseHeaders:
             - X-Auth-Request-Access-Token
             - Authorization
           authSigninURL: /oauth2-<App_ID_service_instance_name>/sign_in?rd={url}
           tls:
             insecureSkipVerify: true
       ```
       * Se você especificar `authSigninURL` e a autenticação do cliente falhar, o cliente será redirecionado para OAuth2-Proxy, que, por sua vez, redirecionará o cliente para a página de login App ID.
       * Se você não especificar ` `authSigninURL``, o cliente deverá se autenticar com um token de portador válido. Se a autenticação falhar, a solicitação será rejeitada com o erro “ `401 Unauthorized` ”.
   
   

6. Opcional: Se a sua configuração exigir, crie um recurso do Traefik ServersTransport para ignorar a verificação d TLS para solicitações encaminhadas ao recurso Service do seu aplicativo.

   # Example (Kubernetes ServersTransport)
   apiVersion: traefik.io/v1alpha1
   kind: ServersTransport
   metadata:
     name: skip-tls-verify
   spec:
     insecureSkipVerify: true
   

   Aplique a política de segurança “ ServersTransport ” ao seu recurso de serviço usando a anotação “Traefik Service”.

7. Edite seus recursos do Ingress para exigir a autenticação do tipo “ App ID ”, aplicando o middleware “ ForwardAuth ” que você criou. Use a seguinte anotação do Traefik Ingress.

   traefik.ingress.kubernetes.io/router.middlewares: "default-oauth-verify@kubernetescrd"
   

   Depois que um recurso Ingress com as anotações apropriadas é reaplicado, o complemento ALB OAuth Proxy implanta uma implantação do oauth2-proxy, cria um serviço para a implantação e cria um recurso Ingress separado para configurar o roteamento para a implantação do oauth2-proxy. Não exclua esses recursos de complemento.

8. Verifique se a autenticação do App ID é imposta para seus apps.

   • Se o seu aplicativo for compatível com a estratégia de aplicativos da Web: acesse URL do seu aplicativo em um navegador da Web. Se o App ID estiver corretamente aplicado, você será redirecionado para uma página de login de autenticação do App ID.
   • Se seu aplicativo for compatível com a estratégia de API: especifique seu token de acesso Bearer no cabeçalho “Authorization” das solicitações enviadas aos aplicativos. Para obter seu token de acesso, consulte a documentação do App ID. Se o App ID for aplicado corretamente, a solicitação será autenticada com sucesso e será roteada para o seu app. Se você enviar solicitações aos seus aplicativos sem um token de acesso no cabeçalho “Authorization”, ou se o token de acesso não for aceito por App ID, a solicitação será rejeitada.

9. Opcional: Se você utilizar políticas de rede ou outra solução de firewall no seu cluster para limitar o tráfego de saída, certifique-se de que o cluster possa acessar o serviço público App ID. Para obter o intervalo de endereços IP desse serviço, envie uma solicitação ao suporte ao cliente.

10. Opcional: é possível customizar o comportamento padrão do OAuth2-Proxy criando um ConfigMap do Kubernetes.

    1. Crie um arquivo YAML do ConfigMap que especifique valores para as configurações de OAuth2-Proxy que você deseja mudar.

        apiVersion: v1
        kind: ConfigMap
        metadata:
          name: oauth2-<App_ID_service_instance_name>
          namespace: <ingress_resource_namespace>
        data:
          auth_logging: <true|false>
          # Log all authentication attempts.
          auth_logging_format:
          # Format for authentication logs. For more info, see https://oauth2-proxy.github.io/oauth2-proxy/configuration/overview#logging-configuration
          cookie_csrf_expire: "15m"
          # Expiration time for CSRF cookie. Default is "15m".
          cookie_csrf_per_request: <true|false>
          # Enable multiple CSRF cookies per request, making it possible to have parallel requests. Default is "false".
          cookie_domains:
          # A list of optional domains to force cookies to. The longest domain that matches the request’s host is used. If there is no match for the request’s host, the shortest domain is used. Example: sub.domain.com,example.com
          cookie_expire: "168h0m0s"
          # Expiration time for cookies. Default: "168h0m0s".
          cookie_samesite: ""
          # SameSite attribute for cookies. Supported values: "lax", "strict", "none", or "".
          email_domains: ""
          # Authenticate IDs that use the specified email domain. To authenticate IDs that use any email domain, use "*". Default: "". Example: example.com,example2.com
          pass_access_token: <true|false>
          # Pass the OAuth access token to the back-end app via the X-Forwarded-Access-Token header.
          request_logging: <true|false>
          # Log all requests to the back-end app.
          request_logging_format:
          # Format for request logs. For more info, see https://oauth2-proxy.github.io/oauth2-proxy/configuration/overview#request-log-format
          scope:
          # Scope of the OAuth authentication. For more info, see https://oauth.net/2/scope/
          set_authorization_header: <true|false>
          # Set the Authorization Bearer response header when the app responds to the Ingress ALB, such as when using the Traefik ForwardAuth Middleware.
          set_xauthrequest: <true|false>
          # Set X-Auth-Request-User, X-Auth-Request-Email, and X-Auth-Request-Preferred-Username response headers when the app responds to the Ingress ALB, such as when using the Traefik ForwardAuth Middleware.
          standard_logging: <true|false>
          # Log standard runtime information.
          standard_logging_format:
          # Format for standard logs. For more info, see https://oauth2-proxy.github.io/oauth2-proxy/configuration/overview#standard-log-format
          tls_secret_name:
          # The name of a secret that contains the server-side TLS certificate and key to enable TLS between the OAuth2-Proxy and the Ingress ALB. By default, the TLS secret defined in your Ingress resources is used.
          whitelist_domains:
          # Allowed domains for redirection after authentication. Default: "". Example: example.com,*.example2.com For more info, see: https://oauth2-proxy.github.io/oauth2-proxy/configuration/overview#command-line-options
          oidc_extra_audiences:
          # Additional audiences which are allowed to pass verification.
          cookie_refresh:
          # Refresh the cookie after this duration. Example: "15m". To use this feature, you must enable "Refresh token" for the AppID instance. For more info, see: /docs/appid?topic=appid-managing-idp&interface=ui#idp-token-lifetime
        ```
    2. Aplique o recurso ConfigMap em seu complemento. As suas mudanças são aplicadas automaticamente.
    ```sh {: pre}
        kubectl apply -f oauth2-<App_ID_service_instance_name>.yaml
        ```
    

Para obter a lista de alterações de cada versão do complemento ALB OAuth Proxy, consulte o registro de alterações do complemento ALB OAuth Proxy em IBM Cloud.

Atualização do complemento de proxy “ OAuth ” do ALB

Para atualizar o complemento ALB OAuth Proxy para uma versão mais recente, desative a instalação atual e reative-a com a versão desejada. Suas instâncias existentes do oauth2-proxy não serão interrompidas durante a atualização.

O processo de atualização não causa interrupções, pois as instâncias supervisionadas do oauth2-proxy permanecem no cluster mesmo quando o complemento está desativado.

1. Desative o complemento .

   ibmcloud ks cluster addon disable alb-oauth-proxy --cluster CLUSTER_NAME_OR_ID
   

2. Liste as versões disponíveis do complemento e anote a versão que você deseja usar. A saída mostra as versões disponíveis e qual delas é a padrão.

   ibmcloud ks cluster addon versions --addon alb-oauth-proxy
   

3. Ative o complemento e especifique a opção --version. Se você não especificar uma versão, a versão padrão será ativada.

   ibmcloud ks cluster addon enable alb-oauth-proxy --cluster CLUSTER_NAME_OR_ID [--version VERSION]
   

Preservando o endereço IP de origem

Por padrão, o ALB do Ingress não mantém o endereço IP de origem original das solicitações dos clientes. Isso pode impedir que o controle de acesso baseado em IP, o registro de atividades e as políticas de segurança funcionem corretamente. Escolha o método adequado ao seu tipo de cluster para habilitar a preservação do IP de origem.

Configurando protocolos e algoritmos de criptografi TLS

Use um recurso TLSOption para impor versões mínimas do TLS, restringir conjuntos de criptografia e configurar outros parâmetros de conexão do TLS para o tráfego que chega ao seu ALB. Depois de criar o recurso TLSOption, aplique-o ao seu recurso Ingress usando a anotação Traefik Ingress.

Enviando seu certificado customizado para clientes anteriores

Dispositivos mais antigos que não suportam a Indicação de Nome do Servidor (SNI) não conseguem negociar qual certificado do TLS deve ser usado; por isso, recebem o certificado padrão do Let's Encrypt do ALB, em vez do seu certificado personalizado. Para garantir que esses dispositivos recebam seu certificado personalizado, atualize as configurações padrão do servidor do ALB para que apontem para seu segredo personalizado do TLS.

Os certificados Let's Encrypt gerados por padrão não são destinados ao uso de produção. Para as cargas de trabalho de produção, traga o seu próprio certificado customizado.

Ao criar um cluster clássico, o IBM fornece um certificado Let's Encrypt para o segredo padrão do Ingress. Se você criar um segredo personalizado e especificá-lo para a terminação d TLS e em seus recursos do Ingress, o ALB enviará seu certificado personalizado aos clientes, em vez do certificado do Let's Encrypt. No entanto, se um cliente não for compatível com SNI, o ALB utiliza por padrão o certificado da Let's Encrypt, pois o segredo padrão está listado nas configurações padrão do servidor do ALB. Para enviar seu certificado personalizado para dispositivos que não suportam SNI, siga as etapas a seguir.

1. Edite o recurso do Ingress alb-default-server.

   kubectl edit ingress alb-default-server -n kube-system
   

2. Na seção spec.tls, mude o valor da configuração hosts.secretName para o nome de seu segredo customizado que contenha seu certificado customizado.

   spec:
     rules:
     ...
     tls:
     - hosts:
       - invalid.mycluster-<hash>-0000.us-south.containers.appdomain.cloud
       secretName: <custom_secret_name>
   

3. Salve o arquivo de recursos.

4. Verifique se o recurso agora aponta para o nome do segredo customizado. As mudanças são aplicadas a seus ALBs automaticamente. Na saída, verifique se “ spec.tls[].secretName ” corresponde ao nome do seu segredo personalizado.

   kubectl get ingress alb-default-server -n kube-system -o yaml
   

Ajustando o desempenho do ALB

Os nós de trabalho são provisionados automaticamente com um ajuste otimizado do kernel, adequado à maioria das cargas de trabalho. Se o seu cluster tiver requisitos específicos de alto rendimento ou baixa latência, você pode ajustar os parâmetros do kernel Linux sysctl nos nós de trabalho para otimizar ainda mais o desempenho do ALB. Altere essas configurações somente quando houver uma necessidade clara de otimização de desempenho, pois valores incorretos podem desestabilizar o nó.

Próximas etapas

• Gerencie seus ALBs do Ingress para dimensionar, atualizar ou desativar os ALBs em seu cluster.
• Configure o Ingress para expor seus aplicativos usando o serviço gerenciado do Ingress.
• Utilize o Debug Ingress para diagnosticar e resolver problemas comuns do Ingress.

Links relacionados

• Documentação do Traefik
• Referência do middleware Traefik
• Referência do CRD do Traefik
• IBM Cloud App ID documentação