Background
Identity and Access Management custom roles enable you to grant granular permissions to user accounts and service accounts. Unlike predefined roles, which are maintained by Google and updated accordingly, custom roles are maintained by your organization as new permissions become available.
Cloud Deployment Manager can make it easier to configure and maintain your custom roles. You can use Deployment Manager to describe roles using configuration files, that can then be checked in to your source control system of choice. Together, Deployment Manager and source control can make it easier to make "config-as-code" for:
- Tracking custom roles as they change over time
- Promoting custom roles through launch stages as they are tested and validated
- Automating how roles are deployed throughout your organization
Before you begin
-
Enable the IAM and Cloud Deployment Manager APIs.
Scenarios for maintaining custom roles using Deployment Manager
Consider the following scenarios that demonstrate the benefits of using Deployment Manager to maintain custom roles:
- Controlling access to new permissions: You have a custom role that contains permissions for a Google Cloud service. The service adds new Beta features and exposes new permissions. Your custom role will not automatically inherit these new permissions -- they must be added manually. Until the new permissions are added to your custom role, users in your organization will not have access to the Beta features. You can use Deployment Manager's configuration files and source control to help audit existing permissions, update your custom roles as necessary, and maintain a revision history.
- Role lifecycle management: You have a new custom role to which you have
assigned an
ALPHA
launch stage. After the custom role has been tested and validated, you can use Deployment Manager to update the custom role's configuration and advance it toBETA
stage without using the Google Cloud console. - Understanding custom roles adoption: By having more of your organization's custom role definitions in source control, it makes it easier to share, learn from patterns of usage, and enforce access controls across multiple projects.
Understanding Deployment Manager configuration files
Deployment Manager uses three different file types to describe a deployment. Each type is described below:
- Configurations are YAML files that describe resources and their properties. For Identity and Access Management (IAM) custom roles, each YAML file specifies all of the properties for one or more custom roles, such as its name, description, and permissions.
- Schemas specify all possible properties for a given resource and their default values. For IAM custom roles, there are schemas for project-level and organization-level custom roles.
- Templates, which are Jinja or Python files that enhance configurations by allowing you to break down a configuration into reusable parts. For IAM custom roles, there are two provided templates: one for project-level custom roles, and one for organization-level custom roles.
For more information about these types, see Deployment Manager Fundamentals.
Before you begin
If you are unfamiliar with Deployment Manager, first complete the Quickstart. Then follow the steps below:- Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
-
Enable the Deployment Manager and IAM APIs.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
-
Enable the Deployment Manager and IAM APIs.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
Once these prerequisite steps have been completed, you can start using Deployment Manager with IAM to maintain your custom roles.
Grant permissions to the Google APIs service account
To maintain custom roles using Deployment Manager, you must first grant the appropriate permissions to the Google APIs service account. This account is created by default for each organization and project.
In the Google Cloud console, go to the IAM page.
From the list of principals, locate the principal with the name Google APIs service agent.
To edit the service account's roles, click the Edit
button, and then add the Roles > Role Administrator role.Click Save to apply the role.
Now that the Google APIs service account has been granted the permission to maintain custom roles, you can deploy a sample custom role using Deployment Manager.
Deploy custom roles to your project
As described in the section above, Deployment Manager uses a combination of configuration files to describe a deployment. For IAM, consider the following two example files for a project's custom roles:
project_custom_role.yaml
imports: - path: project_custom_role.jinja resources: - name: custom-role type: project_custom_role.jinja properties: roleId: myCustomRole title: My Title description: My description. includedPermissions: - iam.roles.get - iam.roles.list
This YAML file specifies the properties about a custom role named custom-role
,
which grants permissions to iam.roles.get
and iam.roles.list
.
Note that it references a .jinja file twice; these references use the values
provided by the Jinja template as described below.
project_custom_role.jinja
# Copyright 2017 Google LLC. All rights reserved. # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # http://www.apache.org/licenses/LICENSE-2.0 # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. resources: - name: custom-role type: gcp-types/iam-v1:projects.roles properties: parent: projects/{{ env["project"] }} roleId: {{ properties["roleId"] }} role: title: {{ properties["title"] }} description: {{ properties["description"] }} stage: {{ properties["stage"] }} includedPermissions: {{ properties["includedPermissions"] }}
This Jinja file provides a template for a custom role to minimize duplication of the same properties across many roles. Default values are inserted from a .schema file if the corresponding YAML file does not specify values for each property.
To deploy this custom role with Deployment Manager:
- Download the contents of this GitHub repository to your local machine.
- In a terminal window, navigate to the
examples/v2/iam_custom_role/jinja
directory in the downloaded repository. It contains the project_custom_role.yaml file and the associated Jinja files. Execute the following command to deploy the example custom role, replacing the your-deployment-name placeholder value with a deployment name of your choice:
gcloud deployment-manager deployments create \ your-deployment-name --config project_custom_role.yaml
Wait for the operation to complete. The deployment fingerprint and a progress indicator are shown:
The fingerprint of the deployment is PUo2fmKdoFdJqiLViHjT3Q== Waiting for create [operation-1513228867042-560460d157ad1-b4ababb8-c6a7dddc]...done.
If the operation was successful, you will see the following status message:
Create operation operation-1513228867042-560460d157ad1-b4ababb8-c6a7dddc completed successfully. NAME TYPE STATE ERRORS INTENT custom-role gcp-types/iam-v1:projects.roles COMPLETED []
View your deployed custom role
To view your custom role in Deployment Manager:
In a terminal window, execute the following command:
gcloud deployment-manager deployments describe your-deployment-name
You will see a description of the deployment, including comprehensive information about its status, any errors, and more.
fingerprint: oaJoGesEFYvsAldP2bm5jQ== id: '3222872306422524501' insertTime: '2018-01-29T13:40:10.822-08:00' manifest: manifest-1517262010855 name: your-deployment-name operation: endTime: '2018-01-29T13:40:26.500-08:00' name: operation-1517262010573-563f1172be0c9-ce5f0242-239fe1af operationType: insert progress: 100 startTime: '2018-01-29T13:40:11.535-08:00' status: DONE user: [email protected] NAME TYPE STATE INTENT custom-role gcp-types/iam-v1:projects.roles COMPLETED
You can also see the detailed information about the custom role's configuration by retrieving the deployment's manifest. In the output from the
describe
command in step 2 above, note themanifest
ID. Copy this ID, including themanifest-
prefix, and use it to replace the placeholder value below:gcloud deployment-manager manifests describe your-manifest-id \ --deployment your-deployment-name
The manifest contains exhaustive information about the custom role deployment, including the raw contents of the source project_custom_role.yaml and project_custom_role.jinja files. In particular, note the
resources
block near the bottom of the manifest, which summarizes the details about the custom role:... resources: - name: custom-role properties: description: My description. includedPermissions: - iam.roles.get - iam.roles.list roleId: aCustomRole stage: ALPHA title: My Title resources: - name: custom-role type: gcp-types/iam-v1:projects.roles type: project_custom_role.jinja ...
To view your custom role in the Google Cloud console:
In the Google Cloud console, go to the IAM page.
Select a project and click Open.
On the left menu, click Roles.
Click the name of the newly created custom role from the list. It should look similar to the screenshot below: