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.

Preview — Apigee APIM Operator for Kubernetes

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

Esta página descreve as etapas necessárias para instalar e configurar o operador APIM da Apigee para Kubernetes (pré-lançamento). Para saber mais sobre os benefícios do uso do 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 de APIM, confira 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 de APIM: antes de começar.

Funções exigidas

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

• Criar e gerenciar 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 da instância do Compute (roles/compute.instanceAdmin)
• Crie e gerencie 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 por meio de papéis personalizados ou de 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 do APIM:

1. Definir as variáveis de ambiente.
2. Ative as APIs necessárias.
3. Recuperar e configurar credenciais.
4. Instale o operador do APIM.
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 da Apigee, use o seguinte comando para definir as 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 que 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 saída do 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

Extraia as credenciais do cluster e crie uma conta de serviço para se conectar aos serviços 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 as funções e permissões necessárias à conta de serviço criada usando os seguintes comandos:
   • Função de administrador da Apigee: é necessária 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"

   • Função de administrador de extensão de serviço: é necessária 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"

   • Função de administrador de rede: é necessária 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, na sigla em inglês) 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 helm do operador do APIM 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 associar a uma identidade de carga de trabalho usada pelo operador do APIM para acessar os recursos necessários da Apigee e da 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 a KSA à conta de serviço Google que você criou em Extrair e configurar credenciais e atribui o papel workloadIdentityUser.

Pode levar alguns minutos, possivelmente sete 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\
  -- 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 do Kubernetes (CRDs, na sigla em inglês) e o operador do APIM:

1. Crie um namespace para o operador do APIM:

   kubectl create ns apim

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

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

3. Instale o operador do APIM:

   helm install apigee-apim-operator oci://us-docker.pkg.dev/apigee-release/apigee-k8s-tooling-helm-charts/apigee-apim-operator-helm --version 0.6.0 --set project_id=${PROJECT_ID} --set serviceAccount=apigee-apim-gsa@${PROJECT_ID}.iam.gserviceaccount.com --set apigeeOrg=${PROJECT_ID} --set generateEnv=TRUE --set apigeeMgmtUrl="https://apigee.googleapis.com" -n apim --atomic

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

   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-0.6.0	0.6.0      
   apigee-apim-operator	apim     	1       	2025-02-01 00:15:00.362829981 +0000 UTC	deployed	apigee-apim-operator-helm-0.6.0	0.6.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 do APIM 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 o READY não mostrar 1/1, consulte Resolver problemas do operador do APIM para resolver problemas de instalação.

Criar um ambiente da Apigee

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

Se você instalou o operador do 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/$ORG_NAME/environments" -H \
        "Authorization: Bearer $TOKEN" -H "content-type:application/json" \
         -d '{
           "name": "ENV_NAME",
           "properties": {
               "apigee-service-extension-enabled":"true"
         }
       }'

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

   • Para organizações de assinatura de 2024 e pagamento por uso:

     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" : ENV_TYPE,
       "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 é intermediário ou abrangente para oferecer suporte ao uso de proxies extensível. Esse recurso não pode ser usado com ambientes básicos.
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.

Resolver problemas

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

A seguir

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