Create a custom role with narrowly-defined permissions for a project or organization scope. This role grants only the minimum access necessary to perform specific tasks, adhering to the principle of least privilege.
EXAMPLES
To create an organization-level custom role with specific permissions, run:
gdcloud iam roles create org-viewer --scope=organization --title="Organization Viewer" --description="Grants read-only access to storage buckets and compute instances at the organization level" --permissions=storageAdmin:compute:instances.get,storageAdmin:storage:buckets.list --stage=<BETA|GA|ALPHA>
To create a project-level custom role for deploying resources in specific project namespaces, run:
gdcloud iam roles create project-resource-manager --scope=project --title="Project Resource Manager" --description="Allows managing compute instances and disks within specific projects" --permissions=storageAdmin:compute:instances.get,storageAdmin:compute:disks.create --stage=<BETA|GA|ALPHA> --projects=project-id-1,project-id-2...
To create a project-level custom role applicable to all projects, run:
gdcloud iam roles create project-instance-operator --scope=project --title="Project Instance Operator" --description=""Grants permissions to start and stop compute instances across all projects" --permissions=admin:compute:instances.start,admin:compute:instances.stop --stage=<BETA|GA|ALPHA>
To create a custom role in a specific system namespace, run:
gdcloud iam roles create iam-role-manager --scope=organization --title="IAM Role Manager" --description="Allows creating and updating IAM roles" --permissions=iamAdmin:iam:roles:create,iamAdmin:iam:roles:update --stage=<BETA|GA|ALPHA> --namespace=<namespace-name>
To create a custom role from a YAML configuration file, run:
gdcloud iam roles create my_role --file=ROLE_FILE
REQUIRED FLAGS
--description string Description of the CustomRole custom resource.
--permissions iamRoleName:apiGroup:resource:verb A list of permissions granted to this CustomRole. Each permission must be specified in one of the following formats: iamRoleName:apiGroup:resource:verb (for resource that don't have individual name) or `iamRoleName:apiGroup:resource:resourceName:verb` (for resource with specific name). Wildcards (`*`) are explicitly prohibited in any part of the permission string (apiGroup, resource, verb, or resourceName) to enforce the principle of least privilege.
--title string Title of the CustomRole custom resource.
OPTIONAL FLAGS
--file string Path to a file containing YAML configuration for a CustomRole custom resource. If set, the gdcloud CLI creates the CustomRole from the YAML configuration and ignores the other flags. The YAML must include 'title', 'description', and 'permissions' (formatted as 'iamRoleName:apiGroup:resource:verb' or 'iamRoleName:apiGroup:resource:resourceName:verb', no wildcards). Optional fields: 'stage', 'scope', 'projects', 'namespace' (if applicable). These fields, if present, must follow the same format as their corresponding command-line flags.
--namespace string Namespace of the CustomRole custom resource, required only when defining permissions in organization scope.
--projects strings Comma-separated list of project IDs where the CustomRole will be applied. Required when the scope is 'project'; not applicable for 'organization' scope. Example: --projects=project-id-1,project-id-2,project-id-3
--scope string Scope of the CustomRole (organization or project). Use 'organization' for system-level permissions and 'project' for project-specific permissions. (default "organization")
--stage string Release stage of the CustomRole (ALPHA, BETA, or GA). (default "ALPHA")
GDCLOUD WIDE FLAGS
These flags are available to all commands: --configuration, --format, --help, --project, --quiet.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-25 UTC."],[[["\u003cp\u003eThe \u003ccode\u003egdcloud iam roles create\u003c/code\u003e command is used to define custom roles with specific permissions, tailored to either an organization or a project.\u003c/p\u003e\n"],["\u003cp\u003eRoles can be configured with a title, description, and a set of narrowly-defined permissions, adhering to the principle of least privilege.\u003c/p\u003e\n"],["\u003cp\u003eRoles can be created at an organizational or project level, with project-level roles potentially applying to a specific list of projects or all projects.\u003c/p\u003e\n"],["\u003cp\u003eYou can either specify role details directly through command-line flags or define a role using a YAML configuration file, offering flexibility in role definition.\u003c/p\u003e\n"],["\u003cp\u003eThe created roles can be set to a specific release stage (ALPHA, BETA, or GA) to manage the availability and maturity of the custom role.\u003c/p\u003e\n"]]],[],null,["# gdcloud iam roles create\n\nNAME\n----\n\ngdcloud iam roles create - Create a custom role.\n\nSYNOPSIS\n--------\n\n gdcloud iam roles create ROLE_NAME\n { --file=ROLE_FILE |\n --description=DESCRIPTION\n --title=TITLE\n [--scope=[PROJECT | ORGANIZATION]]\n [--permissions=[permissions1,...]]\n [--stage=[ALPHA | BETA | GA | DISABLED]]\n [--projects=[project1,...]]\n [--namespace=NAMESPACE]\n } [flags]\n\nDESCRIPTION\n-----------\n\nCreate a custom role with narrowly-defined permissions for a project or organization scope. This role grants only the minimum access necessary to perform specific tasks, adhering to the principle of least privilege.\n\n### EXAMPLES\n\n\n To create an organization-level custom role with specific permissions, run:\n\n gdcloud iam roles create org-viewer --scope=organization --title=\"Organization Viewer\" --description=\"Grants read-only access to storage buckets and compute instances at the organization level\" --permissions=storageAdmin:compute:instances.get,storageAdmin:storage:buckets.list --stage=\u003cBETA|GA|ALPHA\u003e\n\n To create a project-level custom role for deploying resources in specific project namespaces, run:\n\n gdcloud iam roles create project-resource-manager --scope=project --title=\"Project Resource Manager\" --description=\"Allows managing compute instances and disks within specific projects\" --permissions=storageAdmin:compute:instances.get,storageAdmin:compute:disks.create --stage=\u003cBETA|GA|ALPHA\u003e --projects=project-id-1,project-id-2...\n\n To create a project-level custom role applicable to all projects, run:\n\n gdcloud iam roles create project-instance-operator --scope=project --title=\"Project Instance Operator\" --description=\"\"Grants permissions to start and stop compute instances across all projects\" --permissions=admin:compute:instances.start,admin:compute:instances.stop --stage=\u003cBETA|GA|ALPHA\u003e\n\n To create a custom role in a specific system namespace, run:\n\n gdcloud iam roles create iam-role-manager --scope=organization --title=\"IAM Role Manager\" --description=\"Allows creating and updating IAM roles\" --permissions=iamAdmin:iam:roles:create,iamAdmin:iam:roles:update --stage=\u003cBETA|GA|ALPHA\u003e --namespace=\u003cnamespace-name\u003e\n\n To create a custom role from a YAML configuration file, run:\n\n gdcloud iam roles create my_role --file=ROLE_FILE\n\n### REQUIRED FLAGS\n\n --description string Description of the CustomRole custom resource.\n --permissions iamRoleName:apiGroup:resource:verb A list of permissions granted to this CustomRole. Each permission must be specified in one of the following formats: iamRoleName:apiGroup:resource:verb (for resource that don't have individual name) or `iamRoleName:apiGroup:resource:resourceName:verb` (for resource with specific name). Wildcards (`*`) are explicitly prohibited in any part of the permission string (apiGroup, resource, verb, or resourceName) to enforce the principle of least privilege.\n --title string Title of the CustomRole custom resource.\n\n### OPTIONAL FLAGS\n\n --file string Path to a file containing YAML configuration for a CustomRole custom resource. If set, the gdcloud CLI creates the CustomRole from the YAML configuration and ignores the other flags. The YAML must include 'title', 'description', and 'permissions' (formatted as 'iamRoleName:apiGroup:resource:verb' or 'iamRoleName:apiGroup:resource:resourceName:verb', no wildcards). Optional fields: 'stage', 'scope', 'projects', 'namespace' (if applicable). These fields, if present, must follow the same format as their corresponding command-line flags.\n --namespace string Namespace of the CustomRole custom resource, required only when defining permissions in organization scope.\n --projects strings Comma-separated list of project IDs where the CustomRole will be applied. Required when the scope is 'project'; not applicable for 'organization' scope. Example: --projects=project-id-1,project-id-2,project-id-3\n --scope string Scope of the CustomRole (organization or project). Use 'organization' for system-level permissions and 'project' for project-specific permissions. (default \"organization\")\n --stage string Release stage of the CustomRole (ALPHA, BETA, or GA). (default \"ALPHA\")\n\n### GDCLOUD WIDE FLAGS\n\nThese flags are available to all commands: `--configuration`, `--format`, `--help`, `--project`, `--quiet`.\n\nFor more information, see the [gdcloud CLI reference overview](/distributed-cloud/hosted/docs/latest/gdch/resources/gdcloud-reference/gdcloud) page."]]
