Adding allowed-use expressions to custom images

Use an allowed-use expression with your custom image to define the capabilities and restrictions of an image and help you find compatible image and profile combinations during server creation.

You can use allowed-use expressions to configure which profiles, images, and server settings can be used together when you provision a virtual server instance or bare metal server. When you make selections to create a virtual server instance or bare metal server, if you use a custom image with defined allowed-use expressions, you can then determine which profiles are compatible with those expressions.

During the creation of a virtual server instance or a bare metal server with custom images that have an allowed-use expression, the information that is provided in the allowed-use properties is then evaluated against a potential virtual server instance or bare metal server properties to determine whether that custom image can be used to create the virtual server instance or bare metal server.

With the UI, CLI, and API, you can define allowed-use expressions for any custom image, image from volume, detached boot volume, or snapshots of boot volumes. IBM Cloud® Virtual Private Cloud sets the allowed-use expression for all stock images, but you can define them for any custom image you created. The default value is the allowed-use expressions evaluates to true, meaning that the custom image is allowed to be used with all potential server provisions. You must define or edit the allowed-use expression if you don't want the custom image to be used in specific situations.

For custom images and images shared with a private catalog, you can define the allowed-use expression when creating the image in IBM Cloud VPC. For images from volumes, detached boot volumes, and snapshots of boot volumes, the allowed-use expression is inherited from the source by default. However, you can override this expression when creating the resource. For all images, boot volumes, and snapshots of boot volumes, the allowed-use expression can be updated after creation.

For more information on x86 virtual server profiles and to get the information to define the allowed-use expression you want to use for your custom image, see x86-64 instance profiles. For more information on x86-64 bare metal server profiles, see x86-64 bare metal server profiles.

IAM authority required to define allowed-use expressions

You must have one or more of the following authorizations to be able to define allowed-use expressions, depending on what type of resource you are working with.

is.image.image.manage-allowed-use for custom images, images that are managed by a private catalog, and image from volume
is.volume.volume.manage-allowed-use for boot volumes
is.snapshot.snapshot.manage-allowed-use for snapshots of boot volumes

Defining allowed-use expressions by using the UI

When you are creating an image by using the UI, you can add the allowed-use expression details in the Advanced Options area. If you are viewing an existing image, the image details include Virtual server expression and Bare metal server expression. Click edit on one of these fields to open the allowed-use expression text box.

The allowed-use expression section is a text box where you can add the expressions as detailed in the following table. See the following tables for the allowed-use expression details for virtual server instances and bare metal servers.

Virtual server instance UI allowed-use expressions
Virtual server instance UI allowed-use expression options
Allowed-use expression	Expression variable	Type
Virtual server expression	`gpu.count` Indicates the number of GPUs assigned to the virtual server instance.	Integer
	`gpu.manufacturer` Indicates the GPU manufacturer.	Case-sensitive string
	`gpu.memory` Indicates the overall amount of GPU memory in GiB.	Integer
	`gpu.model` Indicates the GPU model.	Case-sensitive string
	`enable_secure_boot` Indicates whether secure boot is enabled for the virtual server instance.	Boolean

Bare metal server UI allowed-use expressions
Bare metal server UI allowed-use expression options
Allowed-use expression	Expression variable	Type
Bare metal server expression	`enable_secure_boot` Indicates whether secure boot is enabled for the bare metal server.	Boolean

The following example is an allowed-use expression for a virtual server instance for GPU count that is greater than one with Nvidia as the GPU manufacturer. Secure boot is required.

gpu.count > 1 && gpu.manufacturer == 'nvidia' && enable_secure_boot

For more information about Common Expression Language, which is used to create the allowed-use expression, see Google's CEL Language Definition reference

Defining allowed-use expressions by using the CLI

See the following tables for the allowed-use expression details for virtual server instances and bare metal servers.

Virtual server instance CLI allowed-use expressions
Virtual server instance CLI allowed-use expression options
Allowed-use option	Expression variable	Type
`--allowed-use-instance`	`gpu.count` Indicates the number of GPUs assigned to the virtual server instance.	Integer
	`gpu.manufacturer` Indicates the GPU manufacturer.	Case-sensitive string
	`gpu.memory` Indicates the overall amount of GPU memory in GiB.	Integer
	`gpu.model` Indicates the GPU model.	Case-sensitive string
	`enable_secure_boot` Indicates whether secure boot is enabled for the virtual server instance.	Boolean

Bare metal server CLI allowed-use expressions
Bare metal server CLI allowed-use expression options
Allowed-use option	Expression variable	Type
`--allowed-use-bare-metal-server`	`enable_secure_boot` Indicates whether secure boot is enabled for the bare metal server.	Boolean

The following code example shows how to use the allowed-use expression options when you create a new custom image by using the CLI. The example sets up the image to require secure boot enablement for a bare metal server, and to allow any provision of a virtual server instance.

ibmcloud is image-create my-ubuntu-20-amd64 --file cos://us-south/custom-image-vpc-bucket/customImage-0.qcow2 --os-name ubuntu-20-04-amd64 --allowed-use-bare-metal-server "enable_secure_boot==true" --allowed-use-instance true

The following code example shows how to use the allowed-use expression options when you update an existing custom image by using the CLI. The example is updating an image to require secure boot enablement for provisions of both a bare metal server and a virtual server instance.

ibmcloud is image-update r134-c9da1575-20cd-4412-9269-8ed08d3ac278 --allowed-use-bare-metal-server enable_secure_boot==true --allowed-use-instance enable_secure_boot==true

For more information about the CLI allowed-use expression options and variables, see the VPC CLI reference: Images. For more information regarding Common Expression Language, which is used to create the allowed-use expression, see Google's CEL Language Definition reference

Defining allowed-use expressions by using the API

See the following tables for the allowed-use expression details for virtual server instances and bare metal servers.

Virtual server instance API allowed-use expressions
Virtual server instance API allowed-use expression options
Allowed-use property	Allowed-use subproperty	Expression variable	Type
`allowed_use`	`instance`	`gpu.count` Indicates the number of GPUs assigned to the virtual server instance.	Integer
		`gpu.manufacturer` Indicates the GPU manufacturer.	Case-sensitive string
		`gpu.memory` Indicates the overall amount of GPU memory in GiB.	Integer
		`gpu.model` Indicates the GPU model.	Case-sensitive string
		`enable_secure_boot` Indicates whether secure boot is enabled for the virtual server instance.	Boolean

Bare metal server API allowed-use expressions
Bare metal server API allowed-use expression options
Allowed-use property	Allowed-use sub-property	Expression variable	Type
`allowed_use`	`bare_metal_server`	`enable_secure_boot` Indicates whether secure boot is enabled for the bare metal server.	Boolean

To create a new custom image with an allowed-use expression, use the POST /images API command. The following example creates a new custom image with an allowed-use expression for a virtual server instance for GPU count that is greater than one with Nvidia as the GPU manufacturer. Secure boot is required. The bare metal server allowed-use expression is set to false which prevents the image from being used to provision a bare metal server.

curl -X POST "$vpc_api_endpoint/v1/images?version=$today&generation=2" -H "Authorization: Bearer $iam_token" -d '{
      "name": "my-image",
      "file": {
        "href": "cos://us-south/my-bucket/my-image.qcow2"
      },
      "operating_system": {
        "name": "debian-9-amd64"
      },
      "allowed_use": {
         "instance": "gpu.count > 1 && gpu.manufacturer == \"nvidia\" && enable_secure_boot",
         "bare_metal_server": "false"
      }
    }'

To update an existing custom image with an allowed-use expression, use the PATCH /images API command. The following example updates an existing custom image with an allowed-use expression for a virtual server instance for GPU count that is greater than one with Nvidia as the GPU manufacturer. Secure boot is required. The bare metal server allowed-use expression is set to false which prevents the image from being used to provision a bare metal server.

curl -X PATCH "$vpc_api_endpoint/v1/images/$image_id?version=$today&generation=2" -H 'Content-Type: application/json' -H "Authorization: Bearer $iam_token"  -d '{
"allowed_use": {
  "instance": "gpu.count > 1 && gpu.manufacturer == \"nvidia\" && enable_secure_boot",
  "bare_metal_server": "false"
  }
}'

For more details on the API allowed-use expression property, sub-properties, and expressions, see the Virtual Private Cloud API: Create image and Virtual Private Cloud API: Update image. For more information regarding Common Expression Language, which is used to create the allowed-use expression, see Google's CEL Language Definition reference