Resolver problemas do operador do Apigee APIM para Kubernetes

Esta página se aplica à Apigee, mas não à Apigee híbrida.

Confira a documentação da Apigee Edge.

Esta página descreve como resolver problemas do operador APIM da Apigee para Kubernetes. Há várias ferramentas disponíveis para resolver problemas. Esta página descreve como verificar o status dos recursos personalizados, usar o Logs Explorer e resolver problemas com o tráfego do ambiente de execução da Apigee.

Verificar o status do recurso personalizado

Todos os recursos personalizados usados no operador do Apigee APIM para Kubernetes contêm um objeto de status com dois campos:

  • ESTADO: descreve o estado do recurso. Os valores incluem running e created.
  • ERRORMESSAGE: se a operação do recurso falhar, o campo da mensagem de erro será preenchido com uma mensagem explicativa.

Quando um arquivo yaml de recurso personalizado é aplicado ao cluster, o Kubernetes faz as mudanças correspondentes na infraestrutura. A verificação do objeto de status do recurso personalizado pode fornecer informações sobre o estado do recurso e mostrar os erros resultantes se as operações de infraestrutura subjacentes falharem.

Verifique o status do recurso personalizado com o seguinte comando: 

kubectl -n NAMESPACE get CUSTOM_RESOURCE_KIND CUSTOM_RESOURCE_NAME

Em que:

  • NAMESPACE: o namespace em que o recurso personalizado é implantado.
  • CUSTOM_RESOURCE_KIND: o tipo do recurso personalizado.
  • CUSTOM_RESOURCE_NAME: o nome do recurso personalizado.

Por exemplo, o comando a seguir verifica o status do recurso personalizado APIMExtensionPolicy chamado apim-extension-policy no namespace apim: 

kubectl -n apim get APIMExtensionPolicy apim-extension-policy-1

O resultado será assim:

NAME                      STATE                  ERRORMESSAGE
apim-extension-policy     Create_Update_Failed   Permission denied

Ver registros

Esta seção descreve como usar registros para resolver problemas no recurso de gateway do Google Kubernetes Engine (GKE) e no recurso do operador do APIM.

Registros do GKE Gateway

Quando você aplica a APIMExtensionPolicy, o gateway do GKE criado no cluster é configurado com uma extensão de tráfego. A extensão usa o processamento externo do Kubernetes (ext-proc) para chamar o ambiente de execução e as políticas de processo da Apigee. Os registros relacionados ao tráfego ext-proc podem ser úteis para resolver problemas.

Conferir os registros de destaques de ext-proc

Para conferir os registros do tráfego de chamada ext-proc:

  1. Encontre o ID do serviço de back-end criado para o ambiente de execução da Apigee: 
    kubectl get gateways.gateway.networking.k8s.io GATEWAY_NAME
   -o=jsonpath="{.metadata.annotations.networking\.gke\.io/backend-services}"

    Em que GATEWAY_NAME é o nome do gateway do GKE.

    O serviço de back-end vai conter apigee-service-extension-backend-service no ID.

  2. Siga as etapas em Ativar a geração de registros em um serviço de back-end para ativar a geração de registros.
  3. Para conferir os registros no console do Google Cloud, acesse a página Análise de registros:

    Explorador de registros

  4. Consulte Mensagens de registro para um serviço de back-end para ver as informações de entrada de registro de chamada disponíveis, incluindo a estrutura de payload JSON para a entrada de registro do balanceador de carga service_extension_info. Use o campo Pesquisar no Explorador de registros para filtrar as informações relevantes.

    O exemplo a seguir é uma entrada de registro que pode aparecer para uma chamada ext-proc com falha: 

    {
  "insertId": "s14dmrf10g6hi",
  "jsonPayload": {
    "serviceExtensionInfo": [
      {
        "extension": "ext11",
        "perProcessingRequestInfo": [
          {
            "eventType": "REQUEST_HEADERS",
            "latency": "0.001130s"
          }
        ],
        "backendTargetType": "BACKEND_SERVICE",
        "grpcStatus": "ABORTED",
        "backendTargetName": "gkegw1-2y13-apigee-service-extension-backend-service-443-yhsnrauznpwh",
        "chain": "chain1",
        "resource": "projects/${PROJECT}/locations/us-west1/lbTrafficExtensions/apim-extension"
      }
    ],
    "backendTargetProjectNumber": "projects/763484362408",
    "@type": "type.googleapis.com/google.cloud.loadbalancing.type.LoadBalancerLogEntry"
  },
  "httpRequest": {
    ...
  },
  "resource": {
    "type": "internal_http_lb_rule",
    "labels": {
      ...
    }
  },
  "timestamp": "2024-04-01T20:15:15.182137Z",
  "severity": "INFO",
  "logName": "projects/${PROJECT}/logs/loadbalancing.googleapis.com%2Frequests",
  "receiveTimestamp": "2024-04-01T20:15:18.209706689Z"
}

    O campo grpcStatus mostra ABORTED.

Registros do operador do APIM

O operador do APIM é um operador do Kubernetes que processa eventos de recursos personalizados do APIM (como criar, ler, atualizar e excluir) e os traduz na configuração adequada do Apigee.

Para conferir os registros do operador do APIM:

  1. Para conferir os registros no console do Google Cloud, acesse a página Análise de registros:

    Explorador de registros

  2. No painel de consulta, insira uma consulta semelhante a esta: 
    resource.type="k8s_container"
resource.labels.namespace_name="apim"
labels.k8s-pod/app="apigee-apim-operator" severity>=DEFAULT
  3. Clique em Executar consulta.
  4. As entradas de registro filtradas são exibidas no painel Resultados da consulta.
  5. Anote todos os problemas com a criação, atualização ou exclusão dos serviços de rede APIMExtensionPolicy em Google Cloud ou com os produtos de API nos planos de gerenciamento da Apigee.

    Um exemplo de erro é semelhante ao seguinte: 

    ApimExtensionPolicy creation status400
response body:{
  "error": {
    "code": 400,
    "message": "The request was invalid: backend service https://www.googleapis.com/compute/v1/projects/... must use HTTP/2 as the protocol",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "lb_traffic_extension.extension_chains[0].extensions[0].service"
          }
        ]
      },
      {
        "@type": "type.googleapis.com/google.rpc.RequestInfo",
        "requestId": "d4e6f00ab5d367ec"
      }
    ]
  }
}

Solucionar erros de acesso 403 no Operador do APIM

Se você descobrir erros de código de status 403 indicando problemas de acesso, confirme o seguinte:

  • O cluster do GKE tem a federação de identidade da carga de trabalho ativada. A federação de identidade da carga de trabalho é ativada por padrão para clusters criados com o modo Autopilot. Se você criou um cluster usando o modo padrão, ative a federação de identidade da carga de trabalho conforme descrito em Ativar a federação de identidade da carga de trabalho para o GKE.
  • A conta de serviço do Kubernetes (apim-ksa) é anotada corretamente pela instalação do Helm. Para confirmar isso, use o seguinte comando: 
    kubectl describe serviceaccount apim-ksa -n NAMESPACE

    Em que NAMESPACE é o namespace em que o operador do APIM é implantado.

    Confirme se apigee-apim-gsa@${PROJECT}.iam.gserviceaccount.com aparece no campo Anotações da saída.

    Exemplo: 

    kubectl describe serviceaccount apim-ksa -n apim

    A saída será semelhante a esta: Nome: apim-ksa Namespace: apim Rótulos: ... Anotações: iam.gke.io/gcp-service-account: apigee-apim-gsa@apigee-product-demo.iam.gserviceaccount.com ... Secrets de pull de imagem: Secrets acionáveis: Tokens: Eventos:

  • A conta de serviço apigee-apim-gsa tem os papéis e as permissões do IAM corretos. Para confirmar isso, use o seguinte comando: 
     gcloud iam service-accounts get-iam-policy \
apigee-apim-gsa@${PROJECT}.iam.gserviceaccount.com

    A conta de serviço precisa ter o papel roles/iam.workloadIdentityUser.

    Por exemplo, a saída a seguir mostra o papel roles/iam.workloadIdentityUser: 

    bindings:
- members:
  - serviceAccount:${PROJECT}.svc.id.goog[/apim-ksa]
  role: roles/iam.workloadIdentityUser
etag: BwYUpeaM7XQ=
version: 1
  • Não há condições especiais do IAM nos papéis necessários, o que impediria o acesso do operador.

Resolver problemas com o tráfego de execução da Apigee

Esta seção descreve como resolver problemas com o tráfego do ambiente do Apigee. As seções a seguir descrevem como resolver problemas com solicitações válidas e inválidas.

As solicitações válidas falham

Se você não conseguir enviar solicitações válidas para o ambiente de execução da Apigee, os seguintes problemas podem estar presentes:

  • O gateway do GKE não consegue acessar o ambiente de execução do Apigee.
  • As credenciais da chave de API ou do JWT são inválidas.
  • O produto da API Apigee não está configurado para o destino e o ambiente corretos.
  • O ambiente de execução da Apigee não tem acesso ao produto da API Apigee.

Etapas da solução de problemas

Para resolver problemas com solicitações válidas:

  • Ative os registros do balanceador de carga para o gateway do GKE e analise-os para determinar a causa das falhas da chamada de extensão. Consulte os registros do gateway do GKE para mais detalhes.
  • Confirme se o serviço de back-end referenciado pelo serviço externo está em bom estado.
  • Revise a configuração do produto da API na Apigee:
    • Confirme se o produto da API está ativado para o ambiente correto (por exemplo, test ou prod).
    • Confirme se o caminho do recurso corresponde à sua solicitação. Um caminho como / ou /** corresponderá a qualquer caminho. Também é possível usar os caracteres curinga * ou ** para fazer a correspondência.
    • Confirme se você tem um app de desenvolvedor configurado para o produto da API. O produto da API precisa estar vinculado a um app do desenvolvedor para validar as chaves de API.
  • Analise sua solicitação para o gateway:
    • Confirme se a chave do consumidor é transmitida no cabeçalho x-api-key.
    • Confira se a chave do consumidor é válida. As credenciais do app do desenvolvedor precisam ser aprovadas para seu produto de API.

Solicitações inválidas bem-sucedidas

Se as solicitações inválidas para o ambiente de execução da Apigee forem bem-sucedidas, os seguintes problemas poderão estar presentes:

  • FailOpen está definido como true na APIMExtensionPolicy.
  • Não há uma extensão de tráfego definida para o balanceador de carga do gateway do GKE.

Etapas da solução de problemas

Para resolver problemas com solicitações inválidas:

  • Confirme se uma extensão de serviço existe e faz referência aos serviços de back-end e à regra de encaminhamento corretas para o gateway do GKE.

    Use o comando a seguir para conferir a extensão do serviço: 

    gcloud beta service-extensions lb-traffic-extensions describe NAME_OF_APIM_EXTENSION_POLICY --location=LOCATION  --project=PROJECT

    Em que:

    • NAME_OF_APIM_EXTENSION_POLICY: o nome do recurso personalizado APIMExtensionPolicy.
    • PROJECT: o ID do projeto.
    • LOCATION: o local do cluster do GKE em que o gateway foi implantado.

    A saída será semelhante a esta: 

    ...
extensionChains:
- extensions:
  - authority: ext11.com
    failOpen: false  # make sure this is false
    name: ext11
    service: https://www.googleapis.com/compute/v1/projects/my-project/regions/us-west1/backendServices/gkegw1-2y13-apigee-service-extension-backend-service-443-yhsnrauznpwh # Confirm this is correct 
    supportedEvents:
    - REQUEST_HEADERS
    - RESPONSE_HEADERS
    - REQUEST_BODY
    - RESPONSE_BODY
    timeout: 0.100s
  matchCondition:
    celExpression: 'true' # Confirm this is set
  name: chain1
forwardingRules:
- https://www.googleapis.com/compute/v1/projects/my-project/regions/us-west1/forwardingRules/gkegw1-2y13-default-internal-http-h6c1hhp1ce6q # Confirm this is the correct forwarding rule for your application load balancer
loadBalancingScheme: INTERNAL_MANAGED
name: projects/my-project/locations/us-west1/lbTrafficExtensions/apim-extension-policy-1

    Análises ausentes

    Se não for possível acessar a Análise de APIs da Apigee para o Operador de APIM no console do Google Cloud, saiba que a coleta de dados da Apigee pode demorar alguns minutos.

    Outros recursos

    Os recursos a seguir também podem ser usados para resolver problemas com o operador da APIM e o tráfego do ambiente de execução da Apigee: