Cloud Resource Names

CRN format

The base canonical format of a CRN is:

crn:version:cname:ctype:service-name:location:scope:service-instance:resource-type:resource

version

The version segment identifies the version of the CRN format. Currently, the only valid version segment value is v1.

cname

The cname segment identifies the cloud instance and is an alphanumeric identifier that uniquely identifies the cloud instance that contains the resource. A cname effectively identifies an independent control plane that owns the identified resource. The value for the cname segment must be bluemix for IBM Cloud users.

ctype

The ctype segment identifies the type of cloud instance that is represented by the specified cname segment.

Valid values:

• public: All services that are available from the public catalog
• dedicated: Only for current IBM Cloud dedicated environments
• local: All services that are deployed locally in your own environment

service-name

IBM Cloud enforces global uniqueness of service names. The service-name segment identifies a capability (service, component, or product) that is offered by the cloud. The capability can be a user-provided service, such as with the services that are listed in the IBM Cloud catalog, or an internal architectural component critical to the IBM Cloud functionality.

The service-name segment indicates the service that the resource belongs to. The service-name segment must be alphanumeric, lowercase, and have no spaces or special characters other than -. If you're identifying a service name for a child service, you must have a period . that separates the parent service name from the child. For example, if you have a service that's called iam-service and a child of that is called micro, iam-service is the parent service and iam-service.micro is considered the child service.

For services that are registered into the IBM Cloud catalog, the service-name segment must correspond to one of the services that are registered to the IBM Cloud global catalog service. It is the name property that is returned by the IBM Cloud global catalog service API GET https://globalcatalog.cloud.ibm.com/api/v1/{id} for the corresponding resource instance or the service-name value that is displayed by the command-line interface (CLI): ibmcloud service offerings in the service column.

location

The cloud geography/region/zone/data center that the resource resides.

The location segment must be one of the location names listed by the ibmcloud catalog locations CLI command.

Some resources do not require a region, as they can be considered global. In this case, the region segment is set to global.

scope

The scope segment identifies the containment or owner of the resource. Some resources do not require an owner (they can be considered global). In this case, the scope segment is empty (a blank string).

The value of the scope segment must be formatted as {scopePrefix}/{id}. The scopePrefix represents the format that is used to identify the owner or containment. The id represents the identity of the owner or containment in a format that is specific to the scopePrefix.

service-instance

The service-instance segment identifies the service instance uniquely. The format of the service-instance segment varies by service. Each service must document the format of their service_instance segment as part of their service metadata. Some services do not have instances because the instance is global, and in this case the service-instance field is blank.

The service-instance must be alphanumeric, lowercase, no spaces, or special characters other than '-' and '/'.

For example, a DevOps tool that is used to track and plan work items can have a simple GUID instance ID ("1234-5678-9012-3456"). But, the policy component of an autoscale group service can use a hierarchical naming convention and have a service-id segment of:

c7a27f55-d35e-4153-b044-8ca9155fc467/my-test-asg1/my-scaleout-policy

You can also obtain a CRN from an IBM Cloud resource by using the following CLI command:

ibmcloud resource service-instance

resource-type, resource

The values of the resource-type and resource segments vary by service. A service is required to document their supported resource types segment and the format of the resource segment as part of their service metadata.

As an example, an image in the customer receipts container in an Object Storage service can have a resource-type segment of object and a resource value of CustomerReceipts/clientdinner.png.

The resource-type segment must be alphanumeric, lowercase, and no spaces or special characters other than '-'. A service can decide that the resource-type segment is optional, in which case it remains blank.

CRN examples

The following table provides a list of CRN examples.