Maintaining Custom Roles with Deployment Manager

Background

Google Cloud 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.

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

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 Platform 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 Platform 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 restrictions 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 Cloud 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 Cloud 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 Cloud 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:

  1. Sign in to your Google Account.

    If you don't already have one, sign up for a new account.

  2. Select or create a GCP project.

    Go to the Manage resources page

  3. Make sure that billing is enabled for your project.

    Learn how to enable billing

  4. Enable the Deployment Manager and Cloud IAM APIs.

    Enable the APIs

  5. Download and authenticate gcloud.

Once these prerequisite steps have been completed, you can start using Deployment Manager with Cloud 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.

  1. Open the IAM page in the Google Cloud Platform Console.
    Open the IAM page
  2. Click Select a project.
  3. Select a project and click Open.
  4. From the list of members, locate the member titled Google APIs service account.
  5. Click the Role(s) drop-down menu for the Google APIs service account, and then click the Roles > Role Administrator role.
  6. 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 Cloud 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 Inc. 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.

  1. Download the contents of this GitHub repository to your local machine.
  2. 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.
  3. Execute the following command to deploy the example custom role, replacing the [YOUR-DEPLOYMENT-NAME] placeholder value with your own:

    gcloud deployment-manager deployments create \
       [YOUR-DEPLOYMENT-NAME] --config project_custom_role.yaml
    

  4. 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.
    

  5. 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:

  1. In a terminal window, execute the following command:

    gcloud deployment-manager deployments describe [YOUR-DEPLOYMENT-NAME]
    

  2. 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: id-7201362145@my-example-project.iam.gserviceaccount.com
    NAME         TYPE                             STATE      INTENT
    custom-role  gcp-types/iam-v1:projects.roles  COMPLETED
    

  3. 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]
    

  4. 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 Platform Console:

  1. Open the IAM page in the Google Cloud Platform Console.
    Open the IAM page
  2. Click Select a project.
  3. Select a project and click Open.
  4. On the left menu, click Roles.
  5. Click the name of the newly created custom role from the list. It should look similar to the screenshot below:

Send feedback about...

Cloud Identity and Access Management Documentation