About service accounts

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

Aservice account is a special type of account in Google Cloud that enables components and applications of a system to interact with each other and with other APIs. For more information about Google Cloud, seeAbout Google Cloud services.

SERVICE ACCOUNT FACTOID
Google Cloud projects have a limit of 100 service accounts—including the default service accounts (if any).

Apigee hybrid uses Google Cloud service accounts to perform a variety of tasks, including:

  • Send log and metrics data
  • Pull trace requests
  • Connect to API gateway for administrative API requests
  • Execute back ups
  • Download proxy bundles

While one service accountcould perform all of these operations, for production environments Apigee recommends that you create multiple service accounts, each assigned to a specific task and each with its own set of permissions. This enhances security by compartmentalizing access and limiting each service account's scope and access privileges. As with user accounts, these permissions are applied by assigning one or more roles to the service account.

Service accounts and roles used by hybrid components

To operate properly, Apigee hybrid requires you to create several service accounts. Each service account requires a specific role or roles that enable it to perform its function.

The following table describes the service accounts for the hybrid components. The names given foreach service account are the default names. You can use any names you want, but the names should beeasy to identify with each account's purpose.

Component*RoleRequired for basic install?Description
apigee-cassandraStorage Object Admin
roles/storage.objectAdmin		Allows Cassandra backups to Cloud Storage, as described inBackup and recovery.
apigee-distributed-traceCloud Trace Agent
roles/cloudtrace.agent		Allows the hybrid runtime plane to participate in distributed request tracing in a format compatible with systems likeGoogle Cloud Trace andJaeger.
apigee-loggerLogs Writer
roles/logging.logWriter		Allows logging data collection, as described inLogging. Only required for non-GKE cluster installations.
apigee-martApigee Connect Agent
roles/apigeeconnect.Agent		Allows MART service authentication. The Apigee Connect Agent role allows it to communicate securely with the Apigee Connect process, as described inUsing Apigee Connect.
apigee-metricsMonitoring Metric Writer
roles/monitoring.metricWriter		Allows metrics data collection, as described inMetrics collection overview.
apigee-synchronizerApigee Synchronizer Manager
roles/apigee.synchronizerManager		Allows the synchronizer to download proxy bundles and environment configuration data. Also enables operation of the trace feature.
apigee-udcaApigee Analytics Agent
roles/apigee.analyticsAgent		Allows the transfer of trace, analytics and deployment status data to the management plane.
apigee-watcherApigee Runtime Agent
roles/apigee.runtimeAgent		Apigee Watcher pulls virtual hosts related changes for an org from synchronizer and makes necessary changes to configure istio ingress.
* This name is used in the downloaded service account key's filename.

As an alternative, for nonproduction, test, and demo environments, you can use a single service account with all the roles assigned to it. This is not recommended for production environments.

Component*RoleRequired for basic install?Description
apigee-non-prodApigee Analytics Agent, Apigee Connect Agent, Apigee Organization Admin, Apigee Runtime Agent, Apigee Synchronizer Manager, Cloud Trace Agent, Logs Writer, Monitoring Metric Writer, Storage Object AdminOr all required SAs aboveSingle service account for demo or test environments. SeeInstall, Part 2, Step 5: Create service accounts.

In addition to creating the service accounts listed in this table, you will use each accounts private keys to generate access tokens so that you can access the Apigee APIs. Thecreate-service-account tool automaticallyl downloads the key files into a directory on your local machine when it creates or updates the service accounts.

Create the service accounts

Deleting and recreating service accounts:Note that reusing the name of a deleted service account might result in unexpected behavior. If you create a service account and delete it, always recreate it with a unique name. For details, see Deleting and recreating service accounts.

There are several ways to create service accounts, including:

Each of these is described in the following sections.

Use thecreate-service-account tool

Thecreate-service-account tool is available after youdownload and expandapigeectl in thetools/ directory. It hybrid component-specific service accounts and assigns the required roles for you. The tool also automatically downloads the service account keys and stores them on your local machine.

For example, the following command will create all the separate individual service accounts for a production environment, assign the appropriate IAM roles to each service account, and download each accounts private key file to the./service-accounts directory:

./tools/create-service-account --env prod

The following command creates a single service account namedapigee-non-prod with all IAM roles for all hybrid components, suitable for demo and test environments, but not for production environments:

./tools/create-service-account --env non-prod

For more information on usingcreate-service-account, seecreate-service-account reference.

Use the Google Cloud console

You can create service accounts with the Google Cloud console.

Complete the following steps for each service account listed inService accounts and roles used by hybrid components.

Note: To create service accounts in the Google Cloud console,you must have the Service Account Admin role (roles/iam.serviceAccountAdmin) oranother role with theiam.serviceAccounts.create permission.

To create a service account with the Google Cloud console and generate a key for the service account, do the following:

  1. Create a service account:

    1. In the Cloud console, go to theService Accounts page.

      Go to Service Accounts

    2. Select your project.
    3. ClickCreate Service Account.

    4. In theService account name field, enter a name. The Cloud console fills in theService account ID field based on this name.

      Apigee recommends that you use a name that reflects the service account's role; you can set the name of the service account to be the same name as the component that uses it. For example, set the name of the Logs Writer service accountapigee-logger.

      For more information about the service accounts names and roles, seeService accounts and roles used by hybrid components.

    5. Optional: In theService account description field, enter a description for the service account. Descriptions are helpful at reminding you what a particular service account is used for.
    6. ClickCreate and continue.

    7. Click theSelect a role field and select a role, as described inService accounts and roles used by hybrid components. If the Apigee roles do not appear in the drop down list, refresh the page.

      For example, for the logging component, select the Logs Writer role.

      If necessary, enter text to filter the list of roles by name. For example, to list only the Apigee roles, enterApigee in the filter field.

      You can add more than one role to a service account, but Apigee recommends that you only use one role for each of the recommended service accounts. To change the roles of a service account after you have created it, use theIAM page in the Cloud console.

      Note: If you do not see the roles listed inRecommended service accounts, check with your Apigee account representative to be sure that your account was properly configured and that your organization was provisioned.

    8. ClickDone to finish creating the service account.

      Do not close your browser window. You will use it in the next step.

  2. Download a JSON key for the service account you just created:

    1. In the Cloud console, click the email address for the service account that you created.
    2. ClickKeys.
    3. ClickAdd key, then clickCreate new key.

    4. ClickCreate. A JSON key file is downloaded to your computer.

      Make sure to store the key file securely, because it can be used to authenticate as your service account. You can move and rename this file however you would like.

      You will later use some of the service account keys to configure hybrid runtime services. For example, when you configure the hybrid runtime, you will specify the location of the service account keys using theSERVICE_NAME.serviceAccountPath properties.

      These keys are used by the service accounts to get access tokens, which the service account then uses to make requests against the Apigee APIs on your behalf. (But that's not for a while yet; for now, just remember where you saved it.)

    5. ClickClose.

After you create a service account, if you want to add or remove a role to it, you must usetheIAM page in the Cloud console. You cannot manage roles for serviceaccounts in theService accounts view.

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.

Use the gcloud service account creation APIs

You can create and manage service accounts with the Cloud Identity and Access Management API.

For more information, seeCreatingand managing service accounts.

Troubleshooting

Deleting and recreating service accounts:Note that reusing the name of a deleted service account, might result in unexpected behavior. If you create a service account and delete it, always recreate it with a unique name. For details, see Deleting and recreating service accounts.

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.