Get a list of all resource instances
GET /v2/resource_instances
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.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
resource-controller.instance.retrieve
Request
Path Parameters
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. The number of items returned may be less than the specified limit if the caller lacks sufficient access to retrieve certain resource instances.
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`, `inactive`, `failed`, `provisioning` and `pre_provisioning` are returned.
updated_from
string
Start date inclusive filter.
updated_to
string
End date inclusive filter.
sort
string
Optional sort property, valid values are `name`, `created_at` and `updated_at`. If specified, the items are sorted by the value of this property.
order
string
Optional sort order, valid values are `asc` and `desc`.
Response
200 - The list of resource instances was successfully retrieved.
rows_count
integer
The number of resource instances in `resources`.
next_url
string
The URL for requesting the next page of results.
resources
array
A list of resource instances.
401 -
403 -
429 -
500 -
Create (provision) a new resource instance
POST /v2/resource_instances
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.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
resource-controller.instance.create
Auditing
Calling this method generates the following auditing event.
resource-controller.instance.create
Request
Request Body
ResourceInstancePost
name
Required *
string
The name of the instance.
target
Required *
string
The deployment CRN or location where the instance should be hosted.
resource_group
Required *
string
The CRN or ID of the resource group.
resource_plan_id
Required *
string
The unique ID of the plan associated with the offering. This value is provided by and stored in the global catalog.
tags
array
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
boolean
A boolean that dictates if the resource instance should be deleted (cleaned up) during the processing of a region instance delete call.
parameters
object
Configuration options represented as key-value pairs that are passed through to the target resource brokers.<br><br> 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.<br><br> Set the `subscription_id` property to the ID of the subscription if the targeted plan is a subscription plan.
Path Parameters
Query Parameters
Response
201 - The resource instance was provisioned.
id
string
The ID associated with the instance.
guid
string
The GUID of the instance.
url
string
When you provision a new resource, a relative URL path is created identifying the location of the instance.
created_at
string
The date when the instance was created.
updated_at
string
The date when the instance was last updated.
deleted_at
string
The date when the instance was deleted.
created_by
string
The subject who created the instance.
updated_by
string
The subject who updated the instance.
deleted_by
string
The subject who deleted the instance.
scheduled_reclaim_at
string
The date when the instance was scheduled for reclamation.
restored_at
string
The date when the instance under reclamation was restored.
restored_by
string
The subject who restored the instance back from reclamation.
scheduled_reclaim_by
string
The subject who initiated the instance reclamation.
name
string
The human-readable name of the instance.
region_id
string
The deployment location where the instance was provisioned.
account_id
string
An alpha-numeric value identifying the account ID.
reseller_channel_id
string
The unique ID of the reseller channel where the instance was provisioned from.
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.
resource_group_id
string
The ID of the resource group.
resource_group_crn
string
The CRN of the resource group.
target_crn
string
The deployment CRN as defined in the global catalog where the instance is provisioned.
onetime_credentials
boolean
Whether newly created resource key credentials can be retrieved by using get resource key or get a list of all of the resource keys requests.
parameters
object
The current configuration parameters of the instance from the previous operation. Any future operation on the instance may reset this these values.
allow_cleanup
boolean
A boolean that dictates if the resource instance should be deleted (cleaned up) during the processing of a region instance delete call.
crn
string
The full Cloud Resource Name (CRN) associated with the instance. For more information about this format, see Cloud Resource Names.
state
string
The current state of the instance. For example, if the instance is deleted, it will return removed.
type
string
The type of the instance, for example, `service_instance`.
sub_type
string
The sub-type of instance, for example, `cfaas`.
resource_id
string
The unique ID of the offering. This value is provided by and stored in the global catalog.
dashboard_url
string
The resource-broker-provided URL to access administrative features of the instance.
last_operation
object
The status of the last operation requested on the instance.
resource_keys_url
string
The relative path to the resource keys for the instance.
plan_history
array
The plan history of the instance.
migrated
boolean
A boolean that dictates if the resource instance was migrated from a previous CF instance.
extensions
object
Additional instance properties, contributed by the service and/or platform, are represented as key-value pairs.
controlled_by
string
The CRN of the resource that has control of the instance.
locked
boolean
A boolean that dictates if the resource instance is locked or not.
subscription_id
string
The subscription ID associated with the instance.
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.
id
string
The ID associated with the instance.
guid
string
The GUID of the instance.
url
string
When you provision a new resource, a relative URL path is created identifying the location of the instance.
created_at
string
The date when the instance was created.
updated_at
string
The date when the instance was last updated.
deleted_at
string
The date when the instance was deleted.
created_by
string
The subject who created the instance.
updated_by
string
The subject who updated the instance.
deleted_by
string
The subject who deleted the instance.
scheduled_reclaim_at
string
The date when the instance was scheduled for reclamation.
restored_at
string
The date when the instance under reclamation was restored.
restored_by
string
The subject who restored the instance back from reclamation.
scheduled_reclaim_by
string
The subject who initiated the instance reclamation.
name
string
The human-readable name of the instance.
region_id
string
The deployment location where the instance was provisioned.
account_id
string
An alpha-numeric value identifying the account ID.
reseller_channel_id
string
The unique ID of the reseller channel where the instance was provisioned from.
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.
resource_group_id
string
The ID of the resource group.
resource_group_crn
string
The CRN of the resource group.
target_crn
string
The deployment CRN as defined in the global catalog where the instance is provisioned.
onetime_credentials
boolean
Whether newly created resource key credentials can be retrieved by using get resource key or get a list of all of the resource keys requests.
parameters
object
The current configuration parameters of the instance from the previous operation. Any future operation on the instance may reset this these values.
allow_cleanup
boolean
A boolean that dictates if the resource instance should be deleted (cleaned up) during the processing of a region instance delete call.
crn
string
The full Cloud Resource Name (CRN) associated with the instance. For more information about this format, see Cloud Resource Names.
state
string
The current state of the instance. For example, if the instance is deleted, it will return removed.
type
string
The type of the instance, for example, `service_instance`.
sub_type
string
The sub-type of instance, for example, `cfaas`.
resource_id
string
The unique ID of the offering. This value is provided by and stored in the global catalog.
dashboard_url
string
The resource-broker-provided URL to access administrative features of the instance.
last_operation
object
The status of the last operation requested on the instance.
resource_keys_url
string
The relative path to the resource keys for the instance.
plan_history
array
The plan history of the instance.
migrated
boolean
A boolean that dictates if the resource instance was migrated from a previous CF instance.
extensions
object
Additional instance properties, contributed by the service and/or platform, are represented as key-value pairs.
controlled_by
string
The CRN of the resource that has control of the instance.
locked
boolean
A boolean that dictates if the resource instance is locked or not.
subscription_id
string
The subscription ID associated with the instance.
400 -
401 -
403 -
404 -
429 -
500 -
Get a resource instance
GET /v2/resource_instances/{id}
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.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
resource-controller.instance.retrieve
Request
Response
200 - The resource instance was successfully retrieved.
id
string
The ID associated with the instance.
guid
string
The GUID of the instance.
url
string
When you provision a new resource, a relative URL path is created identifying the location of the instance.
created_at
string
The date when the instance was created.
updated_at
string
The date when the instance was last updated.
deleted_at
string
The date when the instance was deleted.
created_by
string
The subject who created the instance.
updated_by
string
The subject who updated the instance.
deleted_by
string
The subject who deleted the instance.
scheduled_reclaim_at
string
The date when the instance was scheduled for reclamation.
restored_at
string
The date when the instance under reclamation was restored.
restored_by
string
The subject who restored the instance back from reclamation.
scheduled_reclaim_by
string
The subject who initiated the instance reclamation.
name
string
The human-readable name of the instance.
region_id
string
The deployment location where the instance was provisioned.
account_id
string
An alpha-numeric value identifying the account ID.
reseller_channel_id
string
The unique ID of the reseller channel where the instance was provisioned from.
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.
resource_group_id
string
The ID of the resource group.
resource_group_crn
string
The CRN of the resource group.
target_crn
string
The deployment CRN as defined in the global catalog where the instance is provisioned.
onetime_credentials
boolean
Whether newly created resource key credentials can be retrieved by using get resource key or get a list of all of the resource keys requests.
parameters
object
The current configuration parameters of the instance from the previous operation. Any future operation on the instance may reset this these values.
allow_cleanup
boolean
A boolean that dictates if the resource instance should be deleted (cleaned up) during the processing of a region instance delete call.
crn
string
The full Cloud Resource Name (CRN) associated with the instance. For more information about this format, see Cloud Resource Names.
state
string
The current state of the instance. For example, if the instance is deleted, it will return removed.
type
string
The type of the instance, for example, `service_instance`.
sub_type
string
The sub-type of instance, for example, `cfaas`.
resource_id
string
The unique ID of the offering. This value is provided by and stored in the global catalog.
dashboard_url
string
The resource-broker-provided URL to access administrative features of the instance.
last_operation
object
The status of the last operation requested on the instance.
resource_keys_url
string
The relative path to the resource keys for the instance.
plan_history
array
The plan history of the instance.
migrated
boolean
A boolean that dictates if the resource instance was migrated from a previous CF instance.
extensions
object
Additional instance properties, contributed by the service and/or platform, are represented as key-value pairs.
controlled_by
string
The CRN of the resource that has control of the instance.
locked
boolean
A boolean that dictates if the resource instance is locked or not.
subscription_id
string
The subscription ID associated with the instance.
401 -
403 -
404 -
429 -
500 -
Delete a resource instance
DELETE /v2/resource_instances/{id}
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.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
resource-controller.instance.delete
Auditing
Calling this method generates the following auditing event.
resource-controller.instance.delete
Request
Path Parameters
Query Parameters
recursive
boolean
Will delete keys associated with the instance.
Response
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 -
401 -
403 -
404 -
410 -
429 -
500 -
Update a resource instance
PATCH /v2/resource_instances/{id}
Use the resource instance URL-encoded CRN or GUID to make updates to the resource instance, like changing the name or plan.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
resource-controller.instance.update
Auditing
Calling this method generates the following auditing event.
resource-controller.instance.update
Request
Request Body
ResourceInstancePatch
name
string
The new name of the instance.
parameters
object
The new configuration options for the instance.<br><br>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.
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.
allow_cleanup
boolean
A boolean that dictates if the resource instance should be deleted (cleaned up) during the processing of a region instance delete call.
Response
200 - The requested changes have been applied
id
string
The ID associated with the instance.
guid
string
The GUID of the instance.
url
string
When you provision a new resource, a relative URL path is created identifying the location of the instance.
created_at
string
The date when the instance was created.
updated_at
string
The date when the instance was last updated.
deleted_at
string
The date when the instance was deleted.
created_by
string
The subject who created the instance.
updated_by
string
The subject who updated the instance.
deleted_by
string
The subject who deleted the instance.
scheduled_reclaim_at
string
The date when the instance was scheduled for reclamation.
restored_at
string
The date when the instance under reclamation was restored.
restored_by
string
The subject who restored the instance back from reclamation.
scheduled_reclaim_by
string
The subject who initiated the instance reclamation.
name
string
The human-readable name of the instance.
region_id
string
The deployment location where the instance was provisioned.
account_id
string
An alpha-numeric value identifying the account ID.
reseller_channel_id
string
The unique ID of the reseller channel where the instance was provisioned from.
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.
resource_group_id
string
The ID of the resource group.
resource_group_crn
string
The CRN of the resource group.
target_crn
string
The deployment CRN as defined in the global catalog where the instance is provisioned.
onetime_credentials
boolean
Whether newly created resource key credentials can be retrieved by using get resource key or get a list of all of the resource keys requests.
parameters
object
The current configuration parameters of the instance from the previous operation. Any future operation on the instance may reset this these values.
allow_cleanup
boolean
A boolean that dictates if the resource instance should be deleted (cleaned up) during the processing of a region instance delete call.
crn
string
The full Cloud Resource Name (CRN) associated with the instance. For more information about this format, see Cloud Resource Names.
state
string
The current state of the instance. For example, if the instance is deleted, it will return removed.
type
string
The type of the instance, for example, `service_instance`.
sub_type
string
The sub-type of instance, for example, `cfaas`.
resource_id
string
The unique ID of the offering. This value is provided by and stored in the global catalog.
dashboard_url
string
The resource-broker-provided URL to access administrative features of the instance.
last_operation
object
The status of the last operation requested on the instance.
resource_keys_url
string
The relative path to the resource keys for the instance.
plan_history
array
The plan history of the instance.
migrated
boolean
A boolean that dictates if the resource instance was migrated from a previous CF instance.
extensions
object
Additional instance properties, contributed by the service and/or platform, are represented as key-value pairs.
controlled_by
string
The CRN of the resource that has control of the instance.
locked
boolean
A boolean that dictates if the resource instance is locked or not.
subscription_id
string
The subscription ID associated with the instance.
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.
id
string
The ID associated with the instance.
guid
string
The GUID of the instance.
url
string
When you provision a new resource, a relative URL path is created identifying the location of the instance.
created_at
string
The date when the instance was created.
updated_at
string
The date when the instance was last updated.
deleted_at
string
The date when the instance was deleted.
created_by
string
The subject who created the instance.
updated_by
string
The subject who updated the instance.
deleted_by
string
The subject who deleted the instance.
scheduled_reclaim_at
string
The date when the instance was scheduled for reclamation.
restored_at
string
The date when the instance under reclamation was restored.
restored_by
string
The subject who restored the instance back from reclamation.
scheduled_reclaim_by
string
The subject who initiated the instance reclamation.
name
string
The human-readable name of the instance.
region_id
string
The deployment location where the instance was provisioned.
account_id
string
An alpha-numeric value identifying the account ID.
reseller_channel_id
string
The unique ID of the reseller channel where the instance was provisioned from.
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.
resource_group_id
string
The ID of the resource group.
resource_group_crn
string
The CRN of the resource group.
target_crn
string
The deployment CRN as defined in the global catalog where the instance is provisioned.
onetime_credentials
boolean
Whether newly created resource key credentials can be retrieved by using get resource key or get a list of all of the resource keys requests.
parameters
object
The current configuration parameters of the instance from the previous operation. Any future operation on the instance may reset this these values.
allow_cleanup
boolean
A boolean that dictates if the resource instance should be deleted (cleaned up) during the processing of a region instance delete call.
crn
string
The full Cloud Resource Name (CRN) associated with the instance. For more information about this format, see Cloud Resource Names.
state
string
The current state of the instance. For example, if the instance is deleted, it will return removed.
type
string
The type of the instance, for example, `service_instance`.
sub_type
string
The sub-type of instance, for example, `cfaas`.
resource_id
string
The unique ID of the offering. This value is provided by and stored in the global catalog.
dashboard_url
string
The resource-broker-provided URL to access administrative features of the instance.
last_operation
object
The status of the last operation requested on the instance.
resource_keys_url
string
The relative path to the resource keys for the instance.
plan_history
array
The plan history of the instance.
migrated
boolean
A boolean that dictates if the resource instance was migrated from a previous CF instance.
extensions
object
Additional instance properties, contributed by the service and/or platform, are represented as key-value pairs.
controlled_by
string
The CRN of the resource that has control of the instance.
locked
boolean
A boolean that dictates if the resource instance is locked or not.
subscription_id
string
The subscription ID associated with the instance.
400 -
401 -
403 -
404 -
422 -
429 -
500 -
Get a list of all the resource keys for the instance.
GET /v2/resource_instances/{id}/resource_keys
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.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
resource-controller.key.retrieve
Auditing
Calling this method generates the following auditing event.
resource-controller.key.retrieve
Request
Path Parameters
Query Parameters
limit
integer
Limit on how many items should be returned. The number of items returned may be less than the specified limit if the caller lacks sufficient access to retrieve certain resource keys.
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.
sort
string
Optional sort property, valid values are `name`, `created_at` and `updated_at`. If specified, the items are sorted by the value of this property.
order
string
Optional sort order, valid values are `asc` and `desc`.
Response
200 - The list of resource keys was successfully retrieved.
rows_count
integer
The number of resource keys in `resources`.
next_url
string
The URL for requesting the next page of results.
resources
array
A list of resource keys.
401 -
403 -
429 -
500 -
Lock a resource instance
POST /v2/resource_instances/{id}/lock
Locks a resource instance. A locked instance can not be updated or deleted. It does not affect actions performed on child resources like keys.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
resource-controller.instance.update
Auditing
Calling this method generates the following auditing event.
resource-controller.instance.update
Request
Response
200 - Successfully locked the instance.
id
string
The ID associated with the instance.
guid
string
The GUID of the instance.
url
string
When you provision a new resource, a relative URL path is created identifying the location of the instance.
created_at
string
The date when the instance was created.
updated_at
string
The date when the instance was last updated.
deleted_at
string
The date when the instance was deleted.
created_by
string
The subject who created the instance.
updated_by
string
The subject who updated the instance.
deleted_by
string
The subject who deleted the instance.
scheduled_reclaim_at
string
The date when the instance was scheduled for reclamation.
restored_at
string
The date when the instance under reclamation was restored.
restored_by
string
The subject who restored the instance back from reclamation.
scheduled_reclaim_by
string
The subject who initiated the instance reclamation.
name
string
The human-readable name of the instance.
region_id
string
The deployment location where the instance was provisioned.
account_id
string
An alpha-numeric value identifying the account ID.
reseller_channel_id
string
The unique ID of the reseller channel where the instance was provisioned from.
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.
resource_group_id
string
The ID of the resource group.
resource_group_crn
string
The CRN of the resource group.
target_crn
string
The deployment CRN as defined in the global catalog where the instance is provisioned.
onetime_credentials
boolean
Whether newly created resource key credentials can be retrieved by using get resource key or get a list of all of the resource keys requests.
parameters
object
The current configuration parameters of the instance from the previous operation. Any future operation on the instance may reset this these values.
allow_cleanup
boolean
A boolean that dictates if the resource instance should be deleted (cleaned up) during the processing of a region instance delete call.
crn
string
The full Cloud Resource Name (CRN) associated with the instance. For more information about this format, see Cloud Resource Names.
state
string
The current state of the instance. For example, if the instance is deleted, it will return removed.
type
string
The type of the instance, for example, `service_instance`.
sub_type
string
The sub-type of instance, for example, `cfaas`.
resource_id
string
The unique ID of the offering. This value is provided by and stored in the global catalog.
dashboard_url
string
The resource-broker-provided URL to access administrative features of the instance.
last_operation
object
The status of the last operation requested on the instance.
resource_keys_url
string
The relative path to the resource keys for the instance.
plan_history
array
The plan history of the instance.
migrated
boolean
A boolean that dictates if the resource instance was migrated from a previous CF instance.
extensions
object
Additional instance properties, contributed by the service and/or platform, are represented as key-value pairs.
controlled_by
string
The CRN of the resource that has control of the instance.
locked
boolean
A boolean that dictates if the resource instance is locked or not.
subscription_id
string
The subscription ID associated with the instance.
400 -
401 -
403 -
404 -
422 -
429 -
500 -
Unlock a resource instance
DELETE /v2/resource_instances/{id}/lock
Unlock a resource instance to update or delete it. Unlocking a resource instance does not affect child resources like keys.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
resource-controller.instance.update
Auditing
Calling this method generates the following auditing event.
resource-controller.instance.update
Request
Response
200 - Successfully unlocked the instance.
id
string
The ID associated with the instance.
guid
string
The GUID of the instance.
url
string
When you provision a new resource, a relative URL path is created identifying the location of the instance.
created_at
string
The date when the instance was created.
updated_at
string
The date when the instance was last updated.
deleted_at
string
The date when the instance was deleted.
created_by
string
The subject who created the instance.
updated_by
string
The subject who updated the instance.
deleted_by
string
The subject who deleted the instance.
scheduled_reclaim_at
string
The date when the instance was scheduled for reclamation.
restored_at
string
The date when the instance under reclamation was restored.
restored_by
string
The subject who restored the instance back from reclamation.
scheduled_reclaim_by
string
The subject who initiated the instance reclamation.
name
string
The human-readable name of the instance.
region_id
string
The deployment location where the instance was provisioned.
account_id
string
An alpha-numeric value identifying the account ID.
reseller_channel_id
string
The unique ID of the reseller channel where the instance was provisioned from.
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.
resource_group_id
string
The ID of the resource group.
resource_group_crn
string
The CRN of the resource group.
target_crn
string
The deployment CRN as defined in the global catalog where the instance is provisioned.
onetime_credentials
boolean
Whether newly created resource key credentials can be retrieved by using get resource key or get a list of all of the resource keys requests.
parameters
object
The current configuration parameters of the instance from the previous operation. Any future operation on the instance may reset this these values.
allow_cleanup
boolean
A boolean that dictates if the resource instance should be deleted (cleaned up) during the processing of a region instance delete call.
crn
string
The full Cloud Resource Name (CRN) associated with the instance. For more information about this format, see Cloud Resource Names.
state
string
The current state of the instance. For example, if the instance is deleted, it will return removed.
type
string
The type of the instance, for example, `service_instance`.
sub_type
string
The sub-type of instance, for example, `cfaas`.
resource_id
string
The unique ID of the offering. This value is provided by and stored in the global catalog.
dashboard_url
string
The resource-broker-provided URL to access administrative features of the instance.
last_operation
object
The status of the last operation requested on the instance.
resource_keys_url
string
The relative path to the resource keys for the instance.
plan_history
array
The plan history of the instance.
migrated
boolean
A boolean that dictates if the resource instance was migrated from a previous CF instance.
extensions
object
Additional instance properties, contributed by the service and/or platform, are represented as key-value pairs.
controlled_by
string
The CRN of the resource that has control of the instance.
locked
boolean
A boolean that dictates if the resource instance is locked or not.
subscription_id
string
The subscription ID associated with the instance.
400 -
401 -
403 -
404 -
422 -
429 -
500 -
Cancel the in progress last operation of the resource instance
DELETE /v2/resource_instances/{id}/last_operation
Cancel the in progress last operation of the resource instance. This is applicable for instances where the in progress last operation is `cancelable`.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
resource-controller.instance.delete
Auditing
Calling this method generates the following auditing event.
resource-controller.instance.delete
Request
Response
200 - Successfully canceled the in progress last operation of the resource instance.
id
string
The ID associated with the instance.
guid
string
The GUID of the instance.
url
string
When you provision a new resource, a relative URL path is created identifying the location of the instance.
created_at
string
The date when the instance was created.
updated_at
string
The date when the instance was last updated.
deleted_at
string
The date when the instance was deleted.
created_by
string
The subject who created the instance.
updated_by
string
The subject who updated the instance.
deleted_by
string
The subject who deleted the instance.
scheduled_reclaim_at
string
The date when the instance was scheduled for reclamation.
restored_at
string
The date when the instance under reclamation was restored.
restored_by
string
The subject who restored the instance back from reclamation.
scheduled_reclaim_by
string
The subject who initiated the instance reclamation.
name
string
The human-readable name of the instance.
region_id
string
The deployment location where the instance was provisioned.
account_id
string
An alpha-numeric value identifying the account ID.
reseller_channel_id
string
The unique ID of the reseller channel where the instance was provisioned from.
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.
resource_group_id
string
The ID of the resource group.
resource_group_crn
string
The CRN of the resource group.
target_crn
string
The deployment CRN as defined in the global catalog where the instance is provisioned.
onetime_credentials
boolean
Whether newly created resource key credentials can be retrieved by using get resource key or get a list of all of the resource keys requests.
parameters
object
The current configuration parameters of the instance from the previous operation. Any future operation on the instance may reset this these values.
allow_cleanup
boolean
A boolean that dictates if the resource instance should be deleted (cleaned up) during the processing of a region instance delete call.
crn
string
The full Cloud Resource Name (CRN) associated with the instance. For more information about this format, see Cloud Resource Names.
state
string
The current state of the instance. For example, if the instance is deleted, it will return removed.
type
string
The type of the instance, for example, `service_instance`.
sub_type
string
The sub-type of instance, for example, `cfaas`.
resource_id
string
The unique ID of the offering. This value is provided by and stored in the global catalog.
dashboard_url
string
The resource-broker-provided URL to access administrative features of the instance.
last_operation
object
The status of the last operation requested on the instance.
resource_keys_url
string
The relative path to the resource keys for the instance.
plan_history
array
The plan history of the instance.
migrated
boolean
A boolean that dictates if the resource instance was migrated from a previous CF instance.
extensions
object
Additional instance properties, contributed by the service and/or platform, are represented as key-value pairs.
controlled_by
string
The CRN of the resource that has control of the instance.
locked
boolean
A boolean that dictates if the resource instance is locked or not.
subscription_id
string
The subscription ID associated with the instance.
202 - Last operation cancel request accepted.
id
string
The ID associated with the instance.
guid
string
The GUID of the instance.
url
string
When you provision a new resource, a relative URL path is created identifying the location of the instance.
created_at
string
The date when the instance was created.
updated_at
string
The date when the instance was last updated.
deleted_at
string
The date when the instance was deleted.
created_by
string
The subject who created the instance.
updated_by
string
The subject who updated the instance.
deleted_by
string
The subject who deleted the instance.
scheduled_reclaim_at
string
The date when the instance was scheduled for reclamation.
restored_at
string
The date when the instance under reclamation was restored.
restored_by
string
The subject who restored the instance back from reclamation.
scheduled_reclaim_by
string
The subject who initiated the instance reclamation.
name
string
The human-readable name of the instance.
region_id
string
The deployment location where the instance was provisioned.
account_id
string
An alpha-numeric value identifying the account ID.
reseller_channel_id
string
The unique ID of the reseller channel where the instance was provisioned from.
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.
resource_group_id
string
The ID of the resource group.
resource_group_crn
string
The CRN of the resource group.
target_crn
string
The deployment CRN as defined in the global catalog where the instance is provisioned.
onetime_credentials
boolean
Whether newly created resource key credentials can be retrieved by using get resource key or get a list of all of the resource keys requests.
parameters
object
The current configuration parameters of the instance from the previous operation. Any future operation on the instance may reset this these values.
allow_cleanup
boolean
A boolean that dictates if the resource instance should be deleted (cleaned up) during the processing of a region instance delete call.
crn
string
The full Cloud Resource Name (CRN) associated with the instance. For more information about this format, see Cloud Resource Names.
state
string
The current state of the instance. For example, if the instance is deleted, it will return removed.
type
string
The type of the instance, for example, `service_instance`.
sub_type
string
The sub-type of instance, for example, `cfaas`.
resource_id
string
The unique ID of the offering. This value is provided by and stored in the global catalog.
dashboard_url
string
The resource-broker-provided URL to access administrative features of the instance.
last_operation
object
The status of the last operation requested on the instance.
resource_keys_url
string
The relative path to the resource keys for the instance.
plan_history
array
The plan history of the instance.
migrated
boolean
A boolean that dictates if the resource instance was migrated from a previous CF instance.
extensions
object
Additional instance properties, contributed by the service and/or platform, are represented as key-value pairs.
controlled_by
string
The CRN of the resource that has control of the instance.
locked
boolean
A boolean that dictates if the resource instance is locked or not.
subscription_id
string
The subscription ID associated with the instance.
400 -
401 -
403 -
404 -
422 -
429 -
500 -
502 -
Get a list of all of the resource keys
GET /v2/resource_keys
View all of the resource keys that exist for all of your resource instances.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
resource-controller.key.retrieve
Request
Path Parameters
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. The number of items returned may be less than the specified limit if the caller lacks sufficient access to retrieve certain resource keys.
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.
updated_to
string
End date inclusive filter.
sort
string
Optional sort property, valid values are `name`, `created_at` and `updated_at`. If specified, the items are sorted by the value of this property.
order
string
Optional sort order, valid values are `asc` and `desc`.
Response
200 - The list of resource keys was successfully retrieved.
rows_count
integer
The number of resource keys in `resources`.
next_url
string
The URL for requesting the next page of results.
resources
array
A list of resource keys.
401 -
403 -
429 -
500 -
Create a new resource key
POST /v2/resource_keys
A resource key is a saved credential you can use to authenticate with a resource instance.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
resource-controller.key.create
Auditing
Calling this method generates the following auditing event.
resource-controller.key.create
Request
Request Body
ResourceKeyPost
name
Required *
string
The name of the key.
source
Required *
string
The CRN or GUID of resource instance.
parameters
object
Configuration options represented as key-value pairs. Service defined options are passed through to the target resource brokers, whereas platform defined options are not.
serviceid_crn
string
An optional platform defined option to reuse an existing IAM serviceId for the role assignment.
onetime_credentials
boolean
An optional Boolean that determines whether the created resource key credentials can be retrieved by using get resource key or get a list of all the resource keys requests. The default value is 'onetime_credentials' from the instance.
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.
Response
201 - Created
id
string
The ID associated with the key.
guid
string
The GUID of the key.
url
string
When you created a new key, a relative URL path is created identifying the location of the key.
created_at
string
The date when the key was created.
updated_at
string
The date when the key was last updated.
deleted_at
string
The date when the key was deleted.
created_by
string
The subject who created the key.
updated_by
string
The subject who updated the key.
deleted_by
string
The subject who deleted the key.
source_crn
string
The CRN of resource instance associated to the key.
name
string
The human-readable name of the key.
crn
string
The full Cloud Resource Name (CRN) associated with the key. For more information about this format, see Cloud Resource Names.
state
string
The state of the key.
account_id
string
An alpha-numeric value identifying the account ID.
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.
onetime_credentials
boolean
Whether newly created resource key credentials can be retrieved by using get resource key or get a list of all of the resource keys requests.
credentials
object
The credentials for the key. Additional key-value pairs are passed through from the resource brokers. After a credential is created for a service, it can be viewed at any time for users that need the API key value. However, all users must have the correct level of access to see the details of a credential that includes the API key value. For additional details, see viewing a credential or the service’s documentation.
iam_compatible
boolean
Specifies whether the key’s credentials support IAM.
migrated
boolean
A boolean that dictates if the key was migrated from a previous CF instance.
resource_instance_url
string
The relative path to the resource.
400 -
401 -
403 -
404 -
429 -
500 -
Get resource key
GET /v2/resource_keys/{id}
View the details of a resource key by URL-encoded CRN or GUID, like the credentials for the key and who created it.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
resource-controller.key.retrieve
Request
Response
200 - The resource key was successfully retrieved.
id
string
The ID associated with the key.
guid
string
The GUID of the key.
url
string
When you created a new key, a relative URL path is created identifying the location of the key.
created_at
string
The date when the key was created.
updated_at
string
The date when the key was last updated.
deleted_at
string
The date when the key was deleted.
created_by
string
The subject who created the key.
updated_by
string
The subject who updated the key.
deleted_by
string
The subject who deleted the key.
source_crn
string
The CRN of resource instance associated to the key.
name
string
The human-readable name of the key.
crn
string
The full Cloud Resource Name (CRN) associated with the key. For more information about this format, see Cloud Resource Names.
state
string
The state of the key.
account_id
string
An alpha-numeric value identifying the account ID.
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.
onetime_credentials
boolean
Whether newly created resource key credentials can be retrieved by using get resource key or get a list of all of the resource keys requests.
credentials
object
The credentials for the key. Additional key-value pairs are passed through from the resource brokers. After a credential is created for a service, it can be viewed at any time for users that need the API key value. However, all users must have the correct level of access to see the details of a credential that includes the API key value. For additional details, see viewing a credential or the service’s documentation.
iam_compatible
boolean
Specifies whether the key’s credentials support IAM.
migrated
boolean
A boolean that dictates if the key was migrated from a previous CF instance.
resource_instance_url
string
The relative path to the resource.
401 -
403 -
404 -
429 -
500 -
Delete a resource key
DELETE /v2/resource_keys/{id}
Deleting a resource key does not affect any resource instance associated with the key.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
resource-controller.key.delete
Auditing
Calling this method generates the following auditing event.
resource-controller.key.delete
Request
Response
204 - Deleted
400 -
401 -
403 -
404 -
410 -
429 -
500 -
Update a resource key
PATCH /v2/resource_keys/{id}
Use the resource key URL-encoded CRN or GUID to update the resource key.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
resource-controller.key.update
Auditing
Calling this method generates the following auditing event.
resource-controller.key.update
Request
Request Body
ResourceKeyPatch
name
Required *
string
The new name of the key.
Response
200 - The resource key was successfully updated.
id
string
The ID associated with the key.
guid
string
The GUID of the key.
url
string
When you created a new key, a relative URL path is created identifying the location of the key.
created_at
string
The date when the key was created.
updated_at
string
The date when the key was last updated.
deleted_at
string
The date when the key was deleted.
created_by
string
The subject who created the key.
updated_by
string
The subject who updated the key.
deleted_by
string
The subject who deleted the key.
source_crn
string
The CRN of resource instance associated to the key.
name
string
The human-readable name of the key.
crn
string
The full Cloud Resource Name (CRN) associated with the key. For more information about this format, see Cloud Resource Names.
state
string
The state of the key.
account_id
string
An alpha-numeric value identifying the account ID.
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.
onetime_credentials
boolean
Whether newly created resource key credentials can be retrieved by using get resource key or get a list of all of the resource keys requests.
credentials
object
The credentials for the key. Additional key-value pairs are passed through from the resource brokers. After a credential is created for a service, it can be viewed at any time for users that need the API key value. However, all users must have the correct level of access to see the details of a credential that includes the API key value. For additional details, see viewing a credential or the service’s documentation.
iam_compatible
boolean
Specifies whether the key’s credentials support IAM.
migrated
boolean
A boolean that dictates if the key was migrated from a previous CF instance.
resource_instance_url
string
The relative path to the resource.
400 -
401 -
403 -
404 -
422 -
429 -
500 -
Get a list of all reclamations
GET /v1/reclamations
View all of the resource reclamations that exist for every resource instance.
Request
Path Parameters
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.
Response
200 - The list of reclamations was successfully retrieved.
resources
array
A list of reclamations.
401 -
403 -
404 -
429 -
500 -
Perform a reclamation action
POST /v1/reclamations/{id}/actions/{action_name}
Reclaim a resource instance so that it can no longer be used, or restore the resource instance so that it's usable again.
Request
Request Body
ReclamationActionsPost
request_by
string
The request initiator, if different from the request token.
comment
string
A comment to describe the action.
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.
Query Parameters
Response
200 - The reclamation action, such as restore or reclaim, was successfully performed.
id
string
The ID associated with the reclamation.
entity_id
string
The ID of the entity for the reclamation.
entity_type_id
string
The ID of the entity type for the reclamation.
entity_crn
string
The CRN of the entity for the reclamation.
resource_instance_id
string
The ID of the resource instance.
resource_group_id
string
The ID of the resource group.
account_id
string
An alpha-numeric value identifying the account ID.
policy_id
string
The ID of policy for the reclamation.
state
string
The state of the reclamation.
target_time
string
The target time that the reclamation retention period end.
custom_properties
object
The custom properties of the reclamation.
created_at
string
The date when the reclamation was created.
created_by
string
The subject who created the reclamation.
updated_at
string
The date when the reclamation was last updated.
updated_by
string
The subject who updated the reclamation.