Resource Manager | IBM Cloud API Docs

Introduction

Last updated: 2021-10-19

Quickly assign users access to more than one resource at a time by creating and updating resource groups with the IBM Cloud® Resource Manager API. You can delete any resource group only if it doesn't contain any resources, and it isn't the default resource group. When a user creates an account, a default resource group is created in the account. All IBM Cloud resources must be provisioned within a resource group. If an account is suspended, the corresponding resource group and all resources within it are also suspended.

In a Lite account, a user can have only one resource group. For a Pay-As-You-Go or Subscription account, a user can create more than one resource group.

To create resource instances within resource groups, see the IBM Cloud® Resource Controller API.

SDKs for Java, Node, Python, and Go are available to make it easier to programmatically access the API from your code. The client libraries that are provided by the SDKs implement best practices for using the API and reduce the amount of code that you need to write. The tab for each language includes code examples that demonstrate how to use the client libraries. For more information about using the SDKs, see the IBM Cloud SDK Common project on GitHub.

Installing the Java SDK

Maven

<dependency>
    <groupId>com.ibm.cloud</groupId>
    <artifactId>resource-manager</artifactId>
    <version>{version}</version>
</dependency>

Gradle

compile 'com.ibm.cloud:resource-manager:{version}'

View on GitHub https://github.com/IBM/platform-services-java-sdk

Installing the Go SDK

Go modules (recommended): Add the following import in your code, and then run go build or go mod tidy

import (
	"github.com/IBM/platform-services-go-sdk/resourcemanagerv2"
)

Go get

go get -u github.com/IBM/platform-services-go-sdk/resourcemanagerv2

View on GitHub https://github.com/IBM/platform-services-go-sdk

Installing the Node SDK

npm install @ibm-cloud/platform-services

View on GitHub https://github.com/IBM/platform-services-node-sdk

Installing the Python SDK

pip install --upgrade ibm-platform-services

View on GitHub https://github.com/IBM/platform-services-python-sdk

Endpoint URLs

The Resource Manager API uses the following global endpoint URL for all regions. When you call the API, add the path for each method to form the complete API endpoint for your requests.

https://resource-controller.cloud.ibm.com

If you enabled service endpoints in your account, you can send API requests over the IBM Cloud private network at the following base endpoint URLs. For more information, see Enabling VRF and service endpoints.

Private endpoint URL for VPC infrastructure: https://private.resource-controller.cloud.ibm.com
Private endpoint URLs for classic infrastructure:
- Dallas: https://private.us-south.resource-controller.cloud.ibm.com
- Washington DC: https://private.us-east.resource-controller.cloud.ibm.com

Example API request

curl -X {request_method} "https://resource-controller.cloud.ibm.com/{method_endpoint}"

Replace {request_method} and {method_endpoint} in this example with the values for your particular API call.

Authentication

Authorization to the Resource Manager API is enforced by using an IBM Cloud Identity and Access Management (IAM) access token. The token is used to determine the actions that a user or service ID has access to when they use the API.

Obtaining an IAM token for an authenticated user or service ID is described in the IAM Identity Services API documentation.

To use the API, add a valid IAM token to the HTTP Authorization request header, for example, -H 'Authorization: Bearer <TOKEN>'.

When you use the SDK, configure an IAM authenticator with the IAM API key. The authenticator automatically obtains the IAM access token for the API key and includes it with each request. You can construct an authenticator in either of two ways:

Programmatically by constructing an IAM authenticator instance and supplying your IAM API key
By defining the API key in external configuration properties and then using the SDK authenticator factory to construct an IAM authenticator that uses the configured IAM API key

In this example of using external configuration properties, an IAM authenticator instance is created with the configured API key, and then the service client is constructed with this authenticator instance and the configured service URL.

For more information, see the Authentication section of the IBM Cloud SDK Common documentation.

To call each method, you'll need to be assigned a role that includes the required IAM actions. Each method lists the associated action. For more information about IAM actions and how they map to roles, see Assigning access to account management services.

To retrieve your access token:

curl -X POST   "https://iam.test.cloud.ibm.com/identity/token"   --header 'Content-Type: application/x-www-form-urlencoded'   --header 'Accept: application/json'   --data-urlencode 'grant_type=urn:ibm:params:oauth:grant-type:apikey'   --data-urlencode 'apikey=<API_KEY>'

Replace <API_KEY> with your IAM API key.

Setting client options through external configuration

Example environment variables, where <SERVICE_URL> is the endpoint URL and <API_KEY> is your IAM API key

export RESOURCE_MANAGER_URL=<SERVICE_URL>
export RESOURCE_MANAGER_AUTHTYPE=iam
export RESOURCE_MANAGER_APIKEY=<API_KEY>

Example of constructing the service client

import {
    "github.com/IBM/platform-services-go-sdk/resourcemanagerv2"
}
...
serviceClientOptions := &resourcemanagerv2.ResourceManagerV2Options{}
serviceClient, err := resourcemanagerv2.NewResourceManagerV2UsingExternalConfig(serviceClientOptions)

For more authentication examples, check out the IBM Cloud SDK Common project on GitHub.

Setting client options through external configuration

Example environment variables, where <SERVICE_URL> is the endpoint URL and <API_KEY> is your IAM API key

export RESOURCE_MANAGER_URL=<SERVICE_URL>
export RESOURCE_MANAGER_AUTHTYPE=iam
export RESOURCE_MANAGER_APIKEY=<API_KEY>

Example of constructing the service client

import com.ibm.cloud.platform_services.resource_manager.v2.ResourceManager;
...
ResourceManager serviceClient = ResourceManager.newInstance();

For more authentication examples, check out the IBM Cloud SDK Common project on GitHub.

Setting client options through external configuration

Example environment variables, where <SERVICE_URL> is the endpoint URL and <API_KEY> is your IAM API key

export RESOURCE_MANAGER_URL=<SERVICE_URL>
export RESOURCE_MANAGER_AUTHTYPE=iam
export RESOURCE_MANAGER_APIKEY=<API_KEY>

Example of constructing the service client

const ResourceManagerV2 = require('@ibm-cloud/platform-services/resource-manager/v2');
...
const serviceClient = ResourceManagerV2.newInstance({});

For more authentication examples, check out the IBM Cloud SDK Common project on GitHub.

Setting client options through external configuration

Example environment variables, where <SERVICE_URL> is the endpoint URL and <API_KEY> is your IAM API key

export RESOURCE_MANAGER_URL=<SERVICE_URL>
export RESOURCE_MANAGER_AUTHTYPE=iam
export RESOURCE_MANAGER_APIKEY=<API_KEY>

Example of constructing the service client

from ibm_platform_services import ResourceManagerV2
...
service_client = ResourceManagerV2.new_instance()

For more authentication examples, check out the IBM Cloud SDK Common project on GitHub.

Auditing

You can monitor API activity within your account by using the IBM Cloud Activity Tracker service. When an API method is called, an event is generated that you can then track and audit from within Activity Tracker. For methods that generate these events, the specific event type is listed with each individual method.

For more information about how to track Account and Billing activity, see Auditing events for account management.

Error handling

This API uses standard HTTP response codes to indicate whether a method completed successfully. A 200 response indicates success. A 400 type response indicates a failure, and a 500 type response indicates an internal system error.

HTTP Error Code	Description	Recovery
`200`	Success	The request was successful.
`201`	Success	The resource group was successfully created.
`400`	Bad Request	The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request.
`401`	Unauthorized	You are not authorized to make this request. Log in to IBM Cloud and try again. If this error persists, contact the account owner to check your permissions.
`403`	Forbidden	The supplied authentication is not authorized to access '{namespace}'.
`404`	Not Found	The requested resource cannot be found.
`410`	Gone	The resource is valid but has been removed already in a previous call
`500`	Internal Server Error	offering_name is currently unavailable. Your request cannot not be processed. Wait a few minutes and try again.

Rate limiting

Rate limits for API requests are enforced on a per-caller basis. If the number of requests for a particular method and endpoint reaches the request limit within the specified time window, no further requests are accepted until the timer expires. After the timer expires, a new time window begins with the next accepted request.

The response to each HTTP request includes headers that you can use to determine whether you are close to the rate limit:

X-RateLimit-Reset: The time the current timer expires (in UNIX epoch time)
X-RateLimit-Remaining: The number of requests that remain in the current time window
X-RateLimit-Limit: The total number of requests that are allowed within the time window

An HTTP status code of 429 indicates that the rate limit was exceeded.

Currently, the rate of allowed requests for all resource manager APIs is 500 requests per 10 seconds.

See the following related APIs for more actions for service and resource management.

Call this method to retrieve information about all resource groups and associated quotas in an account. The id returned in the response can be used to create a resource instance later. The response can be filtered based on queryParams such as account_id, name, default, and more to narrow your search.Users need to be assigned IAM policies with the Viewer role or higher on the targeted resource groups.

GET /v2/resource_groups

(resourceManager *ResourceManagerV2) ListResourceGroups(listResourceGroupsOptions *ListResourceGroupsOptions) (result *ResourceGroupList, response *core.DetailedResponse, err error)

(resourceManager *ResourceManagerV2) ListResourceGroupsWithContext(ctx context.Context, listResourceGroupsOptions *ListResourceGroupsOptions) (result *ResourceGroupList, response *core.DetailedResponse, err error)

ServiceCall<ResourceGroupList> listResourceGroups(ListResourceGroupsOptions listResourceGroupsOptions)

listResourceGroups(params)

list_resource_groups(self,
        *,
        account_id: str = None,
        date: str = None,
        name: str = None,
        default: bool = None,
        include_deleted: bool = None,
        **kwargs
    ) -> DetailedResponse

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

resource-controller.group.retrieve

Request

Instantiate the ListResourceGroupsOptions struct and set the fields to provide parameter values for the ListResourceGroups method.

Use the ListResourceGroupsOptions.Builder to create a ListResourceGroupsOptions object that contains the parameter values for the listResourceGroups method.

Query Parameters

account_id
string
The ID of the account that contains the resource groups that you want to get.
date
string
The date in the format of YYYY-MM which returns resource groups. Deleted resource groups will be excluded before this month.
name
string
The name of the resource group.
default
boolean
Boolean value to specify whether or not to list default resource groups.
include_deleted
boolean
Boolean value to specify whether or not to list deleted resource groups.

parameter

WithContext method only

ListResourceGroupsOptions

The ListResourceGroups options.

ListResourceGroupsOptions

The listResourceGroups options.

parameters

accountId
string
The ID of the account that contains the resource groups that you want to get.
date
string
The date in the format of YYYY-MM which returns resource groups. Deleted resource groups will be excluded before this month.
name
string
The name of the resource group.
_default
boolean
Boolean value to specify whether or not to list default resource groups.
includeDeleted
boolean
Boolean value to specify whether or not to list default resource groups.

parameters

account_id
str
The ID of the account that contains the resource groups that you want to get.
date
str
The date in the format of YYYY-MM which returns resource groups. Deleted resource groups will be excluded before this month.
name
str
The name of the resource group.
default
bool
Boolean value to specify whether or not to list default resource groups.
include_deleted
bool
Boolean value to specify whether or not to list default resource groups.

Example request

curl -X GET   https://resource-controller.cloud.ibm.com/v2/resource_groups?account_id=987d4cfd77b04e9b9e1a6asdcc861234&date=2019-09&name=test   -H 'Authorization: Bearer <IAM_TOKEN>'

Example request

listResourceGroupsOptions := resourceManagerService.NewListResourceGroupsOptions()
listResourceGroupsOptions.SetAccountID(exampleUserAccountID)
listResourceGroupsOptions.SetIncludeDeleted(true)

resourceGroupList, response, err := resourceManagerService.ListResourceGroups(listResourceGroupsOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(resourceGroupList, "", "  ")
fmt.Println(string(b))

Example request

ListResourceGroupsOptions listResourceGroupsOptions = new ListResourceGroupsOptions.Builder()
        .accountId(exampleUserAccountId)
        .includeDeleted(true)
        .build();

Response<ResourceGroupList> response = resourceManagerService.listResourceGroups(listResourceGroupsOptions).execute();
ResourceGroupList resourceGroupList = response.getResult();

System.out.println(resourceGroupList);

Example request

const params = {
  accountId: exampleUserAccountId,
  includeDeleted: true,
}

resourceManagerService.listResourceGroups(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err)
  });

Example request

resource_group_list = resource_manager_service.list_resource_groups(
  account_id=example_user_account_id,
  include_deleted=True,
).get_result()

print(json.dumps(resource_group_list, indent=2))

Response

Response Body

ResourceGroupList

A list of resource groups

ResourceGroupList

A list of resource groups.

ResourceGroupList

A list of resource groups.

ResourceGroupList

A list of resource groups.

ResourceGroupList

A list of resource groups.

Status Code

200
The resource groups was successfully retrieved.
400
The request could have invalid payload.
401
Your access token is invalid or authentication of your token failed.
403
Your access token is valid but does not have the necessary permissions to access this resource.
404
The resource could not be found.
429
Too many requests. Please wait a few minutes and try again.
500
Your request could not be processed. Please try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

Example responses

Status 200

{
  "resources": [
    {
      "id": "fee82deba12e4c0fb69c3b09d1f12345",
      "crn": "crn:v1:bluemix:public:resource-controller::a/987d4cfd77b04e9b9e1a6asdcc861234::resource-group:fee82deba12e4c0fb69c3b09d1f12345",
      "account_id": "987d4cfd77b04e9b9e1a6asdcc861234",
      "name": "test",
      "state": "ACTIVE",
      "default": false,
      "quota_id": "a3d7b8d01e261c24677937c29ab33f3c",
      "quota_url": "/v2/quota_definitions/a3d7b8d01e261c24677937c29ab33f3c",
      "payment_methods_url": "/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345/payment_methods",
      "resource_linkages": [],
      "teams_url": "/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345/teams",
      "created_at": "2019-03-04T17:30:33.826Z",
      "updated_at": "2019-03-04T17:30:33.826Z"
    }
  ]
}

Success example

{
  "resources": [
    {
      "id": "fee82deba12e4c0fb69c3b09d1f12345",
      "crn": "crn:v1:bluemix:public:resource-controller::a/987d4cfd77b04e9b9e1a6asdcc861234::resource-group:fee82deba12e4c0fb69c3b09d1f12345",
      "account_id": "987d4cfd77b04e9b9e1a6asdcc861234",
      "name": "test",
      "state": "ACTIVE",
      "default": false,
      "quota_id": "a3d7b8d01e261c24677937c29ab33f3c",
      "quota_url": "/v2/quota_definitions/a3d7b8d01e261c24677937c29ab33f3c",
      "payment_methods_url": "/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345/payment_methods",
      "resource_linkages": [],
      "teams_url": "/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345/teams",
      "created_at": "2019-03-04T17:30:33.826Z",
      "updated_at": "2019-03-04T17:30:33.826Z"
    }
  ]
}

Create a resource group in an account to organize your account resources in customizable groupings so that you can quickly assign users access to more than one resource at a time. To learn what makes a good resource group strategy, see Best practices for organizing resources. A default resource group is created when an account is created. If you have a Lite account or 30-day trial, you cannot create extra resource groups, but you can rename your default resource group. If you have a Pay-As-You-Go or Subscription account, you can create multiple resource groups. You must be assigned an IAM policy with the Administrator role on All Account Management services to create extra resource groups.

POST /v2/resource_groups

(resourceManager *ResourceManagerV2) CreateResourceGroup(createResourceGroupOptions *CreateResourceGroupOptions) (result *ResCreateResourceGroup, response *core.DetailedResponse, err error)

(resourceManager *ResourceManagerV2) CreateResourceGroupWithContext(ctx context.Context, createResourceGroupOptions *CreateResourceGroupOptions) (result *ResCreateResourceGroup, response *core.DetailedResponse, err error)

ServiceCall<ResCreateResourceGroup> createResourceGroup(CreateResourceGroupOptions createResourceGroupOptions)

createResourceGroup(params)

create_resource_group(self,
        *,
        name: str = None,
        account_id: str = None,
        **kwargs
    ) -> DetailedResponse

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

resource-controller.group.create

Request

Instantiate the CreateResourceGroupOptions struct and set the fields to provide parameter values for the CreateResourceGroup method.

Use the CreateResourceGroupOptions.Builder to create a CreateResourceGroupOptions object that contains the parameter values for the createResourceGroup method.

Request Body

ReqBodyResourceGroupPost

Request body for creating a resource group

parameter

WithContext method only

CreateResourceGroupOptions

The CreateResourceGroup options.

CreateResourceGroupOptions

The createResourceGroup options.

parameters

name
string
The new name of the resource group.

Examples:
value
_source
_lines
_html
accountId
string
The account id of the resource group.

Examples:
value
_source
_lines
_html

parameters

name
str
The new name of the resource group.

Examples:
value
_source
_lines
_html
account_id
str
The account id of the resource group.

Examples:
value
_source
_lines
_html

Example request

curl -X POST   https://resource-controller.cloud.ibm.com/v2/resource_groups   -H 'Authorization: Bearer <IAM_TOKEN>'
  -H 'Content-Type: application/json'     -d '{
      "account_id": "987d4cfd77b04e9b9e1a6asdcc861234",
      "name": "test"
    }'

Example request

createResourceGroupOptions := resourceManagerService.NewCreateResourceGroupOptions()
createResourceGroupOptions.SetAccountID(exampleUserAccountID)
createResourceGroupOptions.SetName("ExampleGroup")

resCreateResourceGroup, response, err := resourceManagerService.CreateResourceGroup(createResourceGroupOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(resCreateResourceGroup, "", "  ")
fmt.Println(string(b))

Example request

CreateResourceGroupOptions createResourceGroupOptions = new CreateResourceGroupOptions.Builder()
        .accountId(exampleUserAccountId)
        .name("ExampleGroup")
        .build();

Response<ResCreateResourceGroup> response = resourceManagerService.createResourceGroup(createResourceGroupOptions).execute();
ResCreateResourceGroup resCreateResourceGroup = response.getResult();

System.out.println(resCreateResourceGroup);

Example request

const params = {
  accountId: exampleUserAccountId,
  name: "ExampleGroup"
};

resourceManagerService.createResourceGroup(params)
  .then(res => {
    resourceGroupId = res.result.id;
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err)
  });

Example request

res_create_resource_group = resource_manager_service.create_resource_group(
  account_id=example_user_account_id,
  name='ExampleGroup',
).get_result()

print(json.dumps(res_create_resource_group, indent=2))

Response

Response Body

ResCreateResourceGroup

A newly-created resource group

ResCreateResourceGroup

A newly-created resource group.

ResCreateResourceGroup

A newly-created resource group.

ResCreateResourceGroup

A newly-created resource group.

ResCreateResourceGroup

A newly-created resource group.

Status Code

201
Resource group has been created.
400
The request could have invalid payload.
401
Your access token is invalid or authentication of your token failed.
403
Your access token is valid but does not have the necessary permissions to access this resource.
404
The resource could not be found.
429
Too many requests. Please wait a few minutes and try again.
500
Your request could not be processed. Please try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

Example responses

Status 201

{
  "id": "fee82deba12e4c0fb69c3b09d1f12345",
  "crn": "crn:v1:bluemix:public:resource-controller::a/987d4cfd77b04e9b9e1a6asdcc861234::resource-group:fee82deba12e4c0fb69c3b09d1f12345"
}

Success example

{
  "id": "fee82deba12e4c0fb69c3b09d1f12345",
  "crn": "crn:v1:bluemix:public:resource-controller::a/987d4cfd77b04e9b9e1a6asdcc861234::resource-group:fee82deba12e4c0fb69c3b09d1f12345"
}

Retrieve a resource group by alias ID. Call this method to get details about a particular resource group, like the name of the resource group, associated quotas, whether the state is active, the resource group ID and the CRN. The id returned in the response can be used to create a resource instance later. Users need to be assigned an IAM policy with the Viewer role or higher on the targeted resource group.

GET /v2/resource_groups/{id}

(resourceManager *ResourceManagerV2) GetResourceGroup(getResourceGroupOptions *GetResourceGroupOptions) (result *ResourceGroup, response *core.DetailedResponse, err error)

(resourceManager *ResourceManagerV2) GetResourceGroupWithContext(ctx context.Context, getResourceGroupOptions *GetResourceGroupOptions) (result *ResourceGroup, response *core.DetailedResponse, err error)

ServiceCall<ResourceGroup> getResourceGroup(GetResourceGroupOptions getResourceGroupOptions)

getResourceGroup(params)

get_resource_group(self,
        id: str,
        **kwargs
    ) -> DetailedResponse

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

resource-controller.group.retrieve

Request

Instantiate the GetResourceGroupOptions struct and set the fields to provide parameter values for the GetResourceGroup method.

Use the GetResourceGroupOptions.Builder to create a GetResourceGroupOptions object that contains the parameter values for the getResourceGroup method.

Path Parameters

id
Required*
string
The short or long ID of the alias.

parameter

WithContext method only

GetResourceGroupOptions

The GetResourceGroup options.

GetResourceGroupOptions

The getResourceGroup options.

parameters

id
Required*
string
The short or long ID of the alias.

parameters

id
Required*
str
The short or long ID of the alias.

Example request

curl -X GET   https://resource-controller.cloud.ibm.com/v2/resource_groups/09f8c1c0742c493f80baaf7835212345   -H 'Authorization: Bearer <IAM_TOKEN>'

Example request

getResourceGroupOptions := resourceManagerService.NewGetResourceGroupOptions(
  resourceGroupID,
)

resourceGroup, response, err := resourceManagerService.GetResourceGroup(getResourceGroupOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(resourceGroup, "", "  ")
fmt.Println(string(b))

Example request

GetResourceGroupOptions getResourceGroupOptions = new GetResourceGroupOptions.Builder()
  .id(resourceGroupId)
  .build();

Response<ResourceGroup> response = resourceManagerService.getResourceGroup(getResourceGroupOptions).execute();
ResourceGroup resourceGroup = response.getResult();

System.out.println(resourceGroup);

Example request

const params = {
  id: resourceGroupId,
};

resourceManagerService.getResourceGroup(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err)
  });

Example request

resource_group = resource_manager_service.get_resource_group(
  id=resource_group_id,
).get_result()

print(json.dumps(resource_group, indent=2))

Response

Response Body

ResourceGroup

A resource group

ResourceGroup

A resource group.

ResourceGroup

A resource group.

ResourceGroup

A resource group.

ResourceGroup

A resource group.

Status Code

200
200 OK
401
Your access token is invalid or authentication of your token failed.
403
Your access token is valid but does not have the necessary permissions to access this resource.
404
The resource could not be found.
429
Too many requests. Please wait a few minutes and try again.
500
Your request could not be processed. Please try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

Example responses

Status 200

{
  "id": "fee82deba12e4c0fb69c3b09d1f12345",
  "crn": "crn:v1:bluemix:public:resource-controller::a/987d4cfd77b04e9b9e1a6asdcc861234::resource-group:fee82deba12e4c0fb69c3b09d1f12345",
  "account_id": "987d4cfd77b04e9b9e1a6asdcc861234",
  "name": "test",
  "state": "ACTIVE",
  "default": false,
  "quota_id": "a3d7b8d01e261c24677937c29ab33f3c",
  "quota_url": "/v2/quota_definitions/a3d7b8d01e261c24677937c29ab33f3c",
  "payment_methods_url": "/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345/payment_methods",
  "resource_linkages": [],
  "teams_url": "/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345/teams",
  "created_at": "2019-03-04T17:30:33.826Z",
  "updated_at": "2019-03-04T17:30:33.826Z"
}

Success example

{
  "id": "fee82deba12e4c0fb69c3b09d1f12345",
  "crn": "crn:v1:bluemix:public:resource-controller::a/987d4cfd77b04e9b9e1a6asdcc861234::resource-group:fee82deba12e4c0fb69c3b09d1f12345",
  "account_id": "987d4cfd77b04e9b9e1a6asdcc861234",
  "name": "test",
  "state": "ACTIVE",
  "default": false,
  "quota_id": "a3d7b8d01e261c24677937c29ab33f3c",
  "quota_url": "/v2/quota_definitions/a3d7b8d01e261c24677937c29ab33f3c",
  "payment_methods_url": "/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345/payment_methods",
  "resource_linkages": [],
  "teams_url": "/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345/teams",
  "created_at": "2019-03-04T17:30:33.826Z",
  "updated_at": "2019-03-04T17:30:33.826Z"
}

Update a resource group by the alias ID. Call this method to update information about an existing resource group. You can rename a resource group and activate or suspend a particular resource group. To update a resource group, users need to be assigned with IAM policies with the Editor role or higher.

PATCH /v2/resource_groups/{id}

(resourceManager *ResourceManagerV2) UpdateResourceGroup(updateResourceGroupOptions *UpdateResourceGroupOptions) (result *ResourceGroup, response *core.DetailedResponse, err error)

(resourceManager *ResourceManagerV2) UpdateResourceGroupWithContext(ctx context.Context, updateResourceGroupOptions *UpdateResourceGroupOptions) (result *ResourceGroup, response *core.DetailedResponse, err error)

ServiceCall<ResourceGroup> updateResourceGroup(UpdateResourceGroupOptions updateResourceGroupOptions)

updateResourceGroup(params)

update_resource_group(self,
        id: str,
        *,
        name: str = None,
        state: str = None,
        **kwargs
    ) -> DetailedResponse

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

resource-controller.group.update

Request

Instantiate the UpdateResourceGroupOptions struct and set the fields to provide parameter values for the UpdateResourceGroup method.

Use the UpdateResourceGroupOptions.Builder to create a UpdateResourceGroupOptions object that contains the parameter values for the updateResourceGroup method.

Path Parameters

id
Required*
string
The short or long ID of the alias.

Request Body

ReqBodyResourceGroupPatch

Request body for updating a resource group

parameter

WithContext method only

UpdateResourceGroupOptions

The UpdateResourceGroup options.

UpdateResourceGroupOptions

The updateResourceGroup options.

parameters

id
Required*
string
The short or long ID of the alias.
name
string
The new name of the resource group.
state
string
The state of the resource group.

parameters

id
Required*
str
The short or long ID of the alias.
name
str
The new name of the resource group.
state
str
The state of the resource group.

Example request

curl -X PATCH   https://resource-controller.cloud.ibm.com/v2/resource_groups/09f8c1c0742c493f80baaf7835212345   -H 'Authorization: Bearer <IAM_TOKEN>'
  -H 'Content-Type: application/json'     -d '{
      "name": "test1"
    }'

Example request

updateResourceGroupOptions := resourceManagerService.NewUpdateResourceGroupOptions(
  resourceGroupID,
)
updateResourceGroupOptions.SetName("RenamedExampleGroup")
updateResourceGroupOptions.SetState("ACTIVE")

resourceGroup, response, err := resourceManagerService.UpdateResourceGroup(updateResourceGroupOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(resourceGroup, "", "  ")
fmt.Println(string(b))

Example request

UpdateResourceGroupOptions updateResourceGroupOptions = new UpdateResourceGroupOptions.Builder()
  .id(resourceGroupId)
  .name("RenamedExampleGroup")
  .state("ACTIVE")
  .build();

Response<ResourceGroup> response = resourceManagerService.updateResourceGroup(updateResourceGroupOptions).execute();
ResourceGroup resourceGroup = response.getResult();

System.out.println(resourceGroup);

Example request

const params = {
  id: resourceGroupId,
  state: 'ACTIVE',
  name: 'RenamedExampleGroup'
};

resourceManagerService.updateResourceGroup(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err)
  });

Example request

resource_group = resource_manager_service.update_resource_group(
  id=resource_group_id,
  name='RenamedExampleGroup',
  state='ACTIVE',
).get_result()

print(json.dumps(resource_group, indent=2))

Response

Response Body

ResourceGroup

A resource group

ResourceGroup

A resource group.

ResourceGroup

A resource group.

ResourceGroup

A resource group.

ResourceGroup

A resource group.

Status Code

200
Successfully updated resource group.
400
The request could have invalid payload.
401
Your access token is invalid or authentication of your token failed.
403
Your access token is valid but does not have the necessary permissions to access this resource.
404
The resource could not be found.
429
Too many requests. Please wait a few minutes and try again.
500
Your request could not be processed. Please try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

Example responses

Status 200

{
  "id": "fee82deba12e4c0fb69c3b09d1f12345",
  "crn": "crn:v1:bluemix:public:resource-controller::a/987d4cfd77b04e9b9e1a6asdcc861234::resource-group:fee82deba12e4c0fb69c3b09d1f12345",
  "account_id": "987d4cfd77b04e9b9e1a6asdcc861234",
  "name": "test1",
  "state": "ACTIVE",
  "default": false,
  "quota_id": "a3d7b8d01e261c24677937c29ab33f3c",
  "quota_url": "/v2/quota_definitions/a3d7b8d01e261c24677937c29ab33f3c",
  "payment_methods_url": "/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345/payment_methods",
  "resource_linkages": [],
  "teams_url": "/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345/teams",
  "created_at": "2019-03-04T17:30:33.826Z",
  "updated_at": "2019-03-04T17:30:33.826Z"
}

Success example

{
  "id": "fee82deba12e4c0fb69c3b09d1f12345",
  "crn": "crn:v1:bluemix:public:resource-controller::a/987d4cfd77b04e9b9e1a6asdcc861234::resource-group:fee82deba12e4c0fb69c3b09d1f12345",
  "account_id": "987d4cfd77b04e9b9e1a6asdcc861234",
  "name": "test1",
  "state": "ACTIVE",
  "default": false,
  "quota_id": "a3d7b8d01e261c24677937c29ab33f3c",
  "quota_url": "/v2/quota_definitions/a3d7b8d01e261c24677937c29ab33f3c",
  "payment_methods_url": "/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345/payment_methods",
  "resource_linkages": [],
  "teams_url": "/v2/resource_groups/fee82deba12e4c0fb69c3b09d1f12345/teams",
  "created_at": "2019-03-04T17:30:33.826Z",
  "updated_at": "2019-03-04T17:30:33.826Z"
}

Delete a resource group by the alias ID. You can delete a resource group only if the targeted resource group does not contain any resources or if it is not a default resource group. When a user creates an account, a default resource group is created in the account. If you want to delete a resource group that contains resources, first delete the resource instances. Then, delete the resource group when all resource instances in the group are deleted. Users need to be assigned an IAM policy with the Editor role or higher on the targeted resource group.

DELETE /v2/resource_groups/{id}

(resourceManager *ResourceManagerV2) DeleteResourceGroup(deleteResourceGroupOptions *DeleteResourceGroupOptions) (response *core.DetailedResponse, err error)

(resourceManager *ResourceManagerV2) DeleteResourceGroupWithContext(ctx context.Context, deleteResourceGroupOptions *DeleteResourceGroupOptions) (response *core.DetailedResponse, err error)

ServiceCall<Void> deleteResourceGroup(DeleteResourceGroupOptions deleteResourceGroupOptions)

deleteResourceGroup(params)

delete_resource_group(self,
        id: str,
        **kwargs
    ) -> DetailedResponse

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

resource-controller.group.delete

Request

Instantiate the DeleteResourceGroupOptions struct and set the fields to provide parameter values for the DeleteResourceGroup method.

Use the DeleteResourceGroupOptions.Builder to create a DeleteResourceGroupOptions object that contains the parameter values for the deleteResourceGroup method.

Path Parameters

id
Required*
string
The short or long ID of the alias.

parameter

WithContext method only

DeleteResourceGroupOptions

The DeleteResourceGroup options.

DeleteResourceGroupOptions

The deleteResourceGroup options.

parameters

id
Required*
string
The short or long ID of the alias.

parameters

id
Required*
str
The short or long ID of the alias.

Example request

curl -X DELETE   https://resource-controller.cloud.ibm.com/v2/resource_groups/09f8c1c0742c493f80baaf7835212345   -H 'Authorization: Bearer <IAM_TOKEN>'
  -H 'Content-Type: application/json'

Example request

deleteResourceGroupOptions := resourceManagerService.NewDeleteResourceGroupOptions(
  resourceGroupID,
)

response, err := deleteResourceManagerService.DeleteResourceGroup(deleteResourceGroupOptions)
if err != nil {
  panic(err)
}

Example request

DeleteResourceGroupOptions deleteResourceGroupOptions = new DeleteResourceGroupOptions.Builder()
        .id(resourceGroupId)
        .build();

deleteResourceManagerService.deleteResourceGroup(deleteResourceGroupOptions).execute();

Example request

const params = {
  id: resourceGroupId,
};

deleteResourceManagerService.deleteResourceGroup(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err)
  });

Example request

response = delete_resource_manager_service.delete_resource_group(
  id=resource_group_id,
).get_result()

print(json.dumps(response, indent=2))

Response

Status Code

204
The resource group is successfully deleted.
400
The request could have invalid payload.
401
Your access token is invalid or authentication of your token failed.
403
Your access token is valid but does not have the necessary permissions to access this resource.
404
The resource could not be found.
429
Too many requests. Please wait a few minutes and try again.
500
Your request could not be processed. Please try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

Get a list of all quota definitions. Quotas for a resource group limit the number of apps, instances, and memory allowed for that specific resource group. Each resource group that you have on your account has a specific set of quotas. Standard quotas are for resource groups that are created by users with a Lite account, and Pay-As-You-Go quotas are for resource groups that are created with a Pay-As-You-Go account. This method provides list of all available quota definitions. No specific IAM policy needed.

GET /v2/quota_definitions

(resourceManager *ResourceManagerV2) ListQuotaDefinitions(listQuotaDefinitionsOptions *ListQuotaDefinitionsOptions) (result *QuotaDefinitionList, response *core.DetailedResponse, err error)

(resourceManager *ResourceManagerV2) ListQuotaDefinitionsWithContext(ctx context.Context, listQuotaDefinitionsOptions *ListQuotaDefinitionsOptions) (result *QuotaDefinitionList, response *core.DetailedResponse, err error)

ServiceCall<QuotaDefinitionList> listQuotaDefinitions()

listQuotaDefinitions(params)

list_quota_definitions(self,
        **kwargs
    ) -> DetailedResponse

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

resource-controller.quota.retrieve

Request

No Request Parameters

This method does not accept any request parameters.

parameter

WithContext method only

No Request Parameters

This method does not accept any request parameters.

No Request Parameters

This method does not accept any request parameters.

No Request Parameters

This method does not accept any request parameters.

No Request Parameters

This method does not accept any request parameters.

Example request

curl -X GET https://resource-controller.cloud.ibm.com/v2/quota_definitions -H 'Authorization: Bearer <IAM_TOKEN>'

Example request

listQuotaDefinitionsOptions := resourceManagerService.NewListQuotaDefinitionsOptions()

quotaDefinitionList, response, err := resourceManagerService.ListQuotaDefinitions(listQuotaDefinitionsOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(quotaDefinitionList, "", "  ")
fmt.Println(string(b))

Example request

ListQuotaDefinitionsOptions listQuotaDefinitionsOptions = new ListQuotaDefinitionsOptions();

Response<QuotaDefinitionList> response = resourceManagerService.listQuotaDefinitions().execute();
QuotaDefinitionList quotaDefinitionList = response.getResult();

System.out.println(quotaDefinitionList);

Example request

resourceManagerService.listQuotaDefinitions({})
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err)
  });

Example request

quota_definition_list = resource_manager_service.list_quota_definitions().get_result()

print(json.dumps(quota_definition_list, indent=2))

Response

Response Body

QuotaDefinitionList

A list of quota definitions

QuotaDefinitionList

A list of quota definitions.

QuotaDefinitionList

A list of quota definitions.

QuotaDefinitionList

A list of quota definitions.

QuotaDefinitionList

A list of quota definitions.

Status Code

200
The quota definitions were successfully retrieved.
400
The request could have invalid payload.
401
Your access token is invalid or authentication of your token failed.
403
Your access token is valid but does not have the necessary permissions to access this resource.
404
The resource could not be found.
429
Too many requests. Please wait a few minutes and try again.
500
Your request could not be processed. Please try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

Example responses

Status 200

{
  "resources": [
    {
      "_id": "7ce89f4a-4381-4600-b814-3cd9a412345",
      "_rev": "14-e8384c02aac04afcc08ce7991234556",
      "name": "Trial Quota",
      "type": "SDQ",
      "number_of_service_instances": 1000,
      "number_of_apps": 4,
      "instances_per_app": 4,
      "instance_memory": "1G",
      "total_app_memory": "1G",
      "vsi_limit": 1,
      "resource_quotas": [
        {
          "_id": "65012f5b6fa84ecaaac5eab4abc12345",
          "resource_id": "rcf0c17db8-35ad-11e7-a919-92ebc1234567",
          "crn": "crn:v1:bluemix:public:resource-catalog::global:::rcf0c17db8-35ad-11e7-a919-92ebc1234567",
          "limit": 1
        }
      ],
      "created_at": "2017-05-16T17:12:52.925Z",
      "updated_at": "2019-01-09T17:12:52.925Z"
    }
  ]
}

Success example

{
  "resources": [
    {
      "_id": "7ce89f4a-4381-4600-b814-3cd9a412345",
      "_rev": "14-e8384c02aac04afcc08ce7991234556",
      "name": "Trial Quota",
      "type": "SDQ",
      "number_of_service_instances": 1000,
      "number_of_apps": 4,
      "instances_per_app": 4,
      "instance_memory": "1G",
      "total_app_memory": "1G",
      "vsi_limit": 1,
      "resource_quotas": [
        {
          "_id": "65012f5b6fa84ecaaac5eab4abc12345",
          "resource_id": "rcf0c17db8-35ad-11e7-a919-92ebc1234567",
          "crn": "crn:v1:bluemix:public:resource-catalog::global:::rcf0c17db8-35ad-11e7-a919-92ebc1234567",
          "limit": 1
        }
      ],
      "created_at": "2017-05-16T17:12:52.925Z",
      "updated_at": "2019-01-09T17:12:52.925Z"
    }
  ]
}

Call this method to retrieve information about a particular quota by passing the quota ID. The response can be used to identify the quota type, Standard or Paid. Information about available resources, such as number of apps, number of service instances, and memory, are returned in the response. Quotas for a resource group limit the number of apps, instances, and memory allowed for that specific resource group. Each resource group that you have on your account has a specific set of quotas. Standard quotas are for resource groups that are created by users with a Lite account, and Pay-As-You-Go quotas are for resource groups that are created with a Pay-As-You-Go account. No specific IAM policy needed.

GET /v2/quota_definitions/{id}

(resourceManager *ResourceManagerV2) GetQuotaDefinition(getQuotaDefinitionOptions *GetQuotaDefinitionOptions) (result *QuotaDefinition, response *core.DetailedResponse, err error)

(resourceManager *ResourceManagerV2) GetQuotaDefinitionWithContext(ctx context.Context, getQuotaDefinitionOptions *GetQuotaDefinitionOptions) (result *QuotaDefinition, response *core.DetailedResponse, err error)

ServiceCall<QuotaDefinition> getQuotaDefinition(GetQuotaDefinitionOptions getQuotaDefinitionOptions)

getQuotaDefinition(params)

get_quota_definition(self,
        id: str,
        **kwargs
    ) -> DetailedResponse

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action. You can check your access by going to Users > User > Access.

resource-controller.quota.retrieve

Request

Instantiate the GetQuotaDefinitionOptions struct and set the fields to provide parameter values for the GetQuotaDefinition method.

Use the GetQuotaDefinitionOptions.Builder to create a GetQuotaDefinitionOptions object that contains the parameter values for the getQuotaDefinition method.

Path Parameters

id
Required*
string
The id of the quota.

parameter

WithContext method only

GetQuotaDefinitionOptions

The GetQuotaDefinition options.

GetQuotaDefinitionOptions

The getQuotaDefinition options.

parameters

id
Required*
string
The id of the quota.

parameters

id
Required*
str
The id of the quota.

Example request

curl -X GET   https://resource-controller.cloud.ibm.com/v2/quota_definitions/7ce89f4a-4381-4600-b814-3cd9a4f12345   -H 'Authorization: Bearer <IAM_TOKEN>'

Example request

getQuotaDefinitionOptions := resourceManagerService.NewGetQuotaDefinitionOptions(
  exampleQuotaID,
)

quotaDefinition, response, err := resourceManagerService.GetQuotaDefinition(getQuotaDefinitionOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(quotaDefinition, "", "  ")
fmt.Println(string(b))

Example request

GetQuotaDefinitionOptions getQuotaDefinitionOptions = new GetQuotaDefinitionOptions.Builder()
  .id(exampleQuotaId)
  .build();

Response<QuotaDefinition> response = resourceManagerService.getQuotaDefinition(getQuotaDefinitionOptions).execute();
QuotaDefinition quotaDefinition = response.getResult();

System.out.println(quotaDefinition);

Example request

const params = {
  id: exampleQuotaId,
};

resourceManagerService.getQuotaDefinition(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err)
  });

Example request

quota_definition = resource_manager_service.get_quota_definition(
  id=example_quota_id,
).get_result()

print(json.dumps(quota_definition, indent=2))

Response

Response Body

QuotaDefinition

A returned quota definition

QuotaDefinition

A returned quota definition.

QuotaDefinition

A returned quota definition.

QuotaDefinition

A returned quota definition.

QuotaDefinition

A returned quota definition.

Status Code

200
The quota is successfully retrieved.
400
The request could have invalid payload.
401
Your access token is invalid or authentication of your token failed.
403
Your access token is valid but does not have the necessary permissions to access this resource.
404
The resource could not be found.
429
Too many requests. Please wait a few minutes and try again.
500
Your request could not be processed. Please try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

Example responses

Status 200

{
  "_id": "7ce89f4a-4381-4600-b814-3cd9a412345",
  "_rev": "14-e8384c02aac04afcc08ce7991234556",
  "name": "Trial Quota",
  "type": "SDQ",
  "number_of_service_instances": 1000,
  "number_of_apps": 4,
  "instances_per_app": 4,
  "instance_memory": "1G",
  "total_app_memory": "1G",
  "vsi_limit": 1,
  "resource_quotas": [
    {
      "_id": "65012f5b6fa84ecaaac5eab4abc12345",
      "resource_id": "rcf0c17db8-35ad-11e7-a919-92ebc1234567",
      "crn": "crn:v1:bluemix:public:resource-catalog::global:::rcf0c17db8-35ad-11e7-a919-92ebc1234567",
      "limit": 1
    }
  ],
  "created_at": "2017-05-16T17:12:52.925Z",
  "updated_at": "2019-01-09T17:12:52.925Z"
}

Success example

{
  "_id": "7ce89f4a-4381-4600-b814-3cd9a412345",
  "_rev": "14-e8384c02aac04afcc08ce7991234556",
  "name": "Trial Quota",
  "type": "SDQ",
  "number_of_service_instances": 1000,
  "number_of_apps": 4,
  "instances_per_app": 4,
  "instance_memory": "1G",
  "total_app_memory": "1G",
  "vsi_limit": 1,
  "resource_quotas": [
    {
      "_id": "65012f5b6fa84ecaaac5eab4abc12345",
      "resource_id": "rcf0c17db8-35ad-11e7-a919-92ebc1234567",
      "crn": "crn:v1:bluemix:public:resource-catalog::global:::rcf0c17db8-35ad-11e7-a919-92ebc1234567",
      "limit": 1
    }
  ],
  "created_at": "2017-05-16T17:12:52.925Z",
  "updated_at": "2019-01-09T17:12:52.925Z"
}

Introduction

Endpoint URLs

Authentication

Auditing

Error handling

Rate limiting

Related APIs

Methods

Get a list of all resource groups

Authorization

Request

Query Parameters

account_id

date

name

default

include_deleted

parameter

ctx

ListResourceGroupsOptions

AccountID

Date

Name

Default

IncludeDeleted

ListResourceGroupsOptions

accountId

date

name

xDefault

includeDeleted

parameters

accountId

date

name

_default

includeDeleted

parameters

account_id

date

name

default

include_deleted

Response

Response Body

resources

ResourceGroupList

Resources

ID

CRN

AccountID

Name

State

Default

QuotaID

QuotaURL

PaymentMethodsURL

ResourceLinkages

TeamsURL

CreatedAt

UpdatedAt

ResourceGroupList

resources

id

crn

accountId

name

state

xDefault

quotaId

quotaUrl

paymentMethodsUrl

resourceLinkages

teamsUrl

createdAt

updatedAt

ResourceGroupList

resources

id

crn