Google Cloud Credentials

Google Cloud Credentials

A Cloud Run deploy authenticates as a Google Cloud service account, using a JSON key you create once and paste into the Designer. This page is the exact procedure: which APIs to turn on, which roles to grant, how to create the key, and how to confirm it works before running a deploy.

Caution

A deploy that fails on a missing permission fails late — after the bundle has been built and pushed. Use Check permissions (below) first. It takes seconds and reports every missing permission at once.

What you will end up with

Thing	Example	Where it goes
Project ID	acme-prod-1234	GCP project id
Cloud Run region	asia-southeast1	Cloud Run region
Artifact Registry repository	greentic	Artifact Registry repository (optional — defaults to greentic)
Service-account key	a JSON file	Service-account key JSON
Runtime service account	gtc-acme-runtime@acme-prod-1234.iam.gserviceaccount.com	Created for you on the first deploy — see Runtime service account

The project ID, not the project name or number. In the Google Cloud console the ID is the lowercase, hyphenated string shown under Project ID on the project picker — it often has a numeric suffix Google appended.

Note

The project_id field inside the key file is ignored. Greentic reads the project from the environment’s own configuration, so a key minted in one project cannot silently redirect a deploy to another.

1. Enable the APIs

The deploy and its preflight both call Google APIs directly. Each must be enabled on the project or every request returns 403 SERVICE_DISABLED.

gcloud services enable \
  cloudresourcemanager.googleapis.com \
  artifactregistry.googleapis.com \
  iam.googleapis.com \
  run.googleapis.com \
  secretmanager.googleapis.com \
  --project=acme-prod-1234

API	Used by
cloudresourcemanager.googleapis.com	the permission check, at project scope
artifactregistry.googleapis.com	pushing the bundle image, and the repository-scope permission check
iam.googleapis.com	the actAs check on the runtime service account
run.googleapis.com	creating and updating the Cloud Run service
secretmanager.googleapis.com	storing the deployment’s secrets

Caution

Cloud Resource Manager is the one that catches people out. It is not enabled by default on a brand-new project, and when it is off the permission check gets a 403 rather than an answer — which looks exactly like a service account that has been granted nothing at all. If the check reports that a scope could not be checked, read the detail line: a SERVICE_DISABLED there means you need this command, not more IAM.

2. Create the service account

1. Open IAM & Admin → Service Accounts in the Google Cloud console, with the right project selected, and click Create service account.

2. Name it something that says what it is — greentic-deployer is a good default. Note the generated address; you need it in the next step. It looks like greentic-deployer@acme-prod-1234.iam.gserviceaccount.com.

3. Skip the “Grant this service account access” step. The roles are granted explicitly below, some of them at a scope this screen cannot express.

Or, in one command:

gcloud iam service-accounts create greentic-deployer \
  --display-name="Greentic deployer" \
  --project=acme-prod-1234

3. Grant the roles

Greentic checks permissions at three different scopes, because Google answers a permission question only for the resource you ask about. A grant made at the wrong scope is invisible to the deploy even though it is plainly there in the console.

Set these once:

PROJECT=acme-prod-1234
REGION=asia-southeast1
REPO=greentic
SA=greentic-deployer@$PROJECT.iam.gserviceaccount.com

Project scope

gcloud projects add-iam-policy-binding $PROJECT \
  --member="serviceAccount:$SA" --role=roles/run.admin --condition=None

gcloud projects add-iam-policy-binding $PROJECT \
  --member="serviceAccount:$SA" --role=roles/secretmanager.admin --condition=None

gcloud projects add-iam-policy-binding $PROJECT \
  --member="serviceAccount:$SA" --role=roles/logging.viewer --condition=None

gcloud projects add-iam-policy-binding $PROJECT \
  --member="serviceAccount:$SA" --role=roles/iam.serviceAccountAdmin --condition=None

• roles/logging.viewer lets the Designer’s Log tab read your deployed service’s logs with this same key. roles/run.admin does not include it.
• roles/iam.serviceAccountAdmin lets Greentic create the runtime service account for you on the first deploy (next section). Without it, the first deploy stops and hands you two gcloud commands to run by hand instead.

Artifact Registry

The bundle image is pushed from Greentic, so this account needs write, not just read.

If the repository already exists, grant on the repository — narrower, and it is where Greentic looks:

gcloud artifacts repositories add-iam-policy-binding $REPO \
  --location=$REGION --project=$PROJECT \
  --member="serviceAccount:$SA" --role=roles/artifactregistry.writer

If it does not exist yet, grant at project scope instead, and add artifactregistry.admin so the first deploy can create it:

gcloud projects add-iam-policy-binding $PROJECT \
  --member="serviceAccount:$SA" --role=roles/artifactregistry.writer --condition=None

gcloud projects add-iam-policy-binding $PROJECT \
  --member="serviceAccount:$SA" --role=roles/artifactregistry.admin --condition=None

Tip

roles/artifactregistry.writer can push to a repository but cannot create one. That is why the first deploy into a fresh project needs roles/artifactregistry.admin as well. Once the repository exists you can drop back to writer, scoped to the repository.

Runtime service account

A deployed Cloud Run service runs as its own identity, separate from the deployer account above. Greentic gives every workspace a dedicated one, named gtc-<workspace>-runtime (for example gtc-acme-runtime@acme-prod-1234.iam.gserviceaccount.com), rather than letting services fall back to the project’s default compute service account, which is shared by everything in the project.

Google only lets an account deploy a service that runs as another identity if it holds iam.serviceAccounts.actAs on that identity. So the runtime account needs two things: it must exist, and the deployer must hold roles/iam.serviceAccountUser on it.

With roles/iam.serviceAccountAdmin granted (above), you do nothing. On the first deploy Greentic creates gtc-<workspace>-runtime, grants the deployer roles/iam.serviceAccountUser on that one account, and remembers it for every later deploy.

Without it, the first deploy stops before building anything and shows the two commands to run once, with your project, workspace and deployer filled in:

gcloud iam service-accounts create gtc-acme-runtime \
  --project=$PROJECT --display-name='Greentic Cloud Run runtime'

gcloud iam service-accounts add-iam-policy-binding \
  gtc-acme-runtime@$PROJECT.iam.gserviceaccount.com \
  --project=$PROJECT \
  --member="serviceAccount:$SA" --role=roles/iam.serviceAccountUser

Run both and deploy again. Both options are sound — pick one:

	Grant roles/iam.serviceAccountAdmin	Run the two commands
Who acts	Greentic, on each new workspace’s first deploy	You, once per workspace
Deployer’s IAM power	Can create and manage service accounts in the project	actAs on one named account only
Best when	Several workspaces deploy into this project	One workspace, or a locked-down project

Caution

roles/iam.serviceAccountUser goes on the runtime account, not on the project. The second command binds it to gtc-<workspace>-runtime alone. Granting it at project scope instead lets the deployer act as every service account in the project — and it still does not create the runtime account, so the deploy stops at the same place.

Note

Using your own runtime account. If you already have one you want services to run as, enter its address in Runtime service account. Greentic then uses it and creates nothing; the deployer still needs roles/iam.serviceAccountUser on it (the second command above, with your account’s address).

4. Create the key

1. Open the service account, go to the Keys tab, and choose Add key → Create new key.

2. Pick JSON. The file downloads once and Google keeps no copy.

3. Open the file and copy its entire contents, braces included.

gcloud iam service-accounts keys create greentic-deployer.json \
  --iam-account=$SA --project=$PROJECT

The file must be a service-account key. It looks like this:

{
  "type": "service_account",
  "project_id": "acme-prod-1234",
  "private_key_id": "…",
  "private_key": "-----BEGIN PRIVATE KEY-----\n…\n-----END PRIVATE KEY-----\n",
  "client_email": "greentic-deployer@acme-prod-1234.iam.gserviceaccount.com",
  "client_id": "…",
  "token_uri": "https://oauth2.googleapis.com/token"
}

Greentic reads three fields from it — client_email, private_key and token_uri — and requires token_uri to be an https:// URL.

Caution

A gcloud auth application-default login file is not this file. That one has "type": "authorized_user" and is rejected by name, with an error saying so. Application-default credentials belong to you, expire, and cannot be used for an unattended deploy. Create a service-account key as above.

5. Paste it in and check it

1. In the Designer, open the Deploy panel and expand Google Cloud Run.

2. Fill in GCP project id, Cloud Run region, and — if you are not using the default — Artifact Registry repository.

3. Paste the whole key file into Service-account key JSON.

4. Click Check permissions.

The check is read-only. It changes nothing in your project and stores nothing; it asks Google what this key is allowed to do, at each of the three scopes, and prints what is missing.

Each scope comes back as one of three answers, and they are deliberately not collapsed into a pass/fail:

• satisfied — every permission is granted.
• missing — Google answered, and named permissions are absent. The report offers the gcloud command that grants them.
• not checked — Google did not answer, so nothing is known. This is not a pass. The commonest cause is an API that is not enabled (see step 1).

Note

On a first deploy the repository does not exist yet. The check notices the 404, re-asks at project scope — where a grant genuinely does cover the push — and tells you it did. That is expected, not a fallback that hides a problem.

The permissions, exactly

If you prefer a custom role to the predefined ones above, this is the full set Greentic probes, and the scope each one is asked about.

Project scope

run.services.get, run.services.list, run.services.create, run.services.update, run.services.delete, run.services.getIamPolicy, run.services.setIamPolicy, run.revisions.get, run.revisions.list, run.revisions.delete, run.operations.get, secretmanager.secrets.get, secretmanager.secrets.create, secretmanager.secrets.update, secretmanager.versions.add, secretmanager.versions.access, secretmanager.secrets.getIamPolicy, secretmanager.secrets.setIamPolicy, secretmanager.secrets.delete, logging.logEntries.list

Plus five advisory permissions, reported but never counted as a failure:

• artifactregistry.repositories.create — needed only to create the repository, so a deploy into one that already exists does not need it; on a first run it decides whether the deploy gets far enough to need any of the others (roles/artifactregistry.admin).
• iam.serviceAccounts.get, iam.serviceAccounts.create, iam.serviceAccounts.getIamPolicy, iam.serviceAccounts.setIamPolicy — needed only to create the runtime service account for you (roles/iam.serviceAccountAdmin). A workspace whose runtime account already exists needs none of them.

Repository scope

artifactregistry.repositories.get, artifactregistry.repositories.downloadArtifacts, artifactregistry.repositories.uploadArtifacts

Service-account scope

iam.serviceAccounts.actAs, asked about the runtime service account.

Tip

artifactregistry.repositories.uploadArtifacts is easy to miss. Bootstrap tooling that validates a Google Cloud credential for the deployer alone checks only the two read verbs, because it does not push anything — the bundle push happens in Greentic, before the deployer is invoked. A credential built strictly to that tooling’s output passes its own validation and then fails on the push. Grant roles/artifactregistry.writer (which includes uploadArtifacts), not roles/artifactregistry.reader.

Rotating or removing a key

The Designer stores the key encrypted and never shows it again — the panel only reports whether a credential is present. To rotate, use Replace and paste the new key; the old value is overwritten. Delete the superseded key in Google Cloud afterwards:

gcloud iam service-accounts keys list --iam-account=$SA --project=$PROJECT
gcloud iam service-accounts keys delete <KEY_ID> --iam-account=$SA --project=$PROJECT

Troubleshooting

Symptom	Cause	Fix
Every scope reports not checked	The APIs are not enabled	Step 1
Project scope reports not checked with a 403	Cloud Resource Manager is off	gcloud services enable cloudresourcemanager.googleapis.com
The key is rejected on paste	It is an authorized_user file, or a field is blank	Create a service-account key (step 4)
The permission check passes, the deploy fails on push	artifactregistry.repositories.uploadArtifacts was granted at a scope the deploy does not use	Grant roles/artifactregistry.writer on the repository and confirm the repository name matches
Service-account scope reports not checked	No runtime service account exists yet	Expected before the first deploy — it is created then (Runtime service account)
The deploy stops and shows gcloud iam service-accounts create gtc-…-runtime plus an add-iam-policy-binding … roles/iam.serviceAccountUser	The deployer cannot create the runtime service account	Run the two commands once, or grant roles/iam.serviceAccountAdmin and deploy again (Runtime service account)
You granted roles/iam.serviceAccountUser and the deploy still shows the same two commands	It was granted on the project, or the account does not exist yet	Run the create command, then bind the role on gtc-<workspace>-runtime itself
The Log tab says Google refused to read logs	logging.logEntries.list is missing	roles/logging.viewer at project scope

See also

• Cloud Deploy Environments — how an operator configures a deploy environment for a tenant.
• AWS Credentials
• Azure Credentials