VPC considerations when using custom images in a private catalog

Using cross-account image references in a private catalog in the UI

Instances you provision belong to your account. Images shared to your account through a private catalog might belong to other accounts. When you provision an instance from an image that belongs to another account or from an instance template that specifies such an image, the image still belongs to the other account even though the instance belongs to your account. A reference to such an image might exist in details of the instance and related resources. For example, details about its boot volume and any snapshot that was created from that boot volume might reference that image. Regardless of your authorizations, you can't access the referenced image by its ID or CRN and attempts fail as if the image does not exist.

Additionally, it is possible that the referenced image might have the same name as a custom image in your account. But these image names are for two different images in two different accounts. The ID and CRN each uniquely identifies an image across IBM Cloud®. To avoid possible retrieval or use of the wrong image, when you cut-and-paste an image’s identity outside of the UI, use its ID or CRN, rather than its name.

Using cross-account image references in a private catalog in the CLI

Instances you provision belong to your account. Images shared to your account through a private catalog might belong to other accounts. When you provision an instance from an image that belongs to another account or from an instance template that specifies such an image, the image still belongs to the other account even though the instance belongs to your account. A reference to such an image might exist in details of the instance and related resources. For example, details about its boot volume and any snapshot that was created from that boot volume might reference that image. Regardless of your authorizations, you can't access this type of custom image by its ID and attempts fail as if the image does not exist.

Image references are used in a few different places in the CLI. For example, if you use the ibmcloud is instance command to retrieve instance data, you see the following within the output.

Image                                 ID                                          Name
                                      r006-6cab2dbd-4e57-4dc5-810b-b7366cb78999   test-image

If you try to retrieve information about this image by using its ID,

ibmcloud is image r006-6cab2dbd-4e57-4dc5-810b-b7366cb78999

then this attempt fails with an error such as the following example:

FAILED
Response HTTP Status Code: 404
Error code: not_found
Error message: The requested resource does not exist, or cannot be accessed.
Error target name: id, type: parameter
Trace ID: d8b4d382-2993-4a89-a371-1db991b510d8

This error means that the image doesn't exist in your account. If the instance was provisioned by using a shared catalog image in another account, this output is the output that you always see even if the image exists in the owning account.

Additionally, it is possible that the referenced image might have the same name as a custom image in your account. But these image names are for two different images in two different accounts. While the CLI uses both ID and Name to identify an image, only the ID uniquely identifies an image across IBM Cloud®.

Verify that your CLI-based automation handles image reference lookup failures gracefully and do not assume that inaccessible images were deleted, even if it runs with full access to your images. To avoid possible retrieval or use of the wrong image by Name, specify the image ID instead.

Using cross-account image references in a private catalog in the API

Instances that you provision belong to your account. Images that are shared to your account through a private catalog might belong to other accounts. When you provision an instance from an image that belongs to another account or from an instance template that specifies such an image, the image still belongs to the other account even though the instance belongs to your account. A reference to such an image might exist in details of the instance and related resources. For example, details about its boot volume and any snapshot that are created from that boot volume might reference that image. Regardless of your authorizations, you can't access such an image by its id, crn, or href and attempts fail as if the image does not exist.

In the API, an image reference appears in places such as the image properties of the Instance and BareMetalServerInitialization response schemas and in the source_image properties of the Volume and Snapshot response schemas. The following example uses retrieving instance data to illustrate how this error might occur.

curl -X GET "$vpc_api_endpoint/v1/instances/r006-44905aa4-119d-5622-00ce-face32b78999?version=2022-09-06&generation=2" -H "Authorization: Bearer $iam_token" | jq -r '(.image)'

When you run this command, you see the following output.

{
  "crn": "crn:v1:bluemix:public:is:us-south:a/123456::image:r006-6cab2dbd-4e57-4dc5-810b-b7366cb78999",
  "href": "https://us-south.iaas.cloud.ibm.com/v1/images/r006-6cab2dbd-4e57-4dc5-810b-b7366cb78999",
  "id": "r006-6cab2dbd-4e57-4dc5-810b-b7366cb78999",
  "name": "test-image"
}

If you try to retrieve information about this image by using its id,

curl -X GET "$vpc_api_endpoint/v1/images/r006-6cab2dbd-4e57-4dc5-810b-b7366cb78999?version=2022-09-06&generation=2" -H "Authorization: Bearer $iam_token"

then this attempt fails with HTTP status code 404 (not found). This status code means that the image doesn't exist in your account. If the instance was provisioned by using a shared catalog image in another account, this response is the response that you always get even if the image still exists in the owning account.

Additionally, it is possible that the referenced image might have the same name as a custom image in your account. But these image names are for two different images in two different accounts. The id, crn, and href each uniquely identifies an image across IBM Cloud®.

Verify that your clients handle image reference lookup failures gracefully and do not assume that inaccessible images were deleted, even when it runs with full access to your images. To avoid possible retrieval or use of the wrong image by name, specify the image id, crn, or href instead.

Using cross-account image references in a private catalog in Terraform

Instances that you provision belong to your account. Images that are shared to your account through a private catalog might belong to other accounts. When you provision an instance from an image that belongs to another account or from an instance template that specifies such an image, the image still belongs to the other account even though the instance belongs to your account. A reference to such an image might exist in details of the instance and related resources. For example, details about its boot volume and any snapshot that was created from that boot volume might reference that image. Regardless of your authorizations, you can't access this type of custom image by its ID and attempts fail as if the image does not exist.

Image references are used in a few different places in the terraform. For example, if you use the instance data source to retrieve instance data, you see the following within the data source response.

"image": "r006-e0d3b6fb-5421-4421-9061-0ca9f79a4990"

If you try to retrieve information about this image by using its data source,

data "ibm_is_image" "example" {
  identifier = "r006-e0d3b6fb-5421-4421-9061-0ca9f79a4990"
}

then this attempt fails with an error such as the following example:

Error: [ERROR] No image found with id  r006-e0d3b6fb-5421-4421-9061-0ca9f79a4990

This error means that the image doesn't exist in your account. If the instance was provisioned by using a shared catalog image in another account, this output is the output that you always see even if the image still exists in the owning account.

Additionally, it is possible that the referenced image might have the same name as a custom image in your account. But these image names are for two different images in two different accounts. While the terraform uses both ID or Name to identify an image, only the ID uniquely identifies an image across IBM Cloud®. To avoid possible retrieval or use of the wrong image by name, specify the image ID instead. For more information, see image data source.