About service accounts

A service account is a special type of account in GCP that enables components and applications of a system to interact with each other and with other APIs. For more information about GCP, see About GCP services.

Hybrid uses GCP 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 account could perform all of these operations, 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.

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:

Component* Role Required for basic install? Description
apigee-cassandra Storage Object Admin Allows Cassandra backups to Google Cloud Storage (GCS), as described in Backup and recovery.
apigee-logger Logs Writer Allows logging data collection, as described in Logging. Only required for non-GKE cluster installations.
apigee-mart No role Allows MART service authentication. This service account should not have a role associated with it; as a result, when you create this service account, do not assign a role to it.
apigee-metrics Monitoring Metric Writer Allows metrics data collection, as described in Metrics collection
apigee-org-admin Apigee Organization Admin Lets you call the getSyncAuthorization API and setSyncAuthorization API. You cannot create this service account with the create-service-account tool.
apigee-synchronizer Apigee Synchronizer Manager Allows the synchronizer to download proxy bundles and environment configuration data. Also enables operation of the trace feature.
apigee-udca Apigee Analytics Agent Allows the transfer of trace, analytics and deployment status data to the management plane.
* This name is used in the downloaded service account key's filename.

In addition to creating the service accounts listed in this table, you also download their private keys. You later use these keys to generate access tokens so that you can access the Apigee APIs.

Create the service accounts

There are several ways to create service accounts, including:

Each of these is described in the following sections.

Use the service account creation tool

The create-service-account tool (available after you download and expand apigeectl) creates 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 in the specified directory.

To create service accounts with the create-service-account tool:

  1. Download and expand apigeectl (if you haven't done so already), as described in download and install apigeectl.
  2. Create a directory to store your service account keys. For example:
    mkdir ./service-accounts
  3. Execute the following commands:
    ./tools/create-service-account apigee-metrics ./service-accounts
    ./tools/create-service-account apigee-synchronizer ./service-accounts
    ./tools/create-service-account apigee-udca ./service-accounts
    ./tools/create-service-account apigee-mart ./service-accounts
    ./tools/create-service-account apigee-cassandra ./service-accounts
    ./tools/create-service-account apigee-logger ./service-accounts

    These commands create most of the required accounts and stores their keys in the ./service-accounts directory. These commands do not create the apigee-org-admin service account.

    If these commands fail, make sure you referenced an existing directory in which to store the key files.

    For more information on using create-service-account, see create-service-account reference.

  4. Create the apigee-org-admin service account. To do this, use the GCP console.

Use the GCP console

You can create service accounts with the GCP console.

To create service accounts with the GCP console:

  1. Open the Google Cloud Platform (GCP) Console and log in with the user account you created in Step 1: Create a GCP account.
  2. Select the project that you created in Step 2: Create a GCP project.
  3. Select IAM & admin > Service accounts.

    The console displays the Service accounts view. This view displays a list of the project’s service accounts. (In most cases, there will be no accounts listed yet, although there might be default service accounts in the list, depending on how you created your project.)

  4. To create a new service account, click +Create Service Account at the top of the view.

    The Service account details view displays.

  5. In the Service account name field, enter the name of the service account.

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

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

    As you enter a name, GCP generates a unique service account ID for you, which is structured like an email address, as the following example shows:

    You can optionally add a description in the Service account description field. Descriptions are helpful at reminding you what a particular service account is used for.

  6. Click Create.

    GCP creates a new service account and displays the Service account permissions view, as the following example shows:

    Use this view to assign a role to your new service account.

  7. Click the Select a role drop-down list.
  8. Select the role for the service account, as described in Service accounts and roles used by hybrid components.

    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, enter “Apigee” in the filter field, as the following example shows:

    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 the IAM & admin panel in the GCP.

  9. Click Continue.

    GCP displays the Grant users access to this service account view:

  10. Under Create key (optional), click Create Key.

    GCP gives you the option to download a JSON or P12 key:

  11. Select JSON (the default) and click Create.

    GCP saves the key file in JSON format to your local machine and displays a confirmation when it is successful, as the following example shows:

    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 the service_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.)

  12. Repeat steps 4 through 11 for each service account listed in Service accounts and roles used by hybrid components (except the apigee-mart account—which has no role associated with it—so do not assign it a role).

    When you're finished, you should have the following service accounts (in addition to the defaults, if any):

    In the GCP Console, service accounts are indicated with a .

After you create a service account, if you want to add or remove a role to it, you must use the IAM & Admin view. You cannot manage roles for service accounts in the Service accounts view.

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, see Creating and managing service accounts.

Troubleshooting