create-service-account

create-serice-account overview

create-serice-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. create-service-account reads the value of the PROJECT_ID environment variable. If it is not present, you can use the --project-id flag.

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

Depending on the tool you are using to install and manage Apigee hybrid, create-service-account can be found in the following directories:

  • Helm Charts: $APIGEE_HELM_CHARTS_HOME/apigee-operator/etc/tools/
  • apigeectl: $APIGEECTL_HOME/apigeectl/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 --env 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-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-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-udca roles/apigee.analyticsAgent apigee-udca@PROJECT_ID.iam.gserviceaccount.com PROJECT_ID-apigee-udca.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 --env 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.analyticsAgent
roles/apigee.runtimeAgent
roles/apigee.synchronizerManager
roles/apigeeconnect.Agent
roles/logging.logWriter
roles/monitoring.metricWriter
roles/storage.objectAdmin		 apigee-non-prod@PROJECT_ID.iam.gserviceaccount.com PROJECT_ID-apigee-non-prod.json

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.

--env
-e		 prod
non-prod		 Specifies if you are creating service accounts for a production (prod) environment or a non-production (non-prod) environment.
  • --env prod creates service accounts for production hybrid environments.

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

    create-service-account -env prod will create all the service accounts used by Apigee hybrid unless you specify a specific service account with --profile.

  • --env non-prod 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 will be named apigee-non-prod unless you specify a name with the --name flag.

If you run create-service-account without --env, it will prompt you to enter prod or non-prod.

--help
-h		 none Displays help text.
--name
-n		 service account name Specifies a name for the service account. --name only applies to a single service account, either specified with --profile or --env non-prod.

The name is also part of the cert file name and email for the service account. For example if you run create-service-account --profile apigee-logger --name my-logger (assuming for this example your current Cloud project is my-hybrid-project) create-service-account will create an account with:

  • Name: my-logger
  • Email: my-logger@my-hybrid-project.iam.gserviceaccount.com
  • Cert file: my-hybrid-project-my-logger.json

If you do not specify --name, create-service-account uses the name of the profile for the name of the service account or "apigee-non-prod" if you specify --env non-prod.

‑‑profile
-p		 apigee‑cassandra
apigee‑logger
apigee‑mart
apigee‑metrics
apigee‑runtime
apigee‑synchronizer
apigee‑udca
apigee‑watcher		 For production environments only, specifies a single service account to create.

You can specify a name for the service account with the --name flag.

Requires --env prod.

‑‑project‑id
-i		 project id The Project ID of the Google Cloud project in which you are creating the service accounts.

create-service-account reads the value of the PROJECT_ID environment variable. If it is not present, you can use the --project-id flag.

If you do not specify a Project ID, create-service-account will use 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.