Instale o operador da 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 os passos necessários para instalar e configurar o operador da API Apigee para Kubernetes. Para saber mais sobre as vantagens de usar o operador APIM, consulte o artigo Vista geral do operador APIM do Apigee para Kubernetes.

Antes de começar

Antes de começar a instalar o operador APIM, certifique-se de que tem as funções e as autorizações necessárias para concluir os passos e que concluiu as tarefas pré-requisitos descritas no artigo Operador APIM: antes de começar.

Funções necessárias

Para receber as autorizações de que precisa para instalar o operador APIM, peça ao seu administrador para lhe conceder as seguintes funções de IAM na organização:

• Criar e gerir o cluster do GKE: Administrador de contentores (roles/container.admin)
• Criar e gerir contas de serviço: Administrador da conta de serviço (roles/iam.serviceAccountAdmin)
• Crie e faça a gestão de extensões de serviços: Administrador de extensões de serviços (roles/networkservices.serviceExtensionsAdmin)
• Criar e gerir grupos de pontos finais de rede (NEGs): Administrador de instâncias de computação (roles/compute.instanceAdmin)
• Criar e gerir serviços de back-end: Administrador do balanceador de carga do Compute (roles/compute.loadBalancerAdmin)
• Criar e gerir recursos do Apigee: Administrador do Apigee (roles/apigee.admin)

Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Também pode conseguir as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.

Instale e configure o operador APIM

As secções seguintes descrevem os passos necessários para instalar e configurar o operador APIM:

1. Defina variáveis de ambiente.
2. Ative as APIs necessárias.
3. Obtenha e configure as credenciais.
4. Instale o operador da APIM.
5. Crie uma identidade de carga de trabalho.
6. Crie um ambiente do Apigee.
7. Valide a configuração do GKE Gateway.

Defina variáveis de ambiente

No Google Cloud projeto que contém a 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

Onde:

• PROJECT_ID é o ID do projeto com a sua instância do Apigee.
• CLUSTER_NAME é o nome do seu cluster do GKE.
• REGION é a região do seu cluster do GKE.
• APIGEE_ORG está definido com o mesmo valor que PROJECT_ID.

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

echo $PROJECT_ID $CLUSTER_NAME $REGION $APIGEE_ORG

Ative as APIs necessárias

O operador da APIM requer 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 que as APIs necessárias estão ativadas:

gcloud services list --project=$PROJECT_ID

Se não vir as APIs necessárias listadas no resultado 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

Obtenha e configure credenciais

Obtenha as credenciais do cluster e crie uma conta de serviço para estabelecer ligação aos serviços Google Cloud :

1. Obtenha as credenciais do cluster através do seguinte comando:

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

   Estas credenciais são usadas para comunicar com o cluster do GKE criado nos passos dos pré-requisitos.

2. Configure as credenciais da conta de serviço para estabelecer ligação aos Google Cloud serviços:

   gcloud iam service-accounts create apigee-apim-gsa

3. Conceda as funções e as autorizações necessárias à conta de serviço que criou através dos seguintes comandos:
   • Função de administrador do Apigee: necessária para criar e gerir recursos do 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 da extensão de serviços: necessária para criar e gerir extensões de serviços.

     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 gerir o acesso ao Apigee através de 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 gerir o acesso entre grupos de pontos finais da 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"

Crie uma Workload Identity

A instalação do operador da APIM no passo seguinte cria uma conta de serviço do Kubernetes (KSA) necessária denominada apim-ksa no espaço de nomes apim.helm Quando é criado, o KSA contém a anotação necessária para associar a uma identidade de carga de trabalho usada pelo operador da APIM para aceder aos recursos necessários do Apigee e da rede de serviços.

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]"

Este comando associa a KSA à Google conta de serviço que criou em Obtenha e configure credenciais e atribui a função workloadIdentityUser.

A propagação das alterações da identidade da carga de trabalho no sistema pode demorar alguns minutos, potencialmente 7 minutos ou mais.

Para confirmar que 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

O resultado deve ser semelhante ao seguinte:

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

Instale definições de recursos personalizados (CRDs) e o operador da APIM

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

1. Crie um espaço de nomes para o operador APIM:

   kubectl create ns apim

2. Instale as definições de recursos personalizados (CRDs) do operador 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 que a instalação foi concluída com êxito:

   helm list -n apim

   O resultado deve ser semelhante ao seguinte:

   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 o KSA foi criado com a anotação necessária:

   kubectl describe serviceaccounts apim-ksa -n apim

   O resultado deve ser semelhante ao seguinte:

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

6. Confirme que o operador APIM está em funcionamento nos pods do cluster:

   kubectl get pods -n apim

   O resultado deve ser semelhante ao seguinte:

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

   Se STATUS não for Running ou READY não apresentar 1/1, consulte o artigo Resolva problemas do operador da API para resolver problemas de instalação.

Crie um ambiente do Apigee

Se instalou o operador APIM através de generateEnv=TRUE no passo anterior, o operador cria um novo ambiente do Apigee quando a política de extensão APIM é criada e aplicada. O nome do novo ambiente vai ter o prefixo: apim-enabled-dep-env.

Se instalou o operador APIM com generateEnv=FALSE, tem de criar um novo ambiente Apigee:

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

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

2. Crie o ambiente com um dos seguintes comandos:
   • Para organizações com subscrição 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"
               }
             ]
           }
       }'

     Onde ENV_NAME é o nome do ambiente a criar.

   • Para organizações com subscrição de 2024 e pagamento conforme o 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" : "COMPREHENSIVE",
       "properties": {
         "property": [
           {
             "name": "apigee-service-extension-enabled",
             "value": "true"
           }
         ]
       }
     }'

     Onde:

     • ENV_NAME é o nome do ambiente a criar.
     • ENV_TYPE é o tipo de ambiente a criar. Por exemplo, INTERMEDIATE ou COMPREHENSIVE.
     Nota: o ambiente criado neste passo ou criado pelo operador da APIM é um ambiente intermédio ou abrangente para suportar a utilização de proxies extensíveis. Não é possível usar esta funcionalidade com ambientes base.

   Para verificar se o ambiente foi criado com êxito:

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

3. Associe o ambiente à sua instância do 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"}'

   Onde:

   • INSTANCE_NAME é o nome da sua instância do Apigee.
   • ENV_NAME é o nome do ambiente que criou no passo anterior.

   Para verificar o estado da operação de associaçã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 associação do ambiente.

Resolver problemas

Se tiver problemas ao instalar o operador APIM, consulte o artigo Resolva problemas do operador APIM para encontrar soluções para erros comuns.

O que se segue?

• Use políticas da Apigee com o operador APIM.
• Adicione políticas do Apigee ao GKE Gateway.