GCP.IAM reference

Policy

Source: packages/gcp/src/IAM/Policy.ts

An IAM v2 deny policy attached to a project, folder, or organization.

This is not GCP.OrgPolicy.Policy (organization policy constraints). Deny policies use annotations for Alchemy ownership. Create, update, and delete are long-running operations.

Policy: Creating a Deny Policy

const policy = yield* GCP.IAM.Policy("Probe", {
  displayName: "alchemy-probe",
  rules: [{
    denyRule: {
      deniedPermissions: ["iam.googleapis.com/roles.list"],
      deniedPrincipals: [
        "principal://goog/subject/alchemy-deny-probe@example.invalid",
      ],
    },
  }],
});

ServiceAccount

Source: packages/gcp/src/IAM/ServiceAccount.ts

A user-managed Google Cloud IAM service account.

Grant it roles with GCP.IAM.Member (kind: "project" for project-wide roles), and pass its email to resources that run as an identity, such as GKE node pools or Compute instances.

ServiceAccount: Creating a Service Account

Service account with a generated id

const account = yield* GCP.IAM.ServiceAccount("Worker", {
  displayName: "Background worker",
});

Service account with an explicit id

const account = yield* GCP.IAM.ServiceAccount("GkeNodes", {
  accountId: "prod-gke-nodes",
  displayName: "Production GKE nodes",
});

ServiceAccount: Granting Roles

const account = yield* GCP.IAM.ServiceAccount("Worker", {});
yield* GCP.IAM.Member("WorkerLogs", {
  kind: "project",
  name: account.project,
  role: "roles/logging.logWriter",
  member: Output.interpolate`serviceAccount:${account.email}`,
});

ServiceAccountKey

Source: packages/gcp/src/IAM/ServiceAccountKey.ts

A key for a Google Cloud IAM service account, for code that runs outside GCP and has to sign as the account.

Prefer running as the service account (Cloud Run, Cloud Functions, GKE Workload Identity) where you can: a key is a long-lived secret. Some organizations block key creation with the iam.disableServiceAccountKeyCreation policy.

ServiceAccountKey: Creating a Key

const account = yield* GCP.IAM.ServiceAccount("Ci", {});
const key = yield* GCP.IAM.ServiceAccountKey("CiKey", {
  serviceAccount: account.email,
});

WorkloadIdentityPool

Source: packages/gcp/src/IAM/WorkloadIdentityPool.ts

A Google Cloud IAM workload identity pool: a trust boundary that lets external identities (GitHub Actions, AWS, any OIDC or SAML issuer) exchange their tokens for short-lived Google credentials without service-account keys.

Add an issuer with GCP.IAM.WorkloadIdentityProvider, then let the federated principals impersonate a service account with GCP.IAM.Member (roles/iam.workloadIdentityUser).

WorkloadIdentityPool: Creating a Pool

const pool = yield* GCP.IAM.WorkloadIdentityPool("GitHub", {
  workloadIdentityPoolId: "github-actions",
  displayName: "GitHub Actions",
});

WorkloadIdentityPool: Impersonating a Service Account

const deployer = yield* GCP.IAM.ServiceAccount("Deployer", {});
yield* GCP.IAM.Member("GitHubDeployer", {
  kind: "iam.serviceAccount",
  name: deployer.name,
  role: "roles/iam.workloadIdentityUser",
  member: Output.interpolate`principalSet://iam.googleapis.com/${pool.name}/attribute.repository/my-org/my-repo`,
});

WorkloadIdentityProvider

Source: packages/gcp/src/IAM/WorkloadIdentityProvider.ts

An issuer in a Google Cloud IAM workload identity pool (a “workload identity pool provider”). Tokens from the issuer that pass the attribute condition can be exchanged for short-lived Google credentials.

WorkloadIdentityProvider: GitHub Actions

const pool = yield* GCP.IAM.WorkloadIdentityPool("GitHub", {
  workloadIdentityPoolId: "github-actions",
});
yield* GCP.IAM.WorkloadIdentityProvider("GitHubOidc", {
  workloadIdentityPoolId: pool.workloadIdentityPoolId,
  workloadIdentityPoolProviderId: "github",
  attributeMapping: {
    "google.subject": "assertion.sub",
    "attribute.repository": "assertion.repository",
  },
  attributeCondition: `assertion.repository == "my-org/my-repo"`,
  oidc: { issuerUri: "https://token.actions.githubusercontent.com" },
});

WorkloadIdentityProvider: AWS

yield* GCP.IAM.WorkloadIdentityProvider("Aws", {
  workloadIdentityPoolId: pool.workloadIdentityPoolId,
  attributeMapping: {
    "google.subject": "assertion.arn",
    "attribute.aws_role": "assertion.arn.extract('assumed-role/{role}/')",
  },
  aws: { accountId: "123456789012" },
});

Changing workloadIdentityPoolId or workloadIdentityPoolProviderId replaces the provider. GCP keeps a deleted provider for 30 days and reserves its id; deploying that id again restores it and re-applies the declared settings.