Installa l'operatore APIM di Apigee per Kubernetes

Questa pagina si applica ad Apigee, ma non ad Apigee hybrid.

Visualizza la documentazione di 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.

Questa pagina descrive i passaggi necessari per installare e configurare l'operatore APIM di Apigee per Kubernetes (anteprima). Per scoprire di più sui vantaggi dell'utilizzo di APIM Operator, consulta la Panoramica di Apigee APIM Operator per Kubernetes.

Prima di iniziare

Prima di iniziare a installare APIM Operator, assicurati di disporre dei ruoli e delle autorizzazioni necessari per completare i passaggi e di aver completato le attività preliminari descritte in APIM Operator: prima di iniziare.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per installare APIM Operator, chiedi all'amministratore di concederti i seguenti ruoli IAM nell'organizzazione:

• Crea e gestisci il cluster GKE: Amministratore contenitori (roles/container.admin)
• Crea e gestisci gli account di servizio: Amministratore account di servizio (roles/iam.serviceAccountAdmin)
• Crea e gestisci le estensioni di servizio: Service Extensions Admin (roles/networkservices.serviceExtensionsAdmin)
• Crea e gestisci i gruppi di endpoint di rete (NEG): Amministratore delle istanze Compute (roles/compute.instanceAdmin)
• Crea e gestisci i servizi di backend: Amministratore bilanciatore del carico Compute (roles/compute.loadBalancerAdmin)
• Crea e gestisci le risorse Apigee: Apigee Admin (roles/apigee.admin)

Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Installa e configura l'operatore APIM

Le sezioni seguenti descrivono i passaggi necessari per installare e configurare l'operatore APIM:

1. Imposta le variabili di ambiente.
2. Abilita le API richieste.
3. Recupero e configurazione delle credenziali.
4. Installa l'operatore APIM.
5. Crea un'identità del workload.
6. Crea un ambiente Apigee.
7. Verifica la configurazione di GKE Gateway.

Imposta le variabili di ambiente

Nel Google Cloud progetto che contiene l'istanza Apigee, utilizza il seguente comando per impostare le variabili di ambiente:

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

Dove:

• PROJECT_ID è l'ID del progetto con l'istanza Apigee.
• CLUSTER_NAME è il nome del cluster GKE.
• REGION è la regione del cluster GKE.
• APIGEE_ORG è impostato sullo stesso valore di PROJECT_ID.

Per verificare che le variabili di ambiente siano impostate correttamente, esegui il seguente comando:

echo $PROJECT_ID $CLUSTER_NAME $REGION $APIGEE_ORG

Abilita le API richieste

APIM Operator richiede l'accesso alle seguenti API:

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

Usa il seguente comando per verificare che le API richieste siano abilitate:

gcloud services list --project=${PROJECT_ID}

Se non vedi le API richieste nell'output del comando, abilitale:

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}

Recupera e configura le credenziali

Recupera le credenziali del cluster e crea un account di servizio per connetterti ai servizi Google Cloud :

1. Recupera le credenziali del cluster utilizzando il seguente comando:

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

   Queste credenziali vengono utilizzate per comunicare con il cluster GKE creato nei passaggi precedenti.

2. Configura le credenziali dell'account di servizio per connetterti ai Google Cloud servizi:

   gcloud iam service-accounts create apigee-apim-gsa

3. Concedi i ruoli e le autorizzazioni richiesti all'account di servizio che hai creato utilizzando i seguenti comandi:
   • Ruolo Amministratore Apigee: obbligatorio per creare e gestire le risorse Apigee.

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

   • Ruolo Amministratore delle estensioni di servizio: necessario per creare e gestire le estensioni di servizio.

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

   • Ruolo di amministratore di rete: necessario per gestire l'accesso ad Apigee utilizzando le estensioni di servizio.

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

   • Ruolo Amministratore del bilanciatore del carico: obbligatorio per gestire l'accesso tra i gruppi di endpoint di rete (NEG) e i servizi di backend.

     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"

Creare un'identità del workload

L'installazione helm dell'operatore APIM nel passaggio successivo crea un account di servizio Kubernetes (KSA) obbligatorio denominato apim-ksa nello spazio dei nomi apim. Una volta creato, il token KSA contiene l'annotazione necessaria per essere associato a un'identità del carico di lavoro utilizzata dall'operatore APIM per accedere alle risorse Apigee e Service Networking richieste.

Per creare l'identità del carico di lavoro, utilizza il seguente 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]"

Questo comando lega l'account di servizio KSA all' Google account di servizio che hai creato in Recupero e configurazione delle credenziali e assegna il ruolo workloadIdentityUser.

Potrebbero essere necessari alcuni minuti, potenzialmente 7 minuti o più, prima che le modifiche all'identità del carico di lavoro vengano propagate nel sistema.

Per verificare che l'identità del carico di lavoro sia stata creata, utilizza i seguenti comandi:

gcloud config set project $PROJECT_ID

kubectl run --rm -it --image google/cloud-sdk:slim \
  --namespace apim workload-identity-test\
  -- gcloud auth list

L'output dovrebbe essere simile al seguente:

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

Installa le definizioni di risorse personalizzate (CRD) e l'operatore APIM

Installa le definizioni di risorse personalizzate (CRD) di Kubernetes e l'operatore APIM:

1. Crea uno spazio dei nomi per l'operatore APIM:

   kubectl create ns apim

2. Installa le definizioni di risorse personalizzate (CRD) dell'operatore 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. Installa l'operatore 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. Verifica che l'installazione sia stata completata correttamente:

   helm list -n apim

   L'output dovrebbe essere simile al seguente:

   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. Verifica che il KSA sia stato creato con l'annotazione richiesta:

   kubectl describe serviceaccounts apim-ksa -n apim

   L'output dovrebbe essere simile al seguente:

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

6. Verifica che l'operatore APIM sia in esecuzione nei pod del cluster:

   kubectl get pods -n apim

   L'output dovrebbe essere simile al seguente:

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

   Se STATUS non è Running o READY non mostra 1/1, consulta Risolvere i problemi relativi all'operatore APIM per risolvere i problemi di installazione.

Crea un ambiente Apigee

Se hai installato l'operatore APIM utilizzando generateEnv=TRUE nel passaggio precedente, l'operatore crea un nuovo ambiente Apigee quando il regolamento dell'estensione APIM viene creato e applicato. Il nome del nuovo ambiente avrà il prefisso apim-enabled-dep-env.

Se hai installato l'operatore APIM con generateEnv=FALSE, devi creare un nuovo ambiente Apigee:

1. Imposta TOKEN necessario per il comando curl:

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

2. Crea l'ambiente utilizzando uno dei seguenti comandi:
   • Per le organizzazioni con abbonamento 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",
           "displayName": ENV_NAME,
           "state": "ACTIVE",
           "deploymentType": "PROXY",
           "apiProxyType": "PROGRAMMABLE",
           "properties": {
             "property": [
               {
                 "name": "apigee-service-extension-enabled", 
                 "value": "true"  
               }
             ]
           }
       }'

     dove ENV_NAME è il nome dell'ambiente da creare.

   • Per le organizzazioni con abbonamento 2024 e con pagamento a consumo:

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

     Dove:

     • ENV_NAME è il nome dell'ambiente da creare.
     • ENV_TYPE è il tipo di ambiente da creare. Ad esempio, INTERMEDIATE o COMPREHENSIVE.
     Nota: l'ambiente creato in questo passaggio o creato dall'operatore APIM è un ambiente Intermedio o Completo per supportare l'utilizzo dei proxy estensibili. Questa funzionalità non può essere utilizzata con gli ambienti Base.
3. Collega l'ambiente all'istanza 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"}'
   }'

   Dove:

   • INSTANCE_NAME è il nome della tua istanza Apigee.
   • ENV_NAME è il nome dell'ambiente creato nel passaggio precedente.

Risoluzione dei problemi

Se si verificano problemi durante l'installazione di APIM Operator, consulta la sezione Risolvere i problemi di APIM Operator per trovare le soluzioni agli errori più comuni.

Passaggi successivi

• Utilizza i criteri Apigee con l'operatore APIM.
• Aggiungi i criteri Apigee al gateway GKE.