Docs

Google Cloud

A Google Cloud deployment runs your stack in your customer's Google Cloud project: its Cloud Run services, VMs, buckets, and databases live there, inside the customer's boundary. The customer's admin sets it up once, and Alien rolls out every release after that, with no service account keys anywhere.

Architecture diagram. Left: Your side containing Alien manager, OIDC issuer. Right: customer-1's Google Cloud project containing Workload identity pool; Deployment, Management service account, Workload service accounts, Frozen and live resources.

The manager exchanges its own OIDC token for a short-lived token as the management service account. Google checks issuer, subject, and audience on every exchange.

A deployment's life has two parts:

  • Initial setup: the one-time step the admin runs with their own Google credentials, using Google login, Terraform, or the CLI.
  • Ongoing management: everything after. Alien's manager, the service that holds your releases and deployments, rolls out each release without the admin.

Initial setup creates the deployment's management identity: here, a service account the manager acts as through a workload identity pool the admin owns and can delete.

Initial setup also creates the frozen resources: the ones only initial setup may create or change, such as the bucket that holds the customer's data. The manager creates and updates the rest, the live resources.

How the admin reaches initial setup is your Deployment UX choice: a link you send, a Deploy button in your product, or your own setup screen. What happens in Google Cloud is the same either way, and this guide follows it from requirements to removal.

What the customer needs

  • A Google Cloud project. A dedicated project is recommended. The project is the boundary: other projects in the organization are out of reach.
  • Permission to enable APIs and create service accounts, workload identity pools, IAM bindings, and the stack's frozen resources. Project Owner is the usual choice.
  • Quotas for the stack. Initial setup checks them first. See Quotas.

Set up

Terraform and the CLI each run a setup package, which Alien builds from your release. Google login needs none. The deployment portal, the branded setup page Alien hosts for the admin, offers Google login first, then Terraform and the CLI.

To create a setup link that offers only Google Cloud:

alien onboard customer-1 --platforms gcp

Google Login

In the portal, the admin:

  1. Clicks Continue with Google under Connect Google Cloud and approves access.
  2. Picks the project under Choose project, or clicks Enter project ID manually.
  3. Picks a region under Choose region.
  4. Clicks Start deployment.

Initial setup runs with the admin's Google token. See Google login.

Terraform

The admin clicks Prepare Terraform, saves the generated main.tf in an empty folder, replaces <gcp-project-id>, and runs:

export TF_VAR_token='<setup token>'
terraform init && terraform apply

TF_VAR_token is the setup token, the credential from the setup link that authorizes this one initial setup. The module uses the admin's google provider credentials.

CLI

The admin installs your CLI, saves the generated deployment.toml, and runs:

export ACMECTL_DEPLOYMENT_TOKEN='<setup token>'
acmectl deploy --config deployment.toml

The CLI uses Application Default Credentials.

Review the module first

To review the module with the customer's security team first:

alien render --format terraform --target gcp --stack .alien/build/gcp/stack.json --output gcp-setup

What the initial setup creates

  • A management service account with custom IAM roles generated from the stack's permission sets. Roles are scoped to the project or to individual resources, with IAM Conditions where Google Cloud supports them.
  • A workload identity pool and OIDC provider owned by the customer. The provider accepts tokens only from the manager's issuer, only for one exact subject, and only for this deployment's audience.
  • One IAM binding: roles/iam.workloadIdentityUser on the management service account, for that single federated subject.
  • One service account per permission profile, for your workloads.
  • The Google Cloud APIs the stack needs, enabled.
  • Frozen resources, the resources only initial setup creates or changes, so Alien can't change them later, such as Cloud Storage buckets or Cloud KMS keys.

The customer can revoke access by deleting the pool, the binding, or the service account.

Google login

Google login asks for the cloud-platform scope, because initial setup may enable APIs, create service accounts and IAM bindings, and create frozen resources.

Alien uses the token only for that one initial setup attempt. It never returns the token to the browser, and it deletes the session afterwards. Ongoing management uses the federated service account above, not the admin's token.

By default, Google's consent screen shows Alien's OAuth app. To show your own name, in the dashboard:

  1. In a dedicated Google Cloud project, create an OAuth web client.
  2. Open project Settings → Deployment Portal → Google Sign-In, set OAuth app to Custom Google OAuth app, and click Copy redirect URI. It has the form https://<manager-host>/v1/gcp/oauth/callback.
  3. Add that redirect URI to the OAuth client in Google Cloud.
  4. Enter the Client ID and Client Secret, and click Save Portal.

From the CLI, alien projects portal google-sign-in sets the same client. See Brand the portal.

Keep this app separate from the one you use for sign-in to your own product. Initial setup needs broad Google Cloud access; sign-in needs only identity scopes.

How updates arrive

Ongoing management on Google Cloud uses push: Alien calls Google Cloud APIs from outside the project, instead of a component inside it pulling releases. When a release reaches the deployment's release channel, the manager takes the federated identity and updates the live resources through Google Cloud APIs. Nothing connects into the customer's network.

A release that changes a frozen resource or needs a new permission waits for the admin to run initial setup again: they sign in with Google again from the portal, reapply Terraform, or rerun the CLI. See Releases that need initial setup again.

To run pull in a Google Cloud project, deploy into a GKE cluster instead. See Kubernetes.

Remove it

  1. Delete the deployment from your side: Delete deployment, or alien deployments delete customer-1/customer-1.

  2. Alien deletes the live resources, and the deployment shows Teardown required.

  3. The admin finishes in the portal:

    • Google login: Finish uninstall → Continue with Google. Alien removes what initial setup created, with that sign-in.
    • Terraform: terraform destroy in the setup folder, with the same TF_VAR_token.
    • CLI: acmectl destroy.

Quotas

Before it creates anything, initial setup checks the Google Cloud quotas the stack needs, such as regional CPUs, custom IAM roles, and service accounts per project. A shortfall stops initial setup with the quota name, current usage, and an increase link.

The CLI accepts --quota-warning-override for a quota the customer chooses to accept. See AWS quotas for how overrides work.

Regions

The portal offers every Google Cloud region in Alien's catalog.

Next

AWS

A deployment in a customer's AWS account: what the admin needs, initial setup with CloudFormation, Terraform, or the CLI, the management role, updates, and removal.

Azure

A deployment in a customer's Azure subscription: what the admin needs, initial setup with Terraform or the CLI, the managed identity and its role limits, updates, and removal.

On this page

What the customer needsSet upGoogle LoginTerraformCLIReview the module firstWhat the initial setup createsGoogle loginHow updates arriveRemove itQuotasRegionsNext