Apigee provides a tool, create-service-account, that creates the service accounts,
assigns the roles to the service accounts, and creates and downloads the key files for the service
account in a single command. To learn about the related Google Cloud concepts, see
Creating
and managing service accounts and
Creating
and managing service account keys.
Execute the following command from inside the hybrid-files directory. This command
creates a service account for the apigee-metrics component and places
the downloaded key in the ./service-accounts directory.
[INFO]: gcloud configured project ID is project_id.
Press: y to proceed with creating service account in project: project_id
Press: n to abort.
If this is the first time an SA with the exact name assigned by the tool was created, then
the tool just creates it, and you do not have to do anything further.
If, however, you see the following message and prompt, enter y to generate
new keys:
[INFO]: Service account apigee-metrics@project_id.iam.gserviceaccount.com already exists.
...
[INFO]: The service account might have keys associated with it. It is recommended to use existing keys.
Press: y to generate new keys.(this does not de-activate existing keys)
Press: n to skip generating new keys.
Now, create the rest of the service accounts using the following commands. The create-service-account command
is interactive and requires a response for each account.
Verify that the service account keys were created using the following command. You are responsible for storing these
private keys securely. The key filenames are prefixed with the name of your Google Cloud project.
ls ./service-accounts
The result should look something like the following:
You are required to provide TLS certificates for the runtime ingress gateway in your
Apigee hybrid configuration. For the purpose of this quickstart (a non-production trial installation),
the runtime gateway can accept self-signed credentials. In the following steps,
openssl is used to generate the self-signed credentials.
In this step, you will create the TLS credential files and add them to
the base_directory/hybrid-files/certs directory.
In Step 6: Configure the
cluster, you will add the file paths to the cluster configuration file.
This command creates a self-signed certificate/key pair that you can use for the quickstart
installation.
Check to make sure the files are in the ./certs directory using the following command:
ls ./certs
keystore.pem
keystore.key
Where keystore.pem is the self-signed TLS certificate file and keystore.key
is the key file.
You now have the service accounts and credentials needed to manage Apigee hybrid
in your Kubernetes cluster. Next, you will create a file that is used by Kubernetes
to deploy the hybrid runtime components to the cluster.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-29 UTC."],[[["\u003cp\u003eThis documentation outlines the process of creating Google Cloud service accounts and TLS credentials necessary for the operation of Apigee hybrid.\u003c/p\u003e\n"],["\u003cp\u003eApigee hybrid uses service accounts to enable its components to communicate through authorized API calls, with a command-line tool provided to create these accounts and their associated private key files.\u003c/p\u003e\n"],["\u003cp\u003eThe process includes creating service accounts for various Apigee components, such as \u003ccode\u003eapigee-metrics\u003c/code\u003e, \u003ccode\u003eapigee-synchronizer\u003c/code\u003e, \u003ccode\u003eapigee-udca\u003c/code\u003e, \u003ccode\u003eapigee-mart\u003c/code\u003e, \u003ccode\u003eapigee-cassandra\u003c/code\u003e, \u003ccode\u003eapigee-logger\u003c/code\u003e, \u003ccode\u003eapigee-watcher\u003c/code\u003e, and \u003ccode\u003eapigee-distributed-trace\u003c/code\u003e, each requiring confirmation prompts.\u003c/p\u003e\n"],["\u003cp\u003eFor TLS credentials, the documentation guides users through generating self-signed certificate and key files using \u003ccode\u003eopenssl\u003c/code\u003e, which are suitable for quickstart installations, but advises the use of signed certificates for production environments.\u003c/p\u003e\n"],["\u003cp\u003eThe key files for service accounts and the TLS certificate/key pair are stored in designated directories (\u003ccode\u003e./service-accounts\u003c/code\u003e and \u003ccode\u003e./certs\u003c/code\u003e, respectively), and their secure storage is the user's responsibility.\u003c/p\u003e\n"]]],[],null,["# Step 5: Create service accounts and credentials\n\n| You are currently viewing version 1.4 of the Apigee hybrid documentation. **This version is end of life.** You should upgrade to a newer version. For more information, see [Supported versions](/apigee/docs/hybrid/supported-platforms#supported-versions).\n\nThis step explains how to create the Google Cloud service accounts and TLS credentials\nthat are required for Apigee hybrid to operate.\n\nCreate the service accounts\n---------------------------\n\n\nApigee hybrid uses Google Cloud [service accounts](https://cloud.google.com/iam/docs/service-accounts) to allow hybrid components to communicate by making authorized\nAPI calls.\n\n\nIn this step, you use an Apigee hybrid command-line tool to create a set of service accounts\nand download the service account private key files.\n\n\nTo learn more about service accounts and read the full list of service accounts recommended for\nproduction environments, see the following:\n\n- [About service accounts](/apigee/docs/hybrid/v1.4/sa-about)\n- [Service accounts and roles used by hybrid components](/apigee/docs/hybrid/v1.4/sa-about#recommended-sas)\n\n\nApigee provides a tool, `create-service-account`, that creates the service accounts,\nassigns the roles to the service accounts, and creates and downloads the key files for the service\naccount in a single command. To learn about the related Google Cloud concepts, see\n[Creating\nand managing service accounts](https://cloud.google.com/iam/docs/creating-managing-service-accounts) and\n[Creating\nand managing service account keys](https://cloud.google.com/iam/docs/creating-managing-service-account-keys).\n\n1. Be sure that you are in the \u003cvar translate=\"no\"\u003ebase_directory\u003c/var\u003e`/hybrid-files` directory you configured in [Set up the project directory structure](#setup-directory).\n2. Execute the following command from inside the `hybrid-files` directory. This command creates a service account for the `apigee-metrics` component and places the downloaded key in the `./service-accounts` directory. \n\n ```\n ./tools/create-service-account apigee-metrics ./service-accounts\n ```\n\n\n When you see the following prompt, enter \u003ckbd\u003ey\u003c/kbd\u003e: \n\n ```\n [INFO]: gcloud configured project ID is project_id.\n Press: y to proceed with creating service account in project: project_id\n Press: n to abort.\n ```\n\n\n If this is the first time an SA with the exact name assigned by the tool was created, then\n the tool just creates it, and you do not have to do anything further.\n\n\n If, however, you see the following message and prompt, enter \u003ckbd\u003ey\u003c/kbd\u003e to generate\n new keys: \n\n ```\n [INFO]: Service account apigee-metrics@project_id.iam.gserviceaccount.com already exists.\n ...\n [INFO]: The service account might have keys associated with it. It is recommended to use existing keys.\n Press: y to generate new keys.(this does not de-activate existing keys)\n Press: n to skip generating new keys.\n ```\n3. Now, create the rest of the service accounts using the following commands. The `create-service-account` command is interactive and requires a response for each account. \n\n ```\n ./tools/create-service-account apigee-synchronizer ./service-accounts\n ``` \n\n ```\n ./tools/create-service-account apigee-udca ./service-accounts\n ``` \n\n ```\n ./tools/create-service-account apigee-mart ./service-accounts\n ``` \n\n ```\n ./tools/create-service-account apigee-cassandra ./service-accounts\n ``` \n\n ```\n ./tools/create-service-account apigee-logger ./service-accounts\n ``` \n\n ```\n ./tools/create-service-account apigee-watcher ./service-accounts\n ``` \n\n ```\n ./tools/create-service-account apigee-distributed-trace ./service-accounts\n ```\n | **Note:** The Cloud Pub/Sub API must be enabled in the Google Cloud project that owns the service account for Synchronizer. See [Enable APIs](/apigee/docs/hybrid/v1.4/precog-enableapi).\n4. Verify that the service account keys were created using the following command. You are responsible for storing these private keys securely. The key filenames are prefixed with the name of your Google Cloud project. \n\n ```\n ls ./service-accounts\n ```\n\n\n The result should look something like the following: \n\n ```\n gcp-project-id-apigee-cassandra.json\n gcp-project-id-apigee-distributed-trace.json\n gcp-project-id-apigee-logger.json\n gcp-project-id-apigee-mart.json\n gcp-project-id-apigee-metrics.json\n gcp-project-id-apigee-synchronizer.json\n gcp-project-id-apigee-udca.json\n gcp-project-id-apigee-watcher.json\n ```\n\n| **Tip:** Apigee hybrid includes a validator that checks your service accounts' key files and permissions when [apigeectl](/apigee/docs/hybrid/v1.4/cli-reference) applies the Apigee hybrid runtime components to your cluster. This validation is enabled by default. For more information, see [Service account\n| validation](/apigee/docs/hybrid/v1.4/sa-validation).\n\nCreate TLS certificates\n-----------------------\n\n\nYou are required to provide TLS certificates for the runtime ingress gateway in your\nApigee hybrid configuration. For the purpose of this quickstart (a non-production trial installation),\nthe runtime gateway can accept self-signed credentials. In the following steps,\n[openssl](https://www.openssl.org/) is used to generate the self-signed credentials.\n| **Note:** In a production environment, you will need to use signed certificates. You can either use either a certificate and key pair or a Kubernetes secret. For an example on how to obtain a TLS certificate from the *Lets Encrypt* certificate authority (CA), see [Obtain TLS credentials: An example](/apigee/docs/hybrid/v1.4/lets-encrypt).\n\n\nIn this step, you will create the TLS credential files and add them to\nthe \u003cvar translate=\"no\"\u003ebase_directory\u003c/var\u003e`/hybrid-files/certs` directory.\nIn [Step 6: Configure the\ncluster](/apigee/docs/hybrid/v1.4/2-6-install-configure-cluster), you will add the file paths to the cluster configuration file.\n\n1. Be sure that you are in the \u003cvar translate=\"no\"\u003ebase_directory\u003c/var\u003e`/hybrid-files` directory you configured in [Set up the project directory structure](#setup-directory).\n2. Make sure to save a domain name to the **`DOMAIN`** environment variable using the following command: \n\n ```\n echo $DOMAIN\n ```\n3. Execute the following command from inside the `hybrid-files` directory: \n\n ```\n openssl req -nodes -new -x509 -keyout ./certs/keystore.key -out \\\n ./certs/keystore.pem -subj '/CN='$DOMAIN'' -days 3650\n ```\n\n\n Where **`DOMAIN`** is the same one you used for your environment in\n [Part 1, Step 5: Create an\n environment group](/apigee/docs/hybrid/v1.4/precog-add-environment).\n\n\n This command creates a self-signed certificate/key pair that you can use for the quickstart\n installation.\n4. Check to make sure the files are in the `./certs` directory using the following command: \n\n ls ./certs\n keystore.pem\n keystore.key\n\n\n Where `keystore.pem` is the self-signed TLS certificate file and `keystore.key`\n is the key file.\n\n\nYou now have the service accounts and credentials needed to manage Apigee hybrid\nin your Kubernetes cluster. Next, you will create a file that is used by Kubernetes\nto deploy the hybrid runtime components to the cluster.\n[1](/apigee/docs/hybrid/v1.4/2-1-install-create-cluster) [2](/apigee/docs/hybrid/v1.4/2-2-install-cert-manager) [3](/apigee/docs/hybrid/v1.4/2-3-install-asm) [4](/apigee/docs/hybrid/v1.4/2-4-install-apigeectl) [5](/apigee/docs/hybrid/v1.4/2-5-install-service-accounts) [(NEXT) Step 6: Configure the hybrid runtime](/apigee/docs/hybrid/v1.4/2-6-install-configure-cluster) [7](/apigee/docs/hybrid/v1.4/2-7-install-hybrid-runtime)\n\n\u003cbr /\u003e"]]
