Resolva problemas do operador APIM da Apigee para Kubernetes

Esta página aplica-se ao Apigee, mas não ao Apigee Hybrid.

Veja a documentação do Apigee Edge.

Esta página descreve como resolver problemas do operador da APIM do Apigee para Kubernetes. Existem várias ferramentas disponíveis para resolver quaisquer problemas que possa encontrar. Esta página descreve como verificar o estado dos recursos personalizados, usar o Explorador de registos e resolver problemas com o tráfego de tempo de execução do Apigee.

Verifique o estado do recurso personalizado

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

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

Quando um ficheiro de recursos personalizados yaml é aplicado ao cluster, o Kubernetes faz as alterações correspondentes à infraestrutura subjacente. A verificação do objeto de estado do recurso personalizado pode fornecer informações sobre o estado do recurso e apresentar quaisquer erros resultantes se as operações de infraestrutura subjacentes falharem.

Pode verificar o estado do recurso personalizado com o seguinte comando: 

kubectl -n NAMESPACE get CUSTOM_RESOURCE_KIND CUSTOM_RESOURCE_NAME

Onde:

  • NAMESPACE: o espaço de nomes onde o recurso personalizado está implementado.
  • CUSTOM_RESOURCE_KIND: o tipo do recurso personalizado.
  • CUSTOM_RESOURCE_NAME: o nome do recurso personalizado.

Por exemplo, o comando seguinte verifica o estado do recurso personalizado APIMExtensionPolicy denominado apim-extension-policy no espaço de nomes apim: 

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

O resultado é semelhante ao seguinte:

NAME                      STATE                  ERRORMESSAGE
apim-extension-policy     Create_Update_Failed   Permission denied

Ver registos

Esta secção descreve como usar os registos para resolver problemas do recurso do Gateway do Google Kubernetes Engine (GKE) e do recurso do operador da APIM.

Registos do GKE Gateway

Quando aplica a APIMExtensionPolicy, o GKE Gateway que criou no seu cluster é configurado com uma extensão de tráfego. A extensão usa o processamento externo do Kubernetes (ext-proc) para chamar o tempo de execução do Apigee e processar políticas. Os registos relacionados com o tráfego ext-proc podem ser úteis na resolução de problemas.

Veja os registos de textos destacados ext-proc

Para ver os registos do tráfego de ext-proc textos destacados:

  1. Obtenha o ID do serviço de back-end criado para o tempo de execução do 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-serviceno ID.

  2. Siga os passos em Ative o registo num serviço de back-end para ativar o registo.
  3. Para ver os registos na Google Cloud consola, aceda à página Explorador de registos:

    Explorador de registos

  4. Reveja o artigo Mensagens de registo para um serviço de back-end para ver as informações de entrada de registo de chamadas disponíveis, incluindo a estrutura do payload JSON para a entrada de registo do equilibrador de carga service_extension_info. Pode usar o campo Pesquisar no Explorador de registos para filtrar as informações relevantes.

    O exemplo seguinte é uma entrada de registo que pode ver para um texto destacado 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_ID/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_ID/logs/loadbalancing.googleapis.com%2Frequests",
  "receiveTimestamp": "2024-04-01T20:15:18.209706689Z"
}

    Tenha em atenção que o campo grpcStatus mostra ABORTED.

Registos do operador da APIM

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

Para ver os registos do operador da APIM:

  1. Para ver os registos na Google Cloud consola, aceda à página Explorador de registos:

    Explorador de registos

  2. No painel de consultas, introduza uma consulta semelhante à seguinte: 
    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 registo filtradas são apresentadas no painel Resultados da consulta.
  5. Tome nota de quaisquer problemas com a criação, a atualização ou a eliminação dos serviços de rede APIMExtensionPolicy em Google Cloud ou problemas com produtos de API nos planos de gestão da Apigee.

    Um erro de exemplo teria um aspeto 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"
      }
    ]
  }
}

Resolva problemas de erros de acesso 403 no operador da APIM

Se descobrir erros do código de estado 403 que indicam problemas de acesso, confirme o seguinte:

  • O seu cluster do GKE tem a federação de identidade da carga de trabalho ativada. A federação de identidade da carga de trabalho está ativada por predefinição para os clusters criados com o modo de piloto automático. Se criou um cluster com o modo padrão, no caso de estar a usar um cluster padrão, ative a federação de identidades de carga de trabalho, conforme descrito no artigo Ative a federação de identidades de carga de trabalho para o GKE.
  • A conta de serviço do Kubernetes (apim-ksa) está corretamente anotada pela instalação do Helm. Pode confirmar esta informação com o seguinte comando: 
    kubectl describe serviceaccount apim-ksa -n NAMESPACE

    Em que NAMESPACE é o espaço de nomes onde o operador da APIM está implementado.

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

    Por exemplo: 

    kubectl describe serviceaccount apim-ksa -n apim

    O resultado é semelhante ao seguinte: Name: apim-ksa Namespace: apim Labels: ... Annotations: iam.gke.io/gcp-service-account: apigee-apim-gsa@apigee-product-demo.iam.gserviceaccount.com ... Image pull secrets: Mountable secrets: Tokens: Events:

  • A conta de serviço apigee-apim-gsa tem as funções e as autorizações do IAM corretas. Pode confirmar esta informação com o seguinte comando: 
     gcloud iam service-accounts get-iam-policy \
apigee-apim-gsa@$PROJECT_ID.iam.gserviceaccount.com

    A conta de serviço tem de ter a função roles/iam.workloadIdentityUser.

    Por exemplo, o resultado seguinte mostra a função roles/iam.workloadIdentityUser: 

    bindings:
- members:
  - serviceAccount:$PROJECT_ID.svc.id.goog[/apim-ksa]
  role: roles/iam.workloadIdentityUser
etag: BwYUpeaM7XQ=
version: 1
  • Não existem condições de IAM especiais nas funções necessárias, o que impediria o acesso do operador.

Resolva problemas com o tráfego de tempo de execução do Apigee

Esta secção descreve como resolver problemas com o tráfego do tempo de execução do Apigee. As secções seguintes descrevem como resolver problemas com pedidos válidos e inválidos.

Falha nos pedidos válidos

Se não conseguir enviar pedidos válidos para o seu tempo de execução do Apigee, podem estar presentes os seguintes problemas:

  • O GKE Gateway não consegue aceder ao tempo de execução do Apigee.
  • A sua chave da API ou credenciais JWT são inválidas.
  • O produto da API Apigee não está configurado para o destino e o ambiente corretos.
  • O tempo de execução do Apigee não tem conhecimento do produto da API Apigee.

Passos de resolução de problemas

Para resolver problemas com pedidos válidos:

  • Ative os registos do balanceador de carga para o GKE Gateway e reveja os registos para determinar a causa das falhas do apelo de extensão. Consulte os registos do GKE Gateway para ver mais detalhes.
  • Confirme que o serviço de back-end referenciado a partir do serviço ext-proc está em bom estado.
  • Reveja a configuração do produto de API no Apigee:
    • Confirme se o produto API está ativado para o ambiente correto (por exemplo, test ou prod).
    • Confirme se o caminho do recurso corresponde ao seu pedido. Um caminho como / ou /** corresponde a qualquer caminho. Também pode usar os carateres universais * ou ** para a correspondência.
    • Confirme que tem uma app de programador configurada para o produto API. O produto da API tem de estar associado a uma app de programador para validar as respetivas chaves da API.
  • Reveja o seu pedido ao gateway:
    • Confirme que a chave do consumidor é transmitida no cabeçalho x-api-key.
    • Certifique-se de que a chave do consumidor é válida. As credenciais da app de programador têm de ser aprovadas para o seu produto de API.

Os pedidos inválidos são bem-sucedidos

Se os pedidos inválidos ao seu tempo de execução do Apigee forem bem-sucedidos, podem estar presentes os seguintes problemas:

  • FailOpen está definido como true na sua APIMExtensionPolicy.
  • Não existe nenhuma extensão de tráfego definida para o equilibrador de carga do GKE Gateway.

Passos de resolução de problemas

Para resolver problemas com pedidos inválidos:

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

    Use o seguinte comando para ver a extensão de serviço: 

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

    Onde:

    • NAME_OF_APIM_EXTENSION_POLICY: o nome do recurso personalizado APIMExtensionPolicy.
    • PROJECT: o ID do projeto.
    • LOCATION: a localização do cluster do GKE onde o gateway está implementado.

    O resultado será semelhante ao seguinte: 

    ...
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
    - REQUEST_TRAILERS
    - RESPONSE_TRAILERS
    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

    Estatísticas em falta

    Se não conseguir ver as estatísticas de APIs da Apigee para o operador APIM na Google Cloud consola, tenha em atenção que a receção da Apigee pode sofrer um atraso de alguns minutos.

    Recursos adicionais

    Também pode usar os seguintes recursos para resolver problemas com o operador da API e o tráfego de tempo de execução do Apigee: