The recommended way to set up GCP as a meshPlatform is via the public terraform GCP meshPlatform Module. The steps below are not needed if you decide to use it.
Set up the Service Account for Replication
meshStack needs a well-defined set of permissions for its automation. meshStack is designed so that it does not require access to workload. We highly recommend that permissions are configured according to the "least privilege" principle.
Operators need to define a Custom IAM Role called
meshfed-service at the Organization Level with the following permissions
resourcemanager.folders.get resourcemanager.folders.list resourcemanager.organizations.get resourcemanager.projects.create resourcemanager.projects.get resourcemanager.projects.getIamPolicy resourcemanager.projects.list resourcemanager.projects.move resourcemanager.projects.setIamPolicy resourcemanager.projects.update resourcemanager.projects.createBillingAssignment resourcemanager.projects.deleteBillingAssignment billing.resourceAssociations.create serviceusage.services.enable serviceusage.services.get deploymentmanager.deployments.delete deploymentmanager.deployments.create deploymentmanager.deployments.update deploymentmanager.deployments.get
Configure the Root Project
meshStack requires a project in GCP for some of the resources it uses. It is reserved for use by meshstack and operators. For this guide, we’ll call the project
Enable the following APIs on the
meshstack-root project from the API Library
Create meshfed-service Service Account
meshfed-service Service Account in the
- Enable the Service Account for “G Suite Domain-wide Delegation” and note the generated
- Generate and Download a Service Account Key
The Service Account will be identified by an email address like
Grant Resource Permissions
The Service Account will be used by meshStack to perform project replication. Operators thus need to grant it the permissions of the
meshfed-service IAM role on those folders of the GCP resource hierarchy
that make up the Landing Zones for client projects.
It's a best practice to segregate "user" and "infrastructure" projects in GCP using the resource hierarchy. By setting granular permissions (instead of organization-wide permissions) this can limit the access of meshStack's replicator to only the parts of the resource hierarchy that it needs to actively manage (principle of least privilege).
Grant Billing Account Permissions to the Service Account
In order to associate created projects with a Billing Account, the replicator needs to be granted the
billing.resourceAssociations.create permission on the Billing Account. This is best achieved by assigning the
meshfed-service IAM Role to the
meshfed-service Service Account on the Billing Account in the Billing Account's permissions.
Optional: Billing Account owned by a different organization
In order to use a billing account that is owned by a different organization the permissons for
meshfed-service user need to be adjusted.
Operators create a custom role
meshfed-billing-creator in the organization that owns the target billing account with the following permisson
meshfed-service user needs to be granted the
meshfed-billing-creator role in the organization that owns the target billing account.
Following the principle of least privilege, operators should remove the
billing.resourceAssociations.create permisson from the custom role
meshfed-service created in meshfed-service IAM Role.
Set up Cloud Identity
Authorize the Service Account
In order to perform certain group related administrative tasks the previously created
meshfed-service service account needs the "Groups Admin" role from the Admin Console (G Suite).
To authorize the Service Account via the Google Admin Console navigate to
@Account in the sidebar and then
Admin Roles -> Groups Admin and click
Assign Service Accounts. In the prompt that appears, enter the service account email, which looks like
You can alternatively authorize the Service Account via the Cloud Identity Groups API. Please find the instructions in for this in the official Google guide.
Set up the Service Account for Metering
meshStack needs a separate service account to provide metering functionality. Create a new service account
assign it the following predefined roles:
roles/bigquery.jobUser (on the project of the ServiceAccount) roles/bigquery.dataViewer (on the project that holds the bigquery billing/carbon export dataset)
To enable meshStack to periodically collect active projects, create an IAM role with the following permissions and assign it to the service account.
resourcemanager.folders.get resourcemanager.folders.list resourcemanager.projects.get resourcemanager.projects.list
Set up GCP Billing data export
Complete the GCP instructions to set up Cloud Billing data export to BigQuery. We recommend using the "standard usage cost data" export with meshStack.
Once billing export has been setup as explained in the GCP documentation linked above, set up the
kraken-service service account with
access to the exported billing dataset. You can set up this permission either on the project containing the dataset
or directly on the dataset itself.
Optional: Provide a custom BigQuery table
Beyond the default BigQuery Billing Export, meshStack can also support custom BigQuery tables. You might want to apply some custom transformations or logic on the data. As long as the view or table is given in the same format as the default BigQuery Billing Export, meshStack can handle and process the data.
Below, the columns are listed that are required by meshStack, and in which format. Make sure that the data types are the same as the default export.
- Partition Time*
*Since BigQuery doesn't allow column names that start with an underscore character, you have to map the
column to a different name (see example query below). This column name has to be configured in the platform configuration
under 'Partition Time Column'.
Make sure that the
kraken-service service account has permission on the table or view as described above.
Then, enter the BigQuery reference in the GCP meshPlatform configuration in meshStack, which you can find under
'Metering Configuration' -> 'BigQuery Table'.
Example: multiple billing accounts for the same GCP organization
There can be situations where you want the projects inside a single GCP meshPlatform to be associated with multiple billing accounts. One such example is when you have one billing account which has Spend-based committed use discounts applied and another billing account which contains free credit applied. To ensure that meshStack collects data from both the accounts, you can to create a view in BigQuery which is a union of the two billing data exports from the two billing accounts. Such a union can be created with a query which looks similar to the following.
(SELECT _PARTITIONTIME as PARTITIONTIME, billing_account_id,service, sku, STRUCT(project.id as id, project.ancestry_numbers as ancestry_numbers) as project, labels, system_labels, location, cost, currency, usage, credits, invoice, cost_type, adjustment_info from `project-name-root.billing_export.gcp_billing_export_general`) UNION ALL (SELECT _PARTITIONTIME as PARTITIONTIME,billing_account_id,service, sku, STRUCT(project.id as id, project.ancestry_numbers as ancestry_numbers) as project, labels, system_labels, location, cost, currency, usage, credits, invoice, cost_type, adjustment_info from `project-name.billing_export.gcp_billing_export_credit`)
Configure this view as mentioned in the section above and meshStack will start using this data for cost collection.
Optional: Filter billable projects from the export
The GCP platform configuration offers an "additional filter" setting. meshStack will include configured filters in the
WHERE clause of its query to read billing data from the export table. This enables scenarios like excluding projects
under a certain part of the organizational hiearchy from meshStack.
The following example excludes all projects nested underneath folder
123456789 in your resource hierarchy.
AND "123456789" IN UNNEST(SPLIT(project.ancestry_number, "/"))
Optional: Enable GCP Cloud Carbon Footprint Export
meshStack metering supports general environmental reports based on GCP Cloud Carbon Footprint data. To enable this feature,set up a big query data set containing the carbon footprint export data, see Export your carbon footprint on the GCP documentation.
Then enable the
kraken-service service account to read this dataset.
Finally configure the table id containing the exported carbon data in the meshPlatform configuration.
Setting up GCP Big Query Transfer configuration will execute the transfer job on behalf of the user setting up the transfer config. The user must therefore grant permission to the big query service to access their account. This is a limitation of the big query data transfer service authorization model.
Optional: Enable Audit Logs for meshfed-service User
The actions of the
meshfed-service User can be monitored via Audit Logs. This allows an in-depth view meshStack activities for GCP project at any moment.
Enable Audit Logs
Enabling Audit Logs may incur charges.
meshcloud recommends to enable Audit Logs on the organizational level for monitoring
meshfed-service User. This is achivied by following these steps:
- Navigate to the organizational level in GCP Cloud Console
- Navigate to IAM & Admin --> Audit logs
- Filter the table for
Cloud Resource Manager APIand select the resulting entry
- Enable all log types
You may want to check the official Google instructions on enabling Auit Logs for further information.
The below screen shot show how to set up the Audit Logs for the organization
Query Audit Logs in Google Cloud Console
Please consult Google docs for options to querying Audit Logs.