Resource Controller | IBM Cloud API Docs

Introduction

Last updated: 2025-01-21

The resource controller is the next-generation IBM Cloud® platform provisioning layer that manages the lifecycle of IBM Cloud resources in a customer account. A resource is an instance of a service like Cloudant, a Cloud Foundry application, a virtual machine, a container, a software image, or a data set.

The resource controller provides APIs to help you manage the following elements of your resource lifecycle:

Catalog management
Provisioning (creating an instance)
Updating a resource instance
Resource keys
De-provisioning (deleting an instance)
Dashboard SSO

Resources are provisioned globally in an account scope. The resource controller supports both synchronous and asynchronous provisioning of resources.

Resources are created by the resource controller within resource groups. A resource group belongs to an account. All IBM Cloud resources must be provisioned within a resource group. If an account is suspended, the corresponding resource group is suspended as well, and all resources within the resource group are suspended.

Installing the Java SDK

Maven

<dependency>
	<groupId>com.ibm.cloud</groupId>
	<artifactId>resource-controller</artifactId>
	<version>{version}</version>
</dependency>
Copy to clipboard

Gradle

'com.ibm.cloud:resource-controller:{version}'

Replace {version} in these examples with the release 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/resourcecontrollerv2"
)

Go get

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

View on GitHub

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

Installation

npm install @ibm-cloud/platform-services

For more installation options, view this project in GitHub. https://github.com/IBM/platform-services-node-sdk

Installation

pip install --upgrade "ibm-platform-services"

For more installation options, view this project in GitHub. https://github.com/IBM/platform-services-python-sdk

Resource instances

The resource controller can provision or create an instance. Provisioning reserves a resource on a service, and the reserved resource is a service instance. A resource instance can vary by service. Examples include a single database on a multi-tenant server, a dedicated cluster, or an account on a web application.

API endpoint

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

API endpoint

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

API endpoint

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

API endpoint

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

API endpoint

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

Using the SDK

With the Java SDK, you can build a service client for the Resource Controller by implementing the ResourceController class within the com.ibm.cloud.platform_services.resource_controller.v2 package. To construct the client, you can set your options programmatically, or you can define external configuration properties to be used by your application.

The examples that are provided on this page demonstrate how to build a service client by using these two options. For more information and detailed examples, check out the IBM Cloud SDK Common project on GitHub.

With the Go SDK, you can build a service client for the Resource Controller by implementing the ResourceControllerV2 class within the resourcecontrollerv2 package. To construct the client, you can set your options programmatically, or you can define external configuration properties to be used by your application.

The examples that are provided on this page demonstrate how to build a service client by using these two options. For more information and detailed examples, check out the IBM Cloud SDK Common project on GitHub.

With the Node.js SDK, you can build a service client for the Resource Controller by implementing the ResourceControllerV2 class within the resource-controller/v2 module. To construct the client, you can set your options programmatically, or you can define external configuration properties to be used by your application.

The examples that are provided on this page demonstrate how to build a service client by using these two options. For more information and detailed examples, check out the IBM Cloud SDK Common project on GitHub.

With the Python SDK, you can build a service client for the Resource Controller by implementing the ResourceControllerV2 class within the ibm-platform-services module. To construct the client, you can set your options programmatically, or you can define external configuration properties to be used by your application.

The examples that are provided on this page demonstrate how to build a service client by using these two options. For more information and detailed examples, check out the IBM Cloud SDK Common project on GitHub.

Endpoint URLs

The Resource Controller 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 (only available in US regions): https://private.resource-controller.cloud.ibm.com
Private endpoint URLs for classic and non-US region VPC 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

To work with the API, you must use 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.

For more information, see IAM authentication with the SDK.

To retrieve your access token:

curl -X POST
https://iam.cloud.ibm.com/identity/token
  -H "Content-Type: application/x-www-form-urlencoded"
  -H "Accept: application/json"
  -d "grant_type=urn%3Aibm%3Aparams%3Aoauth%3Agrant-type%3Aapikey&apikey=<API_KEY>"
Copy to clipboard

Replace <API_KEY> with your service credentials. Then, use the full IAM token value that is prefixed by the Bearer token type to authenticate your API requests.

To retrieve your instance ID:

ibmcloud resource service-instance <instance_name> --id

Replace <instance_name> with the name that you assigned to your service instance.

Setting client options through external configuration

Example environment variables, where <API_KEY> is your IAM API key

export RESOURCE_CONTROLLER_APIKEY=<API_KEY>

Example of constructing the service client

import com.ibm.cloud.platform_services.resource_controller.v2.ResourceController;
...
ResourceController resourceControllerService = ResourceController.newInstance();
Copy to clipboard

Setting client options through external configuration

Example environment variables, where <API_KEY> is your IAM API key

export RESOURCE_CONTROLLER_APIKEY=<API_KEY>

Example of constructing the service client

import {
    "github.com/IBM/platform-services-go-sdk/resourcecontrollerv2"
}
...
resourceControllerServiceOptions := &resourcecontrollerv2.ResourceControllerV2Options{}
resourceControllerService, err := resourcecontrollerv2.NewResourceControllerV2UsingExternalConfig(resourceControllerServiceOptions)

Setting client options through external configuration

Example environment variables, where <API_KEY> is your IAM API key

export RESOURCE_CONTROLLER_APIKEY=<API_KEY>

Example of constructing the service client

from ibm_platform_services import ResourceControllerV2
...
resource_controller_service = ResourceControllerV2.new_instance()

Setting client options through external configuration

Example environment variables, where <API_KEY> is your IAM API key

export RESOURCE_CONTROLLER_APIKEY=<API_KEY>

Example of constructing the service client

const ResourceControllerV2 = require('ibm-platform-services/resource-controller/v2');
...
const resourceControllerService = ResourceControllerV2.newInstance({});

# Error handling {: #errors}

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.

Additionally, each response includes a `Transaction-Id` header that can be referenced when you contact [IBM Cloud support](https://www.ibm.com/cloud/support).

| HTTP Error Code | Description           | Recovery |
|-----------------|-----------------------|----------|
| `200`           | Success               | The request was successful. |
| `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 could not be found. |
| `409`           | Conflict              | The entity is already in the requested state. |
| `410`           | Gone                  | The resource is valid but was removed in a previous call. |
| `500`           | Internal Server Error | *Offering_name* is unavailable. Your request could not be processed. Wait a few minutes and try again. |

# Auditing {: #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](/docs/activity-tracker?topic=activity-tracker-at_events_acc_mgt).

# Pagination {: #pagination}

Some API requests might return a large number of results. To avoid performance issues, these results are returned one page at a time, with a limited number of results on each page. GET requests for the following resources use pagination:

   * /v2/resource_instances
   * /v2/resource_keys

The default page and max size is 100 objects. To use a different page size, use the `limit` query parameter.

For any request that uses pagination, the response includes a `next_url` object that specifies pagination information. `next_url` is the URL for requesting the next page of results. The `next_url` property is null if there are no more results, and retains the same `limit` parameter that is used for the initial request.

# Rate limiting {: #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 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 remaining requests in the current time window
   * X-RateLimit-Limit: the total number of requests allowed within the time window

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

The number of allowed requests, and the length of the time window, vary by method and endpoint. The reference information for each endpoint specifies the rate limit that applies.


# Related APIs {: #related-apis}

When you work with the resource controller endpoints, it might be helpful to be aware of the IBM Cloud OSB APIs used to create your service broker.

* [IBM Cloud Open Service Broker](/apidocs/resource-controller/ibm-cloud-osb-api)
* [IBM Cloud Resource Manager](/apidocs/resource-controller/resource-manager)
Copy to clipboard

View a list of all available resource instances. Resources is a broad term that could mean anything from a service instance to a virtual machine associated with the customer account.

GET /v2/resource_instances

(resourceController *ResourceControllerV2) ListResourceInstances(listResourceInstancesOptions *ListResourceInstancesOptions) (result *ResourceInstancesList, response *core.DetailedResponse, err error)

(resourceController *ResourceControllerV2) ListResourceInstancesWithContext(ctx context.Context, listResourceInstancesOptions *ListResourceInstancesOptions) (result *ResourceInstancesList, response *core.DetailedResponse, err error)

ServiceCall<ResourceInstancesList> listResourceInstances(ListResourceInstancesOptions listResourceInstancesOptions)
Copy to clipboard

listResourceInstances(params)

list_resource_instances(
        self,
        *,
        guid: Optional[str] = None,
        name: Optional[str] = None,
        resource_group_id: Optional[str] = None,
        resource_id: Optional[str] = None,
        resource_plan_id: Optional[str] = None,
        type: Optional[str] = None,
        sub_type: Optional[str] = None,
        subscription_id: Optional[str] = None,
        limit: Optional[int] = None,
        start: Optional[str] = None,
        state: Optional[str] = None,
        updated_from: Optional[str] = None,
        updated_to: Optional[str] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

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.instance.retrieve

Request

Instantiate the ListResourceInstancesOptions struct and set the fields to provide parameter values for the ListResourceInstances method.

Use the ListResourceInstancesOptions.Builder to create a ListResourceInstancesOptions object that contains the parameter values for the listResourceInstances method.

Query Parameters

guid
string
The GUID of the instance.
name
string
The human-readable name of the instance.
resource_group_id
string
The ID of the resource group.
resource_id
string
The unique ID of the offering. This value is provided by and stored in the global catalog.
resource_plan_id
string
The unique ID of the plan associated with the offering. This value is provided by and stored in the global catalog.
type
string
The type of the instance, for example, service_instance.
sub_type
string
The sub-type of instance, for example, kms.
subscription_id
string
The ID of the subscription.
limit
integer
Limit on how many items should be returned.

Possible values: value ≤ 100
Default: 100
start
string
An optional token that indicates the beginning of the page of results to be returned. Any additional query parameters are ignored if a page token is present. If omitted, the first page of results is returned. This value is obtained from the 'start' query parameter in the 'next_url' field of the operation response.
state
string
The state of the instance. If not specified, instances in state active and provisioning are returned.

Allowable values: [active,inactive,failed,pending_reclamation,provisioning,pre_provisioning,removed]
updated_from
string
Start date inclusive filter.

Example: 2021-01-01
updated_to
string
End date inclusive filter.

Example: 2021-01-01

parameter

WithContext method only

ListResourceInstancesOptions

The ListResourceInstances options.

ListResourceInstancesOptions

The listResourceInstances options.

parameters

guid
string
The GUID of the instance.
name
string
The human-readable name of the instance.
resourceGroupId
string
The ID of the resource group.
resourceId
string
The unique ID of the offering. This value is provided by and stored in the global catalog.
resourcePlanId
string
The unique ID of the plan associated with the offering. This value is provided by and stored in the global catalog.
type
string
The type of the instance, for example, service_instance.
subType
string
The sub-type of instance, for example, kms.
subscriptionId
string
The ID of the subscription.
limit
number
Limit on how many items should be returned.

Possible values: value ≤ 100
Default: 100
start
string
An optional token that indicates the beginning of the page of results to be returned. Any additional query parameters are ignored if a page token is present. If omitted, the first page of results is returned. This value is obtained from the 'start' query parameter in the 'next_url' field of the operation response.
state
string
The state of the instance. If not specified, instances in state active and provisioning are returned.

Allowable values: [active,inactive,failed,pending_reclamation,provisioning,pre_provisioning,removed]
updatedFrom
string
Start date inclusive filter.
Examples:
updatedTo
string
End date inclusive filter.
Examples:

parameters

guid
str
The GUID of the instance.
name
str
The human-readable name of the instance.
resource_group_id
str
The ID of the resource group.
resource_id
str
The unique ID of the offering. This value is provided by and stored in the global catalog.
resource_plan_id
str
The unique ID of the plan associated with the offering. This value is provided by and stored in the global catalog.
type
str
The type of the instance, for example, service_instance.
sub_type
str
The sub-type of instance, for example, kms.
subscription_id
str
The ID of the subscription.
limit
int
Limit on how many items should be returned.

Possible values: value ≤ 100
Default: 100
start
str
An optional token that indicates the beginning of the page of results to be returned. Any additional query parameters are ignored if a page token is present. If omitted, the first page of results is returned. This value is obtained from the 'start' query parameter in the 'next_url' field of the operation response.
state
str
The state of the instance. If not specified, instances in state active and provisioning are returned.

Allowable values: [active,inactive,failed,pending_reclamation,provisioning,pre_provisioning,removed]
updated_from
str
Start date inclusive filter.
Examples:
updated_to
str
End date inclusive filter.
Examples:

Example request

curl -X GET https://resource-controller.cloud.ibm.com/v2/resource_instances -H "Authorization: Bearer <IAM token>"

Example request

listResourceInstancesOptions := &resourcecontrollerv2.ListResourceInstancesOptions{
  Name: &resourceInstanceName,
}

pager, err := resourceControllerService.NewResourceInstancesPager(listResourceInstancesOptions)
if err != nil {
  panic(err)
}

var allResults []resourcecontrollerv2.ResourceInstance
for pager.HasNext() {
  nextPage, err := pager.GetNext()
  if err != nil {
    panic(err)
  }
  allResults = append(allResults, nextPage...)
}
b, _ := json.MarshalIndent(allResults, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

ListResourceInstancesOptions listResourceInstancesOptions = new ListResourceInstancesOptions.Builder()
  .name(resourceInstanceName)
  .build();

ResourceInstancesPager pager =
    new ResourceInstancesPager(resourceControllerService, listResourceInstancesOptions);
List<ResourceInstance> allResults = new ArrayList<>();
while (pager.hasNext()) {
  List<ResourceInstance> nextPage = pager.getNext();
  allResults.addAll(nextPage);
}

System.out.println(GsonSingleton.getGson().toJson(allResults));
Copy to clipboard

Example request

const params = {
  name: resourceInstanceName,
};

const allResults = [];
try {
  const pager = new ResourceControllerV2.ResourceInstancesPager(
    resourceControllerService, params);
  while (pager.hasNext()) {
    const nextPage = await pager.getNext();
    expect(nextPage).not.toBeNull();
    allResults.push(...nextPage);
  }
  console.log(JSON.stringify(allResults, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

all_results = []
pager = ResourceInstancesPager(
  client=resource_controller_service,
  name=resource_instance_name,
)
while pager.has_next():
  next_page = pager.get_next()
  assert next_page is not None
  all_results.extend(next_page)

print(json.dumps(all_results, indent=2))
Copy to clipboard

Response

Response Body

ResourceInstancesList

A list of resource instances.

ResourceInstancesList

A list of resource instances.

ResourceInstancesList

A list of resource instances.

ResourceInstancesList

A list of resource instances.

ResourceInstancesList

A list of resource instances.

Status Code

200
The list of resource instances was successfully retrieved.
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.
429
Too many requests. Wait a few minutes and try again.
500
Your request could not be processed. Try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

Example responses

Status 200

{
  "rows_count": 1,
  "next_url": "/v2/resource_instances?start=bmV4dF9kb2NpZD1nMUFBQUFGVGVKekxZV0JnWU1sZ1RtSFFTa2xLemk5S2RVaEpNdFZMeXRWTlR0Wk5TVTNKVEU0c1NVMHhNckRVUzg3SkwwMUp6Q3ZSeTBzdHlRSHFZVW9TQUpKSjh2X19fODhDODkyY1N0XzlxWGc5Z1NGeFJ4YXFlZWJFbWFjQU1rOGZ5Ynl5eE5Pdml6NHdKREV3YU5pUVoyUUF5TWg0WkNjLU43cTQ0UUxJU0QyMUxISjhuY2NDSkJrV0FDbWdxZXZoTGsxbTRGQUNHOXMtSnlzTEFONl9iU2cmbGltaXQ9NSZhY2NvdW50X2lkPTQzMjkwNzNkMTZkMmYzNjYzZjc0YmZhOTU1MjU5MTM5",
  "resources": [
    {
      "id": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::",
      "guid": "8d7af921-b136-4078-9666-081bd8470d94",
      "url": "/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94",
      "created_at": "2018-04-19T00:18:53.302077457Z",
      "updated_at": "2018-04-19T00:18:53.302077457Z",
      "deleted_at": null,
      "created_by": "IBMid-5500093BHN",
      "updated_by": "IBMid-5500093BHN",
      "deleted_by": "",
      "scheduled_reclaim_at": null,
      "restored_at": null,
      "scheduled_reclaim_by": "",
      "restored_by": "",
      "name": "my-instance",
      "region_id": "global",
      "account_id": "4329073d16d2f3663f74bfa955259139",
      "resource_plan_id": "2fdf0c08-2d32-4f46-84b5-32e0c92fffd8",
      "resource_group_id": "0be5ad401ae913d8ff665d92680664ed",
      "resource_group_crn": "crn:v1:bluemix:public:resource-controller::a/4329073d16d2f3663f74bfa955259139::resource-group:0be5ad401ae913d8ff665d92680664ed",
      "target_crn": "crn:v1:bluemix:public:resource-catalog::a/9e16d1fed8aa7e1bd73e7a9d23434a5a::deployment:2fdf0c08-2d32-4f46-84b5-32e0c92fffd8%3Aglobal",
      "crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::",
      "allow_cleanup": true,
      "state": "active",
      "type": "service_instance",
      "resource_id": "dff97f5c-bc5e-4455-b470-411c3edbe49c",
      "dashboard_url": "/objectstorage/crn%3Av1%3Abluemix%3Apublic%3Acloud-object-storage%3Aglobal%3Aa%2F4329073d16d2f3663f74bfa955259139%3A8d7af921-b136-4078-9666-081bd8470d94%3A%3A",
      "last_operation": null,
      "resource_keys_url": "/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94/resource_keys",
      "plan_history": [
        {
          "resource_plan_id": "2fdf0c08-2d32-4f46-84b5-32e0c92fffd8",
          "start_date": "2018-04-19T00:18:53.302077457Z"
        }
      ],
      "migrated": false,
      "controlled_by": ""
    }
  ]
}
Copy to clipboard

Success example

{
  "rows_count": 1,
  "next_url": "/v2/resource_instances?start=bmV4dF9kb2NpZD1nMUFBQUFGVGVKekxZV0JnWU1sZ1RtSFFTa2xLemk5S2RVaEpNdFZMeXRWTlR0Wk5TVTNKVEU0c1NVMHhNckRVUzg3SkwwMUp6Q3ZSeTBzdHlRSHFZVW9TQUpKSjh2X19fODhDODkyY1N0XzlxWGc5Z1NGeFJ4YXFlZWJFbWFjQU1rOGZ5Ynl5eE5Pdml6NHdKREV3YU5pUVoyUUF5TWg0WkNjLU43cTQ0UUxJU0QyMUxISjhuY2NDSkJrV0FDbWdxZXZoTGsxbTRGQUNHOXMtSnlzTEFONl9iU2cmbGltaXQ9NSZhY2NvdW50X2lkPTQzMjkwNzNkMTZkMmYzNjYzZjc0YmZhOTU1MjU5MTM5",
  "resources": [
    {
      "id": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::",
      "guid": "8d7af921-b136-4078-9666-081bd8470d94",
      "url": "/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94",
      "created_at": "2018-04-19T00:18:53.302077457Z",
      "updated_at": "2018-04-19T00:18:53.302077457Z",
      "deleted_at": null,
      "created_by": "IBMid-5500093BHN",
      "updated_by": "IBMid-5500093BHN",
      "deleted_by": "",
      "scheduled_reclaim_at": null,
      "restored_at": null,
      "scheduled_reclaim_by": "",
      "restored_by": "",
      "name": "my-instance",
      "region_id": "global",
      "account_id": "4329073d16d2f3663f74bfa955259139",
      "resource_plan_id": "2fdf0c08-2d32-4f46-84b5-32e0c92fffd8",
      "resource_group_id": "0be5ad401ae913d8ff665d92680664ed",
      "resource_group_crn": "crn:v1:bluemix:public:resource-controller::a/4329073d16d2f3663f74bfa955259139::resource-group:0be5ad401ae913d8ff665d92680664ed",
      "target_crn": "crn:v1:bluemix:public:resource-catalog::a/9e16d1fed8aa7e1bd73e7a9d23434a5a::deployment:2fdf0c08-2d32-4f46-84b5-32e0c92fffd8%3Aglobal",
      "crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::",
      "allow_cleanup": true,
      "state": "active",
      "type": "service_instance",
      "resource_id": "dff97f5c-bc5e-4455-b470-411c3edbe49c",
      "dashboard_url": "/objectstorage/crn%3Av1%3Abluemix%3Apublic%3Acloud-object-storage%3Aglobal%3Aa%2F4329073d16d2f3663f74bfa955259139%3A8d7af921-b136-4078-9666-081bd8470d94%3A%3A",
      "last_operation": null,
      "resource_keys_url": "/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94/resource_keys",
      "plan_history": [
        {
          "resource_plan_id": "2fdf0c08-2d32-4f46-84b5-32e0c92fffd8",
          "start_date": "2018-04-19T00:18:53.302077457Z"
        }
      ],
      "migrated": false,
      "controlled_by": ""
    }
  ]
}
Copy to clipboard

When you provision a service you get an instance of that service. An instance represents the resource with which you create, and additionally, represents a chargeable record of which billing can occur.

POST /v2/resource_instances

(resourceController *ResourceControllerV2) CreateResourceInstance(createResourceInstanceOptions *CreateResourceInstanceOptions) (result *ResourceInstance, response *core.DetailedResponse, err error)

(resourceController *ResourceControllerV2) CreateResourceInstanceWithContext(ctx context.Context, createResourceInstanceOptions *CreateResourceInstanceOptions) (result *ResourceInstance, response *core.DetailedResponse, err error)

ServiceCall<ResourceInstance> createResourceInstance(CreateResourceInstanceOptions createResourceInstanceOptions)
Copy to clipboard

createResourceInstance(params)

create_resource_instance(
        self,
        name: str,
        target: str,
        resource_group: str,
        resource_plan_id: str,
        *,
        tags: Optional[List[str]] = None,
        allow_cleanup: Optional[bool] = None,
        parameters: Optional[dict] = None,
        entity_lock: Optional[bool] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

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.instance.create

Auditing

Calling this method generates the following auditing event.

resource-controller.instance.create

Request

Instantiate the CreateResourceInstanceOptions struct and set the fields to provide parameter values for the CreateResourceInstance method.

Use the CreateResourceInstanceOptions.Builder to create a CreateResourceInstanceOptions object that contains the parameter values for the createResourceInstance method.

Custom Headers

Entity-Lock
boolean
Indicates if the resource instance is locked for further update or delete operations. It does not affect actions performed on child resources like keys. False by default.

Default: false

Request Body

Required*

ResourceInstancePost

Property values for the new resource instance.

Examples:

parameter

WithContext method only

CreateResourceInstanceOptions

The CreateResourceInstance options.

CreateResourceInstanceOptions

The createResourceInstance options.

parameters

name
Required*
string
The name of the instance. Must be 180 characters or less and cannot include any special characters other than (space) - . _ :.

Possible values: Value must match regular expression /^([^[:ascii:]]{1,256}|[a-zA-Z0-9-._: ]{1,256})$/
Examples:
target
Required*
string
The deployment location where the instance should be hosted.
Examples:
resourceGroup
Required*
string
The ID of the resource group.
Examples:
resourcePlanId
Required*
string
The unique ID of the plan associated with the offering. This value is provided by and stored in the global catalog.
Examples:
tags
string[]
Tags that are attached to the instance after provisioning. These tags can be searched and managed through the Tagging API in IBM Cloud.
allowCleanup
boolean
A boolean that dictates if the resource instance should be deleted (cleaned up) during the processing of a region instance delete call.

Default: false
parameters
JsonObject
Configuration options represented as key-value pairs that are passed through to the target resource brokers.

Set the onetime_credentials property to specify whether newly created resource key credentials can be retrieved by using the get resource key or the get a list of all of the resource keys requests.

Set the subscription_id property to the ID of the subscription if the targeted plan is a subscription plan.
entityLock
boolean
Indicates if the resource instance is locked for further update or delete operations. It does not affect actions performed on child resources like keys. False by default.

Default: false

parameters

name
Required*
str
The name of the instance. Must be 180 characters or less and cannot include any special characters other than (space) - . _ :.

Possible values: Value must match regular expression /^([^[:ascii:]]{1,256}|[a-zA-Z0-9-._: ]{1,256})$/
Examples:
target
Required*
str
The deployment location where the instance should be hosted.
Examples:
resource_group
Required*
str
The ID of the resource group.
Examples:
resource_plan_id
Required*
str
The unique ID of the plan associated with the offering. This value is provided by and stored in the global catalog.
Examples:
tags
List[str]
Tags that are attached to the instance after provisioning. These tags can be searched and managed through the Tagging API in IBM Cloud.
allow_cleanup
bool
A boolean that dictates if the resource instance should be deleted (cleaned up) during the processing of a region instance delete call.

Default: false
parameters
dict
Configuration options represented as key-value pairs that are passed through to the target resource brokers.

Set the onetime_credentials property to specify whether newly created resource key credentials can be retrieved by using the get resource key or the get a list of all of the resource keys requests.

Set the subscription_id property to the ID of the subscription if the targeted plan is a subscription plan.
entity_lock
bool
Indicates if the resource instance is locked for further update or delete operations. It does not affect actions performed on child resources like keys. False by default.

Default: false

Example request

curl -X POST   https://resource-controller.cloud.ibm.com/v2/resource_instances   -H "Authorization: Bearer <IAM token>"   -H 'Content-Type: application/json'     -d '{
    "name": "my-instance",
    "target": "us-south",
    "resource_group": "5c49eabc-f5e8-5881-a37e-2d100a33b3df",
    "resource_plan_id": "cloudant-standard",
    "tags": [
      "my-tag"
    ]
  }'
Copy to clipboard

Example request

createResourceInstanceOptions := resourceControllerService.NewCreateResourceInstanceOptions(
  resourceInstanceName,
  targetRegion,
  resourceGroup,
  resourcePlanID,
)

resourceInstance, response, err := resourceControllerService.CreateResourceInstance(createResourceInstanceOptions)
if err != nil {
  panic(err)
}

b, _ := json.MarshalIndent(resourceInstance, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

CreateResourceInstanceOptions createResourceInstanceOptions = new CreateResourceInstanceOptions.Builder()
  .name(resourceInstanceName)
  .target(targetRegion)
  .resourceGroup(resourceGroup)
  .resourcePlanId(resourcePlanId)
  .build();

Response<ResourceInstance> response = resourceControllerService.createResourceInstance(createResourceInstanceOptions).execute();
ResourceInstance resourceInstance = response.getResult();

System.out.println(resourceInstance);

Example request

const params = {
  name: resourceInstanceName,
  target: targetRegion,
  resourceGroup: resourceGroupGuid,
  resourcePlanId: resourcePlanId,
};

try {
  const res = await resourceControllerService.createResourceInstance(params)
  instanceGuid = res.result.guid;
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

resource_instance = resource_controller_service.create_resource_instance(
  name=resource_instance_name,
  target=target_region,
  resource_group=resource_group,
  resource_plan_id=resource_plan_id
).get_result()

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

Response

Response Body

ResourceInstance

A resource instance.

ResourceInstance

A resource instance.

ResourceInstance

A resource instance.

ResourceInstance

A resource instance.

ResourceInstance

A resource instance.

Status Code

201
The resource instance was provisioned.
202
Request to provision a resource has been accepted by the broker, and provisioning is in progress. This triggers the platform to poll the service's broker for operation status. Users can call get_resource_instance to get the current state of the instance.
400
The request could not be understood due to malformed syntax.
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. Wait a few minutes and try again.
500
Your request could not be processed. 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": "crn:v1:bluemix:public:cloudantnosqldb:us-south:a/d86af7367f70fba4f306d3c19c7344b2:b723751c-69c1-4e4b-a4dc-ccfccf6c20a0::",
  "guid": "8d7af921-b136-4078-9666-081bd8470d94",
  "url": "/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94",
  "created_at": "2018-04-19T00:18:53.302077457Z",
  "updated_at": "2018-04-19T00:18:53.302077457Z",
  "deleted_at": null,
  "created_by": "IBMid-5500093BHN",
  "updated_by": "IBMid-5500093BHN",
  "deleted_by": "",
  "scheduled_reclaim_at": null,
  "restored_at": null,
  "scheduled_reclaim_by": "",
  "restored_by": "",
  "name": "my-instance",
  "region_id": "us-south",
  "account_id": "4329073d16d2f3663f74bfa955259139",
  "resource_plan_id": "cloudant-standard",
  "resource_group_id": "0be5ad401ae913d8ff665d92680664ed",
  "resource_group_crn": "crn:v1:bluemix:public:resource-controller::a/4329073d16d2f3663f74bfa955259139::resource-group:0be5ad401ae913d8ff665d92680664ed",
  "target_crn": "crn:v1:bluemix:public:resource-catalog::a/9e16d1fed8aa7e1bd73e7a9d23434a5a::deployment:2fdf0c08-2d32-4f46-84b5-32e0c92fffd8%3Aglobal",
  "crn": "crn:v1:bluemix:public:cloudantnosqldb:us-south:a/d86af7367f70fba4f306d3c19c7344b2:b723751c-69c1-4e4b-a4dc-ccfccf6c20a0::",
  "allow_cleanup": false,
  "state": "active",
  "type": "service_instance",
  "resource_id": "cloudant",
  "dashboard_url": "https://dashboard.cloudantnosqldb.cloud.ibm.com/rc/account/crn%3Av1%3Abluemix%3Apublic%3Acloudantnosqldb%3Aus-south%3Aa%2Fd86af7367f70fba4f306d3c19c7344b2%3Ab723751c-69c1-4e4b-a4dc-ccfccf6c20a0%3A%3A",
  "last_operation": null,
  "resource_keys_url": "/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94/resource_keys",
  "plan_history": [
    {
      "resource_plan_id": "cloudant-standard",
      "start_date": "2018-04-19T00:18:53.302077457Z"
    }
  ],
  "migrated": false,
  "controlled_by": ""
}
Copy to clipboard

Success example

{
  "id": "crn:v1:bluemix:public:cloudantnosqldb:us-south:a/d86af7367f70fba4f306d3c19c7344b2:b723751c-69c1-4e4b-a4dc-ccfccf6c20a0::",
  "guid": "8d7af921-b136-4078-9666-081bd8470d94",
  "url": "/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94",
  "created_at": "2018-04-19T00:18:53.302077457Z",
  "updated_at": "2018-04-19T00:18:53.302077457Z",
  "deleted_at": null,
  "created_by": "IBMid-5500093BHN",
  "updated_by": "IBMid-5500093BHN",
  "deleted_by": "",
  "scheduled_reclaim_at": null,
  "restored_at": null,
  "scheduled_reclaim_by": "",
  "restored_by": "",
  "name": "my-instance",
  "region_id": "us-south",
  "account_id": "4329073d16d2f3663f74bfa955259139",
  "resource_plan_id": "cloudant-standard",
  "resource_group_id": "0be5ad401ae913d8ff665d92680664ed",
  "resource_group_crn": "crn:v1:bluemix:public:resource-controller::a/4329073d16d2f3663f74bfa955259139::resource-group:0be5ad401ae913d8ff665d92680664ed",
  "target_crn": "crn:v1:bluemix:public:resource-catalog::a/9e16d1fed8aa7e1bd73e7a9d23434a5a::deployment:2fdf0c08-2d32-4f46-84b5-32e0c92fffd8%3Aglobal",
  "crn": "crn:v1:bluemix:public:cloudantnosqldb:us-south:a/d86af7367f70fba4f306d3c19c7344b2:b723751c-69c1-4e4b-a4dc-ccfccf6c20a0::",
  "allow_cleanup": false,
  "state": "active",
  "type": "service_instance",
  "resource_id": "cloudant",
  "dashboard_url": "https://dashboard.cloudantnosqldb.cloud.ibm.com/rc/account/crn%3Av1%3Abluemix%3Apublic%3Acloudantnosqldb%3Aus-south%3Aa%2Fd86af7367f70fba4f306d3c19c7344b2%3Ab723751c-69c1-4e4b-a4dc-ccfccf6c20a0%3A%3A",
  "last_operation": null,
  "resource_keys_url": "/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94/resource_keys",
  "plan_history": [
    {
      "resource_plan_id": "cloudant-standard",
      "start_date": "2018-04-19T00:18:53.302077457Z"
    }
  ],
  "migrated": false,
  "controlled_by": ""
}
Copy to clipboard

Status 202

{
  "id": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::",
  "guid": "8d7af921-b136-4078-9666-081bd8470d94",
  "url": "/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94",
  "created_at": "2018-04-19T00:18:53.302077457Z",
  "updated_at": "2018-04-19T00:18:53.302077457Z",
  "deleted_at": null,
  "created_by": "IBMid-5500093BHN",
  "updated_by": "IBMid-5500093BHN",
  "deleted_by": "",
  "scheduled_reclaim_at": null,
  "restored_at": null,
  "scheduled_reclaim_by": "",
  "restored_by": "",
  "name": "my-instance",
  "region_id": "global",
  "account_id": "4329073d16d2f3663f74bfa955259139",
  "resource_plan_id": "2fdf0c08-2d32-4f46-84b5-32e0c92fffd8",
  "resource_group_id": "0be5ad401ae913d8ff665d92680664ed",
  "resource_group_crn": "crn:v1:bluemix:public:resource-controller::a/4329073d16d2f3663f74bfa955259139::resource-group:0be5ad401ae913d8ff665d92680664ed",
  "target_crn": "crn:v1:bluemix:public:resource-catalog::a/9e16d1fed8aa7e1bd73e7a9d23434a5a::deployment:2fdf0c08-2d32-4f46-84b5-32e0c92fffd8%3Aglobal",
  "crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::",
  "allow_cleanup": false,
  "state": "provisioning",
  "type": "service_instance",
  "resource_id": "dff97f5c-bc5e-4455-b470-411c3edbe49c",
  "dashboard_url": "/objectstorage/crn%3Av1%3Abluemix%3Apublic%3Acloud-object-storage%3Aglobal%3Aa%2F4329073d16d2f3663f74bfa955259139%3A8d7af921-b136-4078-9666-081bd8470d94%3A%3A",
  "last_operation": {
    "type": "create",
    "state": "in progress",
    "async": true,
    "description": "Started create instance operation",
    "cancelable": false,
    "poll": true
  },
  "resource_keys_url": "/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94/resource_keys",
  "plan_history": [
    {
      "resource_plan_id": "2fdf0c08-2d32-4f46-84b5-32e0c92fffd8",
      "start_date": "2018-04-19T00:18:53.302077457Z"
    }
  ],
  "migrated": false,
  "controlled_by": ""
}
Copy to clipboard

Success example

{
  "id": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::",
  "guid": "8d7af921-b136-4078-9666-081bd8470d94",
  "url": "/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94",
  "created_at": "2018-04-19T00:18:53.302077457Z",
  "updated_at": "2018-04-19T00:18:53.302077457Z",
  "deleted_at": null,
  "created_by": "IBMid-5500093BHN",
  "updated_by": "IBMid-5500093BHN",
  "deleted_by": "",
  "scheduled_reclaim_at": null,
  "restored_at": null,
  "scheduled_reclaim_by": "",
  "restored_by": "",
  "name": "my-instance",
  "region_id": "global",
  "account_id": "4329073d16d2f3663f74bfa955259139",
  "resource_plan_id": "2fdf0c08-2d32-4f46-84b5-32e0c92fffd8",
  "resource_group_id": "0be5ad401ae913d8ff665d92680664ed",
  "resource_group_crn": "crn:v1:bluemix:public:resource-controller::a/4329073d16d2f3663f74bfa955259139::resource-group:0be5ad401ae913d8ff665d92680664ed",
  "target_crn": "crn:v1:bluemix:public:resource-catalog::a/9e16d1fed8aa7e1bd73e7a9d23434a5a::deployment:2fdf0c08-2d32-4f46-84b5-32e0c92fffd8%3Aglobal",
  "crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::",
  "allow_cleanup": false,
  "state": "provisioning",
  "type": "service_instance",
  "resource_id": "dff97f5c-bc5e-4455-b470-411c3edbe49c",
  "dashboard_url": "/objectstorage/crn%3Av1%3Abluemix%3Apublic%3Acloud-object-storage%3Aglobal%3Aa%2F4329073d16d2f3663f74bfa955259139%3A8d7af921-b136-4078-9666-081bd8470d94%3A%3A",
  "last_operation": {
    "type": "create",
    "state": "in progress",
    "async": true,
    "description": "Started create instance operation",
    "cancelable": false,
    "poll": true
  },
  "resource_keys_url": "/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94/resource_keys",
  "plan_history": [
    {
      "resource_plan_id": "2fdf0c08-2d32-4f46-84b5-32e0c92fffd8",
      "start_date": "2018-04-19T00:18:53.302077457Z"
    }
  ],
  "migrated": false,
  "controlled_by": ""
}
Copy to clipboard

Retrieve a resource instance by URL-encoded CRN or GUID. Find more details on a particular instance, like when it was provisioned and who provisioned it.

GET /v2/resource_instances/{id}

(resourceController *ResourceControllerV2) GetResourceInstance(getResourceInstanceOptions *GetResourceInstanceOptions) (result *ResourceInstance, response *core.DetailedResponse, err error)

(resourceController *ResourceControllerV2) GetResourceInstanceWithContext(ctx context.Context, getResourceInstanceOptions *GetResourceInstanceOptions) (result *ResourceInstance, response *core.DetailedResponse, err error)

ServiceCall<ResourceInstance> getResourceInstance(GetResourceInstanceOptions getResourceInstanceOptions)
Copy to clipboard

getResourceInstance(params)

get_resource_instance(
        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.instance.retrieve

Request

Instantiate the GetResourceInstanceOptions struct and set the fields to provide parameter values for the GetResourceInstance method.

Use the GetResourceInstanceOptions.Builder to create a GetResourceInstanceOptions object that contains the parameter values for the getResourceInstance method.

Path Parameters

id
Required*
string
The resource instance URL-encoded CRN or GUID.

parameter

WithContext method only

GetResourceInstanceOptions

The GetResourceInstance options.

GetResourceInstanceOptions

The getResourceInstance options.

parameters

id
Required*
string
The resource instance URL-encoded CRN or GUID.

parameters

id
Required*
str
The resource instance URL-encoded CRN or GUID.

Example request

curl -X GET   https://resource-controller.cloud.ibm.com/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94   -H "Authorization: Bearer <IAM token>" \

Example request

getResourceInstanceOptions := resourceControllerService.NewGetResourceInstanceOptions(
  instanceGUID,
)

resourceInstance, response, err := resourceControllerService.GetResourceInstance(getResourceInstanceOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(resourceInstance, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

GetResourceInstanceOptions getResourceInstanceOptions = new GetResourceInstanceOptions.Builder()
  .id(instanceGuid)
  .build();

Response<ResourceInstance> response = resourceControllerService.getResourceInstance(getResourceInstanceOptions).execute();
ResourceInstance resourceInstance = response.getResult();

System.out.println(resourceInstance);

Example request

const params = {
  id: instanceGuid,
};

try {
  const res = await resourceControllerService.getResourceInstance(params);
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

resource_instance = resource_controller_service.get_resource_instance(
  id=instance_guid
).get_result()

print(json.dumps(resource_instance, indent=2))
Copy to clipboard

Response

Response Body

ResourceInstance

A resource instance.

ResourceInstance

A resource instance.

ResourceInstance

A resource instance.

ResourceInstance

A resource instance.

ResourceInstance

A resource instance.

Status Code

200
The resource instance was successfully retrieved.
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. Wait a few minutes and try again.
500
Your request could not be processed. 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": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::",
  "guid": "8d7af921-b136-4078-9666-081bd8470d94",
  "url": "/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94",
  "created_at": "2018-04-19T00:18:53.302077457Z",
  "updated_at": "2018-04-19T00:18:53.302077457Z",
  "deleted_at": null,
  "created_by": "IBMid-5500093BHN",
  "updated_by": "IBMid-5500093BHN",
  "deleted_by": "",
  "scheduled_reclaim_at": null,
  "restored_at": null,
  "scheduled_reclaim_by": "",
  "restored_by": "",
  "name": "my-instance",
  "region_id": "global",
  "account_id": "4329073d16d2f3663f74bfa955259139",
  "resource_plan_id": "2fdf0c08-2d32-4f46-84b5-32e0c92fffd8",
  "resource_group_id": "0be5ad401ae913d8ff665d92680664ed",
  "resource_group_crn": "crn:v1:bluemix:public:resource-controller::a/4329073d16d2f3663f74bfa955259139::resource-group:0be5ad401ae913d8ff665d92680664ed",
  "target_crn": "crn:v1:bluemix:public:resource-catalog::a/9e16d1fed8aa7e1bd73e7a9d23434a5a::deployment:2fdf0c08-2d32-4f46-84b5-32e0c92fffd8%3Aglobal",
  "crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::",
  "allow_cleanup": false,
  "state": "active",
  "type": "service_instance",
  "resource_id": "dff97f5c-bc5e-4455-b470-411c3edbe49c",
  "dashboard_url": "/objectstorage/crn%3Av1%3Abluemix%3Apublic%3Acloud-object-storage%3Aglobal%3Aa%2F4329073d16d2f3663f74bfa955259139%3A8d7af921-b136-4078-9666-081bd8470d94%3A%3A",
  "last_operation": null,
  "resource_keys_url": "/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94/resource_keys",
  "plan_history": [
    {
      "resource_plan_id": "2fdf0c08-2d32-4f46-84b5-32e0c92fffd8",
      "start_date": "2018-04-19T00:18:53.302077457Z"
    }
  ],
  "migrated": false,
  "controlled_by": ""
}
Copy to clipboard

Success example

{
  "id": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::",
  "guid": "8d7af921-b136-4078-9666-081bd8470d94",
  "url": "/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94",
  "created_at": "2018-04-19T00:18:53.302077457Z",
  "updated_at": "2018-04-19T00:18:53.302077457Z",
  "deleted_at": null,
  "created_by": "IBMid-5500093BHN",
  "updated_by": "IBMid-5500093BHN",
  "deleted_by": "",
  "scheduled_reclaim_at": null,
  "restored_at": null,
  "scheduled_reclaim_by": "",
  "restored_by": "",
  "name": "my-instance",
  "region_id": "global",
  "account_id": "4329073d16d2f3663f74bfa955259139",
  "resource_plan_id": "2fdf0c08-2d32-4f46-84b5-32e0c92fffd8",
  "resource_group_id": "0be5ad401ae913d8ff665d92680664ed",
  "resource_group_crn": "crn:v1:bluemix:public:resource-controller::a/4329073d16d2f3663f74bfa955259139::resource-group:0be5ad401ae913d8ff665d92680664ed",
  "target_crn": "crn:v1:bluemix:public:resource-catalog::a/9e16d1fed8aa7e1bd73e7a9d23434a5a::deployment:2fdf0c08-2d32-4f46-84b5-32e0c92fffd8%3Aglobal",
  "crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::",
  "allow_cleanup": false,
  "state": "active",
  "type": "service_instance",
  "resource_id": "dff97f5c-bc5e-4455-b470-411c3edbe49c",
  "dashboard_url": "/objectstorage/crn%3Av1%3Abluemix%3Apublic%3Acloud-object-storage%3Aglobal%3Aa%2F4329073d16d2f3663f74bfa955259139%3A8d7af921-b136-4078-9666-081bd8470d94%3A%3A",
  "last_operation": null,
  "resource_keys_url": "/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94/resource_keys",
  "plan_history": [
    {
      "resource_plan_id": "2fdf0c08-2d32-4f46-84b5-32e0c92fffd8",
      "start_date": "2018-04-19T00:18:53.302077457Z"
    }
  ],
  "migrated": false,
  "controlled_by": ""
}
Copy to clipboard

Delete a resource instance by URL-encoded CRN or GUID. If the resource instance has any resource keys associated with it, use the recursive=true parameter to delete it.

DELETE /v2/resource_instances/{id}

(resourceController *ResourceControllerV2) DeleteResourceInstance(deleteResourceInstanceOptions *DeleteResourceInstanceOptions) (response *core.DetailedResponse, err error)

(resourceController *ResourceControllerV2) DeleteResourceInstanceWithContext(ctx context.Context, deleteResourceInstanceOptions *DeleteResourceInstanceOptions) (response *core.DetailedResponse, err error)

ServiceCall<Void> deleteResourceInstance(DeleteResourceInstanceOptions deleteResourceInstanceOptions)
Copy to clipboard

deleteResourceInstance(params)

delete_resource_instance(
        self,
        id: str,
        *,
        recursive: Optional[bool] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

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.instance.delete

Auditing

Calling this method generates the following auditing event.

resource-controller.instance.delete

Request

Instantiate the DeleteResourceInstanceOptions struct and set the fields to provide parameter values for the DeleteResourceInstance method.

Use the DeleteResourceInstanceOptions.Builder to create a DeleteResourceInstanceOptions object that contains the parameter values for the deleteResourceInstance method.

Path Parameters

id
Required*
string
The resource instance URL-encoded CRN or GUID.

Query Parameters

recursive
boolean
Will delete keys associated with the instance.

Default: false

parameter

WithContext method only

DeleteResourceInstanceOptions

The DeleteResourceInstance options.

DeleteResourceInstanceOptions

The deleteResourceInstance options.

parameters

id
Required*
string
The resource instance URL-encoded CRN or GUID.
recursive
boolean
Will delete resource keys associated with the instance.

Default: false

parameters

id
Required*
str
The resource instance URL-encoded CRN or GUID.
recursive
bool
Will delete resource keys associated with the instance.

Default: false

Example request

curl -X DELETE   https://resource-controller.cloud.ibm.com/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94   -H "Authorization: Bearer <IAM token>"

Example request

deleteResourceInstanceOptions := resourceControllerService.NewDeleteResourceInstanceOptions(
  instanceGUID,
)
deleteResourceInstanceOptions.SetRecursive(false)

response, err := resourceControllerService.DeleteResourceInstance(deleteResourceInstanceOptions)
if err != nil {
  panic(err)
}
Copy to clipboard

Example request

DeleteResourceInstanceOptions deleteResourceInstanceOptions = new DeleteResourceInstanceOptions.Builder()
  .id(instanceGuid)
  .recursive(false)
  .build();

Response<Void> response = resourceControllerService.deleteResourceInstance(deleteResourceInstanceOptions).execute();

Example request

const params = {
  id: instanceGuid,
  recursive: false,
};

try {
  await resourceControllerService.deleteResourceInstance(params);
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

response = resource_controller_service.delete_resource_instance(
  id=instance_guid,
  recursive=False
)

Response

Status Code

202
Request to delete a resource has been accepted by the broker, and deletion is in progress. This triggers the platform to poll the service's broker for operation status. Users can call get_resource_instance to get the current state of the instance.
204
Deleted
400
The request could not be understood due to malformed syntax.
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.
410
The resource could was previously deleted and is no longer available.
429
Too many requests. Wait a few minutes and try again.
500
Your request could not be processed. 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.

Use the resource instance URL-encoded CRN or GUID to make updates to the resource instance, like changing the name or plan.

PATCH /v2/resource_instances/{id}

(resourceController *ResourceControllerV2) UpdateResourceInstance(updateResourceInstanceOptions *UpdateResourceInstanceOptions) (result *ResourceInstance, response *core.DetailedResponse, err error)

(resourceController *ResourceControllerV2) UpdateResourceInstanceWithContext(ctx context.Context, updateResourceInstanceOptions *UpdateResourceInstanceOptions) (result *ResourceInstance, response *core.DetailedResponse, err error)

ServiceCall<ResourceInstance> updateResourceInstance(UpdateResourceInstanceOptions updateResourceInstanceOptions)
Copy to clipboard

updateResourceInstance(params)

update_resource_instance(
        self,
        id: str,
        *,
        name: Optional[str] = None,
        parameters: Optional[dict] = None,
        resource_plan_id: Optional[str] = None,
        allow_cleanup: Optional[bool] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

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.instance.update

Auditing

Calling this method generates the following auditing event.

resource-controller.instance.update

Request

Instantiate the UpdateResourceInstanceOptions struct and set the fields to provide parameter values for the UpdateResourceInstance method.

Use the UpdateResourceInstanceOptions.Builder to create a UpdateResourceInstanceOptions object that contains the parameter values for the updateResourceInstance method.

Path Parameters

id
Required*
string
The resource instance URL-encoded CRN or GUID.

Request Body

Required*

ResourceInstancePatch

Updated property values for a resource instance.

Examples:

parameter

WithContext method only

UpdateResourceInstanceOptions

The UpdateResourceInstance options.

UpdateResourceInstanceOptions

The updateResourceInstance options.

parameters

id
Required*
string
The resource instance URL-encoded CRN or GUID.
name
string
The new name of the instance. Must be 180 characters or less and cannot include any special characters other than (space) - . _ :.

Possible values: Value must match regular expression /^([^[:ascii:]]{1,256}|[a-zA-Z0-9-._: ]{1,256})$/
Examples:
parameters
JsonObject
The new configuration options for the instance.

Set the onetime_credentials property to specify whether newly created resource key credentials can be retrieved by using the get resource key or the get a list of all of the resource keys requests.
Examples:
resourcePlanId
string
The unique ID of the plan associated with the offering. This value is provided by and stored in the global catalog.
allowCleanup
boolean
A boolean that dictates if the resource instance should be deleted (cleaned up) during the processing of a region instance delete call.

parameters

id
Required*
str
The resource instance URL-encoded CRN or GUID.
name
str
The new name of the instance. Must be 180 characters or less and cannot include any special characters other than (space) - . _ :.

Possible values: Value must match regular expression /^([^[:ascii:]]{1,256}|[a-zA-Z0-9-._: ]{1,256})$/
Examples:
parameters
dict
The new configuration options for the instance.

Set the onetime_credentials property to specify whether newly created resource key credentials can be retrieved by using the get resource key or the get a list of all of the resource keys requests.
Examples:
resource_plan_id
str
The unique ID of the plan associated with the offering. This value is provided by and stored in the global catalog.
allow_cleanup
bool
A boolean that dictates if the resource instance should be deleted (cleaned up) during the processing of a region instance delete call.

Example request

curl -X PATCH   https://resource-controller.cloud.ibm.com/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94   -H "Authorization: Bearer <IAM token>"   -H 'Content-Type: application/json'     -d '{
    "name": "my-instance-new-binding-1",
    "resource_plan_id": "744bfc56-d12c-4866-88d5-dac9139e0e5d"
  }'
Copy to clipboard

Example request

parameters := map[string]interface{}{"exampleProperty": "exampleValue"}
updateResourceInstanceOptions := resourceControllerService.NewUpdateResourceInstanceOptions(
  instanceGUID,
)
updateResourceInstanceOptions = updateResourceInstanceOptions.SetName(resourceInstanceUpdateName)
updateResourceInstanceOptions = updateResourceInstanceOptions.SetParameters(parameters)

resourceInstance, response, err := resourceControllerService.UpdateResourceInstance(updateResourceInstanceOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(resourceInstance, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

Map<String, Object> parameters = new HashMap<String, Object>();
parameters.put("exampleProperty", "exampleValue");

UpdateResourceInstanceOptions updateResourceInstanceOptions = new UpdateResourceInstanceOptions.Builder()
  .id(instanceGuid)
  .name(resourceInstanceUpdateName)
  .parameters(parameters)
  .build();

Response<ResourceInstance> response = resourceControllerService.updateResourceInstance(updateResourceInstanceOptions).execute();
ResourceInstance resourceInstance = response.getResult();

System.out.println(resourceInstance);
Copy to clipboard

Example request

const parameters = {
  'exampleParameter': 'exampleValue',
};

const params = {
  id: instanceGuid,
  name: resourceInstanceUpdateName,
  parameters: parameters,
};

try {
  const res = await resourceControllerService.updateResourceInstance(params);
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

parameters = {
  'exampleProperty': 'exampleValue'
}
resource_instance = resource_controller_service.update_resource_instance(
  id=instance_guid,
  name=resource_instance_update_name,
  parameters=parameters
).get_result()

print(json.dumps(resource_instance, indent=2))
Copy to clipboard

Response

Response Body

ResourceInstance

A resource instance.

ResourceInstance

A resource instance.

ResourceInstance

A resource instance.

ResourceInstance

A resource instance.

ResourceInstance

A resource instance.

Status Code

200
The requested changes have been applied
202
Request to update a resource has been accepted by the broker, and update is in progress. This triggers the platform to poll the service's broker for operation status. Users can call get_resource_instance to get the current state of the instance.
400
The request could not be understood due to malformed syntax.
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.
422
The request could not be processed.
429
Too many requests. Wait a few minutes and try again.
500
Your request could not be processed. 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": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::",
  "guid": "8d7af921-b136-4078-9666-081bd8470d94",
  "url": "/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94",
  "created_at": "2018-04-19T00:18:53.302077457Z",
  "updated_at": "2018-04-19T00:18:53.302077457Z",
  "deleted_at": null,
  "created_by": "IBMid-5500093BHN",
  "updated_by": "IBMid-5500093BHN",
  "deleted_by": "",
  "scheduled_reclaim_at": null,
  "restored_at": null,
  "scheduled_reclaim_by": "",
  "restored_by": "",
  "name": "my-instance",
  "region_id": "global",
  "account_id": "4329073d16d2f3663f74bfa955259139",
  "resource_plan_id": "2fdf0c08-2d32-4f46-84b5-32e0c92fffd8",
  "resource_group_id": "0be5ad401ae913d8ff665d92680664ed",
  "resource_group_crn": "crn:v1:bluemix:public:resource-controller::a/4329073d16d2f3663f74bfa955259139::resource-group:0be5ad401ae913d8ff665d92680664ed",
  "target_crn": "crn:v1:bluemix:public:resource-catalog::a/9e16d1fed8aa7e1bd73e7a9d23434a5a::deployment:2fdf0c08-2d32-4f46-84b5-32e0c92fffd8%3Aglobal",
  "crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::",
  "allow_cleanup": false,
  "state": "active",
  "type": "service_instance",
  "resource_id": "dff97f5c-bc5e-4455-b470-411c3edbe49c",
  "dashboard_url": "/objectstorage/crn%3Av1%3Abluemix%3Apublic%3Acloud-object-storage%3Aglobal%3Aa%2F4329073d16d2f3663f74bfa955259139%3A8d7af921-b136-4078-9666-081bd8470d94%3A%3A",
  "last_operation": null,
  "resource_keys_url": "/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94/resource_keys",
  "plan_history": [
    {
      "resource_plan_id": "2fdf0c08-2d32-4f46-84b5-32e0c92fffd8",
      "start_date": "2018-04-19T00:18:53.302077457Z"
    }
  ],
  "migrated": false,
  "controlled_by": ""
}
Copy to clipboard

Success example

{
  "id": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::",
  "guid": "8d7af921-b136-4078-9666-081bd8470d94",
  "url": "/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94",
  "created_at": "2018-04-19T00:18:53.302077457Z",
  "updated_at": "2018-04-19T00:18:53.302077457Z",
  "deleted_at": null,
  "created_by": "IBMid-5500093BHN",
  "updated_by": "IBMid-5500093BHN",
  "deleted_by": "",
  "scheduled_reclaim_at": null,
  "restored_at": null,
  "scheduled_reclaim_by": "",
  "restored_by": "",
  "name": "my-instance",
  "region_id": "global",
  "account_id": "4329073d16d2f3663f74bfa955259139",
  "resource_plan_id": "2fdf0c08-2d32-4f46-84b5-32e0c92fffd8",
  "resource_group_id": "0be5ad401ae913d8ff665d92680664ed",
  "resource_group_crn": "crn:v1:bluemix:public:resource-controller::a/4329073d16d2f3663f74bfa955259139::resource-group:0be5ad401ae913d8ff665d92680664ed",
  "target_crn": "crn:v1:bluemix:public:resource-catalog::a/9e16d1fed8aa7e1bd73e7a9d23434a5a::deployment:2fdf0c08-2d32-4f46-84b5-32e0c92fffd8%3Aglobal",
  "crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::",
  "allow_cleanup": false,
  "state": "active",
  "type": "service_instance",
  "resource_id": "dff97f5c-bc5e-4455-b470-411c3edbe49c",
  "dashboard_url": "/objectstorage/crn%3Av1%3Abluemix%3Apublic%3Acloud-object-storage%3Aglobal%3Aa%2F4329073d16d2f3663f74bfa955259139%3A8d7af921-b136-4078-9666-081bd8470d94%3A%3A",
  "last_operation": null,
  "resource_keys_url": "/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94/resource_keys",
  "plan_history": [
    {
      "resource_plan_id": "2fdf0c08-2d32-4f46-84b5-32e0c92fffd8",
      "start_date": "2018-04-19T00:18:53.302077457Z"
    }
  ],
  "migrated": false,
  "controlled_by": ""
}
Copy to clipboard

Status 202

{
  "id": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::",
  "guid": "8d7af921-b136-4078-9666-081bd8470d94",
  "url": "/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94",
  "created_at": "2018-04-19T00:18:53.302077457Z",
  "updated_at": "2018-04-19T00:18:53.302077457Z",
  "deleted_at": null,
  "created_by": "IBMid-5500093BHN",
  "updated_by": "IBMid-5500093BHN",
  "deleted_by": "",
  "scheduled_reclaim_at": null,
  "restored_at": null,
  "scheduled_reclaim_by": "",
  "restored_by": "",
  "name": "my-instance",
  "region_id": "global",
  "account_id": "4329073d16d2f3663f74bfa955259139",
  "resource_plan_id": "744bfc56-d12c-4866-88d5-dac9139e0e5d",
  "resource_group_id": "0be5ad401ae913d8ff665d92680664ed",
  "resource_group_crn": "crn:v1:bluemix:public:resource-controller::a/4329073d16d2f3663f74bfa955259139::resource-group:0be5ad401ae913d8ff665d92680664ed",
  "target_crn": "crn:v1:bluemix:public:resource-catalog::a/9e16d1fed8aa7e1bd73e7a9d23434a5a::deployment:2fdf0c08-2d32-4f46-84b5-32e0c92fffd8%3Aglobal",
  "crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::",
  "allow_cleanup": false,
  "state": "active",
  "type": "service_instance",
  "resource_id": "dff97f5c-bc5e-4455-b470-411c3edbe49c",
  "dashboard_url": "/objectstorage/crn%3Av1%3Abluemix%3Apublic%3Acloud-object-storage%3Aglobal%3Aa%2F4329073d16d2f3663f74bfa955259139%3A8d7af921-b136-4078-9666-081bd8470d94%3A%3A",
  "last_operation": {
    "type": "update",
    "state": "in progress",
    "async": true,
    "description": "Started update instance operation",
    "cancelable": false,
    "poll": true
  },
  "resource_keys_url": "/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94/resource_keys",
  "plan_history": [
    {
      "resource_plan_id": "2fdf0c08-2d32-4f46-84b5-32e0c92fffd8",
      "start_date": "2018-04-19T00:18:53.302077457Z"
    }
  ],
  "migrated": false,
  "controlled_by": ""
}
Copy to clipboard

Success example

{
  "id": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::",
  "guid": "8d7af921-b136-4078-9666-081bd8470d94",
  "url": "/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94",
  "created_at": "2018-04-19T00:18:53.302077457Z",
  "updated_at": "2018-04-19T00:18:53.302077457Z",
  "deleted_at": null,
  "created_by": "IBMid-5500093BHN",
  "updated_by": "IBMid-5500093BHN",
  "deleted_by": "",
  "scheduled_reclaim_at": null,
  "restored_at": null,
  "scheduled_reclaim_by": "",
  "restored_by": "",
  "name": "my-instance",
  "region_id": "global",
  "account_id": "4329073d16d2f3663f74bfa955259139",
  "resource_plan_id": "744bfc56-d12c-4866-88d5-dac9139e0e5d",
  "resource_group_id": "0be5ad401ae913d8ff665d92680664ed",
  "resource_group_crn": "crn:v1:bluemix:public:resource-controller::a/4329073d16d2f3663f74bfa955259139::resource-group:0be5ad401ae913d8ff665d92680664ed",
  "target_crn": "crn:v1:bluemix:public:resource-catalog::a/9e16d1fed8aa7e1bd73e7a9d23434a5a::deployment:2fdf0c08-2d32-4f46-84b5-32e0c92fffd8%3Aglobal",
  "crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::",
  "allow_cleanup": false,
  "state": "active",
  "type": "service_instance",
  "resource_id": "dff97f5c-bc5e-4455-b470-411c3edbe49c",
  "dashboard_url": "/objectstorage/crn%3Av1%3Abluemix%3Apublic%3Acloud-object-storage%3Aglobal%3Aa%2F4329073d16d2f3663f74bfa955259139%3A8d7af921-b136-4078-9666-081bd8470d94%3A%3A",
  "last_operation": {
    "type": "update",
    "state": "in progress",
    "async": true,
    "description": "Started update instance operation",
    "cancelable": false,
    "poll": true
  },
  "resource_keys_url": "/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94/resource_keys",
  "plan_history": [
    {
      "resource_plan_id": "2fdf0c08-2d32-4f46-84b5-32e0c92fffd8",
      "start_date": "2018-04-19T00:18:53.302077457Z"
    }
  ],
  "migrated": false,
  "controlled_by": ""
}
Copy to clipboard

You may have many resource keys for one resource instance. For example, you may have a different resource key for each user or each role.

GET /v2/resource_instances/{id}/resource_keys

(resourceController *ResourceControllerV2) ListResourceKeysForInstance(listResourceKeysForInstanceOptions *ListResourceKeysForInstanceOptions) (result *ResourceKeysList, response *core.DetailedResponse, err error)

(resourceController *ResourceControllerV2) ListResourceKeysForInstanceWithContext(ctx context.Context, listResourceKeysForInstanceOptions *ListResourceKeysForInstanceOptions) (result *ResourceKeysList, response *core.DetailedResponse, err error)

ServiceCall<ResourceKeysList> listResourceKeysForInstance(ListResourceKeysForInstanceOptions listResourceKeysForInstanceOptions)
Copy to clipboard

listResourceKeysForInstance(params)

list_resource_keys_for_instance(
        self,
        id: str,
        *,
        limit: Optional[int] = None,
        start: Optional[str] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

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.key.retrieve

Auditing

Calling this method generates the following auditing event.

resource-controller.key.retrieve

Request

Instantiate the ListResourceKeysForInstanceOptions struct and set the fields to provide parameter values for the ListResourceKeysForInstance method.

Use the ListResourceKeysForInstanceOptions.Builder to create a ListResourceKeysForInstanceOptions object that contains the parameter values for the listResourceKeysForInstance method.

Path Parameters

id
Required*
string
The resource instance URL-encoded CRN or GUID.

Query Parameters

limit
integer
Limit on how many items should be returned.

Possible values: value ≤ 100
Default: 100
start
string
An optional token that indicates the beginning of the page of results to be returned. Any additional query parameters are ignored if a page token is present. If omitted, the first page of results is returned. This value is obtained from the 'start' query parameter in the 'next_url' field of the operation response.

parameter

WithContext method only

ListResourceKeysForInstanceOptions

The ListResourceKeysForInstance options.

ListResourceKeysForInstanceOptions

The listResourceKeysForInstance options.

parameters

id
Required*
string
The resource instance URL-encoded CRN or GUID.
limit
number
Limit on how many items should be returned.

Possible values: value ≤ 100
Default: 100
start
string
An optional token that indicates the beginning of the page of results to be returned. Any additional query parameters are ignored if a page token is present. If omitted, the first page of results is returned. This value is obtained from the 'start' query parameter in the 'next_url' field of the operation response.

parameters

id
Required*
str
The resource instance URL-encoded CRN or GUID.
limit
int
Limit on how many items should be returned.

Possible values: value ≤ 100
Default: 100
start
str
An optional token that indicates the beginning of the page of results to be returned. Any additional query parameters are ignored if a page token is present. If omitted, the first page of results is returned. This value is obtained from the 'start' query parameter in the 'next_url' field of the operation response.

Example request

curl -X GET   https://resource-controller.cloud.ibm.com/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94/resource_keys   -H "Authorization: Bearer <IAM token>"

Example request

listResourceKeysForInstanceOptions := &resourcecontrollerv2.ListResourceKeysForInstanceOptions{
  ID: &instanceGUID,
}

pager, err := resourceControllerService.NewResourceKeysForInstancePager(listResourceKeysForInstanceOptions)
if err != nil {
  panic(err)
}

var allResults []resourcecontrollerv2.ResourceKey
for pager.HasNext() {
  nextPage, err := pager.GetNext()
  if err != nil {
    panic(err)
  }
  allResults = append(allResults, nextPage...)
}
b, _ := json.MarshalIndent(allResults, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

ListResourceKeysForInstanceOptions listResourceKeysForInstanceOptions = new ListResourceKeysForInstanceOptions.Builder()
  .id(instanceGuid)
  .build();

ResourceKeysForInstancePager pager = new ResourceKeysForInstancePager(resourceControllerService, listResourceKeysForInstanceOptions);
List<ResourceKey> allResults = new ArrayList<>();
while (pager.hasNext()) {
  List<ResourceKey> nextPage = pager.getNext();
  allResults.addAll(nextPage);
}

System.out.println(GsonSingleton.getGson().toJson(allResults));
Copy to clipboard

Example request

const params = {
  id: instanceGuid,
};

const allResults = [];
try {
  const pager = new ResourceControllerV2.ResourceKeysForInstancePager(
    resourceControllerService, params);
  while (pager.hasNext()) {
    const nextPage = await pager.getNext();
    expect(nextPage).not.toBeNull();
    allResults.push(...nextPage);
  }
  console.log(JSON.stringify(allResults, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

all_results = []
pager = ResourceKeysForInstancePager(
  client=resource_controller_service,
  id=instance_guid,
)
while pager.has_next():
  next_page = pager.get_next()
  assert next_page is not None
  all_results.extend(next_page)

print(json.dumps(all_results, indent=2))
Copy to clipboard

Response

Response Body

ResourceKeysList

A list of resource keys.

ResourceKeysList

A list of resource keys.

ResourceKeysList

A list of resource keys.

ResourceKeysList

A list of resource keys.

ResourceKeysList

A list of resource keys.

Status Code

200
The list of resource keys was successfully retrieved.
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.
429
Too many requests. Wait a few minutes and try again.
500
Your request could not be processed. Try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

Example responses

Status 200

{
  "rows_count": 1,
  "next_url": null,
  "resources": [
    {
      "id": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94:resource-key:23693f48-aaa2-4079-b0c7-334846eff8d0",
      "guid": "23693f48-aaa2-4079-b0c7-334846eff8d0",
      "url": "/v2/resource_keys/23693f48-aaa2-4079-b0c7-334846eff8d0",
      "created_at": "2018-07-02T22:03:43.837979455Z",
      "updated_at": "2018-07-02T22:03:43.837979455Z",
      "deleted_at": null,
      "created_by": "IBMid-5500093BHN",
      "updated_by": "IBMid-5500093BHN",
      "deleted_by": "",
      "source_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::",
      "role": "crn:v1:bluemix:public:iam::::serviceRole:Writer",
      "name": "my-instance-key-1",
      "parameters": {
        "role_crn": "crn:v1:bluemix:public:iam::::serviceRole:Writer"
      },
      "crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94:resource-key:23693f48-aaa2-4079-b0c7-334846eff8d0",
      "state": "active",
      "account_id": "4329073d16d2f3663f74bfa955259139",
      "resource_group_id": "0be5ad401ae913d8ff665d92680664ed",
      "resource_id": "dff97f5c-bc5e-4455-b470-411c3edbe49c",
      "credentials": {
        "apikey": "XXXX-YYYY-ZZZZ\"",
        "endpoints": "https://cos-service-armada-s.us-south.containers.mybluemix.net/endpoints",
        "iam_apikey_description": "Auto generated apikey during resource-key operation for Instance - crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::",
        "iam_apikey_name": "auto-generated-apikey-23693f48-aaa2-4079-b0c7-334846eff8d0",
        "iam_role_crn": "crn:v1:bluemix:public:iam::::serviceRole:Writer",
        "iam_serviceid_crn": "crn:v1:bluemix:public:iam-identity::a/4329073d16d2f3663f74bfa955259139::serviceid:ServiceId-64c29e4f-422d-468c-a11b-1a8f671b5c89",
        "resource_instance_id": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::"
      },
      "iam_compatible": true,
      "migrated": false,
      "resource_instance_url": "/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94"
    }
  ]
}
Copy to clipboard

Success example

{
  "rows_count": 1,
  "next_url": null,
  "resources": [
    {
      "id": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94:resource-key:23693f48-aaa2-4079-b0c7-334846eff8d0",
      "guid": "23693f48-aaa2-4079-b0c7-334846eff8d0",
      "url": "/v2/resource_keys/23693f48-aaa2-4079-b0c7-334846eff8d0",
      "created_at": "2018-07-02T22:03:43.837979455Z",
      "updated_at": "2018-07-02T22:03:43.837979455Z",
      "deleted_at": null,
      "created_by": "IBMid-5500093BHN",
      "updated_by": "IBMid-5500093BHN",
      "deleted_by": "",
      "source_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::",
      "role": "crn:v1:bluemix:public:iam::::serviceRole:Writer",
      "name": "my-instance-key-1",
      "parameters": {
        "role_crn": "crn:v1:bluemix:public:iam::::serviceRole:Writer"
      },
      "crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94:resource-key:23693f48-aaa2-4079-b0c7-334846eff8d0",
      "state": "active",
      "account_id": "4329073d16d2f3663f74bfa955259139",
      "resource_group_id": "0be5ad401ae913d8ff665d92680664ed",
      "resource_id": "dff97f5c-bc5e-4455-b470-411c3edbe49c",
      "credentials": {
        "apikey": "XXXX-YYYY-ZZZZ\"",
        "endpoints": "https://cos-service-armada-s.us-south.containers.mybluemix.net/endpoints",
        "iam_apikey_description": "Auto generated apikey during resource-key operation for Instance - crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::",
        "iam_apikey_name": "auto-generated-apikey-23693f48-aaa2-4079-b0c7-334846eff8d0",
        "iam_role_crn": "crn:v1:bluemix:public:iam::::serviceRole:Writer",
        "iam_serviceid_crn": "crn:v1:bluemix:public:iam-identity::a/4329073d16d2f3663f74bfa955259139::serviceid:ServiceId-64c29e4f-422d-468c-a11b-1a8f671b5c89",
        "resource_instance_id": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::"
      },
      "iam_compatible": true,
      "migrated": false,
      "resource_instance_url": "/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94"
    }
  ]
}
Copy to clipboard

Locks a resource instance. A locked instance can not be updated or deleted. It does not affect actions performed on child resources like keys.

POST /v2/resource_instances/{id}/lock

(resourceController *ResourceControllerV2) LockResourceInstance(lockResourceInstanceOptions *LockResourceInstanceOptions) (result *ResourceInstance, response *core.DetailedResponse, err error)

(resourceController *ResourceControllerV2) LockResourceInstanceWithContext(ctx context.Context, lockResourceInstanceOptions *LockResourceInstanceOptions) (result *ResourceInstance, response *core.DetailedResponse, err error)

ServiceCall<ResourceInstance> lockResourceInstance(LockResourceInstanceOptions lockResourceInstanceOptions)
Copy to clipboard

lockResourceInstance(params)

lock_resource_instance(
        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.instance.update

Auditing

Calling this method generates the following auditing event.

resource-controller.instance.update

Request

Instantiate the LockResourceInstanceOptions struct and set the fields to provide parameter values for the LockResourceInstance method.

Use the LockResourceInstanceOptions.Builder to create a LockResourceInstanceOptions object that contains the parameter values for the lockResourceInstance method.

Path Parameters

id
Required*
string
The resource instance URL-encoded CRN or GUID.

parameter

WithContext method only

LockResourceInstanceOptions

The LockResourceInstance options.

LockResourceInstanceOptions

The lockResourceInstance options.

parameters

id
Required*
string
The resource instance URL-encoded CRN or GUID.

parameters

id
Required*
str
The resource instance URL-encoded CRN or GUID.

Example request

curl -X POST   https://resource-controller.cloud.ibm.com/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94/lock   -H "Authorization: Bearer <IAM token>"

Example request

lockResourceInstanceOptions := resourceControllerService.NewLockResourceInstanceOptions(
  instanceGUID,
)

resourceInstance, response, err := resourceControllerService.LockResourceInstance(lockResourceInstanceOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(resourceInstance, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

LockResourceInstanceOptions lockResourceInstanceOptions = new LockResourceInstanceOptions.Builder()
  .id(instanceGuid)
  .build();

Response<ResourceInstance> response = resourceControllerService.lockResourceInstance(lockResourceInstanceOptions).execute();
ResourceInstance resourceInstance = response.getResult();

System.out.println(resourceInstance);

Example request

const params = {
  id: instanceGuid,
};

try {
  const res = await resourceControllerService.lockResourceInstance(params);
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

resource_instance = resource_controller_service.lock_resource_instance(
  id=instance_guid
).get_result()

print(json.dumps(resource_instance, indent=2))
Copy to clipboard

Response

Response Body

ResourceInstance

A resource instance.

ResourceInstance

A resource instance.

ResourceInstance

A resource instance.

ResourceInstance

A resource instance.

ResourceInstance

A resource instance.

Status Code

200
Successfully locked the instance.
400
The request could not be understood due to malformed syntax.
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.
422
The request could not be processed.
429
Too many requests. Wait a few minutes and try again.
500
Your request could not be processed. 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": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::",
  "guid": "8d7af921-b136-4078-9666-081bd8470d94",
  "url": "/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94",
  "created_at": "2018-04-19T00:18:53.302077457Z",
  "updated_at": "2018-04-19T00:18:53.302077457Z",
  "deleted_at": null,
  "created_by": "IBMid-5500093BHN",
  "updated_by": "IBMid-5500093BHN",
  "deleted_by": "",
  "scheduled_reclaim_at": null,
  "restored_at": null,
  "scheduled_reclaim_by": "",
  "restored_by": "",
  "name": "my-instance",
  "region_id": "global",
  "account_id": "4329073d16d2f3663f74bfa955259139",
  "resource_plan_id": "744bfc56-d12c-4866-88d5-dac9139e0e5d",
  "resource_group_id": "0be5ad401ae913d8ff665d92680664ed",
  "resource_group_crn": "crn:v1:bluemix:public:resource-controller::a/4329073d16d2f3663f74bfa955259139::resource-group:0be5ad401ae913d8ff665d92680664ed",
  "target_crn": "crn:v1:bluemix:public:resource-catalog::a/9e16d1fed8aa7e1bd73e7a9d23434a5a::deployment:2fdf0c08-2d32-4f46-84b5-32e0c92fffd8%3Aglobal",
  "crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::",
  "allow_cleanup": false,
  "state": "active",
  "type": "service_instance",
  "resource_id": "dff97f5c-bc5e-4455-b470-411c3edbe49c",
  "dashboard_url": "/objectstorage/crn%3Av1%3Abluemix%3Apublic%3Acloud-object-storage%3Aglobal%3Aa%2F4329073d16d2f3663f74bfa955259139%3A8d7af921-b136-4078-9666-081bd8470d94%3A%3A",
  "last_operation": null,
  "resource_keys_url": "/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94/resource_keys",
  "plan_history": [
    {
      "resource_plan_id": "2fdf0c08-2d32-4f46-84b5-32e0c92fffd8",
      "start_date": "2018-04-19T00:18:53.302077457Z"
    }
  ],
  "migrated": false,
  "controlled_by": "",
  "locked": true
}
Copy to clipboard

Success example

{
  "id": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::",
  "guid": "8d7af921-b136-4078-9666-081bd8470d94",
  "url": "/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94",
  "created_at": "2018-04-19T00:18:53.302077457Z",
  "updated_at": "2018-04-19T00:18:53.302077457Z",
  "deleted_at": null,
  "created_by": "IBMid-5500093BHN",
  "updated_by": "IBMid-5500093BHN",
  "deleted_by": "",
  "scheduled_reclaim_at": null,
  "restored_at": null,
  "scheduled_reclaim_by": "",
  "restored_by": "",
  "name": "my-instance",
  "region_id": "global",
  "account_id": "4329073d16d2f3663f74bfa955259139",
  "resource_plan_id": "744bfc56-d12c-4866-88d5-dac9139e0e5d",
  "resource_group_id": "0be5ad401ae913d8ff665d92680664ed",
  "resource_group_crn": "crn:v1:bluemix:public:resource-controller::a/4329073d16d2f3663f74bfa955259139::resource-group:0be5ad401ae913d8ff665d92680664ed",
  "target_crn": "crn:v1:bluemix:public:resource-catalog::a/9e16d1fed8aa7e1bd73e7a9d23434a5a::deployment:2fdf0c08-2d32-4f46-84b5-32e0c92fffd8%3Aglobal",
  "crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::",
  "allow_cleanup": false,
  "state": "active",
  "type": "service_instance",
  "resource_id": "dff97f5c-bc5e-4455-b470-411c3edbe49c",
  "dashboard_url": "/objectstorage/crn%3Av1%3Abluemix%3Apublic%3Acloud-object-storage%3Aglobal%3Aa%2F4329073d16d2f3663f74bfa955259139%3A8d7af921-b136-4078-9666-081bd8470d94%3A%3A",
  "last_operation": null,
  "resource_keys_url": "/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94/resource_keys",
  "plan_history": [
    {
      "resource_plan_id": "2fdf0c08-2d32-4f46-84b5-32e0c92fffd8",
      "start_date": "2018-04-19T00:18:53.302077457Z"
    }
  ],
  "migrated": false,
  "controlled_by": "",
  "locked": true
}
Copy to clipboard

Unlock a resource instance to update or delete it. Unlocking a resource instance does not affect child resources like keys.

DELETE /v2/resource_instances/{id}/lock

(resourceController *ResourceControllerV2) UnlockResourceInstance(unlockResourceInstanceOptions *UnlockResourceInstanceOptions) (result *ResourceInstance, response *core.DetailedResponse, err error)

(resourceController *ResourceControllerV2) UnlockResourceInstanceWithContext(ctx context.Context, unlockResourceInstanceOptions *UnlockResourceInstanceOptions) (result *ResourceInstance, response *core.DetailedResponse, err error)

ServiceCall<ResourceInstance> unlockResourceInstance(UnlockResourceInstanceOptions unlockResourceInstanceOptions)
Copy to clipboard

unlockResourceInstance(params)

unlock_resource_instance(
        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.instance.update

Auditing

Calling this method generates the following auditing event.

resource-controller.instance.update

Request

Instantiate the UnlockResourceInstanceOptions struct and set the fields to provide parameter values for the UnlockResourceInstance method.

Use the UnlockResourceInstanceOptions.Builder to create a UnlockResourceInstanceOptions object that contains the parameter values for the unlockResourceInstance method.

Path Parameters

id
Required*
string
The resource instance URL-encoded CRN or GUID.

parameter

WithContext method only

UnlockResourceInstanceOptions

The UnlockResourceInstance options.

UnlockResourceInstanceOptions

The unlockResourceInstance options.

parameters

id
Required*
string
The resource instance URL-encoded CRN or GUID.

parameters

id
Required*
str
The resource instance URL-encoded CRN or GUID.

Example request

curl -X DELETE   https://resource-controller.cloud.ibm.com/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94/lock   -H "Authorization: Bearer <IAM token>"

Example request

unlockResourceInstanceOptions := resourceControllerService.NewUnlockResourceInstanceOptions(
  instanceGUID,
)

resourceInstance, response, err := resourceControllerService.UnlockResourceInstance(unlockResourceInstanceOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(resourceInstance, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

UnlockResourceInstanceOptions unlockResourceInstanceOptions = new UnlockResourceInstanceOptions.Builder()
  .id(instanceGuid)
  .build();

Response<ResourceInstance> response = resourceControllerService.unlockResourceInstance(unlockResourceInstanceOptions).execute();
ResourceInstance resourceInstance = response.getResult();

System.out.println(resourceInstance);

Example request

const params = {
  id: instanceGuid,
};

try {
  const res = await resourceControllerService.unlockResourceInstance(params);
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

resource_instance = resource_controller_service.unlock_resource_instance(
  id=instance_guid
).get_result()

print(json.dumps(resource_instance, indent=2))
Copy to clipboard

Response

Response Body

ResourceInstance

A resource instance.

ResourceInstance

A resource instance.

ResourceInstance

A resource instance.

ResourceInstance

A resource instance.

ResourceInstance

A resource instance.

Status Code

200
Successfully unlocked the instance.
400
The request could not be understood due to malformed syntax.
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.
422
The request could not be processed.
429
Too many requests. Wait a few minutes and try again.
500
Your request could not be processed. 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": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::",
  "guid": "8d7af921-b136-4078-9666-081bd8470d94",
  "url": "/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94",
  "created_at": "2018-04-19T00:18:53.302077457Z",
  "updated_at": "2018-04-19T00:18:53.302077457Z",
  "deleted_at": null,
  "created_by": "IBMid-5500093BHN",
  "updated_by": "IBMid-5500093BHN",
  "deleted_by": "",
  "scheduled_reclaim_at": null,
  "restored_at": null,
  "scheduled_reclaim_by": "",
  "restored_by": "",
  "name": "my-instance",
  "region_id": "global",
  "account_id": "4329073d16d2f3663f74bfa955259139",
  "resource_plan_id": "744bfc56-d12c-4866-88d5-dac9139e0e5d",
  "resource_group_id": "0be5ad401ae913d8ff665d92680664ed",
  "resource_group_crn": "crn:v1:bluemix:public:resource-controller::a/4329073d16d2f3663f74bfa955259139::resource-group:0be5ad401ae913d8ff665d92680664ed",
  "target_crn": "crn:v1:bluemix:public:resource-catalog::a/9e16d1fed8aa7e1bd73e7a9d23434a5a::deployment:2fdf0c08-2d32-4f46-84b5-32e0c92fffd8%3Aglobal",
  "crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::",
  "allow_cleanup": false,
  "state": "active",
  "type": "service_instance",
  "resource_id": "dff97f5c-bc5e-4455-b470-411c3edbe49c",
  "dashboard_url": "/objectstorage/crn%3Av1%3Abluemix%3Apublic%3Acloud-object-storage%3Aglobal%3Aa%2F4329073d16d2f3663f74bfa955259139%3A8d7af921-b136-4078-9666-081bd8470d94%3A%3A",
  "last_operation": null,
  "resource_keys_url": "/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94/resource_keys",
  "plan_history": [
    {
      "resource_plan_id": "2fdf0c08-2d32-4f46-84b5-32e0c92fffd8",
      "start_date": "2018-04-19T00:18:53.302077457Z"
    }
  ],
  "migrated": false,
  "controlled_by": "",
  "locked": false
}
Copy to clipboard

Success example

{
  "id": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::",
  "guid": "8d7af921-b136-4078-9666-081bd8470d94",
  "url": "/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94",
  "created_at": "2018-04-19T00:18:53.302077457Z",
  "updated_at": "2018-04-19T00:18:53.302077457Z",
  "deleted_at": null,
  "created_by": "IBMid-5500093BHN",
  "updated_by": "IBMid-5500093BHN",
  "deleted_by": "",
  "scheduled_reclaim_at": null,
  "restored_at": null,
  "scheduled_reclaim_by": "",
  "restored_by": "",
  "name": "my-instance",
  "region_id": "global",
  "account_id": "4329073d16d2f3663f74bfa955259139",
  "resource_plan_id": "744bfc56-d12c-4866-88d5-dac9139e0e5d",
  "resource_group_id": "0be5ad401ae913d8ff665d92680664ed",
  "resource_group_crn": "crn:v1:bluemix:public:resource-controller::a/4329073d16d2f3663f74bfa955259139::resource-group:0be5ad401ae913d8ff665d92680664ed",
  "target_crn": "crn:v1:bluemix:public:resource-catalog::a/9e16d1fed8aa7e1bd73e7a9d23434a5a::deployment:2fdf0c08-2d32-4f46-84b5-32e0c92fffd8%3Aglobal",
  "crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::",
  "allow_cleanup": false,
  "state": "active",
  "type": "service_instance",
  "resource_id": "dff97f5c-bc5e-4455-b470-411c3edbe49c",
  "dashboard_url": "/objectstorage/crn%3Av1%3Abluemix%3Apublic%3Acloud-object-storage%3Aglobal%3Aa%2F4329073d16d2f3663f74bfa955259139%3A8d7af921-b136-4078-9666-081bd8470d94%3A%3A",
  "last_operation": null,
  "resource_keys_url": "/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94/resource_keys",
  "plan_history": [
    {
      "resource_plan_id": "2fdf0c08-2d32-4f46-84b5-32e0c92fffd8",
      "start_date": "2018-04-19T00:18:53.302077457Z"
    }
  ],
  "migrated": false,
  "controlled_by": "",
  "locked": false
}
Copy to clipboard

Cancel the in progress last operation of the resource instance. This is applicable for instances where the in progress last operation is cancelable.

Cancel the in progress last operation of the resource instance. After successful cancellation, the resource instance is removed.

DELETE /v2/resource_instances/{id}/last_operation

(resourceController *ResourceControllerV2) CancelLastopResourceInstance(cancelLastopResourceInstanceOptions *CancelLastopResourceInstanceOptions) (result *ResourceInstance, response *core.DetailedResponse, err error)

(resourceController *ResourceControllerV2) CancelLastopResourceInstanceWithContext(ctx context.Context, cancelLastopResourceInstanceOptions *CancelLastopResourceInstanceOptions) (result *ResourceInstance, response *core.DetailedResponse, err error)

ServiceCall<ResourceInstance> cancelLastopResourceInstance(CancelLastopResourceInstanceOptions cancelLastopResourceInstanceOptions)
Copy to clipboard

cancelLastopResourceInstance(params)

cancel_lastop_resource_instance(
        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.instance.delete

Auditing

Calling this method generates the following auditing event.

resource-controller.instance.delete

Request

Instantiate the CancelLastopResourceInstanceOptions struct and set the fields to provide parameter values for the CancelLastopResourceInstance method.

Use the CancelLastopResourceInstanceOptions.Builder to create a CancelLastopResourceInstanceOptions object that contains the parameter values for the cancelLastopResourceInstance method.

Path Parameters

id
Required*
string
The resource instance URL-encoded CRN or GUID.

parameter

WithContext method only

CancelLastopResourceInstanceOptions

The CancelLastopResourceInstance options.

CancelLastopResourceInstanceOptions

The cancelLastopResourceInstance options.

parameters

id
Required*
string
The resource instance URL-encoded CRN or GUID.

parameters

id
Required*
str
The resource instance URL-encoded CRN or GUID.

Example request

curl -X DELETE   https://resource-controller.cloud.ibm.com/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94/last_operation   -H 'Authorization: Bearer <>'

Example request

cancelLastopResourceInstanceOptions := resourceControllerService.NewCancelLastopResourceInstanceOptions(
  instanceGUID,
)

resourceInstance, response, err := resourceControllerService.CancelLastopResourceInstance(cancelLastopResourceInstanceOptions)
if err != nil {
  fmt.Println("The instance is not cancelable.")
} else {
  b, _ := json.MarshalIndent(resourceInstance, "", "  ")
  fmt.Println(string(b))
}
Copy to clipboard

Example request

resource_instance = resource_controller_service.cancel_lastop_resource_instance(
  id=instance_guid
).get_result()
print(json.dumps(resource_instance, indent=2))
Copy to clipboard

Response

Response Body

ResourceInstance

A resource instance.

ResourceInstance

A resource instance.

ResourceInstance

A resource instance.

ResourceInstance

A resource instance.

ResourceInstance

A resource instance.

Status Code

200
Successfully canceled the in progress last operation of the resource instance.
202
Last operation cancel request accepted.
400
The request could not be understood due to malformed syntax.
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.
422
The request could not be processed.
429
Too many requests. Wait a few minutes and try again.
500
Your request could not be processed. Try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.
502
The Server has encountered BadGateway error while connecting to the external components. 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": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::",
  "guid": "8d7af921-b136-4078-9666-081bd8470d94",
  "url": "/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94",
  "created_at": "2018-04-19T00:18:53.302077457Z",
  "updated_at": "2018-04-19T00:22:53.302077457Z",
  "deleted_at": "2018-04-19T00:22:53.302077457Z",
  "created_by": "IBMid-5401023BHN",
  "updated_by": "IBMid-5500093BHN",
  "deleted_by": "IBMid-5500093BHN",
  "scheduled_reclaim_at": null,
  "restored_at": null,
  "scheduled_reclaim_by": "",
  "restored_by": "",
  "name": "my-instance",
  "region_id": "global",
  "account_id": "4329073d16d2f3663f74bfa955259139",
  "resource_plan_id": "744bfc56-d12c-4866-88d5-dac9139e0e5d",
  "resource_group_id": "0be5ad401ae913d8ff665d92680664ed",
  "resource_group_crn": "crn:v1:bluemix:public:resource-controller::a/4329073d16d2f3663f74bfa955259139::resource-group:0be5ad401ae913d8ff665d92680664ed",
  "target_crn": "crn:v1:bluemix:public:resource-catalog::a/9e16d1fed8aa7e1bd73e7a9d23434a5a::deployment:2fdf0c08-2d32-4f46-84b5-32e0c92fffd8%3Aglobal",
  "crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::",
  "allow_cleanup": false,
  "state": "removed",
  "type": "service_instance",
  "resource_id": "dff97f5c-bc5e-4455-b470-411c3edbe49c",
  "dashboard_url": "/objectstorage/crn%3Av1%3Abluemix%3Apublic%3Acloud-object-storage%3Aglobal%3Aa%2F4329073d16d2f3663f74bfa955259139%3A8d7af921-b136-4078-9666-081bd8470d94%3A%3A",
  "last_operation": {
    "type": "cancel",
    "state": "succeeded",
    "async": false,
    "description": "Last operation canceled",
    "cancelable": true,
    "poll": true
  },
  "resource_keys_url": "/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94/resource_keys",
  "plan_history": [
    {
      "resource_plan_id": "2fdf0c08-2d32-4f46-84b5-32e0c92fffd8",
      "start_date": "2018-04-19T00:18:53.302077457Z"
    }
  ],
  "migrated": false,
  "controlled_by": "",
  "locked": false
}
Copy to clipboard

Success example

{
  "id": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::",
  "guid": "8d7af921-b136-4078-9666-081bd8470d94",
  "url": "/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94",
  "created_at": "2018-04-19T00:18:53.302077457Z",
  "updated_at": "2018-04-19T00:22:53.302077457Z",
  "deleted_at": "2018-04-19T00:22:53.302077457Z",
  "created_by": "IBMid-5401023BHN",
  "updated_by": "IBMid-5500093BHN",
  "deleted_by": "IBMid-5500093BHN",
  "scheduled_reclaim_at": null,
  "restored_at": null,
  "scheduled_reclaim_by": "",
  "restored_by": "",
  "name": "my-instance",
  "region_id": "global",
  "account_id": "4329073d16d2f3663f74bfa955259139",
  "resource_plan_id": "744bfc56-d12c-4866-88d5-dac9139e0e5d",
  "resource_group_id": "0be5ad401ae913d8ff665d92680664ed",
  "resource_group_crn": "crn:v1:bluemix:public:resource-controller::a/4329073d16d2f3663f74bfa955259139::resource-group:0be5ad401ae913d8ff665d92680664ed",
  "target_crn": "crn:v1:bluemix:public:resource-catalog::a/9e16d1fed8aa7e1bd73e7a9d23434a5a::deployment:2fdf0c08-2d32-4f46-84b5-32e0c92fffd8%3Aglobal",
  "crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::",
  "allow_cleanup": false,
  "state": "removed",
  "type": "service_instance",
  "resource_id": "dff97f5c-bc5e-4455-b470-411c3edbe49c",
  "dashboard_url": "/objectstorage/crn%3Av1%3Abluemix%3Apublic%3Acloud-object-storage%3Aglobal%3Aa%2F4329073d16d2f3663f74bfa955259139%3A8d7af921-b136-4078-9666-081bd8470d94%3A%3A",
  "last_operation": {
    "type": "cancel",
    "state": "succeeded",
    "async": false,
    "description": "Last operation canceled",
    "cancelable": true,
    "poll": true
  },
  "resource_keys_url": "/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94/resource_keys",
  "plan_history": [
    {
      "resource_plan_id": "2fdf0c08-2d32-4f46-84b5-32e0c92fffd8",
      "start_date": "2018-04-19T00:18:53.302077457Z"
    }
  ],
  "migrated": false,
  "controlled_by": "",
  "locked": false
}
Copy to clipboard

Status 202

{
  "id": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::",
  "guid": "8d7af921-b136-4078-9666-081bd8470d94",
  "url": "/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94",
  "created_at": "2018-04-19T00:18:53.302077457Z",
  "updated_at": "2018-04-19T00:22:53.302077457Z",
  "deleted_at": null,
  "created_by": "IBMid-5500093BHN",
  "updated_by": "IBMid-5500093BHN",
  "deleted_by": "",
  "scheduled_reclaim_at": null,
  "restored_at": null,
  "scheduled_reclaim_by": "",
  "restored_by": "",
  "name": "my-instance",
  "region_id": "global",
  "account_id": "4329073d16d2f3663f74bfa955259139",
  "resource_plan_id": "744bfc56-d12c-4866-88d5-dac9139e0e5d",
  "resource_group_id": "0be5ad401ae913d8ff665d92680664ed",
  "resource_group_crn": "crn:v1:bluemix:public:resource-controller::a/4329073d16d2f3663f74bfa955259139::resource-group:0be5ad401ae913d8ff665d92680664ed",
  "target_crn": "crn:v1:bluemix:public:resource-catalog::a/9e16d1fed8aa7e1bd73e7a9d23434a5a::deployment:2fdf0c08-2d32-4f46-84b5-32e0c92fffd8%3Aglobal",
  "crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::",
  "allow_cleanup": false,
  "state": "provisioning",
  "type": "service_instance",
  "resource_id": "dff97f5c-bc5e-4455-b470-411c3edbe49c",
  "dashboard_url": "/objectstorage/crn%3Av1%3Abluemix%3Apublic%3Acloud-object-storage%3Aglobal%3Aa%2F4329073d16d2f3663f74bfa955259139%3A8d7af921-b136-4078-9666-081bd8470d94%3A%3A",
  "last_operation": {
    "type": "cancel",
    "state": "in progress",
    "async": true,
    "description": "Cancelation in progress",
    "cancelable": true,
    "poll": true
  },
  "resource_keys_url": "/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94/resource_keys",
  "plan_history": [
    {
      "resource_plan_id": "2fdf0c08-2d32-4f46-84b5-32e0c92fffd8",
      "start_date": "2018-04-19T00:18:53.302077457Z"
    }
  ],
  "migrated": false,
  "controlled_by": "",
  "locked": false
}
Copy to clipboard

Success example

{
  "id": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::",
  "guid": "8d7af921-b136-4078-9666-081bd8470d94",
  "url": "/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94",
  "created_at": "2018-04-19T00:18:53.302077457Z",
  "updated_at": "2018-04-19T00:22:53.302077457Z",
  "deleted_at": null,
  "created_by": "IBMid-5500093BHN",
  "updated_by": "IBMid-5500093BHN",
  "deleted_by": "",
  "scheduled_reclaim_at": null,
  "restored_at": null,
  "scheduled_reclaim_by": "",
  "restored_by": "",
  "name": "my-instance",
  "region_id": "global",
  "account_id": "4329073d16d2f3663f74bfa955259139",
  "resource_plan_id": "744bfc56-d12c-4866-88d5-dac9139e0e5d",
  "resource_group_id": "0be5ad401ae913d8ff665d92680664ed",
  "resource_group_crn": "crn:v1:bluemix:public:resource-controller::a/4329073d16d2f3663f74bfa955259139::resource-group:0be5ad401ae913d8ff665d92680664ed",
  "target_crn": "crn:v1:bluemix:public:resource-catalog::a/9e16d1fed8aa7e1bd73e7a9d23434a5a::deployment:2fdf0c08-2d32-4f46-84b5-32e0c92fffd8%3Aglobal",
  "crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::",
  "allow_cleanup": false,
  "state": "provisioning",
  "type": "service_instance",
  "resource_id": "dff97f5c-bc5e-4455-b470-411c3edbe49c",
  "dashboard_url": "/objectstorage/crn%3Av1%3Abluemix%3Apublic%3Acloud-object-storage%3Aglobal%3Aa%2F4329073d16d2f3663f74bfa955259139%3A8d7af921-b136-4078-9666-081bd8470d94%3A%3A",
  "last_operation": {
    "type": "cancel",
    "state": "in progress",
    "async": true,
    "description": "Cancelation in progress",
    "cancelable": true,
    "poll": true
  },
  "resource_keys_url": "/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94/resource_keys",
  "plan_history": [
    {
      "resource_plan_id": "2fdf0c08-2d32-4f46-84b5-32e0c92fffd8",
      "start_date": "2018-04-19T00:18:53.302077457Z"
    }
  ],
  "migrated": false,
  "controlled_by": "",
  "locked": false
}
Copy to clipboard

View all of the resource keys that exist for all of your resource instances.

GET /v2/resource_keys

(resourceController *ResourceControllerV2) ListResourceKeys(listResourceKeysOptions *ListResourceKeysOptions) (result *ResourceKeysList, response *core.DetailedResponse, err error)

(resourceController *ResourceControllerV2) ListResourceKeysWithContext(ctx context.Context, listResourceKeysOptions *ListResourceKeysOptions) (result *ResourceKeysList, response *core.DetailedResponse, err error)

ServiceCall<ResourceKeysList> listResourceKeys(ListResourceKeysOptions listResourceKeysOptions)
Copy to clipboard

listResourceKeys(params)

list_resource_keys(
        self,
        *,
        guid: Optional[str] = None,
        name: Optional[str] = None,
        resource_group_id: Optional[str] = None,
        resource_id: Optional[str] = None,
        limit: Optional[int] = None,
        start: Optional[str] = None,
        updated_from: Optional[str] = None,
        updated_to: Optional[str] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

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.key.retrieve

Request

Instantiate the ListResourceKeysOptions struct and set the fields to provide parameter values for the ListResourceKeys method.

Use the ListResourceKeysOptions.Builder to create a ListResourceKeysOptions object that contains the parameter values for the listResourceKeys method.

Query Parameters

guid
string
The GUID of the key.
name
string
The human-readable name of the key.
resource_group_id
string
The ID of the resource group.
resource_id
string
The unique ID of the offering. This value is provided by and stored in the global catalog.
limit
integer
Limit on how many items should be returned.

Possible values: value ≤ 100
Default: 100
start
string
An optional token that indicates the beginning of the page of results to be returned. Any additional query parameters are ignored if a page token is present. If omitted, the first page of results is returned. This value is obtained from the 'start' query parameter in the 'next_url' field of the operation response.
updated_from
string
Start date inclusive filter.

Example: 2021-01-01
updated_to
string
End date inclusive filter.

Example: 2021-01-01

parameter

WithContext method only

ListResourceKeysOptions

The ListResourceKeys options.

ListResourceKeysOptions

The listResourceKeys options.

parameters

guid
string
The GUID of the key.
name
string
The human-readable name of the key.
resourceGroupId
string
The ID of the resource group.
resourceId
string
The unique ID of the offering. This value is provided by and stored in the global catalog.
limit
number
Limit on how many items should be returned.

Possible values: value ≤ 100
Default: 100
start
string
An optional token that indicates the beginning of the page of results to be returned. Any additional query parameters are ignored if a page token is present. If omitted, the first page of results is returned. This value is obtained from the 'start' query parameter in the 'next_url' field of the operation response.
updatedFrom
string
Start date inclusive filter.
Examples:
updatedTo
string
End date inclusive filter.
Examples:

parameters

guid
str
The GUID of the key.
name
str
The human-readable name of the key.
resource_group_id
str
The ID of the resource group.
resource_id
str
The unique ID of the offering. This value is provided by and stored in the global catalog.
limit
int
Limit on how many items should be returned.

Possible values: value ≤ 100
Default: 100
start
str
An optional token that indicates the beginning of the page of results to be returned. Any additional query parameters are ignored if a page token is present. If omitted, the first page of results is returned. This value is obtained from the 'start' query parameter in the 'next_url' field of the operation response.
updated_from
str
Start date inclusive filter.
Examples:
updated_to
str
End date inclusive filter.
Examples:

Example request

curl -X GET https://resource-controller.cloud.ibm.com/v2/resource_keys -H "Authorization: Bearer <IAM token>"

Example request

listResourceKeysOptions := &resourcecontrollerv2.ListResourceKeysOptions{
  Name: &keyName,
}

pager, err := resourceControllerService.NewResourceKeysPager(listResourceKeysOptions)
if err != nil {
  panic(err)
}

var allResults []resourcecontrollerv2.ResourceKey
for pager.HasNext() {
  nextPage, err := pager.GetNext()
  if err != nil {
    panic(err)
  }
  allResults = append(allResults, nextPage...)
}
b, _ := json.MarshalIndent(allResults, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

ListResourceKeysOptions listResourceKeysOptions = new ListResourceKeysOptions.Builder()
  .name(keyName)
  .build();

ResourceKeysPager pager = new ResourceKeysPager(resourceControllerService, listResourceKeysOptions);
List<ResourceKey> allResults = new ArrayList<>();
while (pager.hasNext()) {
  List<ResourceKey> nextPage = pager.getNext();
  allResults.addAll(nextPage);
}

System.out.println(GsonSingleton.getGson().toJson(allResults));
Copy to clipboard

Example request

const params = {
  name: keyName,
};

const allResults = [];
try {
  const pager = new ResourceControllerV2.ResourceKeysPager(resourceControllerService, params);
  while (pager.hasNext()) {
    const nextPage = await pager.getNext();
    expect(nextPage).not.toBeNull();
    allResults.push(...nextPage);
  }
  console.log(JSON.stringify(allResults, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

all_results = []
pager = ResourceKeysPager(
  client=resource_controller_service,
  name=key_name,
)
while pager.has_next():
  next_page = pager.get_next()
  assert next_page is not None
  all_results.extend(next_page)

print(json.dumps(all_results, indent=2))
Copy to clipboard

Response

Response Body

ResourceKeysList

A list of resource keys.

ResourceKeysList

A list of resource keys.

ResourceKeysList

A list of resource keys.

ResourceKeysList

A list of resource keys.

ResourceKeysList

A list of resource keys.

Status Code

200
The list of resource keys was successfully retrieved.
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.
429
Too many requests. Wait a few minutes and try again.
500
Your request could not be processed. Try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

Example responses

Status 200: Non-redacted credential example

{
  "rows_count": 1,
  "next_url": null,
  "resources": [
    {
      "id": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94:resource-key:23693f48-aaa2-4079-b0c7-334846eff8d0",
      "guid": "23693f48-aaa2-4079-b0c7-334846eff8d0",
      "url": "/v2/resource_keys/23693f48-aaa2-4079-b0c7-334846eff8d0",
      "created_at": "2018-07-02T22:03:43.837979455Z",
      "updated_at": "2018-07-02T22:03:43.837979455Z",
      "deleted_at": null,
      "created_by": "IBMid-5500093BHN",
      "updated_by": "IBMid-5500093BHN",
      "deleted_by": "",
      "source_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::",
      "role": "crn:v1:bluemix:public:iam::::serviceRole:Writer",
      "name": "my-instance-key-1",
      "parameters": {
        "role_crn": "crn:v1:bluemix:public:iam::::serviceRole:Writer"
      },
      "crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94:resource-key:23693f48-aaa2-4079-b0c7-334846eff8d0",
      "state": "active",
      "account_id": "4329073d16d2f3663f74bfa955259139",
      "resource_group_id": "0be5ad401ae913d8ff665d92680664ed",
      "resource_id": "dff97f5c-bc5e-4455-b470-411c3edbe49c",
      "credentials": {
        "apikey": "XXXX-YYYY-ZZZZ\"",
        "endpoints": "https://cos-service-armada-s.us-south.containers.mybluemix.net/endpoints",
        "iam_apikey_description": "Auto generated apikey during resource-key operation for Instance - crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::",
        "iam_apikey_name": "auto-generated-apikey-23693f48-aaa2-4079-b0c7-334846eff8d0",
        "iam_role_crn": "crn:v1:bluemix:public:iam::::serviceRole:Writer",
        "iam_serviceid_crn": "crn:v1:bluemix:public:iam-identity::a/4329073d16d2f3663f74bfa955259139::serviceid:ServiceId-64c29e4f-422d-468c-a11b-1a8f671b5c89",
        "resource_instance_id": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::"
      },
      "iam_compatible": true,
      "migrated": false,
      "resource_instance_url": "/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94"
    }
  ]
}
Copy to clipboard

Success example: Non-redacted credential example

{
  "rows_count": 1,
  "next_url": null,
  "resources": [
    {
      "id": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94:resource-key:23693f48-aaa2-4079-b0c7-334846eff8d0",
      "guid": "23693f48-aaa2-4079-b0c7-334846eff8d0",
      "url": "/v2/resource_keys/23693f48-aaa2-4079-b0c7-334846eff8d0",
      "created_at": "2018-07-02T22:03:43.837979455Z",
      "updated_at": "2018-07-02T22:03:43.837979455Z",
      "deleted_at": null,
      "created_by": "IBMid-5500093BHN",
      "updated_by": "IBMid-5500093BHN",
      "deleted_by": "",
      "source_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::",
      "role": "crn:v1:bluemix:public:iam::::serviceRole:Writer",
      "name": "my-instance-key-1",
      "parameters": {
        "role_crn": "crn:v1:bluemix:public:iam::::serviceRole:Writer"
      },
      "crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94:resource-key:23693f48-aaa2-4079-b0c7-334846eff8d0",
      "state": "active",
      "account_id": "4329073d16d2f3663f74bfa955259139",
      "resource_group_id": "0be5ad401ae913d8ff665d92680664ed",
      "resource_id": "dff97f5c-bc5e-4455-b470-411c3edbe49c",
      "credentials": {
        "apikey": "XXXX-YYYY-ZZZZ\"",
        "endpoints": "https://cos-service-armada-s.us-south.containers.mybluemix.net/endpoints",
        "iam_apikey_description": "Auto generated apikey during resource-key operation for Instance - crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::",
        "iam_apikey_name": "auto-generated-apikey-23693f48-aaa2-4079-b0c7-334846eff8d0",
        "iam_role_crn": "crn:v1:bluemix:public:iam::::serviceRole:Writer",
        "iam_serviceid_crn": "crn:v1:bluemix:public:iam-identity::a/4329073d16d2f3663f74bfa955259139::serviceid:ServiceId-64c29e4f-422d-468c-a11b-1a8f671b5c89",
        "resource_instance_id": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::"
      },
      "iam_compatible": true,
      "migrated": false,
      "resource_instance_url": "/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94"
    }
  ]
}
Copy to clipboard

Status 200: Credential REDACTED_EXPLICIT example

{
  "rows_count": 1,
  "next_url": null,
  "resources": [
    {
      "id": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94:resource-key:23693f48-aaa2-4079-b0c7-334846eff8d0",
      "guid": "23693f48-aaa2-4079-b0c7-334846eff8d0",
      "url": "/v2/resource_keys/23693f48-aaa2-4079-b0c7-334846eff8d0",
      "created_at": "2018-07-02T22:03:43.837979455Z",
      "updated_at": "2018-07-02T22:03:43.837979455Z",
      "deleted_at": null,
      "created_by": "IBMid-5500093BHN",
      "updated_by": "IBMid-5500093BHN",
      "deleted_by": "",
      "source_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::",
      "role": "crn:v1:bluemix:public:iam::::serviceRole:Writer",
      "name": "my-instance-key-1",
      "parameters": {
        "role_crn": "crn:v1:bluemix:public:iam::::serviceRole:Writer"
      },
      "crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94:resource-key:23693f48-aaa2-4079-b0c7-334846eff8d0",
      "state": "active",
      "account_id": "4329073d16d2f3663f74bfa955259139",
      "resource_group_id": "0be5ad401ae913d8ff665d92680664ed",
      "resource_id": "dff97f5c-bc5e-4455-b470-411c3edbe49c",
      "credentials": {
        "REDACTED": "REDACTED_EXPLICIT"
      },
      "iam_compatible": true,
      "migrated": false,
      "resource_instance_url": "/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94"
    }
  ]
}
Copy to clipboard

Success example: Credential REDACTED_EXPLICIT example

{
  "rows_count": 1,
  "next_url": null,
  "resources": [
    {
      "id": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94:resource-key:23693f48-aaa2-4079-b0c7-334846eff8d0",
      "guid": "23693f48-aaa2-4079-b0c7-334846eff8d0",
      "url": "/v2/resource_keys/23693f48-aaa2-4079-b0c7-334846eff8d0",
      "created_at": "2018-07-02T22:03:43.837979455Z",
      "updated_at": "2018-07-02T22:03:43.837979455Z",
      "deleted_at": null,
      "created_by": "IBMid-5500093BHN",
      "updated_by": "IBMid-5500093BHN",
      "deleted_by": "",
      "source_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::",
      "role": "crn:v1:bluemix:public:iam::::serviceRole:Writer",
      "name": "my-instance-key-1",
      "parameters": {
        "role_crn": "crn:v1:bluemix:public:iam::::serviceRole:Writer"
      },
      "crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94:resource-key:23693f48-aaa2-4079-b0c7-334846eff8d0",
      "state": "active",
      "account_id": "4329073d16d2f3663f74bfa955259139",
      "resource_group_id": "0be5ad401ae913d8ff665d92680664ed",
      "resource_id": "dff97f5c-bc5e-4455-b470-411c3edbe49c",
      "credentials": {
        "REDACTED": "REDACTED_EXPLICIT"
      },
      "iam_compatible": true,
      "migrated": false,
      "resource_instance_url": "/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94"
    }
  ]
}
Copy to clipboard

A resource key is a saved credential you can use to authenticate with a resource instance.

POST /v2/resource_keys

(resourceController *ResourceControllerV2) CreateResourceKey(createResourceKeyOptions *CreateResourceKeyOptions) (result *ResourceKey, response *core.DetailedResponse, err error)

(resourceController *ResourceControllerV2) CreateResourceKeyWithContext(ctx context.Context, createResourceKeyOptions *CreateResourceKeyOptions) (result *ResourceKey, response *core.DetailedResponse, err error)

ServiceCall<ResourceKey> createResourceKey(CreateResourceKeyOptions createResourceKeyOptions)
Copy to clipboard

createResourceKey(params)

create_resource_key(
        self,
        name: str,
        source: str,
        *,
        parameters: Optional['ResourceKeyPostParameters'] = None,
        role: Optional[str] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

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.key.create

Auditing

Calling this method generates the following auditing event.

resource-controller.key.create

Request

Instantiate the CreateResourceKeyOptions struct and set the fields to provide parameter values for the CreateResourceKey method.

Use the CreateResourceKeyOptions.Builder to create a CreateResourceKeyOptions object that contains the parameter values for the createResourceKey method.

Request Body

Required*

ResourceKeyPost

Property values for the new resource key.

Examples:

parameter

WithContext method only

CreateResourceKeyOptions

The CreateResourceKey options.

CreateResourceKeyOptions

The createResourceKey options.

parameters

name
Required*
string
The name of the key.
Examples:
source
Required*
string
The ID of resource instance.
Examples:
parameters
Configuration options represented as key-value pairs. Service defined options are passed through to the target resource brokers, whereas platform defined options are not.
role
string
The base IAM service role name (Reader, Writer, or Manager), or the service or custom role CRN. Refer to service’s documentation for supported roles.

Default: Writer

parameters

name
Required*
str
The name of the key.
Examples:
source
Required*
str
The ID of resource instance.
Examples:
parameters
Configuration options represented as key-value pairs. Service defined options are passed through to the target resource brokers, whereas platform defined options are not.
role
str
The base IAM service role name (Reader, Writer, or Manager), or the service or custom role CRN. Refer to service’s documentation for supported roles.

Default: Writer

Example request

curl -X POST   https://resource-controller.cloud.ibm.com/v2/resource_keys   -H "Authorization: Bearer <IAM token>"   -H 'Content-Type: application/json'   -d '{
  "name": "my-instance-key-1",
  "source": "267bf377-7fa2-43f6-94ec-09103a8e89d4",
  "role": "Writer"
}'
Copy to clipboard

Example request

createResourceKeyOptions := resourceControllerService.NewCreateResourceKeyOptions(
  keyName,
  instanceGUID,
)

parameters := &resourcecontrollerv2.ResourceKeyPostParameters{}
parameters.SetProperty("exampleParameter", "exampleValue")
createResourceKeyOptions.SetParameters(parameters)

resourceKey, response, err := resourceControllerService.CreateResourceKey(createResourceKeyOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(resourceKey, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

ResourceKeyPostParameters parameters = new ResourceKeyPostParameters.Builder()
  .add("exampleParameter", "exampleValue")
  .build();
CreateResourceKeyOptions createResourceKeyOptions = new CreateResourceKeyOptions.Builder()
  .name(keyName)
  .source(instanceGuid)
  .parameters(parameters)
  .build();

Response<ResourceKey> response = resourceControllerService.createResourceKey(createResourceKeyOptions).execute();
ResourceKey resourceKey = response.getResult();

System.out.println(resourceKey);
Copy to clipboard

Example request

const parameters = {
  'exampleParameter': 'exampleValue'
};

const params = {
  name: keyName,
  source: instanceGuid,
  parameters: parameters,
};

try {
  const res = await resourceControllerService.createResourceKey(params);
  instanceKeyGuid = res.result.guid;
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

parameters = {
  'exampleParameter': 'exampleValue'
}
resource_key = resource_controller_service.create_resource_key(
  name=key_name,
  source=instance_guid,
  parameters=parameters
).get_result()

print(json.dumps(resource_key, indent=2))
Copy to clipboard

Response

Response Body

ResourceKey

A resource key.

ResourceKey

A resource key.

ResourceKey

A resource key.

ResourceKey

A resource key.

ResourceKey

A resource key.

Status Code

201
Created
400
The request could not be understood due to malformed syntax.
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. Wait a few minutes and try again.
500
Your request could not be processed. 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": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94:resource-key:23693f48-aaa2-4079-b0c7-334846eff8d0",
  "guid": "23693f48-aaa2-4079-b0c7-334846eff8d0",
  "url": "/v2/resource_keys/23693f48-aaa2-4079-b0c7-334846eff8d0",
  "created_at": "2018-07-02T22:03:43.837979455Z",
  "updated_at": "2018-07-02T22:03:43.837979455Z",
  "deleted_at": null,
  "created_by": "IBMid-5500093BHN",
  "updated_by": "IBMid-5500093BHN",
  "deleted_by": "",
  "source_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::",
  "name": "my-instance-key-1",
  "role": "crn:v1:bluemix:public:iam::::serviceRole:Writer",
  "parameters": {
    "role_crn": "crn:v1:bluemix:public:iam::::serviceRole:Writer"
  },
  "crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94:resource-key:23693f48-aaa2-4079-b0c7-334846eff8d0",
  "state": "active",
  "account_id": "4329073d16d2f3663f74bfa955259139",
  "resource_group_id": "0be5ad401ae913d8ff665d92680664ed",
  "resource_id": "dff97f5c-bc5e-4455-b470-411c3edbe49c",
  "credentials": {
    "apikey": "XXXX-YYYY-ZZZZ\"",
    "endpoints": "https://cos-service-armada-s.us-south.containers.mybluemix.net/endpoints",
    "iam_apikey_description": "Auto generated apikey during resource-key operation for Instance - crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::",
    "iam_apikey_name": "auto-generated-apikey-23693f48-aaa2-4079-b0c7-334846eff8d0",
    "iam_role_crn": "crn:v1:bluemix:public:iam::::serviceRole:Writer",
    "iam_serviceid_crn": "crn:v1:bluemix:public:iam-identity::a/4329073d16d2f3663f74bfa955259139::serviceid:ServiceId-64c29e4f-422d-468c-a11b-1a8f671b5c89",
    "resource_instance_id": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::"
  },
  "iam_compatible": true,
  "migrated": false,
  "resource_instance_url": "/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94"
}
Copy to clipboard

Success example

{
  "id": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94:resource-key:23693f48-aaa2-4079-b0c7-334846eff8d0",
  "guid": "23693f48-aaa2-4079-b0c7-334846eff8d0",
  "url": "/v2/resource_keys/23693f48-aaa2-4079-b0c7-334846eff8d0",
  "created_at": "2018-07-02T22:03:43.837979455Z",
  "updated_at": "2018-07-02T22:03:43.837979455Z",
  "deleted_at": null,
  "created_by": "IBMid-5500093BHN",
  "updated_by": "IBMid-5500093BHN",
  "deleted_by": "",
  "source_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::",
  "name": "my-instance-key-1",
  "role": "crn:v1:bluemix:public:iam::::serviceRole:Writer",
  "parameters": {
    "role_crn": "crn:v1:bluemix:public:iam::::serviceRole:Writer"
  },
  "crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94:resource-key:23693f48-aaa2-4079-b0c7-334846eff8d0",
  "state": "active",
  "account_id": "4329073d16d2f3663f74bfa955259139",
  "resource_group_id": "0be5ad401ae913d8ff665d92680664ed",
  "resource_id": "dff97f5c-bc5e-4455-b470-411c3edbe49c",
  "credentials": {
    "apikey": "XXXX-YYYY-ZZZZ\"",
    "endpoints": "https://cos-service-armada-s.us-south.containers.mybluemix.net/endpoints",
    "iam_apikey_description": "Auto generated apikey during resource-key operation for Instance - crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::",
    "iam_apikey_name": "auto-generated-apikey-23693f48-aaa2-4079-b0c7-334846eff8d0",
    "iam_role_crn": "crn:v1:bluemix:public:iam::::serviceRole:Writer",
    "iam_serviceid_crn": "crn:v1:bluemix:public:iam-identity::a/4329073d16d2f3663f74bfa955259139::serviceid:ServiceId-64c29e4f-422d-468c-a11b-1a8f671b5c89",
    "resource_instance_id": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::"
  },
  "iam_compatible": true,
  "migrated": false,
  "resource_instance_url": "/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94"
}
Copy to clipboard

View the details of a resource key by URL-encoded CRN or GUID, like the credentials for the key and who created it.

GET /v2/resource_keys/{id}

(resourceController *ResourceControllerV2) GetResourceKey(getResourceKeyOptions *GetResourceKeyOptions) (result *ResourceKey, response *core.DetailedResponse, err error)

(resourceController *ResourceControllerV2) GetResourceKeyWithContext(ctx context.Context, getResourceKeyOptions *GetResourceKeyOptions) (result *ResourceKey, response *core.DetailedResponse, err error)

ServiceCall<ResourceKey> getResourceKey(GetResourceKeyOptions getResourceKeyOptions)
Copy to clipboard

getResourceKey(params)

get_resource_key(
        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.key.retrieve

Request

Instantiate the GetResourceKeyOptions struct and set the fields to provide parameter values for the GetResourceKey method.

Use the GetResourceKeyOptions.Builder to create a GetResourceKeyOptions object that contains the parameter values for the getResourceKey method.

Path Parameters

id
Required*
string
The resource key URL-encoded CRN or GUID.

parameter

WithContext method only

GetResourceKeyOptions

The GetResourceKey options.

GetResourceKeyOptions

The getResourceKey options.

parameters

id
Required*
string
The resource key URL-encoded CRN or GUID.

parameters

id
Required*
str
The resource key URL-encoded CRN or GUID.

Example request

curl -X GET   https://resource-controller.cloud.ibm.com/v2/resource_keys/23693f48-aaa2-4079-b0c7-334846eff8d0   -H "Authorization: Bearer <IAM token>"

Example request

getResourceKeyOptions := resourceControllerService.NewGetResourceKeyOptions(
  instanceKeyGUID,
)

resourceKey, response, err := resourceControllerService.GetResourceKey(getResourceKeyOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(resourceKey, "", "  ")
fmt.Println(string(b))
if resourceKey.Credentials.Redacted != nil && (*resourceKey.Credentials.Redacted == "REDACTED" || *resourceKey.Credentials.Redacted == "REDACTED_EXPLICIT") {
  fmt.Println("Credentials are redacted with code:", *resourceKey.Credentials.Redacted, ".The User doesn't have the correct access to view the credentials. Refer to the API documentation for additional details.")
}
Copy to clipboard

Example request

GetResourceKeyOptions getResourceKeyOptions = new GetResourceKeyOptions.Builder()
  .id(instanceKeyGuid)
  .build();

Response<ResourceKey> response = resourceControllerService.getResourceKey(getResourceKeyOptions).execute();
ResourceKey resourceKey = response.getResult();

System.out.println(resourceKey);

Example request

const params = {
  id: instanceKeyGuid,
};

try {
  const res = await resourceControllerService.getResourceKey(params);
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

resource_key = resource_controller_service.get_resource_key(
  id=instance_key_guid
).get_result()
if resource_key.get('credentials') and resource_key.get('credentials').get('REDACTED'):
  print("Credentials are redacted with code:", resource_key.get('credentials').get('REDACTED'), ".The User doesn't have the correct access to view the credentials. Refer to the API documentation for additional details.")

print(json.dumps(resource_key, indent=2))
Copy to clipboard

Response

Response Body

ResourceKey

A resource key.

ResourceKey

A resource key.

ResourceKey

A resource key.

ResourceKey

A resource key.

ResourceKey

A resource key.

Status Code

200
The resource key was successfully retrieved.
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. Wait a few minutes and try again.
500
Your request could not be processed. Try again later. If the problem persists, note the transaction-id in the response header and contact IBM Cloud support.

Example responses

Status 200: Non-redacted credential example

{
  "id": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94:resource-key:23693f48-aaa2-4079-b0c7-334846eff8d0",
  "guid": "23693f48-aaa2-4079-b0c7-334846eff8d0",
  "url": "/v2/resource_keys/23693f48-aaa2-4079-b0c7-334846eff8d0",
  "created_at": "2018-07-02T22:03:43.837979455Z",
  "updated_at": "2018-07-02T22:03:43.837979455Z",
  "deleted_at": null,
  "created_by": "IBMid-5500093BHN",
  "updated_by": "IBMid-5500093BHN",
  "deleted_by": "",
  "source_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::",
  "role": "crn:v1:bluemix:public:iam::::serviceRole:Writer",
  "name": "my-instance-key-1",
  "parameters": {
    "role_crn": "crn:v1:bluemix:public:iam::::serviceRole:Writer"
  },
  "crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94:resource-key:23693f48-aaa2-4079-b0c7-334846eff8d0",
  "state": "active",
  "account_id": "4329073d16d2f3663f74bfa955259139",
  "resource_group_id": "0be5ad401ae913d8ff665d92680664ed",
  "resource_id": "dff97f5c-bc5e-4455-b470-411c3edbe49c",
  "credentials": {
    "apikey": "XXXX-YYYY-ZZZZ",
    "endpoints": "https://cos-service-armada-s.us-south.containers.mybluemix.net/endpoints",
    "iam_apikey_description": "Auto generated apikey during resource-key operation for Instance - crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::",
    "iam_apikey_name": "auto-generated-apikey-23693f48-aaa2-4079-b0c7-334846eff8d0",
    "iam_role_crn": "crn:v1:bluemix:public:iam::::serviceRole:Writer",
    "iam_serviceid_crn": "crn:v1:bluemix:public:iam-identity::a/4329073d16d2f3663f74bfa955259139::serviceid:ServiceId-64c29e4f-422d-468c-a11b-1a8f671b5c89",
    "resource_instance_id": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::"
  },
  "iam_compatible": true,
  "migrated": false,
  "resource_instance_url": "/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94"
}
Copy to clipboard

Success example: Non-redacted credential example

{
  "id": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94:resource-key:23693f48-aaa2-4079-b0c7-334846eff8d0",
  "guid": "23693f48-aaa2-4079-b0c7-334846eff8d0",
  "url": "/v2/resource_keys/23693f48-aaa2-4079-b0c7-334846eff8d0",
  "created_at": "2018-07-02T22:03:43.837979455Z",
  "updated_at": "2018-07-02T22:03:43.837979455Z",
  "deleted_at": null,
  "created_by": "IBMid-5500093BHN",
  "updated_by": "IBMid-5500093BHN",
  "deleted_by": "",
  "source_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::",
  "role": "crn:v1:bluemix:public:iam::::serviceRole:Writer",
  "name": "my-instance-key-1",
  "parameters": {
    "role_crn": "crn:v1:bluemix:public:iam::::serviceRole:Writer"
  },
  "crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94:resource-key:23693f48-aaa2-4079-b0c7-334846eff8d0",
  "state": "active",
  "account_id": "4329073d16d2f3663f74bfa955259139",
  "resource_group_id": "0be5ad401ae913d8ff665d92680664ed",
  "resource_id": "dff97f5c-bc5e-4455-b470-411c3edbe49c",
  "credentials": {
    "apikey": "XXXX-YYYY-ZZZZ",
    "endpoints": "https://cos-service-armada-s.us-south.containers.mybluemix.net/endpoints",
    "iam_apikey_description": "Auto generated apikey during resource-key operation for Instance - crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::",
    "iam_apikey_name": "auto-generated-apikey-23693f48-aaa2-4079-b0c7-334846eff8d0",
    "iam_role_crn": "crn:v1:bluemix:public:iam::::serviceRole:Writer",
    "iam_serviceid_crn": "crn:v1:bluemix:public:iam-identity::a/4329073d16d2f3663f74bfa955259139::serviceid:ServiceId-64c29e4f-422d-468c-a11b-1a8f671b5c89",
    "resource_instance_id": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::"
  },
  "iam_compatible": true,
  "migrated": false,
  "resource_instance_url": "/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94"
}
Copy to clipboard

Status 200: Credential REDACTED_EXPLICIT example

{
  "id": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94:resource-key:23693f48-aaa2-4079-b0c7-334846eff8d0",
  "guid": "23693f48-aaa2-4079-b0c7-334846eff8d0",
  "url": "/v2/resource_keys/23693f48-aaa2-4079-b0c7-334846eff8d0",
  "created_at": "2018-07-02T22:03:43.837979455Z",
  "updated_at": "2018-07-02T22:03:43.837979455Z",
  "deleted_at": null,
  "created_by": "IBMid-5500093BHN",
  "updated_by": "IBMid-5500093BHN",
  "deleted_by": "",
  "source_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::",
  "role": "crn:v1:bluemix:public:iam::::serviceRole:Writer",
  "name": "my-instance-key-1",
  "parameters": {
    "role_crn": "crn:v1:bluemix:public:iam::::serviceRole:Writer"
  },
  "crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94:resource-key:23693f48-aaa2-4079-b0c7-334846eff8d0",
  "state": "active",
  "account_id": "4329073d16d2f3663f74bfa955259139",
  "resource_group_id": "0be5ad401ae913d8ff665d92680664ed",
  "resource_id": "dff97f5c-bc5e-4455-b470-411c3edbe49c",
  "credentials": {
    "REDACTED": "REDACTED_EXPLICIT"
  },
  "iam_compatible": true,
  "migrated": false,
  "resource_instance_url": "/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94"
}
Copy to clipboard

Success example: Credential REDACTED_EXPLICIT example

{
  "id": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94:resource-key:23693f48-aaa2-4079-b0c7-334846eff8d0",
  "guid": "23693f48-aaa2-4079-b0c7-334846eff8d0",
  "url": "/v2/resource_keys/23693f48-aaa2-4079-b0c7-334846eff8d0",
  "created_at": "2018-07-02T22:03:43.837979455Z",
  "updated_at": "2018-07-02T22:03:43.837979455Z",
  "deleted_at": null,
  "created_by": "IBMid-5500093BHN",
  "updated_by": "IBMid-5500093BHN",
  "deleted_by": "",
  "source_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::",
  "role": "crn:v1:bluemix:public:iam::::serviceRole:Writer",
  "name": "my-instance-key-1",
  "parameters": {
    "role_crn": "crn:v1:bluemix:public:iam::::serviceRole:Writer"
  },
  "crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94:resource-key:23693f48-aaa2-4079-b0c7-334846eff8d0",
  "state": "active",
  "account_id": "4329073d16d2f3663f74bfa955259139",
  "resource_group_id": "0be5ad401ae913d8ff665d92680664ed",
  "resource_id": "dff97f5c-bc5e-4455-b470-411c3edbe49c",
  "credentials": {
    "REDACTED": "REDACTED_EXPLICIT"
  },
  "iam_compatible": true,
  "migrated": false,
  "resource_instance_url": "/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94"
}
Copy to clipboard

Deleting a resource key does not affect any resource instance associated with the key.

DELETE /v2/resource_keys/{id}

(resourceController *ResourceControllerV2) DeleteResourceKey(deleteResourceKeyOptions *DeleteResourceKeyOptions) (response *core.DetailedResponse, err error)

(resourceController *ResourceControllerV2) DeleteResourceKeyWithContext(ctx context.Context, deleteResourceKeyOptions *DeleteResourceKeyOptions) (response *core.DetailedResponse, err error)

ServiceCall<Void> deleteResourceKey(DeleteResourceKeyOptions deleteResourceKeyOptions)
Copy to clipboard

deleteResourceKey(params)

delete_resource_key(
        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.key.delete

Auditing

Calling this method generates the following auditing event.

resource-controller.key.delete

Request

Instantiate the DeleteResourceKeyOptions struct and set the fields to provide parameter values for the DeleteResourceKey method.

Use the DeleteResourceKeyOptions.Builder to create a DeleteResourceKeyOptions object that contains the parameter values for the deleteResourceKey method.

Path Parameters

id
Required*
string
The resource key URL-encoded CRN or GUID.

parameter

WithContext method only

DeleteResourceKeyOptions

The DeleteResourceKey options.

DeleteResourceKeyOptions

The deleteResourceKey options.

parameters

id
Required*
string
The resource key URL-encoded CRN or GUID.

parameters

id
Required*
str
The resource key URL-encoded CRN or GUID.

Example request

curl -X DELETE   https://resource-controller.cloud.ibm.com/v2/resource_keys/23693f48-aaa2-4079-b0c7-334846eff8d0   -H "Authorization: Bearer <IAM token>"

Example request

deleteResourceKeyOptions := resourceControllerService.NewDeleteResourceKeyOptions(
  instanceKeyGUID,
)

response, err := resourceControllerService.DeleteResourceKey(deleteResourceKeyOptions)
if err != nil {
  panic(err)
}
Copy to clipboard

Example request

DeleteResourceKeyOptions deleteResourceKeyOptions = new DeleteResourceKeyOptions.Builder()
  .id(instanceKeyGuid)
  .build();

Response<Void> response = resourceControllerService.deleteResourceKey(deleteResourceKeyOptions).execute();

Example request

const params = {
  id: instanceKeyGuid,
};

try {
  await resourceControllerService.deleteResourceKey(params);
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

response = resource_controller_service.delete_resource_key(
  id=instance_key_guid)

Response

Status Code

204
Deleted
400
The request could not be understood due to malformed syntax.
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.
410
The resource could was previously deleted and is no longer available.
429
Too many requests. Wait a few minutes and try again.
500
Your request could not be processed. 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.

Use the resource key URL-encoded CRN or GUID to update the resource key.

PATCH /v2/resource_keys/{id}

(resourceController *ResourceControllerV2) UpdateResourceKey(updateResourceKeyOptions *UpdateResourceKeyOptions) (result *ResourceKey, response *core.DetailedResponse, err error)

(resourceController *ResourceControllerV2) UpdateResourceKeyWithContext(ctx context.Context, updateResourceKeyOptions *UpdateResourceKeyOptions) (result *ResourceKey, response *core.DetailedResponse, err error)

ServiceCall<ResourceKey> updateResourceKey(UpdateResourceKeyOptions updateResourceKeyOptions)
Copy to clipboard

updateResourceKey(params)

update_resource_key(
        self,
        id: str,
        name: str,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

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.key.update

Auditing

Calling this method generates the following auditing event.

resource-controller.key.update

Request

Instantiate the UpdateResourceKeyOptions struct and set the fields to provide parameter values for the UpdateResourceKey method.

Use the UpdateResourceKeyOptions.Builder to create a UpdateResourceKeyOptions object that contains the parameter values for the updateResourceKey method.

Path Parameters

id
Required*
string
The resource key URL-encoded CRN or GUID.

Request Body

Required*

ResourceKeyPatch

Updated property values for the resource key.

Examples:

parameter

WithContext method only

UpdateResourceKeyOptions

The UpdateResourceKey options.

UpdateResourceKeyOptions

The updateResourceKey options.

parameters

id
Required*
string
The resource key URL-encoded CRN or GUID.
name
Required*
string
The new name of the key. Must be 180 characters or less and cannot include any special characters other than (space) - . _ :.

Possible values: Value must match regular expression /^([^[:ascii:]]{1,256}|[a-zA-Z0-9-._: ]{1,256})$/
Examples:

parameters

id
Required*
str
The resource key URL-encoded CRN or GUID.
name
Required*
str
The new name of the key. Must be 180 characters or less and cannot include any special characters other than (space) - . _ :.

Possible values: Value must match regular expression /^([^[:ascii:]]{1,256}|[a-zA-Z0-9-._: ]{1,256})$/
Examples:

Example request

curl -X PATCH   https://resource-controller.cloud.ibm.com/v2/resource_keys/23693f48-aaa2-4079-b0c7-334846eff8d0   -H "Authorization: Bearer <IAM token>"   -H 'Content-Type: application/json'     -d '{
    "name": "my-instance-new-key-1",
  }'
Copy to clipboard

Example request

updateResourceKeyOptions := resourceControllerService.NewUpdateResourceKeyOptions(
  instanceKeyGUID,
  keyUpdateName,
)

resourceKey, response, err := resourceControllerService.UpdateResourceKey(updateResourceKeyOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(resourceKey, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

UpdateResourceKeyOptions updateResourceKeyOptions = new UpdateResourceKeyOptions.Builder()
  .id(instanceKeyGuid)
  .name(keyUpdateName)
  .build();

Response<ResourceKey> response = resourceControllerService.updateResourceKey(updateResourceKeyOptions).execute();
ResourceKey resourceKey = response.getResult();

System.out.println(resourceKey);

Example request

const params = {
  id: instanceKeyGuid,
  name: keyUpdateName,
};

try {
  const res = await resourceControllerService.updateResourceKey(params);
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

resource_key = resource_controller_service.update_resource_key(
  id=instance_key_guid,
  name=key_update_name
).get_result()

print(json.dumps(resource_key, indent=2))
Copy to clipboard

Response

Response Body

ResourceKey

A resource key.

ResourceKey

A resource key.

ResourceKey

A resource key.

ResourceKey

A resource key.

ResourceKey

A resource key.

Status Code

200
The resource key was successfully updated.
400
The request could not be understood due to malformed syntax.
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.
422
The request could not be processed.
429
Too many requests. Wait a few minutes and try again.
500
Your request could not be processed. 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": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94:resource-key:23693f48-aaa2-4079-b0c7-334846eff8d0",
  "guid": "23693f48-aaa2-4079-b0c7-334846eff8d0",
  "url": "/v2/resource_keys/23693f48-aaa2-4079-b0c7-334846eff8d0",
  "created_at": "2018-07-02T22:03:43.837979455Z",
  "updated_at": "2018-07-02T22:03:43.837979455Z",
  "deleted_at": null,
  "created_by": "IBMid-5500093BHN",
  "updated_by": "IBMid-5500093BHN",
  "deleted_by": "",
  "source_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::",
  "role": "crn:v1:bluemix:public:iam::::serviceRole:Writer",
  "name": "my-instance-new-key-1",
  "parameters": {
    "role_crn": "crn:v1:bluemix:public:iam::::serviceRole:Writer"
  },
  "crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94:resource-key:23693f48-aaa2-4079-b0c7-334846eff8d0",
  "state": "active",
  "account_id": "4329073d16d2f3663f74bfa955259139",
  "resource_group_id": "0be5ad401ae913d8ff665d92680664ed",
  "resource_id": "dff97f5c-bc5e-4455-b470-411c3edbe49c",
  "credentials": {
    "apikey": "XXXX-YYYY-ZZZZ",
    "endpoints": "https://cos-service-armada-s.us-south.containers.mybluemix.net/endpoints",
    "iam_apikey_description": "Auto generated apikey during resource-key operation for Instance - crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::",
    "iam_apikey_name": "auto-generated-apikey-23693f48-aaa2-4079-b0c7-334846eff8d0",
    "iam_role_crn": "crn:v1:bluemix:public:iam::::serviceRole:Writer",
    "iam_serviceid_crn": "crn:v1:bluemix:public:iam-identity::a/4329073d16d2f3663f74bfa955259139::serviceid:ServiceId-64c29e4f-422d-468c-a11b-1a8f671b5c89",
    "resource_instance_id": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::"
  },
  "iam_compatible": true,
  "migrated": false,
  "resource_instance_url": "/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94"
}
Copy to clipboard

Success example

{
  "id": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94:resource-key:23693f48-aaa2-4079-b0c7-334846eff8d0",
  "guid": "23693f48-aaa2-4079-b0c7-334846eff8d0",
  "url": "/v2/resource_keys/23693f48-aaa2-4079-b0c7-334846eff8d0",
  "created_at": "2018-07-02T22:03:43.837979455Z",
  "updated_at": "2018-07-02T22:03:43.837979455Z",
  "deleted_at": null,
  "created_by": "IBMid-5500093BHN",
  "updated_by": "IBMid-5500093BHN",
  "deleted_by": "",
  "source_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::",
  "role": "crn:v1:bluemix:public:iam::::serviceRole:Writer",
  "name": "my-instance-new-key-1",
  "parameters": {
    "role_crn": "crn:v1:bluemix:public:iam::::serviceRole:Writer"
  },
  "crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94:resource-key:23693f48-aaa2-4079-b0c7-334846eff8d0",
  "state": "active",
  "account_id": "4329073d16d2f3663f74bfa955259139",
  "resource_group_id": "0be5ad401ae913d8ff665d92680664ed",
  "resource_id": "dff97f5c-bc5e-4455-b470-411c3edbe49c",
  "credentials": {
    "apikey": "XXXX-YYYY-ZZZZ",
    "endpoints": "https://cos-service-armada-s.us-south.containers.mybluemix.net/endpoints",
    "iam_apikey_description": "Auto generated apikey during resource-key operation for Instance - crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::",
    "iam_apikey_name": "auto-generated-apikey-23693f48-aaa2-4079-b0c7-334846eff8d0",
    "iam_role_crn": "crn:v1:bluemix:public:iam::::serviceRole:Writer",
    "iam_serviceid_crn": "crn:v1:bluemix:public:iam-identity::a/4329073d16d2f3663f74bfa955259139::serviceid:ServiceId-64c29e4f-422d-468c-a11b-1a8f671b5c89",
    "resource_instance_id": "crn:v1:bluemix:public:cloud-object-storage:global:a/4329073d16d2f3663f74bfa955259139:8d7af921-b136-4078-9666-081bd8470d94::"
  },
  "iam_compatible": true,
  "migrated": false,
  "resource_instance_url": "/v2/resource_instances/8d7af921-b136-4078-9666-081bd8470d94"
}
Copy to clipboard

View all of the resource reclamations that exist for every resource instance.

GET /v1/reclamations

(resourceController *ResourceControllerV2) ListReclamations(listReclamationsOptions *ListReclamationsOptions) (result *ReclamationsList, response *core.DetailedResponse, err error)

(resourceController *ResourceControllerV2) ListReclamationsWithContext(ctx context.Context, listReclamationsOptions *ListReclamationsOptions) (result *ReclamationsList, response *core.DetailedResponse, err error)

ServiceCall<ReclamationsList> listReclamations(ListReclamationsOptions listReclamationsOptions)
Copy to clipboard

listReclamations(params)

list_reclamations(
        self,
        *,
        account_id: Optional[str] = None,
        resource_instance_id: Optional[str] = None,
        resource_group_id: Optional[str] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

Request

Instantiate the ListReclamationsOptions struct and set the fields to provide parameter values for the ListReclamations method.

Use the ListReclamationsOptions.Builder to create a ListReclamationsOptions object that contains the parameter values for the listReclamations method.

Query Parameters

account_id
string
An alpha-numeric value identifying the account ID.
resource_instance_id
string
The GUID of the resource instance.
resource_group_id
string
The ID of the resource group.

parameter

WithContext method only

ListReclamationsOptions

The ListReclamations options.

ListReclamationsOptions

The listReclamations options.

parameters

accountId
string
An alpha-numeric value identifying the account ID.
resourceInstanceId
string
The GUID of the resource instance.
resourceGroupId
string
The ID of the resource group.

parameters

account_id
str
An alpha-numeric value identifying the account ID.
resource_instance_id
str
The GUID of the resource instance.
resource_group_id
str
The ID of the resource group.

Example request

curl -X GET   https://resource-controller.cloud.ibm.com/v1/reclamations?account_id=b80a8b513ae24e178438b7a18bd8d609   -H "Authorization: Bearer <IAM token>"

Example request

listReclamationsOptions := resourceControllerService.NewListReclamationsOptions()
listReclamationsOptions = listReclamationsOptions.SetResourceGroupID(resourceGroupID)
reclamationsList, response, err := resourceControllerService.ListReclamations(listReclamationsOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(reclamationsList, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

ListReclamationsOptions listReclamationsOptions = new ListReclamationsOptions.Builder()
  .accountId(accountId)
  .build();

Response<ReclamationsList> response = resourceControllerService.listReclamations(listReclamationsOptions).execute();
ReclamationsList reclamationsList = response.getResult();

System.out.println(reclamationsList);

Example request

const params = {
  accountId: accountId,
};

try {
  const res = await resourceControllerService.listReclamations(params);
  var resources = res.result.resources;
  resources.forEach(reclaim => {
    if (reclaim.resource_instance_id.toString() === instanceGuid) {
      reclamationId = reclaim.id;
    }
  });
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

reclamations_list = resource_controller_service.list_reclamations(
  account_id=account_id
).get_result()

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

Response

Response Body

ReclamationsList

A list of reclamations.

ReclamationsList

A list of reclamations.

ReclamationsList

A list of reclamations.

ReclamationsList

A list of reclamations.

ReclamationsList

A list of reclamations.

Status Code

200
The list of reclamations was successfully retrieved.
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. Wait a few minutes and try again.
500
Your request could not be processed. 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": "8b551a81-4af3-47bd-b543-b6e3d512a3db",
      "entity_id": "dff97f5c-bc5e-4455-b470-411c3edbe49c",
      "entity_type_id": "98941610-5a79-4778-8b1b-ad115857296b",
      "entity_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/b80a8b513ae24e178438b7a18bd8d609:ef8353b4-92d0-456b-a4fb-a15c01ff86a6::",
      "resource_instance_id": "ef8353b4-92d0-456b-a4fb-a15c01ff86a6",
      "resource_group_id": "e7d14b0586ed4bcc9f82fc5e05099292",
      "account_id": "b80a8b513ae24e178438b7a18bd8d609",
      "policy_id": "6c59484f-dad8-4753-92fd-662fcd4968dc",
      "state": "SCHEDULED",
      "target_time": "2019-06-25T10:01:18Z",
      "created_at": "2019-06-18T10:01:18.847689692Z",
      "created_by": ""
    }
  ]
}
Copy to clipboard

Success example

{
  "resources": [
    {
      "id": "8b551a81-4af3-47bd-b543-b6e3d512a3db",
      "entity_id": "dff97f5c-bc5e-4455-b470-411c3edbe49c",
      "entity_type_id": "98941610-5a79-4778-8b1b-ad115857296b",
      "entity_crn": "crn:v1:bluemix:public:cloud-object-storage:global:a/b80a8b513ae24e178438b7a18bd8d609:ef8353b4-92d0-456b-a4fb-a15c01ff86a6::",
      "resource_instance_id": "ef8353b4-92d0-456b-a4fb-a15c01ff86a6",
      "resource_group_id": "e7d14b0586ed4bcc9f82fc5e05099292",
      "account_id": "b80a8b513ae24e178438b7a18bd8d609",
      "policy_id": "6c59484f-dad8-4753-92fd-662fcd4968dc",
      "state": "SCHEDULED",
      "target_time": "2019-06-25T10:01:18Z",
      "created_at": "2019-06-18T10:01:18.847689692Z",
      "created_by": ""
    }
  ]
}
Copy to clipboard

Reclaim a resource instance so that it can no longer be used, or restore the resource instance so that it's usable again.

POST /v1/reclamations/{id}/actions/{action_name}

(resourceController *ResourceControllerV2) RunReclamationAction(runReclamationActionOptions *RunReclamationActionOptions) (result *Reclamation, response *core.DetailedResponse, err error)

(resourceController *ResourceControllerV2) RunReclamationActionWithContext(ctx context.Context, runReclamationActionOptions *RunReclamationActionOptions) (result *Reclamation, response *core.DetailedResponse, err error)

ServiceCall<Reclamation> runReclamationAction(RunReclamationActionOptions runReclamationActionOptions)
Copy to clipboard

runReclamationAction(params)

run_reclamation_action(
        self,
        id: str,
        action_name: str,
        *,
        request_by: Optional[str] = None,
        comment: Optional[str] = None,
        **kwargs,
    ) -> DetailedResponse
Copy to clipboard

Request

Instantiate the RunReclamationActionOptions struct and set the fields to provide parameter values for the RunReclamationAction method.

Use the RunReclamationActionOptions.Builder to create a RunReclamationActionOptions object that contains the parameter values for the runReclamationAction method.

Path Parameters

id
Required*
string
The ID associated with the reclamation.
action_name
Required*
string
The reclamation action name. Specify reclaim to delete a resource, or restore to restore a resource.

Allowable values: [reclaim,restore]

Request Body

ReclamationActionsPost

Perform a reclamation action.

parameter

WithContext method only

RunReclamationActionOptions

The RunReclamationAction options.

RunReclamationActionOptions

The runReclamationAction options.

parameters

id
Required*
string
The ID associated with the reclamation.
actionName
Required*
string
The reclamation action name. Specify reclaim to delete a resource, or restore to restore a resource.
requestBy
string
The request initiator, if different from the request token.
comment
string
A comment to describe the action.

parameters

id
Required*
str
The ID associated with the reclamation.
action_name
Required*
str
The reclamation action name. Specify reclaim to delete a resource, or restore to restore a resource.
request_by
str
The request initiator, if different from the request token.
comment
str
A comment to describe the action.

Example request

curl -X POST   https://resource-controller.cloud.ibm.com/v1/reclamations/0114be9024c6eede47d08a85ac0c5c43/actions/restore   -H "Authorization: Bearer <IAM token>"   -H 'Content-Type: application/json'     -d '{
    "request_by": "bar",
    "comment": "restore resource instance 614fc866-1d4f-4c9e-973e-637f1089a6a1"
  }'
Copy to clipboard

Example request

runReclamationActionOptions := resourceControllerService.NewRunReclamationActionOptions(
  reclamationID,
  "reclaim",
)

reclamation, response, err := resourceControllerService.RunReclamationAction(runReclamationActionOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(reclamation, "", "  ")
fmt.Println(string(b))
Copy to clipboard

Example request

RunReclamationActionOptions runReclamationActionOptions = new RunReclamationActionOptions.Builder()
  .id(reclamationId)
  .actionName("reclaim")
  .build();

Response<Reclamation> response = resourceControllerService.runReclamationAction(runReclamationActionOptions).execute();
Reclamation reclamation = response.getResult();

System.out.println(reclamation);

Example request

const params = {
  id: reclamationId,
  actionName: 'reclaim',
};

try {
  const res = await resourceControllerService.runReclamationAction(params);
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}
Copy to clipboard

Example request

reclamation = resource_controller_service.run_reclamation_action(
  id=reclamation_id,
  action_name='reclaim'
).get_result()

print(json.dumps(reclamation, indent=2))
Copy to clipboard

Response

Response Body

Reclamation

A reclamation.

Reclamation

A reclamation.

Reclamation

A reclamation.

Reclamation

A reclamation.

Reclamation

A reclamation.

Status Code

200
The reclamation action, such as restore or reclaim, was successfully performed.
400
The request could not be understood due to malformed syntax.
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. Wait a few minutes and try again.
500
Your request could not be processed. 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": "0114be9024c6eede47d08a85ac0c5c43",
  "entity_id": "cloudant",
  "entity_type_id": "98941610-5a79-4778-8b1b-ad115857296b",
  "entity_crn": "crn:v1:bluemix:public:cloudantnosqldb:us-south:a/b80a8b513ae24e178438b7a18btest:614fc866-1d4f-4c9e-973e-637f10test::",
  "resource_instance_id": "614fc866-1d4f-4c9e-973e-637f1089a6a1",
  "resource_group_id": "74f5b3fdbea64fbaafe3e1d9d41test",
  "account_id": "b80a8b513ae24e178438b7a18btest",
  "policy_id": "6c59484f-dad8-4753-92fd-662fcd4968dc",
  "state": "RESTORING",
  "target_time": "2019-06-24T07:29:56Z",
  "custom_properties": {
    "request_by": "bar",
    "comment": "restore resource instance 614fc866-1d4f-4c9e-973e-637f1089a6a1"
  },
  "created_at": "2019-06-17T07:29:56.761106722Z",
  "created_by": "foo",
  "updated_at": "2019-06-20T08:27:46.749153Z",
  "updated_by": "bar"
}
Copy to clipboard

Success example

{
  "id": "0114be9024c6eede47d08a85ac0c5c43",
  "entity_id": "cloudant",
  "entity_type_id": "98941610-5a79-4778-8b1b-ad115857296b",
  "entity_crn": "crn:v1:bluemix:public:cloudantnosqldb:us-south:a/b80a8b513ae24e178438b7a18btest:614fc866-1d4f-4c9e-973e-637f10test::",
  "resource_instance_id": "614fc866-1d4f-4c9e-973e-637f1089a6a1",
  "resource_group_id": "74f5b3fdbea64fbaafe3e1d9d41test",
  "account_id": "b80a8b513ae24e178438b7a18btest",
  "policy_id": "6c59484f-dad8-4753-92fd-662fcd4968dc",
  "state": "RESTORING",
  "target_time": "2019-06-24T07:29:56Z",
  "custom_properties": {
    "request_by": "bar",
    "comment": "restore resource instance 614fc866-1d4f-4c9e-973e-637f1089a6a1"
  },
  "created_at": "2019-06-17T07:29:56.761106722Z",
  "created_by": "foo",
  "updated_at": "2019-06-20T08:27:46.749153Z",
  "updated_by": "bar"
}
Copy to clipboard

Introduction

Resource instances

Using the SDK

Endpoint URLs

Authentication

Methods

Get a list of all resource instances

Authorization

Request

Query Parameters

guid

name

resource_group_id

resource_id

resource_plan_id

type

sub_type

subscription_id

limit

start

state

updated_from

updated_to

parameter

ctx

ListResourceInstancesOptions

GUID

Name

ResourceGroupID

ResourceID

ResourcePlanID

Type

SubType

SubscriptionID

Limit

Start

State

UpdatedFrom

UpdatedTo

ListResourceInstancesOptions

guid

name

resourceGroupId

resourceId

resourcePlanId

type

subType

subscriptionId

limit

start

state

updatedFrom

updatedTo

parameters

guid

name

resourceGroupId

resourceId

resourcePlanId

type

subType

subscriptionId

limit

start

state

updatedFrom

updatedTo

parameters

guid

name

resource_group_id

resource_id

resource_plan_id

type

sub_type

subscription_id

limit

start

state

updated_from