Custom roles creation in GCP - Commands & Configuration

Introduction

Sometimes, the default permissions in cloud services are too broad or too narrow. Custom roles let you create a set of permissions tailored exactly to what your team or app needs, improving security and control.

When you want to give a developer access to only specific actions in your cloud project without full admin rights

When a team needs permission to manage only certain resources, like storage buckets but not compute instances

When you want to limit a service account’s permissions to just what it needs to run a specific job

When you want to follow the principle of least privilege by avoiding overly broad default roles

When you want to audit and control exactly what actions are allowed in your cloud environment

Config File - custom_role.yaml

custom_role.yaml

title: Custom Storage Viewer
description: Custom role to view storage buckets and objects
stage: GA
includedPermissions:
  - storage.buckets.get
  - storage.buckets.list
  - storage.objects.get
  - storage.objects.list

This YAML file defines a custom role named 'Custom Storage Viewer'.

title: The name of the role.

description: Explains what the role is for.

stage: The release stage of the role, here 'GA' means generally available.

includedPermissions: Lists the exact permissions this role grants, here for viewing storage buckets and objects.

Commands

This command creates a new custom role named 'customStorageViewer' in the project 'my-gcp-project' using the permissions defined in the 'custom_role.yaml' file.

Terminal

gcloud iam roles create customStorageViewer --project=my-gcp-project --file=custom_role.yaml

Expected Output

Created role [projects/my-gcp-project/roles/customStorageViewer].

→

--project - Specifies the GCP project where the custom role is created.

→

--file - Points to the YAML file that defines the custom role permissions.

This command shows the details of the custom role 'customStorageViewer' to verify it was created correctly.

Terminal

gcloud iam roles describe customStorageViewer --project=my-gcp-project

Expected Output

name: projects/my-gcp-project/roles/customStorageViewer

title: Custom Storage Viewer

description: Custom role to view storage buckets and objects

stage: GA

includedPermissions:

- storage.buckets.get

- storage.buckets.list

- storage.objects.get

- storage.objects.list

→

--project - Specifies the project where the role exists.

This command assigns the custom role 'customStorageViewer' to the user '[e-mail]' in the project, giving her the permissions defined in the role.

Terminal

gcloud projects add-iam-policy-binding my-gcp-project --member=user:[e-mail] --role=projects/my-gcp-project/roles/customStorageViewer

Expected Output

Updated IAM policy for project [my-gcp-project].

→

--member - Specifies the user or service account to assign the role.

→

--role - Specifies the full name of the custom role to assign.

This command retrieves the current IAM policy for the project to confirm the custom role assignment.

Terminal

gcloud projects get-iam-policy my-gcp-project

Expected Output

bindings:

- members:

  - user:[e-mail]

  role: projects/my-gcp-project/roles/customStorageViewer

etag: BwWWja0YfJA=

version: 1

Key Concept

If you remember nothing else from this pattern, remember: custom roles let you give exactly the permissions needed, no more and no less.

Common Mistakes

Trying to create a custom role without specifying the project flag

The command will fail or create the role in the wrong project, causing confusion or errors.

Always include the --project flag with your project ID when creating or managing custom roles.

Assigning a custom role without using the full role name including the project path

The assignment will fail because the role name is incomplete and not recognized.

Use the full role name format: projects/PROJECT_ID/roles/ROLE_NAME when assigning custom roles.

Including permissions in the YAML file that do not exist or are misspelled

The role creation will fail with an error about invalid permissions.

Check the exact permission names in the GCP documentation before adding them to the role definition.

Summary

Create a custom role by defining permissions in a YAML file and running gcloud iam roles create.

Verify the role details with gcloud iam roles describe to ensure correct permissions.

Assign the custom role to users or service accounts with gcloud projects add-iam-policy-binding.

Check the IAM policy with gcloud projects get-iam-policy to confirm role assignments.