Instalar o operador 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 as etapas necessárias para instalar e configurar o operador de APIM da Apigee para Kubernetes. Para saber mais sobre os benefícios de usar o operador APIM, consulte Visão geral do operador APIM do Apigee para Kubernetes.

Antes de começar

Antes de começar a instalar o operador do APIM, verifique se você tem as funções e permissões necessárias para concluir as etapas e se concluiu as tarefas de pré-requisito descritas em Operador do APIM: antes de começar.

Funções exigidas

Para receber as permissões necessárias para instalar o operador do APIM, peça ao administrador para conceder a você os seguintes papéis do IAM na organização:

• Crie e gerencie o cluster do GKE: Administrador de contêineres (roles/container.admin)
• Criar e gerenciar contas de serviço: Administrador da conta de serviço (roles/iam.serviceAccountAdmin)
• Criar e gerenciar extensões de serviço: Administrador de extensões de serviço (roles/networkservices.serviceExtensionsAdmin)
• Criar e gerenciar grupos de endpoints de rede (NEGs): Administrador de instâncias do Compute (roles/compute.instanceAdmin)
• Criar e gerenciar serviços de back-end: Administrador do balanceador de carga do Compute (roles/compute.loadBalancerAdmin)
• Criar e gerenciar recursos da Apigee: Administrador da Apigee (roles/apigee.admin)

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Instalar e configurar o operador do APIM

As seções a seguir descrevem as etapas necessárias para instalar e configurar o operador da APIM:

1. Definir as variáveis de ambiente.
2. Ative as APIs necessárias.
3. Recupere e configure as credenciais.
4. Instale o operador da API Management.
5. Crie uma identidade da carga de trabalho.
6. Crie um ambiente da Apigee.
7. Verifique a configuração do gateway do GKE.

Defina as variáveis de ambiente

No projeto Google Cloud que contém sua instância do Apigee, use o seguinte comando para definir variáveis de ambiente:

export PROJECT_ID=PROJECT_ID
export CLUSTER_NAME=CLUSTER_NAME
export REGION=REGION
export APIGEE_ORG=APIGEE_ORG

Em que:

• PROJECT_ID é o ID do projeto com sua instância da Apigee.
• CLUSTER_NAME é o nome do cluster do GKE.
• REGION é a região do cluster do GKE.
• APIGEE_ORG é definido como o mesmo valor de PROJECT_ID.

Para confirmar se as variáveis de ambiente estão definidas corretamente, execute o seguinte comando:

echo $PROJECT_ID $CLUSTER_NAME $REGION $APIGEE_ORG

Ativar APIs obrigatórias

O operador do APIM exige acesso às seguintes APIs:

Nome	Título
apigee.googleapis.com	API Apigee
compute.googleapis.com	API Compute Engine
networkservices.googleapis.com	API Network Services
container.googleapis.com	API Google Kubernetes Engine

Use o seguinte comando para confirmar se as APIs necessárias estão ativadas:

gcloud services list --project=$PROJECT_ID

Se as APIs necessárias não estiverem listadas na resposta ao comando, ative-as:

gcloud services enable apigee.googleapis.com --project=$PROJECT_ID
gcloud services enable compute.googleapis.com --project=$PROJECT_ID
gcloud services enable networkservices.googleapis.com --project=$PROJECT_ID
gcloud services enable container.googleapis.com --project=$PROJECT_ID

Recuperar e configurar credenciais

Recupere as credenciais do cluster e crie uma conta de serviço para se conectar aos serviços do Google Cloud :

1. Receba as credenciais do cluster usando o seguinte comando:

   gcloud container clusters get-credentials $CLUSTER_NAME --location=$REGION --project=$PROJECT_ID

   Essas credenciais são usadas para se comunicar com o cluster do GKE criado nas etapas de pré-requisito.

2. Configure as credenciais da conta de serviço para se conectar aos serviços Google Cloud :

   gcloud iam service-accounts create apigee-apim-gsa

3. Conceda os papéis e as permissões necessárias à conta de serviço criada usando os seguintes comandos:
   • Papel de administrador da Apigee: necessário para criar e gerenciar recursos da Apigee.

     gcloud projects add-iam-policy-binding $PROJECT_ID \
         --member "serviceAccount:apigee-apim-gsa@$PROJECT_ID.iam.gserviceaccount.com" \
         --role "roles/apigee.admin"

   • Papel de administrador da extensão de serviço: necessário para criar e gerenciar extensões de serviço.

     gcloud projects add-iam-policy-binding $PROJECT_ID \
         --member "serviceAccount:apigee-apim-gsa@$PROJECT_ID.iam.gserviceaccount.com" \
         --role "roles/networkservices.serviceExtensionsAdmin"

   • Papel de administrador de rede: necessário para gerenciar o acesso à Apigee usando extensões de serviço.

     gcloud projects add-iam-policy-binding $PROJECT_ID \
         --member "serviceAccount:apigee-apim-gsa@$PROJECT_ID.iam.gserviceaccount.com" \
         --role "roles/compute.networkAdmin"

   • Função de administrador do balanceador de carga: necessária para gerenciar o acesso entre grupos de endpoints de rede (NEGs) e serviços de back-end.

     gcloud projects add-iam-policy-binding $PROJECT_ID \
         --member "serviceAccount:apigee-apim-gsa@$PROJECT_ID.iam.gserviceaccount.com" \
         --role "roles/compute.loadBalancerAdmin"

     gcloud projects add-iam-policy-binding $PROJECT_ID \
         --member "serviceAccount:apigee-apim-gsa@$PROJECT_ID.iam.gserviceaccount.com" \
         --role "roles/iam.workloadIdentityUser"

Criar uma identidade da carga de trabalho

A instalação do operador do APIM helm na próxima etapa cria uma conta de serviço do Kubernetes (KSA) necessária chamada apim-ksa no namespace apim. Quando criada, a KSA contém a anotação necessária para associação a uma identidade da carga de trabalho usada pelo operador do APIM para acessar os recursos necessários da Apigee e do Service Networking.

Para criar a identidade da carga de trabalho, use o seguinte comando:

gcloud iam service-accounts add-iam-policy-binding apigee-apim-gsa@$PROJECT_ID.iam.gserviceaccount.com --role roles/iam.workloadIdentityUser --member "serviceAccount:$PROJECT_ID.svc.id.goog[apim/apim-ksa]"

Esse comando vincula o KSA à conta de serviço Google que você criou em Recuperar e configurar credenciais e atribui a função workloadIdentityUser.

Pode levar alguns minutos, talvez 7 minutos ou mais, para que as mudanças na identidade da carga de trabalho sejam propagadas pelo sistema.

Para confirmar se a identidade da carga de trabalho foi criada, use os seguintes comandos:

gcloud config set project $PROJECT_ID

kubectl run --rm -it --image google/cloud-sdk:slim \
  --namespace apim workload-identity-test \
  --overrides='{ "spec": { "serviceAccountName": "apim-ksa" } }'  \
  -- gcloud auth list

A saída será parecida com esta:

Credentialed Accounts
  ACTIVE  ACCOUNT
  *       GSA@$PROJECT_ID.iam.gserviceaccount.com

Instalar definições de recursos personalizados (CRDs) e o operador do APIM

Instale as definições de recursos personalizados (CRDs) do Kubernetes e o operador do APIM:

1. Crie um namespace para o operador da API Management:

   kubectl create ns apim

2. Instale as definições de recursos personalizados (CRDs) do operador do APIM:

   helm install apigee-apim-crds -n apim \
     oci://us-docker.pkg.dev/apigee-release/apigee-k8s-tooling-helm-charts/apigee-apim-operator-crds \
     --version 1.0.0 \
     --atomic

3. Instale o operador da APIM:

   helm install apigee-apim-operator -n apim \
     oci://us-docker.pkg.dev/apigee-release/apigee-k8s-tooling-helm-charts/apigee-apim-operator-helm \
     --version 1.0.0 \
     --set projectId=$PROJECT_ID \
     --set serviceAccount=apigee-apim-gsa@$PROJECT_ID.iam.gserviceaccount.com \
     --set apigeeOrg=$PROJECT_ID \
     --set generateEnv=TRUE \
     --atomic

4. Confirme se a instalação foi concluída corretamente:

   helm list -n apim

   A saída será parecida com esta:

   NAME                	NAMESPACE	REVISION	UPDATED                                	STATUS  	CHART                          	APP VERSION
   apigee-apim-crds    	apim     	1       	2025-02-01 00:17:03.399810627 +0000 UTC	deployed	apigee-apim-operator-crds-1.0.0	1.0.0
   apigee-apim-operator	apim     	1       	2025-02-01 00:15:00.362829981 +0000 UTC	deployed	apigee-apim-operator-helm-1.0.0	1.0.0   

5. Confirme se a KSA foi criada com a anotação necessária:

   kubectl describe serviceaccounts apim-ksa -n apim

   A saída será parecida com esta:

   Name:                apim-ksa
   Namespace:           apim
   ...
   Annotations:         iam.gke.io/gcp-service-account: [e-mail]

6. Confirme se o operador da API Management está em execução nos pods do cluster:

   kubectl get pods -n apim

   A saída será parecida com esta:

   NAME                                    READY   STATUS    RESTARTS     AGE
   apigee-apim-operator-8559d4994b-h55fl   1/1     Running   0            8m34s
   

   Se o STATUS não for Running ou se READY não mostrar 1/1, consulte Resolver problemas do operador da APIM para resolver problemas de instalação.

Criar um ambiente da Apigee

Se você instalou o operador do APIM usando generateEnv=TRUE na etapa anterior, ele cria um novo ambiente da Apigee quando a política de extensão do APIM é criada e aplicada. O nome do novo ambiente terá o prefixo: apim-enabled-dep-env.

Se você instalou o operador da APIM com generateEnv=FALSE, crie um novo ambiente da Apigee:

1. Defina o TOKEN necessário para o comando curl:

   export TOKEN=$(gcloud auth print-access-token)

2. Crie o ambiente usando um dos seguintes comandos:
   • Para organizações com assinatura de 2021:

     curl -X POST "https://apigee.googleapis.com/v1/organizations/$APIGEE_ORG/environments" -H \
       "Authorization: Bearer $TOKEN" -H "content-type:application/json" \
         -d '{
           "name": "ENV_NAME",
           "displayName": "ENV_NAME",
           "state": "ACTIVE",
           "deploymentType": "PROXY",
           "apiProxyType": "PROGRAMMABLE",
           "properties": {
             "property": [
               {
                 "name": "apigee-service-extension-enabled",
                 "value": "true"
               }
             ]
           }
       }'

     Em que ENV_NAME é o nome do ambiente a ser criado.

   • Para organizações com assinatura de 2024 e pagamento por utilização:

     curl -i -X POST -H "Authorization: Bearer $TOKEN"  "https://apigee.googleapis.com/v1/organizations/$APIGEE_ORG/environments" -H "Content-Type:application/json" -d '{
       "name": "ENV_NAME",
       "displayName": "ENV_NAME",
       "state": "ACTIVE",
       "deploymentType": "PROXY",
       "apiProxyType": "PROGRAMMABLE",
       "type" : "COMPREHENSIVE",
       "properties": {
         "property": [
           {
             "name": "apigee-service-extension-enabled",
             "value": "true"
           }
         ]
       }
     }'

     Em que:

     • ENV_NAME é o nome do ambiente a ser criado.
     • ENV_TYPE é o tipo de ambiente a ser criado. Por exemplo, INTERMEDIATE ou COMPREHENSIVE.
     Observação: o ambiente criado nesta etapa ou pelo operador do APIM é um ambiente intermediário ou abrangente, para oferecer suporte ao uso de proxies extensíveis. Esse recurso não pode ser usado com ambientes básicos.

   Para verificar se o ambiente foi criado com sucesso:

   curl -i -H "Authorization: Bearer $TOKEN" \
     "https://apigee.googleapis.com/v1/organizations/$APIGEE_ORG/environments"

3. Anexe o ambiente à sua instância da Apigee:

   curl -i -X POST -H "Authorization: Bearer $TOKEN" \
     "https://apigee.googleapis.com/v1/organizations/$APIGEE_ORG/instances/INSTANCE_NAME/attachments" \
     -H "Content-Type:application/json" -d '{"environment": "ENV_NAME"}'

   Em que:

   • INSTANCE_NAME é o nome da instância da Apigee.
   • ENV_NAME é o nome do ambiente que você criou na etapa anterior.

   Para verificar o status da operação de vinculação do ambiente:

   curl -X GET -H "Authorization: Bearer $TOKEN" \
     "https://apigee.googleapis.com/v1/organizations/$APIGEE_ORG/operations/OPERATION_ID"

   Em que OPERATION_ID é o ID da operação de vinculação do ambiente.

Resolver problemas

Se você encontrar problemas ao instalar o operador APIM, consulte Resolver problemas do operador APIM para encontrar soluções para erros comuns.

A seguir

• Usar políticas da Apigee com o operador do APIM.
• Adicione políticas da Apigee ao gateway do GKE.