create-service-account

create-service-account overview

create-service-account is a command-line tool provided with Apigee hybrid that creates Google Cloud service accounts with roles that allow individual Apigee hybrid components to make authorized API calls and downloads the associated service account key files. You can use the service account key files generated by this command in your configuration overrides file.

create-service-account creates one or more service accounts in your current Google Cloud project or the project you specify, assigns the correct IAM role to the service account, and downloads the certificate file for the service account into a directory on your local machine.

To learn more about service accounts and read the full list of service accounts recommended for production environments, see the following:

You can also create service accounts in the Google Cloud console. See also Creating and managing service accounts.

Prerequisites

Role

The create-service-account tool requires that the gcloud CLI be installed. Users invoking the utility should have the role Service Account Admin.

Project

Service accounts are bound to a specific Google Cloud project. create-service-account creates service accounts in your current project or in the project you specify, and binds the IAM roles to the service accounts within that project. create-service-account also uses the Project ID as part of the service account key file name and email. For example, if your project is named my-hybrid-project, the apigee-logger service account key file will be named my-hybrid-project-apigee-logger.json and the service account's email address will be apigee-logger@my-hybrid-project.iam.gserviceaccount.com.

You can specify a project by defining a PROJECT_ID environment variable or with the --project-id flag. If both are set, the --project-id flag takes precedence over the PROJECT_ID environment variable and create-service-account logs a [WARNING]. In all cases the tool logs which source the Project ID was read from, and prints the resolved deployment type, project, and output directory before it creates any service accounts.

If you do not specify a Cloud project ID, create-service-account uses the project in your current gcloud project configuration.

You can check current set gcloud project configuration with the following command: 

gcloud config list project

If you need to change the current project ID, use the following command: 

gcloud config set project PROJECT_ID

Where PROJECT_ID is the ID of your current Cloud project. Instructions for creating a Cloud Project are covered in Step 2: Create a Google Cloud project.

File location

You can find the create-service-account tool in the following directory:

$APIGEE_HELM_CHARTS_HOME/apigee-operator/etc/tools/

Verifying the create-service-account tool is executable

Verify you can execute create-service-account. If you have just downloaded the Apigee Helm charts, the command line tools might not be in an executable mode. Navigate to the directory where create-service-account is installed and verify that it is executable by running it with --help: 

./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 ./create-service-account

Using create-service-account

The following examples show using create-service-account for common Apigee hybrid setup tasks.

Create service accounts for a production environment

In a production hybrid environment Apigee recommends using a separate service account for each component. Use the following command to create all the service accounts for the hybrid components with their default names in the default directory. 

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

This will create the following service accounts with the cert files downloaded in the ./tools/service-accounts directory:

Service account IAM role Email Cert file
apigee-cassandra roles/storage.objectAdmin apigee-cassandra@PROJECT_ID.iam.gserviceaccount.com PROJECT_ID-apigee-cassandra.json
apigee-guardrails roles/serviceusage.serviceUsageViewer apigee-guardrails@PROJECT_ID.iam.gserviceaccount.com PROJECT_ID-apigee-guardrails.json
apigee-logger roles/logging.logWriter apigee-logger@PROJECT_ID.iam.gserviceaccount.com PROJECT_ID-apigee-logger.json
apigee-mart roles/apigeeconnect.Agent apigee-mart@PROJECT_ID.iam.gserviceaccount.com PROJECT_ID-apigee-mart.json
apigee-metrics roles/monitoring.metricWriter apigee-metrics@PROJECT_ID.iam.gserviceaccount.com PROJECT_ID-apigee-metrics.json
apigee-mint-task-scheduler No role assigned apigee-mint-task-scheduler@PROJECT_ID.iam.gserviceaccount.com PROJECT_ID-apigee-mint-task-scheduler.json
apigee-runtime No role assigned apigee-runtime@PROJECT_ID.iam.gserviceaccount.com PROJECT_ID-apigee-runtime.json
apigee-synchronizer roles/apigee.synchronizerManager apigee-synchronizer@PROJECT_ID.iam.gserviceaccount.com PROJECT_ID-apigee-synchronizer.json
apigee-watcher roles/apigee.runtimeAgent apigee-watcher@PROJECT_ID.iam.gserviceaccount.com PROJECT_ID-apigee-watcher.json

Create a single service account for a non-production environment

For non-production environments, like an experimental or demo environment, you can create a single service account named "apigee-non-prod" that you can use for all components. This service account will have all the IAM roles in the previous example assigned to it. 

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

This will create as single service account named apigee-non-prod and download the cert file in the ./tools/service-accounts directory:

Service account IAM roles Email Cert file
apigee-non-prod roles/apigee.runtimeAgent
roles/apigee.synchronizerManager
roles/apigeeconnect.Agent
roles/logging.logWriter
roles/monitoring.metricWriter
roles/serviceusage.serviceUsageViewer
roles/storage.objectAdmin		 apigee-non-prod@PROJECT_ID.iam.gserviceaccount.com PROJECT_ID-apigee-non-prod.json

Give a single production service account a custom name

By default a single production service account is named after the supported service account name you select. For example, --prod apigee-cassandra creates a service account named apigee-cassandra. To give a single production service account a different name while keeping the same IAM role, add the --name flag (or its -n alias): 

./tools/create-service-account --prod apigee-cassandra --name my-cassandra-sa

This creates one production service account named my-cassandra-sa with the IAM role of apigee-cassandra (roles/storage.objectAdmin). The IAM role always comes from the service account name you pass to --prod; --name only changes what the account is called.

create-service-account syntax

The create-service-account tool uses the following syntax:

create-service-account [flags]

The following table lists the create-service-account flags:

Flag Values Description
--dir
-d		 directory name Specifies an output directory for the service account key files. If the directory does not exist, create-service-account will create it. If the directory already exists, create-service-account will overwrite any files in the directory that have the same name as the key files it is creating.

If you do not specify an output directory, create-service-account will write the service account files to the service-accounts/ directory within the directory where create-service-account resides.

--prod service account name
(optional)		 Creates service accounts for a production hybrid environment. This is the default: if you run create-service-account with no deployment-type flag, it behaves as though --prod was passed.

In a production environment it is recommended that you have a single service account for each Apigee service. Each service account created has a single IAM role associated with it.

create-service-account --prod with no service account name creates all the service accounts used by Apigee hybrid. To create only a single production service account, pass its name, for example --prod apigee-cassandra. The supported production service account names are listed in the service accounts table earlier on this page, under Create service accounts for a production environment.

--non-prod service account name
(optional)		 Creates a single service account with all the IAM roles bound to it. This is useful for non-production environments like an experimental or demo installation.

The service account is named apigee-non-prod unless you pass a name, for example --non-prod my-account.

--name
-n		 service account name Changes only what the created service account is called, never which IAM roles it receives. The roles are still determined by the deployment type and, for a single production service account, by SA_NAME.

The precedence rules depend on the deployment type:

  • --prod SA_NAME --name NAME creates a single production service account named NAME with the IAM role of SA_NAME. This lets you give a production service account a name other than SA_NAME.
  • --prod --name NAME with no SA_NAME is an error: with no service account name, --prod creates a separate service account for each supported production service account name, so a single --name would be ambiguous. Use --prod SA_NAME --name NAME to rename a single production service account.
  • --non-prod SA_NAME --name NAME: --name takes precedence. The tool logs a [WARNING] that both a positional name and --name were supplied, and names the single non-production service account NAME.
  • --non-prod --name NAME names the single non-production service account NAME.
--skip-key-download none Creates the service accounts and assigns their IAM roles but does not download the JSON key files. Use this flag when you do not need the key files, such as with the Workload Identity Federation for GKE authentication methods.
--help
-h		 none Displays help text.
‑‑project‑id
-i		 project id The Project ID of the Google Cloud project in which you are creating the service accounts.

You can supply the Project ID either with the --project-id flag or by exporting a PROJECT_ID environment variable. If both are set, the --project-id flag takes precedence over the PROJECT_ID environment variable and create-service-account logs a [WARNING]. In all cases the tool logs which source the Project ID was read from.

If you do not specify a Project ID with either the flag or the environment variable, create-service-account uses the ID of the project in your current gcloud configuration.

For more information about the service accounts used by Apigee hybrid, see About service accounts.

You can also create service accounts in the Google Cloud console. See also Creating and managing service accounts.