Step 4: Create service accounts

You are currently viewing version 1.11 of the Apigee hybrid documentation.This version is end of life. You should upgrade to a newer version. For more information, seeSupported versions.

This step explains how to create the Google Cloud service accounts that are required for Apigee hybrid to operate.

Overview

Apigee hybrid uses Google Cloud service accounts to allow hybrid components to communicate by making authorized API calls.

Production vs. non-production environments

This guide refers toProduction ("Prod") andNon-production ("Non-prod") installations. A production installation is tuned for greater usage capacity, storage, and scalability. A non-production installation uses fewer resources and is mainly for learning and demonstration purposes.

When you create and configure service accounts for Apigee hybrid, it is important to be aware of the type of installation you are targeting.

Forproduction installations, we recommend creating a separate service account for each Apigee hybrid component. For example, runtime, mart, metrics, udca, and so on each get their own service account.

Fornon-prod installations, you can create a single service account that applies to all the components.

To learn more about the service accounts used by Apigee and the roles they are assigned, seeService accounts and roles used by hybrid components.

Workload Identity on GKE

For Apigee hybrid installations on GKE, Google Cloud offers an option calledworkload identity to authenticate hybrid runtime components. This option does not use downloaded certificate files to authenticate the service accounts, Instead, it associates the Google Cloud service accounts that you create in this step with Kubernetes service accounts in the Kubernetes cluster.

Workload Identity is only available on GKE installations.

Create the service accounts

create-service-account

Use thecreate-service-account tool in the following circumstances:

  • You are installing on a platform other than GKE
  • You are installing on GKE but do not plan to use workload identity.

Otherwise, skip toCreate service accounts in the Google Cloud console or withgcloud.

  1. Make sure yourHYBRID_FILES andPROJECT_ID environment variables are set.

    PROJECT_ID must be set to your Google cloud project ID, because thecreate-service-account tool reads thePROJECT_ID environment variable to create the service accounts in the correct project.

    echo $HYBRID_FILESecho $PROJECT_ID
  2. Create the service account with the following command:

    Non-prod

    This command creates a single service account namedapigee-non-prod for use in a non-production installation and downloads the key file for the service account in the$HYBRID_FILES/service-accounts directory.

    $HYBRID_FILES/tools/create-service-account --env non-prod --dir $HYBRID_FILES/service-accounts

    Production

    This command creates all the individual service accounts for aproduction installation and downloads the key files for the service accounts in the$HYBRID_FILES/service-accounts directory.

    $HYBRID_FILES/tools/create-service-account --env prod --dir $HYBRID_FILES/service-accounts

    If you see the following prompt, entery:

    [INFO]:gcloudconfiguredprojectIDisproject_id.Enter:ytoproceedwithcreatingserviceaccountinproject:project_idEnter:ntoabort.

    If you are installing Apigee hybrid on a platform other than GKE, or if you are installing on GKE but do not want to use workload identity, Use the Apigee provided tool, create-service-account, to create the service accounts, assign the roles to the service accounts, and create and download the key files for the service account in a single command.

    If this is the first time you are creating a particular service account, then the tool creates it without further prompts.

    If, however, you see the following message and prompt, entery to generate new keys:

    [INFO]:Serviceaccountapigee-non-prod@project_id.iam.gserviceaccount.comalreadyexists....[INFO]:Theserviceaccountmighthavekeysassociatedwithit.Itisrecommendedtouseexistingkeys.Press:ytogeneratenewkeys.(thisdoesnotdeactivateexistingkeys)Press:ntoskipgeneratingnewkeys.
    Note: The Cloud Pub/Sub API must be enabled in the Google Cloud project that owns the service account for Synchronizer. To see if you enabled this API, seeEnable APIs.
  3. Verify that the service account key was created using the following command. You are responsible for storing these private keys securely. The key filenames are prefixed with the name of your Google Cloud project.
    ls $HYBRID_FILES/service-accounts

    The result should look something like the following:

    project_id-apigee-non-prod.json
    4. Tip: Apigee hybrid includes a validator that checks your service accounts' key files and permissions whenapigeectl applies the Apigee hybrid runtime components to your cluster. This validation is enabled by default. For more information, seeService account validation.

If you plan to useworkload identity on GKE to authenticate hybrid runtime components, you do not need to create and download certificate files for the service accounts. Therefore, do not use thecreate-service-account tool. Instead, create the service accounts in the Google Cloud console or with the IAM API ingcloud.

Follow the instructions inCreate service accounts using to create the following service accounts and assign the following roles to them:

Console

Non-prod

For non-production installations:

Service account nameIAM roles
apigee-non-prod
  • Apigee Analytics Agent
  • Apigee Connect Agent
  • Apigee Runtime Agent
  • Apigee Synchronizer Manager
  • Logs Writer
  • Monitoring Metric Writer
  • Storage Object Admin

Production

For production installations:

Production installations
Service account nameIAM roles
apigee-cassandraStorage Object Admin
apigee-loggerLogs Writer
apigee-martApigee Connect Agent
apigee-metricsMonitoring Metric Writer
apigee-runtimeNo role required
apigee-synchronizerApigee Synchronizer Manager
apigee-udcaApigee Analytics Agent
apigee-watcherApigee Runtime Agent

Use the following commands to create the service accounts and assign the IAM roles.

gcloud

Non-prod

For non-production installations:

  1. Create theapigee-non-prod service account:
    gcloud iam service-accounts create apigee-non-prod \  --display-name="apigee-non-prod" \  --project=$PROJECT_ID
  2. Assign the IAM roles to the service account:
    gcloud projects add-iam-policy-binding $PROJECT_ID \  --member="serviceAccount:apigee-non-prod@$PROJECT_ID.iam.gserviceaccount.com" \  --role="roles/storage.objectAdmin"
    gcloud projects add-iam-policy-binding $PROJECT_ID \  --member="serviceAccount:apigee-non-prod@$PROJECT_ID.iam.gserviceaccount.com" \  --role="roles/logging.logWriter"
    gcloud projects add-iam-policy-binding $PROJECT_ID \  --member="serviceAccount:apigee-non-prod@$PROJECT_ID.iam.gserviceaccount.com" \  --role="roles/apigeeconnect.Agent"
    gcloud projects add-iam-policy-binding $PROJECT_ID \  --member="serviceAccount:apigee-non-prod@$PROJECT_ID.iam.gserviceaccount.com" \  --role="roles/monitoring.metricWriter"
    gcloud projects add-iam-policy-binding $PROJECT_ID \  --member="serviceAccount:apigee-non-prod@$PROJECT_ID.iam.gserviceaccount.com" \  --role="roles/apigee.synchronizerManager"
    gcloud projects add-iam-policy-binding $PROJECT_ID \  --member="serviceAccount:apigee-non-prod@$PROJECT_ID.iam.gserviceaccount.com" \  --role="roles/apigee.analyticsAgent"
    gcloud projects add-iam-policy-binding $PROJECT_ID \  --member="serviceAccount:apigee-non-prod@$PROJECT_ID.iam.gserviceaccount.com" \  --role="roles/apigee.runtimeAgent"
  3. Verify the role bindings:
    gcloud projects get-iam-policy ${PROJECT_ID} \  --flatten="bindings[].members" \  --format='table(bindings.role)' \  --filter="bindings.members:apigee-non-prod@$PROJECT_ID.iam.gserviceaccount.com"

Production

For production installations:

Use the following commands to create each service account and assign the corresponding IAM role.

  1. apigee-cassandra service account:
    gcloud iam service-accounts create apigee-cassandra \  --display-name="apigee-cassandra" \  --project=$PROJECT_ID
    gcloud projects add-iam-policy-binding $PROJECT_ID \  --member="serviceAccount:apigee-cassandra@$PROJECT_ID.iam.gserviceaccount.com" \  --role="roles/storage.objectAdmin"
  2. apigee-logger service account:
    gcloud iam service-accounts create apigee-logger \  --display-name="apigee-logger" \  --project=$PROJECT_ID
    gcloud projects add-iam-policy-binding $PROJECT_ID \  --member="serviceAccount:apigee-logger@$PROJECT_ID.iam.gserviceaccount.com" \  --role="roles/logging.logWriter"
  3. apigee-mart service account:
    gcloud iam service-accounts create apigee-mart \  --display-name="apigee-mart" \  --project=$PROJECT_ID
    gcloud projects add-iam-policy-binding $PROJECT_ID \  --member="serviceAccount:apigee-mart@$PROJECT_ID.iam.gserviceaccount.com" \  --role="roles/apigeeconnect.Agent"
  4. apigee-metrics service account:
    gcloud iam service-accounts create apigee-metrics \  --display-name="apigee-metrics" \  --project=$PROJECT_ID
    gcloud projects add-iam-policy-binding $PROJECT_ID \  --member="serviceAccount:apigee-metrics@$PROJECT_ID.iam.gserviceaccount.com" \  --role="roles/monitoring.metricWriter"
  5. apigee-runtime service account:
    gcloud iam service-accounts create apigee-runtime \  --display-name="apigee-runtime" \  --project=$PROJECT_ID
  6. apigee-synchronizer service account:
    gcloud iam service-accounts create apigee-synchronizer \  --display-name="apigee-synchronizer" \  --project=$PROJECT_ID
    gcloud projects add-iam-policy-binding $PROJECT_ID \  --member="serviceAccount:apigee-synchronizer@$PROJECT_ID.iam.gserviceaccount.com" \  --role="roles/apigee.synchronizerManager"
  7. apigee-udca service account:
    gcloud iam service-accounts create apigee-udca \  --display-name="apigee-udca" \  --project=$PROJECT_ID
    gcloud projects add-iam-policy-binding $PROJECT_ID \  --member="serviceAccount:apigee-udca@$PROJECT_ID.iam.gserviceaccount.com" \  --role="roles/apigee.analyticsAgent"
  8. apigee-watcher service account:
    gcloud iam service-accounts create apigee-watcher \  --display-name="apigee-watcher" \  --project=$PROJECT_ID
    gcloud projects add-iam-policy-binding $PROJECT_ID \  --member="serviceAccount:apigee-watcher@$PROJECT_ID.iam.gserviceaccount.com" \  --role="roles/apigee.runtimeAgent"

To learn more about creating service accounts withgcloud, seeCreate service accounts.

You now have created service accounts and assigned the roles needed by the Apigee hybrid components. Next, create the TLS certificates required by the hybrid ingress gateway.

1234(NEXT) Step 5: Create TLS certificates678910

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-02-19 UTC.