Step 4: Create service accounts

Overview

This step explains how to create the Google Cloud service accounts that are required for Apigee hybrid to operate, and assign the appropriate IAM roles to them.

This procedure uses the following two environment variables defined in Step 2: Download the Apigee Helm charts. These variables are optional. If you did not define them, substitute the appropriate directory path for each variable in the code samples.

$APIGEE_HELM_CHARTS_HOME: The directory where you downloaded the Apigee Helm charts, defined in Step 2: Download the Apigee Helm charts.
$PROJECT_ID: Your Google Cloud project ID, defined in Part 1: Project and Org setup--Step 1: Enable APIs.

Production vs. non-production environments

This guide refers to Production ("Prod") and Non-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.

For production installations, we recommend creating a separate service account for each Apigee hybrid component. For example, runtime, mart, metrics, mint, udca, and so on each component has a dedicated service account.

For non-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, see Service accounts and roles used by hybrid components.

Authenticating service accounts

Apigee hybrid supports the following methods of authenticating Google service accounts:

Kubernetes secrets
Service account JSON key files ("JSON files" in the selection tabs in the following section).
Vault
Workload Identity Federation for GKE ("WIF for GKE" in the selection tabs in the following section).
Workload Identity Federation on other platforms ("WIF on other platforms" in the selection tabs in the following section).

In the following section choose the procedure for the type of authentication you plan to use.

Create the service accounts

Apigee hybrid uses the following service accounts:

Production

Service account	IAM roles	Apigee Helm chart
`apigee-cassandra`	Storage Object Admin	`apigee-datastore`
`apigee-logger`	Logs Writer	`apigee-telemetry`
`apigee-mart`	Apigee Connect Agent	`apigee-org`
`apigee-metrics`	Monitoring Metric Writer	`apigee-telemetry`
`apigee-mint-task-scheduler` (Required only if you are using Monetization for Apigee hybrid)	No role required	`apigee-org`
`apigee-runtime`	No role required	`apigee-env`
`apigee-synchronizer`	Apigee Synchronizer Manager Storage Object Admin	`apigee-env`
`apigee-udca`	Apigee Analytics Agent	`apigee-org` `apigee-env`
`apigee-watcher`	Apigee Runtime Agent	`apigee-org`

Non-prod

Service account	IAM roles	Apigee Helm chart
`apigee-non-prod`	Storage Object Admin Logs Writer Apigee Connect Agent Monitoring Metric Writer Apigee Synchronizer Manager Apigee Analytics Agent Apigee Runtime Agent	`apigee-datastore` `apigee-telemetry` `apigee-org` `apigee-env`

The `create-service-account` tool

Apigee provides a tool, create-service-account, in the apigee-operator/etc/tools directory:

$APIGEE_HELM_CHARTS_HOME/
    └── apigee-operator/
        └── etc/
            └── tools/
                └── create-service-account

This tool creates the service accounts, assigns the IAM roles to each account, and downloads the certificate files in JSON format for each account.

Verify you can execute create-service-account. If you have just downloaded the charts the create-service-account file might not be in an executable mode. In your APIGEE_HELM_CHARTS_HOME directory run the following command:

$APIGEE_HELM_CHARTS_HOME/apigee-operator/etc/tools/create-service-account --help

If your output says permission denied you need to make the file executable, for example with chmod in Linux, MacOS, or UNIX or in the Windows Explorer or with the icacls command in Windows. For example:

chmod +x $APIGEE_HELM_CHARTS_HOME/apigee-operator/etc/tools/create-service-account

Create the service accounts

Choose the procedure for the service account authentication method you plan to use in your installation. For more information, see Service account authentication methods in Apigee hybrid.

Kubernetes Secrets

To prepare the service account key files to store in Kubernetes Secrets you can use the create-service-account tool to create the service account key files with the --dir flag to create a directory for the key files.

Production

Make sure the PROJECT_ID environment variable is defined.
```
echo $PROJECT_ID
```
The create-service-account tool uses the value of thePROJECT_ID environment variable. If it is not defined, either define it with your ID of your Google Cloud Project ID or add the --project-id PROJECT_ID flag to the create-service-account command.
Create the service accounts with the following commands, where $APIGEE_HELM_CHARTS_HOME is the path where you downloaded the Apigee Helm charts. You may be prompted to create each service account. Respond with y.
```
$APIGEE_HELM_CHARTS_HOME/apigee-operator/etc/tools/create-service-account \
  --env prod \
  --dir $APIGEE_HELM_CHARTS_HOME/service-accounts
```

Verify that the service account files were created by checking the contents of the service-accounts directory. Your output should look like:

ls $APIGEE_HELM_CHARTS_HOME/service-accounts/
my-project-apigee-cassandra.json            my-project-apigee-runtime.json
my-project-apigee-logger.json               my-project-apigee-synchronizer.json
my-project-apigee-mart.json                 my-project-apigee-udca.json
my-project-apigee-metrics.json              my-project-apigee-watcher.json
my-project-apigee-mint-task-scheduler.json

Non-prod

Make sure the PROJECT_ID environment variable is defined.
```
echo $PROJECT_ID
```
The create-service-account tool uses the value of thePROJECT_ID environment variable. If it is not defined, either define it with your ID of your Google Cloud Project ID or add the --project-id PROJECT_ID flag to the create-service-account command.
Create the service accounts with the following command, where $APIGEE_HELM_CHARTS_HOME is the path where you downloaded the Apigee Helm charts. You may be prompted to create the service account. Respond with y.
```
$APIGEE_HELM_CHARTS_HOME/apigee-operator/etc/tools/create-service-account \
  --env non-prod \
  --dir $APIGEE_HELM_CHARTS_HOME/service-accounts
```
Verify that the service account file was created by checking the contents of the service-accounts directory. Your output should look like:
```
ls $APIGEE_HELM_CHARTS_HOME/service-accounts/
my-project-apigee-non-prod.json
```

JSON files

Because Helm does not support referencing files outside of the chart directory, you will create each service account certificate file in the chart directory for the corresponding hybrid component.

For the next steps choose whether you are configuring a Production or Non-production installation.

Production

Make sure the PROJECT_ID environment variable is defined.
```
echo $PROJECT_ID
```
The create-service-account tool uses the value of thePROJECT_ID environment variable. If it is not defined, either define it with your ID of your Google Cloud Project ID or add the --project-id PROJECT_ID flag to the create-service-account commands.

Create the service accounts with the following commands, where $APIGEE_HELM_CHARTS_HOME is the path where you downloaded the Apigee Helm charts. You may be prompted to create each service account. Respond with y.

$APIGEE_HELM_CHARTS_HOME/apigee-operator/etc/tools/create-service-account \
  --profile apigee-cassandra \
  --env prod \
  --dir $APIGEE_HELM_CHARTS_HOME/apigee-datastore

$APIGEE_HELM_CHARTS_HOME/apigee-operator/etc/tools/create-service-account \
  --profile apigee-logger \
  --env prod \
  --dir $APIGEE_HELM_CHARTS_HOME/apigee-telemetry

$APIGEE_HELM_CHARTS_HOME/apigee-operator/etc/tools/create-service-account \
  --profile apigee-mart \
  --env prod \
  --dir $APIGEE_HELM_CHARTS_HOME/apigee-org

$APIGEE_HELM_CHARTS_HOME/apigee-operator/etc/tools/create-service-account \
  --profile apigee-metrics \
  --env prod \
  --dir $APIGEE_HELM_CHARTS_HOME/apigee-telemetry

$APIGEE_HELM_CHARTS_HOME/apigee-operator/etc/tools/create-service-account \
  --profile apigee-runtime \
  --env prod \
  --dir $APIGEE_HELM_CHARTS_HOME/apigee-env

$APIGEE_HELM_CHARTS_HOME/apigee-operator/etc/tools/create-service-account \
  --profile apigee-synchronizer \
  --env prod \
  --dir $APIGEE_HELM_CHARTS_HOME/apigee-env

$APIGEE_HELM_CHARTS_HOME/apigee-operator/etc/tools/create-service-account \
  --profile apigee-udca \
  --env prod \
  --dir $APIGEE_HELM_CHARTS_HOME/apigee-env

$APIGEE_HELM_CHARTS_HOME/apigee-operator/etc/tools/create-service-account \
  --profile apigee-udca \
  --env prod \
  --dir $APIGEE_HELM_CHARTS_HOME/apigee-org

$APIGEE_HELM_CHARTS_HOME/apigee-operator/etc/tools/create-service-account \
  --profile apigee-watcher \
  --env prod \
  --dir $APIGEE_HELM_CHARTS_HOME/apigee-org

If you are enabling Monetization for Apigee hybrid (Apigee hybrid v1.15.1 and later):

$APIGEE_HELM_CHARTS_HOME/apigee-operator/etc/tools/create-service-account \
  --profile apigee-mint-task-scheduler \
  --env prod \
  --dir $APIGEE_HELM_CHARTS_HOME/apigee-org

Copy the apigee-udca JSON file to the apigee-env chart directory. It is needed for both org-scope and env-scope operations.
```
cp $APIGEE_HELM_CHARTS_HOME/apigee-org/$PROJECT_ID-apigee-udca.json $APIGEE_HELM_CHARTS_HOME/apigee-env/
```

Verify that the service account files were created in the correct directories by checking the contents of each chart's directory. Your output should look like:

ls ./apigee-datastore
Chart.yaml  my-project-apigee-cassandra.json  templates  values.yaml

ls ./apigee-telemetry
Chart.yaml                     my-project-apigee-metrics.json  values.yaml
my-project-apigee-logger.json  templates

ls ./apigee-org
Chart.yaml                                  my-project-apigee-udca.json
my-project-apigee-mart.json                 my-project-apigee-watcher.json
my-project-apigee-mint-task-scheduler.json  values.yaml

ls ./apigee-env
Chart.yaml                      my-project-apigee-synchronizer.json  templates
my-project-apigee-runtime.json  my-project-apigee-udca.json          values.yaml

Tip: You can also verify the location of the service account files with the following tree command:

tree -P *.json

Non-prod

Make sure the PROJECT_ID environment variable is defined.
```
echo $PROJECT_ID
```
The create-service-account tool uses the value of thePROJECT_ID environment variable. If it is not defined, either define it with your ID of your Google Cloud Project ID or add the --project-id PROJECT_ID flag to the create-service-account commands.
Create the service account with the following command, where $APIGEE_HELM_CHARTS_HOME is the path where you downloaded the Apigee Helm charts. You may be prompted to create each service account. Respond with y.
```
$APIGEE_HELM_CHARTS_HOME/apigee-operator/etc/tools/create-service-account \
  --env non-prod \
  --dir $APIGEE_HELM_CHARTS_HOME/apigee-datastore
```

Verify the name of the service account file created in the apigee-datastore directory:

ls $APIGEE_HELM_CHARTS_HOME/apigee-datastore

Chart.yaml  PROJECT_ID-apigee-non-prod.json  templates  values.yaml

Copy the service account file to the other chart directories that will need to refer to it:

cp $APIGEE_HELM_CHARTS_HOME/apigee-datastore/SA_FILE_NAME $APIGEE_HELM_CHARTS_HOME/apigee-telemetry/

cp $APIGEE_HELM_CHARTS_HOME/apigee-datastore/SA_FILE_NAME $APIGEE_HELM_CHARTS_HOME/apigee-org/

cp $APIGEE_HELM_CHARTS_HOME/apigee-datastore/SA_FILE_NAME $APIGEE_HELM_CHARTS_HOME/apigee-env/

Vault

To prepare the service account key files to store in Vault you can use the create-service-account tool to create the service account key files with the --dir flag to create a directory for the key files.

Production

Make sure the PROJECT_ID environment variable is defined.
```
echo $PROJECT_ID
```
The create-service-account tool uses the value of thePROJECT_ID environment variable. If it is not defined, either define it with your ID of your Google Cloud Project ID or add the --project-id PROJECT_ID flag to the create-service-account command.
Create the service accounts with the following commands, where $APIGEE_HELM_CHARTS_HOME is the path where you downloaded the Apigee Helm charts. You may be prompted to create each service account. Respond with y.
```
$APIGEE_HELM_CHARTS_HOME/apigee-operator/etc/tools/create-service-account \
  --env prod \
  --dir $APIGEE_HELM_CHARTS_HOME/service-accounts
```

Verify that the service account files were created by checking the contents of the service-accounts directory. Your output should look like:

ls $APIGEE_HELM_CHARTS_HOME/service-accounts/
my-project-apigee-cassandra.json            my-project-apigee-runtime.json
my-project-apigee-logger.json               my-project-apigee-synchronizer.json
my-project-apigee-mart.json                 my-project-apigee-udca.json
my-project-apigee-metrics.json              my-project-apigee-watcher.json
my-project-apigee-mint-task-scheduler.json

Non-prod

Make sure the PROJECT_ID environment variable is defined.
```
echo $PROJECT_ID
```
The create-service-account tool uses the value of thePROJECT_ID environment variable. If it is not defined, either define it with your ID of your Google Cloud Project ID or add the --project-id PROJECT_ID flag to the create-service-account command.
Create the service accounts with the following command, where $APIGEE_HELM_CHARTS_HOME is the path where you downloaded the Apigee Helm charts. You may be prompted to create the service account. Respond with y.
```
$APIGEE_HELM_CHARTS_HOME/apigee-operator/etc/tools/create-service-account \
  --env non-prod \
  --dir $APIGEE_HELM_CHARTS_HOME/service-accounts
```
Verify that the service account file was created by checking the contents of the service-accounts directory. Your output should look like:
```
ls $APIGEE_HELM_CHARTS_HOME/service-accounts/
my-project-apigee-non-prod.json
```

WIF for GKE

Create the service accounts for your installation with the following commands:

Production

Make sure the PROJECT_ID environment variable is defined.
```
echo $PROJECT_ID
```
The create-service-account tool uses the value of thePROJECT_ID environment variable. If it is not defined, either define it with your ID of your Google Cloud Project ID or add the --project-id PROJECT_ID flag to the create-service-account command.
Create the service accounts with the following commands, where $APIGEE_HELM_CHARTS_HOME is the path where you downloaded the Apigee Helm charts. You may be prompted to create each service account. Respond with y.
```
$APIGEE_HELM_CHARTS_HOME/apigee-operator/etc/tools/create-service-account \
  --env prod \
  --dir $APIGEE_HELM_CHARTS_HOME/service-accounts
```

Verify the creation of the Google service accounts" with the following command:

gcloud iam service-accounts list --project $PROJECT_ID

The output should look similar to the following:

DISPLAY NAME                EMAIL                                                          DISABLED
apigee-cassandra            apigee-cassandra@my-project.iam.gserviceaccount.com            False
apigee-mart                 apigee-mart@my-project.iam.gserviceaccount.com                 False
apigee-metrics              apigee-metrics@my-project.iam.gserviceaccount.com              False
apigee-mint-task-scheduler  apigee-mint-task-scheduler@my-project.iam.gserviceaccount.com  False
apigee-runtime              apigee-runtime@my-project.iam.gserviceaccount.com              False
apigee-synchronizer         apigee-synchronizer@my-project.iam.gserviceaccount.com         False
apigee-udca                 apigee-udca@my-project.iam.gserviceaccount.com                 False
apigee-watcher              apigee-watcher@my-project.iam.gserviceaccount.com              False

Non-prod

Make sure the PROJECT_ID environment variable is defined.
```
echo $PROJECT_ID
```
The create-service-account tool uses the value of thePROJECT_ID environment variable. If it is not defined, either define it with your ID of your Google Cloud Project ID or add the --project-id PROJECT_ID flag to the create-service-account command.
Create the service accounts with the following command, where $APIGEE_HELM_CHARTS_HOME is the path where you downloaded the Apigee Helm charts. You may be prompted to create the service account. Respond with y.
```
$APIGEE_HELM_CHARTS_HOME/apigee-operator/etc/tools/create-service-account \
  --env non-prod \
  --dir $APIGEE_HELM_CHARTS_HOME/service-accounts
```

Verify the creation of the Google service accounts" with the following command:

gcloud iam service-accounts list --project $PROJECT_ID

The output should look similar to the following:

DISPLAY NAME         EMAIL                                                   DISABLED
apigee-non-prod      apigee-non-prod@my-project.iam.gserviceaccount.com      False

Optional: You will not need the service account key files for Workload Identity Federation for GKE. You may delete the service-accounts directory after you are done.

WIF on other platforms

Create the service accounts for your installation with the following commands:

Production

Make sure the PROJECT_ID environment variable is defined.
```
echo $PROJECT_ID
```
The create-service-account tool uses the value of thePROJECT_ID environment variable. If it is not defined, either define it with your ID of your Google Cloud Project ID or add the --project-id PROJECT_ID flag to the create-service-account command.
Create the service accounts with the following commands, where $APIGEE_HELM_CHARTS_HOME is the path where you downloaded the Apigee Helm charts. You may be prompted to create each service account. Respond with y.
```
$APIGEE_HELM_CHARTS_HOME/apigee-operator/etc/tools/create-service-account \
  --env prod \
  --dir $APIGEE_HELM_CHARTS_HOME/service-accounts
```

Verify the creation of the Google service accounts" with the following command:

gcloud iam service-accounts list --project $PROJECT_ID

The output should look similar to the following:

DISPLAY NAME                EMAIL                                                          DISABLED
apigee-cassandra            apigee-cassandra@my-project.iam.gserviceaccount.com            False
apigee-mart                 apigee-mart@my-project.iam.gserviceaccount.com                 False
apigee-metrics              apigee-metrics@my-project.iam.gserviceaccount.com              False
apigee-mint-task-scheduler  apigee-mint-task-scheduler@my-project.iam.gserviceaccount.com  False
apigee-runtime              apigee-runtime@my-project.iam.gserviceaccount.com              False
apigee-synchronizer         apigee-synchronizer@my-project.iam.gserviceaccount.com         False
apigee-udca                 apigee-udca@my-project.iam.gserviceaccount.com                 False
apigee-watcher              apigee-watcher@my-project.iam.gserviceaccount.com              False

Non-prod

Make sure the PROJECT_ID environment variable is defined.
```
echo $PROJECT_ID
```
The create-service-account tool uses the value of thePROJECT_ID environment variable. If it is not defined, either define it with your ID of your Google Cloud Project ID or add the --project-id PROJECT_ID flag to the create-service-account command.
Create the service accounts with the following command, where $APIGEE_HELM_CHARTS_HOME is the path where you downloaded the Apigee Helm charts. You may be prompted to create the service account. Respond with y.
```
$APIGEE_HELM_CHARTS_HOME/apigee-operator/etc/tools/create-service-account \
  --env non-prod \
  --dir $APIGEE_HELM_CHARTS_HOME/service-accounts
```

Verify the creation of the Google service accounts" with the following command:

gcloud iam service-accounts list --project $PROJECT_ID

The output should look similar to the following:

DISPLAY NAME         EMAIL                                                   DISABLED
apigee-non-prod      apigee-non-prod@my-project.iam.gserviceaccount.com      False

Optional: You will not need the service account key files for Workload Identity Federation for GKE. You may delete the service-accounts directory after you are done.

For more information about service accounts and the create-service-account tool see:

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.

Next step

1 2 3 4 (NEXT) Step 5: Set up service account authentication 6 7 8 9 10 11

Step 4: Create service accounts Stay organized with collections Save and categorize content based on your preferences.

Overview

Production vs. non-production environments

Authenticating service accounts

Create the service accounts

Production

Non-prod

The create-service-account tool

Create the service accounts

Kubernetes Secrets

Production

Non-prod

JSON files

Production

Non-prod

Vault

Production

Non-prod

WIF for GKE

Production

Non-prod

WIF on other platforms

Production

Non-prod

Next step

Step 4: Create service accounts

The `create-service-account` tool