Depurando o Ingress

Nuvem privada virtual Infraestrutura clássica

Você expôs seu app criando um recurso do Ingress para seu app em seu cluster. No entanto, quando você tenta se conectar ao seu app por meio do subdomínio de ingresso ou do endereço IP do controlador de ingresso, a conexão falha ou atinge o tempo limite.

As etapas nas seções a seguir podem ajudar a depurar sua configuração do Ingress.

Antes de começar, certifique-se de ter as políticas de acesso do IBM Cloud IAM a seguir para o IBM Cloud Kubernetes Service: - A função de acesso da plataforma Editor ou Administrador para o cluster. - A função de acesso do serviço Gravador ou Gerenciador

Está vendo uma página O aplicativo não está disponível quando você tenta acessar o subdomínio do seu app? Verifique a implantação do seu aplicativo e a configuração dos recursos Ingress e Route. Está vendo uma página Tempo limite de conexão? Confira o funcionamento dos pods do controlador de ingresso.

Passo 1: Verifique a implantação do seu aplicativo e a configuração dos recursos Ingress e Route

Comece verificando erros na implementação de seu app e na implementação dos recursos do Ingress. As mensagens de erro em suas implementações podem ajudá-lo a localizar as causas raiz para falhas e depurar ainda mais a configuração do Ingress nas próximas seções.

  1. Antes de debug Ingress, primeiro confira Debugging app implemenments. Os problemas do Ingress são frequentemente causados por problemas subjacentes em sua implementação de app ou no serviço ClusterIP que expõe seu app. Por exemplo, seu rótulo de app e seletor de serviço podem não corresponder ou suas portas de destino de app e de serviço podem não corresponder.

  2. Verifique a sua implementação de recursos do Ingress e procure por avisos ou mensagens de erro.

    oc describe ingress <ingress_resource_name>

    Na seção Events da saída, é possível que você veja mensagens de aviso sobre valores inválidos em seu recurso Ingress ou em certas anotações usadas. No que diz respeito às anotações, observe que as anotações do tipo “ IBM Cloud Kubernetes Service ” (ingress.bluemix.net/<annotation>) e as anotações do tipo “Ingress- NGINX ” (nginx.ingress.kubernetes.io/<annotation>) não são suportadas para o controlador Ingress nem para o recurso Ingress na versão 4 do Red Hat OpenShift. Se quiser personalizar as regras de roteamento para aplicativos em um cluster que executa o Red Hat OpenShift versão 4, você pode usar anotações HAProxy específicas da rota, que estão no formato haproxy.router.openshift.io/<annotation> ou router.openshift.io/<annotation>.

    NAME:             myingress
Namespace:        default
Address:          169.xx.xxx.xxx,169.xx.xxx.xxx
Default backend:  default-http-backend:80 (<none>)
Rules:
    Host                                             Path  Backends
    ----                                             ----  --------
    mycluster-<hash>-0000.us-south.containers.appdomain.cloud
    /tea      myservice1:80 (<none>)
    /coffee   myservice2:80 (<none>)
Annotations:  <none>
Events:       <none>

  3. Verifique a implantação do recurso Route e procure por avisos ou mensagens de erro.

    oc describe route <myroute>

    Nas seções “Status” e “Eventos” da saída, você poderá ver mensagens de aviso sobre valores inválidos no seu recurso Route ou em determinadas anotações que você utilizou.

    Name:         myroute
Namespace:    default
Labels:       <none>
Annotations:  <none>
API Version:  route.openshift.io/v1
Kind:         Route
Metadata:
  Creation Timestamp:  2026-07-01T10:18:43Z
  Generation:          1
  Owner References:
    API Version:     networking.k8s.io/v1
    Controller:      true
    Kind:            Ingress
    Name:            coffee-ingress
    UID:             e7a18dd4-402d-461c-a41f-c4750b6d2032
  Resource Version:  178601
  UID:               17c623e6-e9ef-4179-a3ad-af8ea311f2e5
Spec:
  Host:  mycluster-<hash>-0000.us-south.containers.appdomain.cloud
  Path:  /
  Port:
    Target Port:  http
  Tls:
    Certificate:  ...
    Insecure Edge Termination Policy:  Redirect
    Key: ...
    Termination:  edge
  To:
    Kind:           Service
    Name:           myservice1
    Weight:         100
  Wildcard Policy:  None
Status:
  Ingress:
    Conditions:
      Last Transition Time:     2026-07-01T10:18:43Z
      Status:                   True
      Type:                     Admitted
    Host:                       mycluster-<hash>-0000.us-south.containers.appdomain.cloud
    Router Canonical Hostname:  router-default.mycluster-<hash>-0000.us-south.containers.appdomain.cloud
    Router Name:                default
    Wildcard Policy:            None
Events:  <none>

  4. Verifique se há avisos ou mensagens de erro nos eventos no nível do cluster.

    oc get events

    Em alguns casos, eventos de aviso ou erro relacionados aos recursos do Ingress são emitidos no nível do cluster. Lembre-se de que os eventos estão restritos ao namespace.

    LAST SEEN   TYPE      REASON                          OBJECT             MESSAGE
2m40s       Warning   IncompleteIngressToRouteRules   ingress/myingress  Incomplete ingress to route rules detected: Invalid or missing TLS secret for rule host "mycluster-<hash>-0000.us-south.containers.appdomain.cloud" at index 0, path index 0

  5. Verifique o arquivo de configuração do recurso Ingress ou Route.

    oc get ingress -o yaml

    1. Assegure-se de definir um host em apenas um recurso do Ingress. Se um host for definido em diversos recursos do Ingress, o controlador do Ingress poderá não encaminhar o tráfego adequadamente e será possível se deparar com erros.

    2. Verifique se o subdomínio e o certificado TLS estão corretos. Para localizar o certificado TLS e o subdomínio do Ingress fornecido pela IBM, execute ibmcloud oc cluster get --cluster <cluster_name_or_ID>.

    3. Certifique-se de que seu app atenda no mesmo caminho configurado na seção de caminho de seu Ingresso.

    4. Edite seu YAML de configuração de recurso, conforme necessário. Quando você fecha o editor, suas mudanças são salvas e aplicadas automaticamente.

        oc edit ingress <myingressresource>
    ```

  6. Verifique se você atingiu o número máximo de balanceadores de carga VPC permitidos por conta. Verifique a Documentação de cotas da VPC para cotas de recursos da VPC em todos os clusters na VPC.

Etapa 2: Verifique o estado do controlador do Ingress

Verifique se o operador de ingresso e o controlador de ingresso estão funcionais. Os controladores do Ingress são gerenciados pelo operador do Ingress. O controlador de ingresso encaminha solicitações para os pods para esse app apenas de acordo com as regras definidas no recurso de ingresso e implementadas pelo controlador de ingresso.

  1. Verifique o status do seu operador do Ingress consultando o recurso personalizado IngressController. No Red Hat OpenShift em IBM Cloud, o operador do Ingress é gerenciado pela plataforma e seus pods não são acessíveis diretamente. Em vez disso, verifique o estado do operador por meio do status do recurso IngressController.
    1. Descreva o arquivo de configuração padrão IngressController e verifique a seção “Condições” para identificar eventuais entradas de status do tipo “ False ” ou “ Unknown ” e suas mensagens.
        oc describe ingresscontroller/default -n openshift-ingress-operator
    ```
2. Liste todos os recursos do `IngressController` para verificar se nenhum deles está em estado prejudicado.
```sh {: pre}
    oc get ingresscontrollers -n openshift-ingress-operator
    ```
  2. Verifique o status e os logs de seus pods do controlador de ingresso.
    1. Obtenha os pods do controlador de ingresso que estão executando em seu cluster.
        oc get pods -n openshift-ingress
    ```
2. Certifique-se de que todos os pods `router-default` e pods para os controladores de ingresso em qualquer outra zona estão em execução verificando a coluna **STATUS**. Se você tiver um cluster multizona, note que o serviço do controlador de ingresso na primeira zona em que você tem nós de trabalhadores será sempre nomeado `router-default`, e os serviços do controlador de ingresso nas zonas que você posteriormente incluir em seu cluster terão nomes como `router-dal12`.

3. Se um pod não tiver um status `Running`, será possível excluir o pod para reiniciá-lo.
```sh {: pre}
    oc delete pod <pod> -n openshift-ingress
    ```
4. Obtenha os logs para cada pod e procure as mensagens de erro nos logs.
```sh {: pre}
    oc logs <pod> -n openshift-ingress
    ```
  3. Confira eventos e erros em cada serviço do controlador de ingresso.
    1. Liste os serviços no namespace openshift-ingress.
        oc get svc -n openshift-ingress
    ```
    Saída de exemplo para um cluster de diversas zonas com nós do trabalhador em `dal10` e `dal13`:
    ```sh {: screen}
    NAME                                         TYPE           CLUSTER-IP      EXTERNAL-IP    PORT(S)                      AGE
    router-dal13                                 LoadBalancer   172.21.47.119   169.XX.XX.XX   80:32318/TCP,443:30915/TCP   26d
    router-default                               LoadBalancer   172.21.47.119   169.XX.XX.XX   80:32637/TCP,443:31719/TCP   26d
    router-internal-default                      ClusterIP      172.21.51.30    <none>         80/TCP,443/TCP,1936/TCP      26d
    ```
2. Descreva cada serviço de controlador de ingresso e verifique se há mensagens na seção `Events` da saída.
```sh {: pre}
    oc describe svc router-default -n openshift-ingress
    ```
    Por exemplo, em clusters de VPC, é possível que você veja uma mensagem de erro, como `The VPC load balancer that routes requests to this Kubernetes LoadBalancer service is offline`. Para obter mais informações, consulte [Clusters da VPC: por que meu app não pode se conectar através do balanceador de carga?](/docs/openshift?topic=openshift-vpc_ts_lb).

Etapa 3: Faça um ping no subdomínio do Ingress e no endereço IP público do controlador do Ingress

Verifique a disponibilidade dos endereços IP públicos do controlador de ingresso e verifique os seus mapeamentos de subdomínio. Além disso, certifique-se de que o plano de controle do Red Hat OpenShift pode acessar seus controladores de ingresso para verificar o funcionamento deles.

  1. Verifique se os seus serviços de controlador de ingresso estão alcançáveis pela verificação de funcionamento do controlador de ingresso.

    • Clássico: Se você utilizar políticas de rede pré-DNAT do Calico ou outro firewall personalizado para bloquear o tráfego de entrada no seu cluster, será necessário permitir o acesso de entrada nas portas 80 ou 443 a partir do plano de controle Red Hat OpenShift e dos endereços IP IBM, NS1 e IPv4 para os endereços IP dos seus serviços de controlador Ingress, de modo que o plano de controle Red Hat OpenShift possa verificar a integridade dos seus controladores Ingress. Por exemplo, se você utilizar políticas do tipo “ Calico ”, crie uma política de pré-DNAT do tipo “ Calico ” para permitir o acesso de entrada aos seus controladores Ingress a partir dos endereços IP de origem IBM e NS1, que são utilizados para verificar a integridade dos seus controladores Ingress na porta 80, bem como das sub-redes do plano de controle da região onde seu cluster está localizado. Continue com a próxima etapa para obter os endereços IP de serviço do controlador de ingresso.

    • VPC: Se você tiver um grupo de segurança personalizado nas instâncias do VPC LBaaS ( LoadBalancer-as-a-Service ) para o ingresso do cluster, certifique-se de que as regras do grupo de segurança permitam o tráfego necessário para a verificação de integridade proveniente dos endereços IP do plano de controle Kubernetes para a porta 443.

  2. Obtenha os endereços IP externos nos quais os serviços do controlador de ingresso estão atendendo. Se você tiver um cluster multizona, note que o serviço do controlador de ingresso na primeira zona em que você tem nós de trabalhador é sempre nomeada router-default, e os serviços do controlador de ingresso nas zonas que você posteriormente incluir em seu cluster terão nomes como router-dal12. Em clusters VPC, os endereços IP externos estão atrás de um nome do host que é designado pelo balanceador de carga de VPC, como aabb1122-us-south.lb.appdomain.cloud.

    oc get svc -n openshift-ingress

    Saída de exemplo para um cluster multizona clássico com os nós do trabalhador em dal10 e dal13:

    NAME                                         TYPE           CLUSTER-IP      EXTERNAL-IP    PORT(S)                      AGE
router-dal13                                 LoadBalancer   172.21.47.119   169.XX.XX.XX   80:32318/TCP,443:30915/TCP   26d
router-default                               LoadBalancer   172.21.47.119   169.XX.XX.XX   80:32637/TCP,443:31719/TCP   26d
router-internal-default                      ClusterIP      172.21.51.30    <none>         80/TCP,443/TCP,1936/TCP      26d

    Se um controlador de ingresso não tiver endereço IP externo (clássico) ou nome de host (VPC), consulte Versão 4: Por que o controlador de ingresso não implementa em uma zona?.

  3. Verifique o funcionamento dos pods de seu controlador de ingresso (clássico) ou do nome do host (VPC).

    • Clusters clássicos: Verifique o status de seus pods do controlador de ingresso.
    • Clusters de VPC: os serviços de roteamento em clusters multizona são criados com um caminho /healthz para você verificar o funcionamento de cada endereço IP de serviço. O comando HTTP cURL a seguir usa o caminho /healthz, que retorna o status ok de um IP íntegro.
    curl -X GET http://<router_svc_IP_or_hostname>/healthz -H "Host:router-default.<ingress_subdomain>"

    Se um ou mais dos endereços IP não retornar ok, confira o status de seus pods do controlador de ingresso.

  4. Obtenha o subdomínio do Ingresso fornecido pela IBM.

    ibmcloud oc cluster get --cluster <cluster_name_or_ID> | grep Ingress

    Saída de exemplo

    Ingress Subdomain:      mycluster-<hash>-0000.us-south.containers.appdomain.cloud
Ingress Secret:         mycluster-<hash>-0000

  5. Certifique-se de que o endereço IP do controlador de ingresso esteja registrado com o subdomínio de ingresso fornecido pela IBM do seu cluster. Por exemplo, em um cluster multizona, o IP do controlador de ingresso público em cada zona em que você tem nós de trabalhador deve ser registrado sob o mesmo subdomínio.

    host <ingress_subdomain>

    Saída de exemplo

    mycluster-<hash>-0000.us-south.containers.appdomain.cloud has address 169.XX.XX.XXX
mycluster-<hash>-0000.us-south.containers.appdomain.cloud has address 169.XX.XXX.XX

  6. Se você utilizar um domínio customizado, verifique se você usou seu provedor DNS para mapear o domínio customizado para o subdomínio fornecido pela IBM ou o endereço IP público do controlador de ingresso.

    • CNAME de subdomínio fornecido pela IBM: verifique se o seu domínio customizado é mapeado para o subdomínio fornecido pela IBM do cluster no registro de Nome canônico (CNAME).
        host www.my-domain.com
    ```
    Saída de exemplo
    ```sh {: screen}
    www.my-domain.com is an alias for mycluster-<hash>-0000.us-south.containers.appdomain.cloud
    mycluster-<hash>-0000.us-south.containers.appdomain.cloud has address 169.XX.XX.XXX
    mycluster-<hash>-0000.us-south.containers.appdomain.cloud has address 169.XX.XX.XXX
    ```
* **Registro A do endereço IP público**: Verifique se o seu domínio customizado é mapeado para o endereço IP público móvel do controlador de ingresso no registro A.
```sh {: pre}
    host www.my-domain.com
    ```
    Saída de exemplo
    ```sh {: screen}
    www.my-domain.com has address 169.XX.XX.XXX
    www.my-domain.com has address 169.XX.XX.XXX
    ```