Catalog Items

Catalog items are reusable templates that define a deployable resource. Each catalog item references a service type and may specify whether a resource configuration is editable while setting a preset, a default value and/or a validation schema for the user values — for example, CPU, memory, and storage for a virtual machine.

Creating a Catalog Item

To create a catalog item, define its configuration in a YAML or JSON file and pass it to the CLI:

dcm catalog item create --from-file item.yaml

To specify a custom identifier instead of letting DCM generate one:

dcm catalog item create --from-file item.yaml --id my-small-vm

Example YAML

Below is a complete catalog item definition for a small virtual machine:

api_version: v1alpha1
display_name: "Small VM"
spec:
  service_type: vm
  fields:
    - path: metadata
      editable: true
    - path: vcpu.count
      display_name: "CPU Count"
      editable: true
      default: 2
      validation_schema:
        type: integer
        minimum: 1
        maximum: 4
    - path: memory.size
      display_name: "Memory (GB)"
      editable: false
      default: "2GB"
    - path: storage.disks
      display_name: "Storage (GB)"
      editable: false
      default:
        - name: boot
          capacity: "20GB"
      validation_schema:
        type: array
    - path: guest_os.type
      display_name: "Guest OS"
      editable: true
      validation_schema:
        type: string
        enum:
          - fedora
          - centos
          - ubuntu

Key Sections

Section	Purpose
`api_version`	Ties the catalog item to a specific schema version (e.g., `v1alpha1`).
`display_name`	A human-readable name shown in listings and the UI.
`spec.service_type`	Corresponding service type
`spec.fields`	List of fields with const or user values
`spec.fields[].path`	Path of the field within the `service_type` specification
`spec.fields[].display_name`	A human-readable name shown in listings and the UI
`spec.fields[].editable`	Specify whether the user may edit the value
`spec.fields[].default`	Default value for the field. When `editable` is `false` this becomes the actual value
`spec.fields[].validation_schema`	JSON Schema rules to validate input. See: https://json-schema.org/

Fields and Policy Evaluation

Catalog item fields define the governance boundary for placement policies. When DCM builds the resource spec that policies evaluate, it includes only two sources:

Field defaults declared in the catalog item
user_values overrides provided at instance creation

Anything not declared as a catalog item field is invisible to the policy engine, even if set elsewhere on the instance request. This means labels must be exposed through fields with metadata.labels.* paths for policies to inspect them. For example, a field with path: metadata.labels.region makes the region label available to Rego policies as input.spec.metadata.labels.region.

See Policies for details on how input.spec is constructed and how to write policies that use label values.

Verifying the Catalog Item

After creating a catalog item, confirm it was registered successfully:

dcm catalog item get CATALOG_ITEM_ID

Listing Catalog Items

Use dcm catalog item list to view all catalog items:

dcm catalog item list

Example output:

UID                                    DISPLAY NAME   SERVICE TYPE   CREATED
small-vm                               Small VM       vm             2026-03-10T08:15:00Z
a7c2d9e4-b1f3-4567-89ab-cdef01234567   Large VM       vm             2026-03-12T14:30:00Z
web-server                             Web Server     container      2026-03-15T09:45:00Z

Filtering by Service Type

To show only catalog items for a specific service type:

dcm catalog item list --service-type "vm"

Pagination

For environments with many catalog items, use pagination flags:

dcm catalog item list --page-size 10

To fetch the next page, pass the token returned by the previous response:

dcm catalog item list --page-size 10 --page-token "eyJvZmZzZXQiOjEwfQ=="

Getting Catalog Item Details

Use dcm catalog item get to retrieve the full definition of a catalog item:

dcm catalog item get f4a8b3c1-d2e5-6789-abcd-ef0123456789

To view the output in JSON format:

dcm catalog item get f4a8b3c1-d2e5-6789-abcd-ef0123456789 -o json

Example JSON output:

{
  "api_version": "v1alpha1",
  "create_time": "2026-04-15T18:06:02.434302Z",
  "display_name": "Small VM",
  "path": "catalog-items/small-vm",
  "spec": {
    "fields": [
      {
        "editable": true,
        "path": "metadata"
      },
      {
        "default": 2,
        "display_name": "CPU Count",
        "editable": true,
        "path": "vcpu.count",
        "validation_schema": {
          "maximum": 4,
          "minimum": 1,
          "type": "integer"
        }
      },
      {
        "default": "2GB",
        "display_name": "Memory (GB)",
        "path": "memory.size"
      },
      {
        "default": [
          {
            "capacity": "20GB",
            "name": "boot"
          }
        ],
        "display_name": "Storage (GB)",
        "path": "storage.disks",
        "validation_schema": {
          "type": "array"
        }
      },
      {
        "default": "fedora",
        "display_name": "Guest OS",
        "editable": true,
        "path": "guest_os.type",
        "validation_schema": {
          "enum": [
            "fedora",
            "centos",
            "ubuntu"
          ],
          "type": "string"
        }
      }
    ],
    "service_type": "vm"
  },
  "uid": "small-vm",
  "update_time": "2026-04-15T18:06:02.434302Z"
}

Deleting a Catalog Item

To remove a catalog item:

dcm catalog item delete f4a8b3c1-d2e5-6789-abcd-ef0123456789

Note: Deleting a catalog item with instances that were already created from it will fail. Remove all existing instances before deleting the item.

For a step-by-step walkthrough, see Create Small VM Catalog Item.

Service Types Policies