Como adicionar uma porta do servidor a um cabeçalho do host

Para adicionar uma porta de servidor à solicitação do cliente antes que a solicitação seja encaminhada ao seu aplicativo de back-end, configure um proxy para serviços externos em uma anotação de snippet de servidor ou como um campo ibm-k8s-controller-config ConfigMap.

Roteirização de solicitações recebidas com um ALB privado

Para rotear as solicitações recebidas aos seus apps com um ALB privado, especifique a anotação de classe private-iks-k8s-nginx no recurso Ingresso. Os ALBs privados são configurados para usar recursos com esta classe.

kubernetes.io/ingress.class: "private-iks-k8s-nginx"

Autenticando apps com App ID

Configure o Ingress com IBM Cloud App ID para impor a autenticação de seus aplicativos, alterando campos específicos do Kubernetes Ingress. Consulte Adição da autenticação App ID aos aplicativos para obter mais informações.

Como configurar o tamanho máximo do corpo de solicitação do cliente

Para definir o tamanho máximo do corpo que o cliente pode enviar como parte de uma solicitação, use a seguinte anotação de recurso Kubernetes Ingress.

nginx.ingress.kubernetes.io/proxy-body-size: 8m

Ativação e desativação de buffering de dados de resposta do cliente

É possível desativar ou ativar o armazenamento dos dados de resposta no ALB enquanto os dados são enviados ao cliente. Esta configuração está desativada por padrão. Para ativar, configure o seguinte recurso Ingresso anotação.

nginx.ingress.kubernetes.io/proxy-buffering: "on"

Personalização dos tempos limite de conexão e leitura

Para configurar a quantidade de tempo que o ALB espera para se conectar e ler a partir do app back-end antes que o app back-end seja considerado indisponível, use as seguintes anotações.

nginx.ingress.kubernetes.io/proxy-connect-timeout: 62

nginx.ingress.kubernetes.io/proxy-read-timeout: 62

Customizando ações de erro

Para indicar ações personalizadas que o ALB pode executar para erros específicos do site HTTP, defina o campo custom-http-errors.

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

Para alterar as portas padrão para o tráfego de rede HTTP (porta 80) e HTTPS (porta 443), modifique cada serviço ALB com os seguintes campos Kubernetes Ingress ibm-ingress-deploy-config ConfigMap.

Configuração de campo de exemplo.

httpPort=8080
httpsPort=8443

Customizando o cabeçalho da solicitação

Para adicionar informações de cabeçalho a uma solicitação do cliente antes de encaminhá-la ao seu aplicativo de back-end, use o seguinte campodo configmap Kubernetes ibm-k8s-controller-config

proxy-set-headers: "ingress-nginx/custom-headers"

Para os requisitos de configmap custom-headers, consulte este exemplo.

Como personalizar o cabeçalho de resposta

Para adicionar informações de cabeçalho a uma resposta do cliente antes de enviá-lo para o cliente, use a seguinte anotação.

nginx.ingress.kubernetes.io/configuration-snippet: |
    more_set_headers "Request-Id: $req_id";

Adicionando definições de caminho a serviços externos

Para adicionar definições de caminho a serviços externos, como serviços hospedados em IBM Cloud, configure um proxy para serviços externos em um snippet de local. Ou substitua o proxy por um redirecionamento permanente para serviços externos.

Redirecionamento de pedidos inseguros

Por padrão, as solicitações inseguras do cliente HTTP são redirecionadas para HTTPS. Para desativar essa configuração, use o campo e anotação a seguir.

• ibm-k8s-controller-config ConfigMap campo

  ssl-redirect: "false"
  

• Anotação do recurso Ingress:

  nginx.ingress.kubernetes.io/ssl-redirect: "false"
  

Ativação e desativação do HTTP Strict Transport Security

Configure o navegador para acessar o domínio somente usando HTTPS. Esta opção está ativada por padrão.

• Para incluir a idade máxima e a granularidade de subdomínio, consulte este blog do NGINX.
• Para desativar, configure o campo de configmap ibm-k8s-controller-config.

  hsts: false
  

Como configurar um número máximo de solicitações de keepalive

Para definir o número máximo de solicitações que podem ser atendidas por meio de uma conexão keepalive, use o seguinte campo Kubernetes ibm-k8s-controller-config configmap.

keep-alive-requests: 100

O valor padrão para keep-alive-requests no Ingress Kubernetes é 100``, que é muito menor do que o valor padrão de 4096 no Ingress IBM Cloud Kubernetes Service. Se você tiver migrado sua configuração do Ingress do IBM Cloud Kubernetes Service Ingress para o Kubernetes Ingress, poderá ser necessário mudar keep-alive-requests para passar nos testes de desempenho existentes.

Configurando um tempo máximo de solicitação de keepalive

Para definir o tempo máximo em que uma conexão keepalive permanece aberta entre o cliente e o servidor proxy ALB, use o seguinte campo Kubernetes ibm-k8s-controller-config configmap.

keep-alive: 60

Configurando um número máximo de buffers de cabeçalho de grandes clientes

Para definir o número e o tamanho máximos de buffers que leem cabeçalhos de solicitação de clientes grandes, use o seguinte campo Kubernetes ibm-k8s-controller-config configmap.

large-client-header-buffers: 4 8k

Modificando como o ALB corresponde ao URI de solicitação

Para modificar a maneira como o ALB combina o URI da solicitação com o caminho do aplicativo, use a seguinte anotação de recurso Kubernetes Ingress.

nginx.ingress.kubernetes.io/use-regex: "true"

Para obter mais informações, consulte este blog.

Incluindo configurações de blocos de localização personalizadas

Para adicionar uma configuração de bloco de localização personalizada para um serviço, use a seguinte anotação de recurso Kubernetes Ingress.

nginx.ingress.kubernetes.io/configuration-snippet: |
    more_set_headers "Request-Id: $req_id";

Configurando a autenticação mútua

Para configurar a autenticação mútua para o ALB, use as seguintes anotações do recurso Kubernetes Ingress. Note que a autenticação mútua não pode ser aplicada em portas customizadas e deve ser aplicada na porta HTTPS.

nginx.ingress.kubernetes.io/auth-tls-verify-client: "on"
nginx.ingress.kubernetes.io/auth-tls-secret: "default/ca-secret"
nginx.ingress.kubernetes.io/auth-tls-verify-depth: "1"
nginx.ingress.kubernetes.io/auth-tls-error-page: "http://www.mysite.com/error-cert.html"
nginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream: "true"

Configurando tamanho do buffer de proxy

Para configurar o tamanho do buffer do proxy que lê a primeira parte da resposta, use a seguinte anotação de recurso Kubernetes Ingress.

nginx.ingress.kubernetes.io/proxy-buffer-size: "8k"

Configurando números de buffer de proxy

Para configurar o número de buffers de proxy para o ALB, use a seguinte anotação de recurso Kubernetes Ingress.

nginx.ingress.kubernetes.io/proxy-buffers-number: "4"

Configurando tamanho de buffer de proxy ocupado

Para configurar o tamanho de buffers de proxy que podem ser ocupados, use um trecho de localização . Para obter mais informações, consulte os Docs do NGINX.

Configurando quando um ALB pode transmitir uma solicitação

Para definir quando o ALB pode passar uma solicitação para o próximo servidor upstream, use os seguintes campos Kubernetes Ingress.

• Configuração global: campos de configmap ibm-k8s-controller-config:

  retry-non-idempotent: true
  proxy-next-upstream: error timeout http_500
  

• Configuração por recurso: anotações do recurso Ingress:

  nginx.ingress.kubernetes.io/proxy-next-upstream: http_500
  nginx.ingress.kubernetes.io/proxy-next-upstream-timeout: 50
  nginx.ingress.kubernetes.io/proxy-next-upstream-tries: 3
  

Limitação de taxa

Para limitar a taxa de processamento de pedidos e o número de conexões por uma chave definida para os serviços, use o recurso Ingresso anotações para limitação de taxa.

Removendo o cabeçalho de resposta

É possível remover as informações de cabeçalho incluídas na resposta ao cliente a partir do aplicativo de back-end antes que a resposta seja enviada ao cliente. Configure a remoção do cabeçalho de resposta em um trecho de localização, ou use o proxy_hide_header campo como um trecho de configuração no ibm-k8s-controller-config ConfigMap.

Reescrever caminhos

Para rotear o tráfego de rede de entrada em um caminho de domínio ALB para um caminho diferente que seu aplicativo back-end escuta, use a seguinte anotação de recurso Kubernetes Ingress.

nginx.ingress.kubernetes.io/rewrite-target: /newpath

Customizando configurações de blocos do servidor

Para adicionar uma configuração de bloco de servidor personalizada, use a seguinte anotação de recurso Kubernetes Ingress.

nginx.ingress.kubernetes.io/server-snippet: |
    location = /health {
    return 200 'Healthy';
    add_header Content-Type text/plain;
    }

Roteamento de tráfego de rede

Para sempre rotear o tráfego de rede de entrada para o mesmo servidor upstream usando um sticky cookie, use as seguintes anotações de recurso Kubernetes Ingress.

nginx.ingress.kubernetes.io/affinity: "cookie"
nginx.ingress.kubernetes.io/session-cookie-name: "cookie_name1"
nginx.ingress.kubernetes.io/session-cookie-expires: "172800"
nginx.ingress.kubernetes.io/session-cookie-max-age: "172800"
nginx.ingress.kubernetes.io/configuration-snippet: |
  more_set_headers "Set-Cookie: HttpOnly";

Por padrão, o controlador de Ingress do Kubernetes inclui os atributos Secure e HttpOnly nos sticky cookies, o que não pode ser alterado.

Permitir que o suporte a serviços SSL criptografe o tráfego

Para permitir que o suporte a serviços SSL criptografe o tráfego para seus aplicativos upstream que exigem HTTPS, use a anotação de protocolo de backend do recurso Kubernetes Ingress e as anotações de autenticação de certificado de backend.

nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
nginx.ingress.kubernetes.io/proxy-ssl-secret: app1-ssl-secret
nginx.ingress.kubernetes.io/proxy-ssl-verify-depth: 5
nginx.ingress.kubernetes.io/proxy-ssl-name: proxy-ssl-name=mydomain.com
nginx.ingress.kubernetes.io/proxy-ssl-verify: true

Acesso a aplicativos com portas TCP não padrão

Para acessar um aplicativo por meio de uma porta não padrão TCP, siga estas etapas.

1. Crie um configmap tcp-services para especificar a sua porta TCP, como as portas de exemplo a seguir. Para os requisitos do configmap tcp-services, consulte este blog.

   apiVersion: v1
   kind: ConfigMap
   metadata:
     name: tcp-services
     namespace: kube-system
   data:
     9000: "<namespace>/<service>:8080"
   

2. Crie o configmap no namespace kube-system.

   kubectl apply -f tcp-services.yaml -n kube-system
   

3. Especifique o configmap tcp-services como um campo no configmap ibm-ingress-deploy-config.

   "tcpServicesConfig":"kube-system/tcp-services"
   

4. Modifique cada serviço ALB para incluir as portas.

Como configurar um número máximo de pedidos de keepalive upstream

Para definir o número máximo de solicitações que podem ser atendidas por meio de uma conexão keepalive, use o seguinte campo Kubernetes ibm-k8s-controller-config ConfigMap.

upstream-keepalive-requests: 32

Configurando o tempo limite máximo de keepalive de upstream

Para definir o tempo máximo em que uma conexão keepalive permanece aberta entre o servidor proxy ALB e o servidor upstream do seu aplicativo, use o seguinte campo Kubernetes ibm-k8s-controller-config configmap.

upstream-keepalive-timeout: 32

Customizando a implementação do ALB

Customize a implementação para ALBs que executam a imagem do Ingress do Kubernetes criando um configmap ibm-ingress-deploy-config.

1. Obtenha os nomes dos serviços que expõem cada ALB.

   • 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
       ```
   

Customizando a classe do Ingress

Uma classe Ingress associa um nome de classe a um tipo de controlador Ingress. Use o recurso IngressClass para customizar as aulas do Ingress.

Incluindo a autenticação do App ID em apps

Aplique a autenticação para os apps configurando o Ingress com o IBM Cloud App ID.

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, assegure-se de que o nome da instância de serviço contenha apenas caracteres alfanuméricos minúsculos 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 de serviço deve conter apenas caracteres alfanuméricos em 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, o usuário não será autenticado, mas receberá um token de acesso para acesso anônimo ao aplicativo.
   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. Observe que todas as letras no nome da instância de serviço devem ser especificadas como minúsculas.

   Se usar a função de logout do IBM Cloud App ID, você deverá anexar /sign_out ao domínio no formato https://<hostname>/oauth2-<App_ID_service_instance_name>/sign_out e incluir essa URL na lista de URLs de redirecionamento. Se quiser usar uma página de logout personalizada, você deverá definir whitelist_domains em ConfigMap para OAuth2-Proxy. Ligue para o terminal https://<hostname>/oauth2-<App_ID_service_instance_name>/sign_out com o parâmetro de consulta rd ou configure o cabeçalho X-Auth-Request-Redirect com a sua página de logout personalizada. Para obter mais detalhes, veja Inscrever-se.

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. Certifique-se de ligar a instância de serviço ao mesmo namespace no qual seus recursos do Ingress existem. Observe que todas as letras no nome da instância de serviço devem ser especificadas como 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 é ligado com sucesso ao seu cluster, é criado um segredo de cluster que mantém as credenciais de sua instância de serviço. Exemplo de saída da CLI:

   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 implementação de OAuth2-Proxy para a instância de serviço do App ID, um segredo que contém a configuração da implementação do OAuth2-Proxy e um recurso do Ingress que configura ALBs para rotear as solicitações recebidas para a implementação do OAuth2-Proxy para a instância do App ID. O nome de cada um desses recursos 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`.
   ```sh {: pre}
       ibmcloud ks cluster addon ls --cluster CLUSTER_NAME_OR_ID
       ```
   

5. Nos recursos do Ingress para apps nos quais você deseja incluir a autenticação App ID, certifique-se de que o nome do recurso não exceda 25 caracteres de comprimento. Em seguida, inclua as seguintes anotações na seção metadata.annotations.

   1. Inclua a anotação auth-url a seguir. Esta anotação especifica a URL do OAuth2-Proxy para a instância do App ID, que serve como o OIDC Relying Party (RP) para o App ID. Observe que todas as letras no nome da instância de serviço devem ser especificadas como minúsculas.

       ...
       annotations:
          nginx.ingress.kubernetes.io/auth-url: https://oauth2-<App_ID_service_instance_name>.<namespace_of_Ingress_resource>.svc.cluster.local/oauth2-<App_ID_service_instance_name>/auth
       ...
       ```
   2. Às vezes, o cookie de autenticação usado pelo `OAuth2-Proxy` excede 4 KB. Portanto, é dividido em duas partes. O fragmento a seguir deve ser incluído para assegurar que ambos os cookies possam ser atualizados corretamente pelo `OAuth2-Proxy`
   ```yaml {: codeblock}
       ...
       annotations:
           nginx.ingress.kubernetes.io/configuration-snippet: |
           auth_request_set $_oauth2_<App_ID_service_instance_name>_upstream_1 $upstream_cookie__oauth2_<App_ID_service_instance_name>_1;
           access_by_lua_block {
               if ngx.var._oauth2_<App_ID_service_instance_name>_upstream_1 ~= "" then
               ngx.header["Set-Cookie"] = "_oauth2_<App_ID_service_instance_name>_1=" .. ngx.var._oauth2_<App_ID_service_instance_name>_upstream_1 .. ngx.var.auth_cookie:match("(; .*)")
               end
           }
       ...
       ```
   
   3. 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){: external}.
       * Para enviar apenas o ` `ID Token``, adicione a seguinte anotação:
   
           ```yaml {: codeblock}
           ...
           annotations:
               nginx.ingress.kubernetes.io/auth-response-headers: Authorization
           ...
           ```
       * Para enviar apenas o ` `Access Token``, adicione as seguintes informações à anotação ` `configuration-snippet` `. (Isso estende o fragmento da etapa 5.2.)
   
           ```yaml {: codeblock}
           ...
           annotations:
               nginx.ingress.kubernetes.io/configuration-snippet: |
               auth_request_set $_oauth2_<App_ID_service_instance_name>_upstream_1 $upstream_cookie__oauth2_<App_ID_service_instance_name>_1;
               auth_request_set $access_token $upstream_http_x_auth_request_access_token;
               access_by_lua_block {
                   if ngx.var._oauth2_<App_ID_service_instance_name>_upstream_1 ~= "" then
                   ngx.header["Set-Cookie"] = "_oauth2_<App_ID_service_instance_name>_1=" .. ngx.var._oauth2_<App_ID_service_instance_name>_upstream_1 .. ngx.var.auth_cookie:match("(; .*)")
                   end
                   if ngx.var.access_token ~= "" then
                   ngx.req.set_header("Authorization", "Bearer " .. ngx.var.access_token)
                   end
               }
           ...
           ```
       * Para enviar o ` `Access Token` ` e o ` `ID Token``, adicione as seguintes informações à anotação ` `configuration-snippet` `. (Isso estende o fragmento da etapa 5.2.)
           ```yaml {: codeblock}
           ...
            annotations:
               nginx.ingress.kubernetes.io/configuration-snippet: |
               auth_request_set $_oauth2_<App_ID_service_instance_name>_upstream_1 $upstream_cookie__oauth2_<App_ID_service_instance_name>_1;
               auth_request_set $access_token $upstream_http_x_auth_request_access_token;
               auth_request_set $id_token $upstream_http_authorization;
               access_by_lua_block {
                   if ngx.var._oauth2_<App_ID_service_instance_name>_upstream_1 ~= "" then
                   ngx.header["Set-Cookie"] = "_oauth2_<App_ID_service_instance_name>_1=" .. ngx.var._oauth2_<App_ID_service_instance_name>_upstream_1 .. ngx.var.auth_cookie:match("(; .*)")
                   end
                   if ngx.var.id_token ~= "" and ngx.var.access_token ~= "" then
                   ngx.req.set_header("Authorization", "Bearer " .. ngx.var.access_token .. " " .. ngx.var.id_token:match("%s*Bearer%s*(.*)"))
                   end
               }
           ...
           ```
   4. Opcional: se o app suportar a [estratégia de app da web](/docs/appid?topic=appid-key-concepts#term-web-strategy) além ou em vez de a [estratégia de API](/docs/appid?topic=appid-key-concepts#term-api-strategy), inclua a anotação `nginx.ingress.kubernetes.io/auth-signin: https://$host/oauth2-<App_ID_service_instance_name>/start?rd=$escaped_request_uri`. Observe que todas as letras no nome da instância do serviço devem estar em minúsculas.
       * Se você especificar essa anotação e a autenticação para um cliente falhar, o cliente será redirecionado para a URL do OAuth2-Proxy para a instância do App ID. Este OAuth2-Proxy, que funciona como o OIDC Relying Party (RP) para o App ID, redireciona o cliente para a página de login do App ID para autenticação.
       * Se você não especificar essa anotação, um cliente deverá se autenticar com um token de acesso válido. Se a autenticação para um cliente falhar, a solicitação do cliente será rejeitada com uma mensagem de erro `401 Unauthorized`.
   
   

6. Reaplique seus recursos do Ingress para aplicar a autenticação do App ID. Após um recurso do Ingress com as anotações apropriadas ter sido reaplicado, o complemento ALB OAuth Proxy realiza uma implementação do OAuth2-Proxy, cria um serviço para a implementação e cria um recurso separado do Ingress para configurar o roteamento para as mensagens de implementação do OAuth2-Proxy. Não exclua esses recursos de complemento.

   kubectl apply -f <app_ingress_resource>.yaml -n namespace
   

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

   • Se os seus apps suportarem a estratégia de app da web: acesse a URL de seu app em um navegador da web. Se o App ID for aplicado corretamente, você será redirecionado para uma página de login de autenticação do App ID.
   • Se seus apps suportarem a estratégia de API: especifique seu token de acesso Bearer no cabeçalho de Autorização de solicitações para os apps. 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 para seus apps sem um token de acesso no cabeçalho de Autorização ou se o token de acesso não for aceito pelo App ID, a solicitação será rejeitada.

8. Opcional: se você usar políticas de rede ou outra solução de firewall em seu cluster para limitar o tráfego de saída, certifique-se de permitir o acesso ao serviço público AppID's a partir do seu cluster. Para obter o intervalo de endereços IP para esse serviço, envie uma solicitação por meio do suporte ao cliente.

9. 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 backend app via the X-Forwarded-Access-Token header.
         request_logging: <true|false>
         # Log all requests to the backend 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 when using the NGINX auth_request mode.
         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 NGINX auth_request mode.
         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 consultar 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.

Preservando o endereço IP de origem

Por padrão, os endereços IP de origem de solicitações do cliente não são preservados pelo ALB do Ingress. Para preservar os endereços IP de origem, é possível ativar o protocolo PROXY em clusters VPC ou mudar a externalTrafficPolicy em clusters clássicos.

Configurando protocolos SSL e cifras SSL no nível de HTTP

Ative protocolos e cifras SSL no nível do HTTP global, editando o configmap ibm-k8s-controller-config.

Por exemplo, se você ainda tiver clientes anteriores que requeiram o suporte do TLS 1.0 ou 1.1, essas versões do TLS deverão ser ativadas manualmente para substituir apenas a configuração padrão do TLS 1.2 e do TLS 1.3.

Quando você especifica os protocolos ativados para todos os hosts, os parâmetros TLSv1.1 e TLSv1.2 (1.1.13, 1.0.12) funcionam somente quando o OpenSSL 1.0.1 ou superior é usado. O parâmetro TLSv1.3 (1.13.0) funciona somente quando o OpenSSL 1.1.1 construído com o suporte TLSv1.3 é usado.

Para editar o configmap para ativar protocolos e cifras SSL:

1. Edite o arquivo de configuração para o recurso do configmap ibm-k8s-controller-config.

   kubectl edit cm ibm-k8s-controller-config -n kube-system
   

2. Inclua os protocolos e cifras SSL. Formate as cifras de acordo com o Formato de lista de cifras da biblioteca OpenSSL.

   apiVersion: v1
   data:
     ssl-protocols: "TLSv1 TLSv1.1 TLSv1.2 TLSv1.3"
     ssl-ciphers: "HIGH:!aNULL:!MD5:!CAMELLIA:!AESCCM:!ECDH+CHACHA20"
   kind: ConfigMap
   metadata:
     name: ibm-k8s-controller-config
     namespace: kube-system
   

3. Salve o arquivo de configuração.

4. Verifique se as mudanças de configmap foram aplicadas. As mudanças são aplicadas a seus ALBs automaticamente.

   kubectl get cm ibm-k8s-controller-config -n kube-system -o yaml
   

Enviando seu certificado customizado para clientes anteriores

Se você tiver dispositivos legados que não suportam o Server Name Indication (SNI) e usar um certificado TLS customizado nos recursos Ingress, você deverá editar as configurações de servidor do ALB para usar o certificado TLS customizado e o segredo TLS customizado.

Ao criar um cluster clássico, um certificado Let's Encrypt é gerado para o segredo do Ingress padrão que a IBM fornece. Se você criar um segredo customizado em seu cluster e especificá-lo para finalização do TLS em seus recursos do Ingress, o ALB do Ingress enviará o certificado para o seu segredo customizado ao cliente em vez do certificado Let's Encrypt padrão. No entanto, se um cliente não suportar SNI, o ALB do Ingress será padronizado para o certificado Let's Encrypt porque o segredo padrão é listado nas configurações de servidor padrão do ALB. Para enviar o certificado customizado para dispositivos que não suportam SNI, conclua as etapas a seguir para mudar as configurações de servidor padrão do ALB para o segredo customizado.

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.

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. Exemplo:

   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.

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

Ajuste fino do tratamento de conexões

As definições client-header-timeout, client-body-timeout e keep-alive são configurações cruciais que determinam por quanto tempo as conexões permanecem ativas entre os clientes, o controlador Ingress e os servidores back-end. Esses tempos limite desempenham uma função importante na otimização do tratamento de solicitações, principalmente ao lidar com conexões de clientes de longa duração, respostas atrasadas de servidores de back-end e proteção de recursos valiosos contra a ocupação desnecessária.

O endereço client-header-timeout define o tempo máximo que o servidor aguarda por um cabeçalho de cliente completo. Da mesma forma, o client-body-timeout indica a duração que o servidor aguarda para que o cliente envie o corpo da solicitação. Esses dois tempos limite devem estar alinhados com o parâmetro keep-alive, que regula por quanto tempo o servidor mantém uma conexão aberta enquanto aguarda outras solicitações. Se esses tempos limite não corresponderem à configuração keep-alive, o site NGINX encerrará a conexão, o que pode levar a um comportamento inesperado do cliente ou a falhas nas solicitações.

Você pode definir esses parâmetros no ibm-k8s-controller-config ConfigMap, no namespace kube-system.

apiVersion: v1
kind: ConfigMap
metadata:
  name: ibm-k8s-controller-config
  namespace: kube-system
data:
  ...
  client-body-timeout: "100"
  client-header-timeout: "100"
  keep-alive: "100"

Para obter mais informações, consulte a seção client-header-timeout, client-body-timeout e keep-alive na documentação do Ingress Nginx.

Ajustando o desempenho do ALB

Para otimizar o desempenho de seus ALBs do Ingress, é possível mudar as configurações padrão de acordo com suas necessidades.