# GCP

MechCloud uses Workload Identity Federation (WIF) to authenticate with GCP, eliminating the need for service account keys. This is more secure as there are no long-lived credentials to manage or rotate.

### Step 1: Create a GCP Project (if needed)

1. Log on to [GCP Console](https://console.cloud.google.com).
2. If you don't already have a project, create one from the project selector at the top of the page.
3. Note down the **Project ID** (not the project name) — you'll need it later.

### Step 2: Enable Required APIs

Enable the following APIs in your GCP project. Navigate to **APIs & Services** -> **Library** and enable each one:

| API                                     | Purpose                                       |
| --------------------------------------- | --------------------------------------------- |
| **IAM Service Account Credentials API** | Required for Workload Identity Federation     |
| **Security Token Service API**          | Required for token exchange in WIF            |
| **Compute Engine API**                  | For VM, disk, and network resource management |
| **Cloud Resource Manager API**          | For project-level operations                  |
| **Kubernetes Engine API**               | For GKE cluster management (if using GKE)     |
| **Cloud Logging API**                   | For Cost Explorer audit log queries           |
| **Cloud Billing API**                   | For pricing information (Cost Explorer)       |

### Step 3: Create a Service Account

1. In the GCP Console, navigate to **IAM & Admin** -> **Service Accounts**.
2. Click **Create Service Account**.
3. Enter a name (e.g., `mechcloud-wif`) and description.
4. Click **Create and Continue**.
5. Assign the following roles based on your needs:

| Role                                                    | Purpose                                                 |
| ------------------------------------------------------- | ------------------------------------------------------- |
| **Compute Viewer** (`roles/compute.viewer`)             | Read-only access to Compute Engine resources            |
| **Kubernetes Engine Viewer** (`roles/container.viewer`) | Read-only access to GKE clusters (if using GKE)         |
| **Logs Viewer** (`roles/logging.viewer`)                | Read audit logs for Cost Explorer                       |
| **Compute Admin** (`roles/compute.admin`)               | For Stateless IaC to create/update/delete resources     |
| **Kubernetes Engine Admin** (`roles/container.admin`)   | For Stateless IaC to manage GKE clusters (if using GKE) |

Choose read-only roles if you only need asset discovery and Cost Explorer. Add admin roles if you plan to use Stateless IaC.

6. Click **Continue** and then **Done**.
7. Note down the **Service Account Email** (e.g., `mechcloud-wif@your-project.iam.gserviceaccount.com`).

### Step 4: Create a Workload Identity Pool

1. Navigate to **IAM & Admin** -> **Workload Identity Federation**.
2. Click **Create Pool**.
3. Enter the following details:

| Field           | Value                                       |
| --------------- | ------------------------------------------- |
| **Name**        | `mechcloud-pool` (or any descriptive name)  |
| **Pool ID**     | `mechcloud-pool` (auto-generated from name) |
| **Description** | MechCloud OIDC federation pool              |

4. Click **Continue**.

### Step 5: Add an OIDC Provider to the Pool

1. On the **Add a provider to pool** page, select **OpenID Connect (OIDC)**.
2. Fill in the following details:

| Field             | Value                                                                            |
| ----------------- | -------------------------------------------------------------------------------- |
| **Provider name** | `mechcloud-idp` (or any descriptive name)                                        |
| **Provider ID**   | `mechcloud-idp` (auto-generated from name)                                       |
| **Issuer (URL)**  | `https://id.mechcloud.io/`                                                       |
| **Audiences**     | Select **Allowed audiences** and enter your MechCloud audience value (see below) |

#### Finding Your Audience Value

1. Log in to [MechCloud Portal](https://portal.mechcloud.io).
2. Open a new browser tab and navigate to: `https://portal.mechcloud.io/oauth2/auth1`
3. This displays your JWT token. Decode it using [jwt.io](https://jwt.io) or similar tool.
4. Find the **aud** (Audience) claim — use this value for the **Allowed audiences** field (e.g., `n6dMQIo8ZCE5QxLY4o2KjeBaSn8eefTX`).
5. Click **Continue**.

### Step 6: Configure Provider Attributes

On the **Configure provider attributes** page, map the following attributes:

| Google Attribute | OIDC Attribute  |
| ---------------- | --------------- |
| `google.subject` | `assertion.sub` |

This maps the MechCloud user's subject claim to the Google identity.

Click **Save** to create the pool and provider.

### Step 7: Grant Service Account Access to the Pool

1. Navigate to **IAM & Admin** -> **Workload Identity Federation**.
2. Click on the pool you created (`mechcloud-pool`).
3. Click **Grant Access** at the top.
4. Select the service account you created in Step 3 (e.g., `mechcloud-wif@your-project.iam.gserviceaccount.com`).
5. Under **Select principals**, choose **Only identities matching the filter**.
6. Set the attribute condition to restrict access to your specific MechCloud user:

| Field               | Value                                                                |
| ------------------- | -------------------------------------------------------------------- |
| **Attribute name**  | `google.subject`                                                     |
| **Attribute value** | Your MechCloud `sub` claim (e.g., `auth0\|690895c8b0ac201506c31175`) |

#### Finding Your Subject Claim

Use the same JWT token from Step 5. Find the **sub** (Subject) claim — this is your unique MechCloud user identifier.

**(IMPORTANT)** This condition ensures that only your specific MechCloud user can impersonate the service account. Without this condition, any authenticated MechCloud user who knows your project details could access your GCP resources.

7. Click **Save**.
8. A panel will appear showing the **Workload Identity Pool Provider** resource name. It will look like:

```
projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/mechcloud-pool/providers/mechcloud-idp
```

Note down this full provider resource name — you'll need it when adding the account in MechCloud.

**Tip**: You can also find this value later by navigating to **IAM & Admin** -> **Workload Identity Federation** -> click on your pool -> click on your provider -> copy the **Default audience** or **Resource name** value.

### Step 8: Register Your GCP Account in MechCloud

1. Log on to [MechCloud](https://portal.mechcloud.io) and navigate to **Infrastructure** -> **Cloud Accounts**.
2. Select a team.
3. Select **GCP** under **Select a cloud provider** dropdown.
4. Click on **New Cloud Account** button.
5. Enter a name for your account.
6. Fill in the credentials:

| Field                               | Value                                   | Example                                                                                            |
| ----------------------------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------- |
| **Project Id**                      | Your GCP project ID                     | `my-project-123456`                                                                                |
| **Workload Identity Pool Provider** | Full provider resource name from Step 7 | `projects/123456789/locations/global/workloadIdentityPools/mechcloud-pool/providers/mechcloud-idp` |
| **Service Account Email**           | Service account email from Step 3       | `mechcloud-wif@my-project-123456.iam.gserviceaccount.com`                                          |

7. Click **Save** to add the cloud account.

### Verifying the Setup

After adding the account, you can verify the integration by:

1. Navigate to **Infrastructure** -> **Discover Assets**.
2. Select your GCP account and a region.
3. Click **Discover** — if the setup is correct, you should see your GCP resources listed.

### Troubleshooting

| Issue                        | Solution                                                                              |
| ---------------------------- | ------------------------------------------------------------------------------------- |
| **Permission denied** errors | Verify the service account has the required roles assigned in Step 3                  |
| **Token exchange failed**    | Check that the Issuer URL is exactly `https://id.mechcloud.io/` (with trailing slash) |
| **Audience mismatch**        | Verify the audience value matches your JWT token's `aud` claim                        |
| **Subject mismatch**         | Verify the attribute condition matches your JWT token's `sub` claim                   |
| **API not enabled**          | Ensure all required APIs from Step 2 are enabled in your project                      |