iam-custom-roles.md

copyright	lastupdated	keywords	subcollection
years 2023, 2024	2024-10-09		metrics-router

{{site.data.keyword.attribute-definition-list}}

Managing custom roles

{: #custom-roles}

The {{site.data.keyword.metrics_router_full}} service maps different sets of actions to different platform roles. However, you might want to combine some of the actions that are currently spread across multiple roles to make assigning meet your custom use case. With a custom role, you can pick and choose actions that are mapped to different roles so that next time you assign access to the service, you don't have to select three different roles, for example. {: shortdesc}

You can create new roles that are scoped to the {{site.data.keyword.metrics_router_full_notm}} service. This means that you can't combine actions for two different services in a custom role, but you can combine as many actions that you want into a new role for a single service. After you create a custom role with a name of your choosing, anyone in the account who can assign access to the {{site.data.keyword.metrics_router_full_notm}} service can use that role when assigning access.

Permissions to manage custom roles

{: #required-access-role-management}

Anyone can view the pre-defined roles for the {{site.data.keyword.metrics_router_full_notm}} service in the account.

However, to view, create, edit, or delete a custom role, you must be assigned specific access for the IAM Access Management service and the resource type Role Management.

Action	Administrator	Operator	Editor	Viewer
View custom roles
Create custom roles
Update custom roles
Delete custom roles
{: caption="Actions for Role management service" caption-side="top"}

Creating custom roles in the console

{: #custom-access-roles} {: ui}

Complete the following steps:

1. In the {{site.data.keyword.cloud}} console, go to Manage > Access (IAM), and select Roles.

2. Click Create.

3. Enter a name for your role. This name must be unique within the account. Users see this role name in the console when they assign access to the service.

4. Enter an ID for the role. This ID is used in the CRN, which is used when assigning access by using the API. The role ID must begin with a capital letter and use alphanumeric characters only.

5. Optional: Enter a succinct and helpful description that helps the users who are assigning access know what level of access this role assignment gives a user. This description also shows in the console when a user assigns access to the service.

6. Select a service that you want to create the role for.

7. Review the available actions, and select Add for all actions that you want in your new role.

   You must add at least one service-defined action to successfully create the new role. If you aren't sure which actions are defined by the service, look in the Type column. {: important}

8. Click Create when you're done adding actions.

If a service removes an action that you use in a custom role, the custom role is not updated, and might not be valid anymore if the role contained only the removed actions. {: note}

If you plan to delete a custom role because it is no longer needed, you must be assigned the Administrator role. Deleting a custom role automatically updates access for any users, access groups, or service IDs assigned access by using that role to remove it from any existing policies.

Creating custom roles by using the CLI

{: #custom-access-roles-cli} {: cli}

Run the following command to create an authorization for the {{site.data.keyword.metrics_router_full_notm}} service.

ibmcloud iam role-create ROLE_NAME --display-name DISPLAY_NAME --service-name metrics-router [-a, --actions ROLE_ACTION1 [ROLE_ACTION2...]] [-d, --description DESCRIPTION] [--output FORMAT] [-q --quiet]

{: codeblock}

Where

--display-name DISPLAY_NAME : The display name of the role that is shown in the console.

--service-name SERVICE_NAME : The name of the service.

-a, --actions ROLE_ACTION1,ROLE_ACTION2... : The actions of the role. For more information, see IAM actions.

-d, --description DESCRIPTION : The description of the role.

For more information about all of the parameters that are available for this command, see ibmcloud iam authorization-policy-create.

For example, to create a demo custome role, you can run the following command:

Create a role to perform any Cloudant database action:

ibmcloud iam role-create demo --display-name "Demo custom role" --service-name metrics-router --actions metrics-router.target.create,metrics-router.target.list

{: codeblock}

Creating custom roles by using Terraform

{: #custom-access-roles-terraform} {: terraform}

Before you can create custom roles by using Terraform, make sure that you have completed the following:

• Install the Terraform CLI and configure the {{site.data.keyword.cloud_notm}} Provider plug-in for Terraform. For more information, see the tutorial for Getting started with Terraform on {{site.data.keyword.cloud}}. The plug-in abstracts the {{site.data.keyword.cloud_notm}} APIs that are used to complete this task.
• Create a Terraform configuration file that is named main.tf. In this file, you define resources by using HashiCorp Configuration Language. For more information, see the Terraform documentation{: external}.

Use the following steps to create custom roles:

1. Create an argument in your main.tf file. The following example creates a custom role by using the ibm_iam_custom_role resource, where name is a unique name to identify the custom role. You must add at least one service-defined action to successfully create the new role.

   resource "ibm_iam_custom_role" "customrole" {
    name         = "Role1"
    display_name = "Role1"
    description  = "This is a custom role"
    service = "metrics-router"
    actions      = ["metrics-router.target.list"]
   }

   {: codeblock}

   You can specify the name of the service for which you want to create the custom role on the service option. For more information, see the argument reference details on the Terraform Identity and Access Management (IAM){: external} page.

2. After you finish building your configuration file, initialize the Terraform CLI. For more information, see Initializing Working Directories{: external}.

   terraform init

   {: pre}

3. Provision the resources from the main.tf file. For more information, see Provisioning Infrastructure with Terraform{: external}.

   1. Run terraform plan to generate a Terraform execution plan to preview the proposed actions.

      terraform plan

      {: pre}

   2. Run terraform apply to create the resources that are defined in the plan.

      terraform apply

      {: pre}