Maintaining custom roles with Deployment Manager

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.
Enable the 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 to BETA 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.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

Enable the Deployment Manager and IAM APIs.

Enable the 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.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

Enable the Deployment Manager and IAM APIs.

Enable the 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.

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 the manifest ID. Copy this ID, including the manifest- 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.

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: