This document describes the Google-managed and user-managed service accounts
used by App Lifecycle Manager and the Identity and Access Management permissions required for each
service account.

App Lifecycle Manager provisions and manages infrastructure across multiple
Google Cloud projects. To ensure strict security boundaries and
follow the principle of least privilege, App Lifecycle Manager separates system
orchestration from tenant infrastructure deployment using distinct service
accounts. Understanding the structure and roles of these service accounts helps
you grant only the necessary permissions, secure your build and actuation
pipelines, and isolate tenant resources across projects.

## Overview of App Lifecycle Manager service accounts

App Lifecycle Manager uses a combination of Google-managed and user-managed
service accounts:

- *App Lifecycle Manager service account (Google-managed)*: This account is
  automatically created after you create your first SaaS offering resource. It is
  managed by Google and performs actions on your behalf, such as interacting
  with other Google Cloud services during unit provisioning.

- *Actuation service account (User-managed)*: You create and manage this service
  account. App Lifecycle Manager (through Infrastructure Manager) uses this
  account to execute your Terraform configurations when provisioning or updating
  units. This account acts as the identity for creating and managing the
  resources defined in your Terraform configuration. The actuation service
  account permissions are directly tied to the resources that your Terraform
  configuration manages.

  You can have multiple actuation service accounts. We recommend that you use a
  dedicated actuation service account for each tenant.
- *Optional: Artifact creation service account (User-managed)*: This service
  account is used for building and uploading your Terraform configurations
  packaged as Open Container Initiative (OCI) artifacts. This is often a
  Cloud Build service account, but it can be any service account with
  appropriate permissions for your SaaS offering.

> [!CAUTION]
> **Caution:** Careful management of these service accounts is crucial for the security and proper functioning of your App Lifecycle Manager deployment. Always follow the principle of least privilege and grant only the necessary permissions to each service account.

## App Lifecycle Manager service account (Google-managed)

The *App Lifecycle Manager service account* is a Google-managed
[service agent](https://docs.cloud.google.com/iam/docs/service-accounts#service-agents)
used by App Lifecycle Manager to perform operations within your project.

This service account is automatically provisioned when you create your first
App Lifecycle Manager resource. The App Lifecycle Manager service account is
referenced using the following format:

    service-PROJECT_NUMBER@gcp-sa-saasservicemgmt.iam.gserviceaccount.com

Replace the following:

- `PROJECT_NUMBER`: Your project number.

> [!NOTE]
> **Note:** You can find your project number in the Google Cloud console on the [Dashboard page](https://console.cloud.google.com/).

## Actuation service account (User-managed)

The *actuation service account* is a user-managed service account that you must
create. App Lifecycle Manager (through Infra Manager) uses this
service account to execute your Terraform configurations. It is the identity
that creates, modifies, and deletes the resources defined in your Terraform
configuration.

You are responsible for creating this service account within your producer
project or within your tenant project.

### Actuation service account input variables

When you create a unit using Google Cloud CLI, you must provide the actuation
service account as a key-value pair input variable for the Terraform
configuration:

- **Name** : `actuation_sa`

- **Variable type** : `String`

- **Variable value**: Actuation service account email address:

      my-actuation-sa@my-identifier.iam.gserviceaccount.com

### Required permissions

The *actuation service account* requires sufficient permissions to manage the
resources defined in your Terraform configuration. At a minimum, it needs the
following roles:

- `roles/iam.serviceAccountTokenCreator`: Allows the service account to
  generate tokens for authentication.

- `roles/config.admin`: Grants full control over
  Infra Manager resources.

- `roles/storage.admin`: Grants full control of Cloud Storage.

The actuation service account also needs permissions to create and manage the
specific Google Cloud resources used by your application.

For example:

- If your Terraform configuration creates Google Kubernetes Engine (GKE) clusters,
  the service account needs appropriate GKE roles
  (for example, `roles/container.admin`).

- If your Terraform configuration creates Compute Engine instances, the
  service account needs the `roles/compute.admin` role.

- If your Terraform configuration creates Cloud SQL instances, the service
  account needs the appropriate Cloud SQL roles (for example,
  `roles/cloudsql.admin`).

Consult the documentation for each Google Cloud resource that you use in
your Terraform configuration to determine the necessary permissions. Grant the
*least privilege* necessary for your application to function.

> [!NOTE]
> **Note:** It is a best practice to create a dedicated actuation service account for each tenant (unit) to isolate and limit the severity of potential issues.

## Artifact creation service account (User-managed)

The *artifact creation service account* is a user-managed service account that
you create to use a build system (such as Cloud Build) to package and
upload your Terraform artifacts to Artifact Registry.

This service account is separate from the App Lifecycle Manager and actuation
service accounts, and builds your Terraform code and pushes the resulting
artifact to Artifact Registry. Often, this is the Cloud Build service
account.

### Manual artifact creation

If you manually build and upload your Terraform artifacts (for example, using
`docker build` and `docker push` directly), you don't need a separate artifact
creation service account.

Instead, you can authenticate using your own credentials or a service account
with the necessary Artifact Registry permissions.

### Required permissions

If you are using Cloud Build, the Cloud Build service
account typically needs the following roles:

- `roles/artifactregistry.writer`: To push artifacts to Artifact Registry.

- `roles/artifactregistry.repoAdmin`: To manage the Artifact Registry
  repository.

- `roles/storage.admin`: To manage the Cloud Storage buckets.

- `roles/developerconnect.admin`: Permissions to use Developer Connect.

- `roles/developerconnect.readTokenAccessor`: Permissions to get a
  Developer Connect read token.

- `roles/logging.logWriter`: Permissions to write logs.

- `roles/cloudbuild.builds.builder`: To execute builds if you are deploying your
  Terraform configuration using Developer Connect.

- Any other permissions required by your build process (for example, access to
  source code repositories).

## What's next

- Review predefined roles and permissions in
  [Access control with IAM](https://docs.cloud.google.com/app-lifecycle-manager/access-control.md.txt).

- Learn how to isolate tenant resources in
  [Tenants and tenant projects](https://docs.cloud.google.com/app-lifecycle-manager/tenants.md.txt).

- Learn more about App Lifecycle Manager in the
  [App Lifecycle Manager overview](https://docs.cloud.google.com/app-lifecycle-manager/overview.md.txt).

- Get started with
  [Create a SaaS offering](https://docs.cloud.google.com/app-lifecycle-manager/create-saas-offering.md.txt).