Esta página foi traduzida pela API Cloud Translation.

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.

Nesta página, descrevemos como resolver problemas do operador da API Management do Apigee para Kubernetes. Há várias ferramentas disponíveis para resolver qualquer problema que você possa encontrar. Nesta página, descrevemos como verificar o status dos recursos personalizados, usar o Explorador de registros e resolver problemas com o tráfego de tempo de execução da Apigee.

Verificar o status do recurso personalizado

Cada recurso personalizado usado no operador de APIM da Apigee para Kubernetes contém um objeto de status com dois campos:

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

Quando um arquivo de recurso personalizado yaml é aplicado ao cluster, o Kubernetes faz as mudanças correspondentes na infraestrutura subjacente. Verificar o objeto de status do recurso personalizado pode fornecer informações sobre o estado do recurso e mostrar 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

Nesta seção, descrevemos como usar registros para resolver problemas com o recurso de gateway do Google Kubernetes Engine (GKE) e o 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 da Apigee e processar políticas. Os registros relacionados ao tráfego ext-proc podem ser úteis para solucionar problemas.

Ver registros de destaques de `ext-proc`

Para ver os registros do tráfego de destaque ext-proc:

Receba 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.
Siga as etapas em Ativar a geração de registros em um serviço de back-end.
Para ver os registros no console do Google Cloud , acesse a página Análise de registros:
Análise de registros

Consulte Mensagens de registro de um serviço de back-end para conferir as informações disponíveis de entrada de registro de destaque, incluindo a estrutura de payload JSON para a entrada de registro do balanceador de carga service_extension_info. Use o campo Pesquisar na Análise de registros para filtrar as informações relevantes.

Confira a seguir um exemplo de entrada de registro que pode aparecer para uma callout 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"
}

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 traduz esses eventos na configuração apropriada do Apigee.

Para conferir os registros do operador da APIM:

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

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

Clique em Executar consulta.
As entradas de registro filtradas são exibidas no painel Resultados da consulta.

Anote todos os problemas ao criar, atualizar ou excluir os serviços APIMExtensionPolicy in Google Cloud networks ou problemas com produtos de API nos planos de gerenciamento da Apigee.

Um exemplo de erro seria semelhante a este:

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 da APIM

Se você encontrar 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 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) está anotada corretamente pela instalação do Helm. Confirme isso com o seguinte comando:
```
kubectl describe serviceaccount apim-ksa -n NAMESPACE
```
Em que NAMESPACE é o namespace em que o operador da APIM está 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 é semelhante a esta: 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 os papéis e permissões corretos do IAM. Para confirmar isso, use o seguinte comando:
```
 gcloud iam service-accounts get-iam-policy \
apigee-apim-gsa@$PROJECT_ID.iam.gserviceaccount.com
```
A conta de serviço precisa ter o papel roles/iam.workloadIdentityUser.

Por exemplo, a saída a seguir 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
```
Nenhuma condição do IAM especial está presente nos papéis necessários, o que impediria o acesso do operador.

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

Nesta seção, descrevemos como solucionar problemas com o tráfego de tempo de execução da Apigee. As seções a seguir descrevem como solucionar problemas com solicitações válidas e inválidas.

Falha em solicitações válidas

Se não for possível enviar solicitações válidas para o ambiente de execução da Apigee, os seguintes problemas podem estar presentes:

O GKE Gateway não consegue acessar o ambiente de execução da Apigee.
Sua chave de 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 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 na chamada de extensão. Consulte os registros do GKE Gateway para mais detalhes.
Confirme se o serviço de back-end referenciado pelo serviço ext-proc está íntegro.
Revise a configuração do produto da API na Apigee:
- Confirme se o produto de 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 /** vai corresponder a qualquer caminho. Você também pode usar os caracteres curinga * ou ** para fazer a correspondência.
- Confirme se você tem um app de desenvolvedor configurado para o produto de API. O produto da API precisa estar vinculado a um app do desenvolvedor para validar as chaves de API dele.
Revise sua solicitação ao gateway:
- Confirme se a chave do consumidor foi transmitida no cabeçalho x-api-key.
- Verifique 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 são bem-sucedidas

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

FailOpen está definido como true na sua 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 corretos para seu gateway do GKE.

Use o comando a seguir para ver 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 está 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
    - 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

Análises ausentes

Se você não conseguir ver o Apigee API Analytics para o operador do APIM no console Google Cloud , saiba que o consumo do 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 de tempo de execução da Apigee:

Resolver problemas do operador do Apigee APIM para Kubernetes Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Verificar o status do recurso personalizado

Ver registros

Registros do GKE Gateway

Ver registros de destaques de ext-proc

Registros do operador do APIM

Solucionar erros de acesso 403 no operador da APIM

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

Falha em solicitações válidas

Etapas da solução de problemas

Solicitações inválidas são bem-sucedidas

Etapas da solução de problemas

Análises ausentes

Outros recursos

Resolver problemas do operador do Apigee APIM para Kubernetes

Ver registros de destaques de `ext-proc`