Version 1.4. This version is no longer supported. For more information see the version support policy.

Service accounts and keys

This page explains the Google Cloud service accounts and keys that you need to install GKE on-prem.

Overview of service accounts

Before you install GKE on-prem, you need to have these service accounts:

Allowlisted service account
Connect-register service account
Connect-agent service account
Logging-monitoring service account

Depending on the features you want to enable, you might also need to have some optional service accounts.

Understanding service accounts and Google Cloud projects

When you create a service account, you create it in a Google Cloud project. The Google Cloud project where you create a service account is called the parent project of the service account. The service account is a member of its parent project.

You can determine the parent project of a service account by looking at the email address of the service account. For example, here is the email address of a service account named logger. The parent project is alice-123.

logger@alice-123.iam.gserviceaccount.com

When you grant an Identity and Access Management (IAM) role to a service account, you grant the role to the service account on a particular Google Cloud project.This follows the general pattern of granting a role to an identity on a resource.

For example, you could grant the bigquery.dataEditor role to the logger@alice-123.iam.gserviceaccount.com service account on the bob-456 project. In this case, the service account is the identity, and the Google Cloud project is the resource.

It is important to understand that you can grant a role to a service account on a project that is not the parent project of the service account.

Allowlisted service account

You already have an allowlisted service account.

If you have not already created a JSON key file for your allowlisted service account, create one now:

gcloud iam service-accounts keys create whitelisted-key.json \
   --iam-account [ALLOWLISTED_SERVICE_ACCOUNT_EMAIL]

where [ALLOWLISTED_SERVICE_ACCOUNT_EMAIL] is the email address of your allowlisted service account.

Granting roles to your allowlisted service account

The GKE on-prem configuration file has several fields that specify a Google Cloud project ID.

usercluster:
  usagemetering:
    bigqueryprojectid: ""
...
gkeconnect:
  projectid: ""
...
stackdriver:
  projectid: ""
...
cloudauditlogging:
  projectid: ""

The project IDs in your GKE on-prem configuration file do not have to be distinct. For example gkeconnect.projectid could be the same as stackdriver.projectid. In fact, all of the project IDs in your configuration file could be the same.

Your allowlisted service account must be granted the following IAM roles on each project that is specified in your GKE on-prem configuration file:

serviceusage.serviceUsageViewer
iam.serviceAccountCreator
iam.roleViewer

If you used gkeadm to create your admin workstation, then gkeadm set the following fields in your GKE on-prem configuration file to the ID of the parent project of your allowlisted service account.

gkeconnect.projectid
stackdriver.projectid

Also, gkeadm granted your allowlisted service account the required roles on the parent project of your allowlisted service account.

If you did not use gkeadm to create your admin workstation, then you must grant the roles yourself.

For each project that is specified in your GKE on-prem configuration file, grant your allowlisted service account the required roles:

gcloud projects add-iam-policy-binding [PROJECT_ID] \
--member "serviceAccount:[ALLOWLISTED_SERVICE_ACCOUNT_EMAIL]" \
--role "roles/serviceusage.serviceUsageViewer"

gcloud projects add-iam-policy-binding [PROJECT_ID] \
--member "serviceAccount:[ALLOWLISTED_SERVICE_ACCOUNT_EMAIL]" \
--role "roles/iam.serviceAccountCreator"

gcloud projects add-iam-policy-binding [PROJECT_ID] \
--member "serviceAccount:[ALLOWLISTED_SERVICE_ACCOUNT_EMAIL]" \
--role "roles/iam.roleViewer"

where [PROJECT_ID] is the ID of one of the projects you specified in your GKE on-prem configuration file.

Other required service accounts

Recall that in addition to your allowlisted service account, you need these service accounts:

connect-register service account
connect-agent service account
logging-monitoring service account

Depending on how you created your admin workstation, you might already have these service accounts.

Case 1: gkeadm created service accounts for you.

If you used gkeadm to create your admin workstation and you passed the --auto-create-service-accounts flag, then gkeadm did the following for you:

Created a connect-register service account. Granted the appropriate IAM roles to the connect-register service account. Created a JSON key file for the connect-register service account. Copied the JSON key file to your admin workstation.
Created a connect-agent service account. Granted the appropriate IAM roles to the connect-agent service account. Created a JSON key file for the connect-agent service account. Copied the JSON key file to your admin workstation.
Created a logging-monitoring service account. Granted the appropriate IAM roles to the logging-monitoring service account. Created a JSON key file for the logging-monitoring service account. Copied the JSON key file to your admin workstation.

When gkeadm creates service accounts for you, it creates the accounts in the Google Cloud project that is the parent of your allowlisted service account. Also, gkeadm grants roles to the service accounts on that same project. For information about using more than one Google Cloud project, see Using multiple Google Cloud projects.

Case 2: gkeadm did not create service accounts for you.

If you did not use gkeadm with the --auto-create-service-accounts flag to create your admin workstation, then you must create your own service accounts. Also, for each service account, you must create a JSON key file and grant the appropriate IAM roles.

Creating your own service accounts

If you already have service accounts as described in Case 1, you can skip this section.

This section shows how to create the service accounts that you need to install and use GKE on-prem. It also shows how to create JSON key files for your service accounts and how to grant the appropriate IAM roles to your service accounts.

Connect-register service account

Connect uses this service account to register your GKE on-prem clusters with Google Cloud.

Create your connect-register service account::

gcloud iam service-accounts create connect-register-svc-account --project [PARENT_PROJECT_ID]

where [PARENT_PROJECT_ID] is the ID of the project that you want to be the parent of your connect-register service account.

Create a key for your connect-register service account:

gcloud iam service-accounts keys create connect-register-key.json \
   --iam-account [CONNECT_REGISTER_SERVICE_ACCOUNT_EMAIL]

where [CONNECT_REGISTER_SERVICE_ACCOUNT_EMAIL] is the email address of your connect-register service account.

Grant the gkehub.admin role to your connect-register service account:

gcloud projects add-iam-policy-binding [CONNECT_PROJECT_ID] \
--member "serviceAccount:[CONNECT_REGISTER_SERVICE_ACCOUNT_EMAIL]" \
--role "roles/gkehub.admin"

here [CONNECT_PROJECT_ID] is the ID of your connect project. This is the project where you want to register and maintain a connection to your GKE on-prem clusters.

Connect-agent service account

Connect uses this service account to maintain a connection between GKE on-prem and Google Cloud.

Create your connect-agent service account:

gcloud iam service-accounts create connect-agent-svc-account  --project [PARENT_PROJECT_ID]

where [PARENT_PROJECT_ID] is the ID of the project that you want to be the parent of your connect-agent service account.

Create a key for your connect-agent service account:

gcloud iam service-accounts keys create connect-agent-key.json \
   --iam-account [CONNECT_AGENT_SERVICE_ACCOUNT_EMAIL]

where [CONNECT_AGENT_SERVICE_ACCOUNT_EMAIL] is the email address of your connect-agent service account.

Grant the gkehub.connect role to your connect-agent service account:

gcloud projects add-iam-policy-binding [CONNECT_PROJECT_ID] \
--member "serviceAccount:[CONNECT_AGENT_SERVICE_ACCOUNT_EMAIL]" \
--role "roles/gkehub.connect"

where [CONNECT_PROJECT_ID] is the ID of your connect project. This is the project where you want to register and maintain a connection to your GKE on-prem clusters.

Logging-monitoring service account

Connect uses this service account to export logs from clusters to Cloud Logging.

Create your logging-monitoring service account:

gcloud iam service-accounts create logging-monitoring-svc-account --project [PARENT_PROJECT_ID]

where [PARENT_PROJECT_ID] is the ID of the project that you want to be the parent of your logging-monitoring service account.

Create a key for your logging-monitoring service account:

gcloud iam service-accounts keys create logging-monitoring-key.json \
   --iam-account [LOG_MON_SERVICE_ACCOUNT_EMAIL]

where [LOG_MON_SERVICE_ACCOUNT_EMAIL] is the email address of your logging-monitoring service account.

Grant the stackdriver.resourceMetadata.writer, logging.logWriter, and monitoring.metricWriter roles to your logging-monitoring service account:

gcloud projects add-iam-policy-binding [LOG_MON_PROJECT_ID] \
--member "serviceAccount:[LOG_MOM_SERVICE_ACCOUNT_EMAIL]" \
--role "roles/stackdriver.resourceMetadata.writer"

gcloud projects add-iam-policy-binding [LOG_MON_PROJECT_ID] \
--member "serviceAccount:[LOG_MOM_SERVICE_ACCOUNT_EMAIL]" \
--role "roles/logging.logWriter"

gcloud projects add-iam-policy-binding [LOG_MON_PROJECT_ID] \
--member "serviceAccount:[LOG_MON_SERVICE_ACCOUNT_EMAIL]" \
--role "roles/monitoring.metricWriter"

where [LOG_MON_PROJECT_ID] is the ID of your logging-monitoring project. This is the project where you want to view logs for your GKE on-prem clusters.

Optional service accounts

Usage metering service account

GKE usage metering uses this service account to store usage data in a BigQuery dataset.

If you want to enable GKE usage metering for a cluster, you need to have a usage metering service account. The gkeadm tool does not create this service account for you, so you must create it yourself.

Create your usage metering service account:

gcloud iam service-accounts create usage-metering-svc-account --project [PARENT_PROJECT_ID]

where [PARENT_PROJECT_ID] is the ID of the project that you want to be the parent of your usage metering service account.

Create a key for your usage metering service account:

gcloud iam service-accounts keys create usage-metering-key.json \
   --iam-account [USAGE_METERING_SERVICE_ACCOUNT_EMAIL]

where [USAGE_METERING_SERVICE_ACCOUNT_EMAIL] is the email address of your usage metering service account.

Grant the bigquery.dataEditor role to your usage metering service account:

gcloud projects add-iam-policy-binding [USAGE_METERING_PROJECT_ID] \
--member "serviceAccount:[USAGE_METERING_SERVICE_ACCOUNT_EMAIL]" \
--role "roles/bigquery.dataEditor"

where [USAGE_METERING_PROJECT_ID] is the ID of your usage metering project. This is the project where you want to view usage data for your GKE on-prem cluster.

Audit logging service account

GKE on-prem uses this service account to send Kubernetes audit logs from your cluster to Cloud Audit Logs.

If you want to enable Cloud Audit Logs for your GKE on-prem installation, you need to have an audit logging service account. The gkeadm tool does not create this service account for you, so you must create it yourself.

Create your audit logging service account:

gcloud iam service-accounts create audit-logging-svc-account --project [PARENT_PROJECT_ID]

where [PARENT_PROJECT_ID] is the ID of the Google Cloud project that you want to be the parent of your audit logging service account.

Create a key for your audit logging service account:

gcloud iam service-accounts keys create audit-logging-key.json \
   --iam-account [AUDIT_LOGGINGSERVICE_ACCOUNT_EMAIL]

where [AUDIT_LOGGING_SERVICE_ACCOUNT_EMAIL] is the email address of your audit logging service account.

You do not need to grant any roles to your audit logging service account.