Service accounts and keys

This document explains the Google Cloud service accounts and keys that you need to create clusters in your Google Distributed Cloud implementation.

The instructions here are complete. For a shorter introduction to using a service account, see Set up minimal infrastructure.

Before you begin

Create Google Cloud projects.

Overview of service accounts

Before you create your admin and user clusters, you need to have these service accounts:

  • Component access service account
  • Connect-register 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 associate it with a Google Cloud project. This Google Cloud project is called the parent project of the service account.

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 a principle 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 principle, 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 Google Cloud project that is not the parent project of the service account.

Permissions for granting roles to service accounts

Each of your service accounts must be granted certain roles on the relevant Google Cloud project. For example, your connect-register service account must be granted the gkehub.editor role on your fleet host project.

To grant roles on a Google Cloud project, you must have certain permissions on the project. For details, see roles/resourcemanager.projectIamAdmin in Understanding roles.

If you have the required permissions, you can grant the roles yourself. Otherwise, someone else in your organization must grant the roles for you.

Using gkeadm to automatically create service accounts

This page shows how to manually create service accounts and grant roles to service accounts. As an alternative to doing these steps manually, you can have gkeadm create some of the service accounts, and grant roles, for you when you create an admin workstation. For more information, see Creating your admin workstation.

Component access service account

Google Distributed Cloud uses this service account to download cluster components, on your behalf, from Container Registry.

To create a component access service account:

gcloud iam service-accounts create component-access-sa \
    --display-name "Component Access Service Account" \
    --project PROJECT_ID

Replace PROJECT_ID with the ID of the Google Cloud project that you want to be the parent project of your service account.

To create a JSON key for your component access service account:

gcloud iam service-accounts keys create component-access-key.json \
   --iam-account SERVICE_ACCOUNT_EMAIL

Replace SERVICE_ACCOUNT_EMAIL with the email address of your component access service account.

Granting roles to your component access service account

Your component access service account must be granted the following IAM roles on your fleet host project. These roles are required so that Google Distributed Cloud can do preflight checks:

  • serviceusage.serviceUsageViewer
  • iam.roleViewer
  • iam.serviceAccountViewer
  • compute.viewer

To grant the roles:

gcloud projects add-iam-policy-binding FLEET_HOST_PROJECT_ID \
    --member "serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role "roles/serviceusage.serviceUsageViewer"
gcloud projects add-iam-policy-binding FLEET_HOST_PROJECT_ID \
    --member "serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role "roles/iam.roleViewer"
gcloud projects add-iam-policy-binding FLEET_HOST_PROJECT_ID \
    --member "serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role "roles/iam.serviceAccountViewer"
gcloud projects add-iam-policy-binding FLEET_HOST_PROJECT_ID \
    --member "serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role "roles/compute.viewer"

Replace the following:

  • FLEET_HOST_PROJECT_ID: the ID of your fleet host project.

  • SERVICE_ACCOUNT_EMAIL: the email address of your component access service account.

Connect-register service account

Google Distributed Cloud uses this service account to register your clusters to a fleet.

To create a connect-register service account:

gcloud iam service-accounts create connect-register-sa \
    --project PROJECT_ID

Replace PROJECT_ID with the ID of the Google Cloud project that you want to be the parent of your connect-register service account.

To create a JSON key for your connect-register service account:

gcloud iam service-accounts keys create connect-register-key.json \
   --iam-account SERVICE_ACCOUNT_EMAIL

Replace SERVICE_ACCOUNT_EMAIL with the email address of your connect-register service account.

Your connect-register service account must be granted the gkehub.editor role on your fleet host project.

To grant the gkehub.editor role to your connect-register service account:

gcloud projects add-iam-policy-binding FLEET_HOST_PROJECT_ID \
    --member "serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role "roles/gkehub.editor"

Logging-monitoring service account

Google Distributed Cloud uses this service account to export logs and metrics from clusters to Cloud Logging and Cloud Monitoring.

To create a logging-monitoring service account:

gcloud iam service-accounts create logging-monitoring-sa \
    --project=PROJECT_ID

Replace PROJECT_ID with the ID of the Google Cloud project that you want to be the parent of your logging-monitoring service account.

To create a JSON key for your logging-monitoring service account:

gcloud iam service-accounts keys create logging-monitoring-key.json \
    --iam-account SERVICE_ACCOUNT_EMAIL

Your logging-monitoring service account must be granted the following roles on your fleet host project:

  • opsconfigmonitoring.resourceMetadata.writer
  • logging.logWriter
  • monitoring.metricWriter
  • monitoring.dashboardEditor
  • kubernetesmetadata.publisher

To grant the required roles to your logging-monitoring service account:

gcloud projects add-iam-policy-binding FLEET_HOST_PROJECT_ID \
    --member "serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role "roles/opsconfigmonitoring.resourceMetadata.writer"
gcloud projects add-iam-policy-binding FLEET_HOST_PROJECT_ID \
    --member "serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role "roles/logging.logWriter"
gcloud projects add-iam-policy-binding FLEET_HOST_PROJECT_ID \
    --member "serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role "roles/monitoring.metricWriter"
gcloud projects add-iam-policy-binding FLEET_HOST_PROJECT_ID \
    --member "serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role "roles/monitoring.dashboardEditor"
gcloud projects add-iam-policy-binding FLEET_HOST_PROJECT_ID \
    --member "serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role "roles/kubernetesmetadata.publisher"

Replace SERVICE_ACCOUNT_EMAIL with the email address of your logging-monitoring service account.

Optional service accounts

Audit logging service account

Google Distributed Cloud uses this service account to send Kubernetes audit logs from your cluster to Cloud Audit Logs.

To create an audit logging service account:

gcloud iam service-accounts create audit-logging-sa \
    --project PROJECT_ID

Replace PROJECT_ID with the ID of the Google Cloud project that you want to be the parent of your audit logging service account.

To create a JSON key for your audit logging service account:

gcloud iam service-accounts keys create audit-logging-key.json \
   --iam-account SERVICE_ACCOUNT_EMAIL

Replace SERVICE_ACCOUNT_EMAIL with the email address of your audit logging service account.

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

Usage metering service account

Google Distributed Cloud uses this service account to store usage data in a BigQuery dataset.

To create a usage metering service account:

gcloud iam service-accounts create usage-metering-sa \
    --project PROJECT_ID

Replace PROJECT_ID with the ID of the Google Cloud project that you want to be the parent of your usage metering service account.

To create a JSON key for your usage metering service account:

gcloud iam service-accounts keys create usage-metering-key.json \
   --iam-account SERVICE_ACCOUNT_EMAIL

Replace SERVICE_ACCOUNT_EMAIL with the email address of your usage metering service account.

Your usage metering service account must be granted the bigquery.dataEditor role on your usage metering project. This is the Google Cloud project where you want to view usage data for your user cluster.

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

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

Replace USAGE_METERING_PROJECT_ID with the ID of your usage metering project.

Binary authorization service account

Google Distributed Cloud uses this service account to call the Binary Authorization API.

For information on creating a binary authorization service account, see Binary Authorization in GKE on-prem.

What's next

Create an admin workstation.