# Managing Resource Providers Using Config Files

In order to facilitate management of resource provider information in the Placement API, Nova provides a method for admins to add custom inventory and traits to resource providers using YAML files.

Note

Only `CUSTOM_*` resource classes and traits may be managed this way.

## Placing Files

Nova-compute will search for `*.yaml` files in the path specified in `compute.provider_config_location`. These files will be loaded and validated for errors on nova-compute startup. If there are any errors in the files, nova-compute will fail to start up.

Administrators should ensure that provider config files have appropriate permissions and ownership. See the specification and admin guide for more details.

Note

The files are loaded once at nova-compute startup and any changes or new files will not be recognized until the next nova-compute startup.

## Examples

Resource providers to target can be identified by either UUID or name. In addition, the value `$COMPUTE_NODE` can be used in the UUID field to identify all nodes managed by the service.

If an entry does not include any additional inventory or traits, it will be logged at load time but otherwise ignored. In the case of a resource provider being identified by both `$COMPUTE_NODE` and individual UUID/name, the values in the `$COMPUTE_NODE` entry will be ignored for that provider only if the explicit entry includes inventory or traits.

Note

In the case that a resource provider is identified more than once by explicit UUID/name, the nova-compute service will fail to start. This is a global requirement across all supplied `provider.yaml` files.

    meta:
      schema_version: '1.0'
    providers:
      - identification:
          name: 'EXAMPLE_RESOURCE_PROVIDER'
          # Additional valid identification examples:
          # uuid: '$COMPUTE_NODE'
          # uuid: '5213b75d-9260-42a6-b236-f39b0fd10561'
        inventories:
          additional:
            - CUSTOM_EXAMPLE_RESOURCE_CLASS:
                total: 100
                reserved: 0
                min_unit: 1
                max_unit: 10
                step_size: 1
                allocation_ratio: 1.0
        traits:
          additional:
            - 'CUSTOM_EXAMPLE_TRAIT'

## Schema Example

    type: object
    properties:
      # This property is used to track where the provider.yaml file originated.
      # It is reserved for internal use and should never be set in a provider.yaml
      # file supplied by an end user.
      __source_file:
        not: {}
      meta:
        type: object
        properties:
          # Version ($Major, $minor) of the schema must successfully parse
          # documents conforming to ($Major, 0..N). Any breaking schema change
          # (e.g. removing fields, adding new required fields, imposing a stricter
          # pattern on a value, etc.) must bump $Major.
          schema_version:
            type: string
            pattern: '^1\.([0-9]|[1-9][0-9]+)$'
        required:
          - schema_version
        additionalProperties: true
      providers:
        type: array
        items:
          type: object
          properties:
            identification:
              $ref: '#/provider_definitions/provider_identification'
            inventories:
              $ref: '#/provider_definitions/provider_inventories'
            traits:
              $ref: '#/provider_definitions/provider_traits'
          required:
            - identification
          additionalProperties: true
    required:
      - meta
    additionalProperties: true

    provider_definitions:
      provider_identification:
        # Identify a single provider to configure. Exactly one identification
        # method should be used. Currently `uuid` or `name` are supported, but
        # future versions may support others.
        # The uuid can be set to the sentinel value `$COMPUTE_NODE` which will
        # cause the consuming compute service to apply the configuration to
        # to all compute node root providers it manages that are not otherwise
        # specified using a uuid or name.
        type: object
        properties:
          uuid:
            oneOf:
                # TODO(sean-k-mooney): replace this with type uuid when we can depend
                # on a version of the jsonschema lib that implements draft 8 or later
                # of the jsonschema spec.
              - type: string
                pattern: '^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$'
              - type: string
                const: '$COMPUTE_NODE'
          name:
            type: string
            minLength: 1
        # This introduces the possibility of an unsupported key name being used to
        # get by schema validation, but is necessary to support forward
        # compatibility with new identification methods. This should be checked
        # after schema validation.
        minProperties: 1
        maxProperties: 1
        additionalProperties: false
      provider_inventories:
        # Allows the admin to specify various adjectives to create and manage
        # providers' inventories. This list of adjectives can be extended in the
        # future as the schema evolves to meet new use cases. As of v1.0, only one
        # adjective, `additional`, is supported.
        type: object
        properties:
          additional:
            type: array
            items:
              patternProperties:
                # Allows any key name matching the resource class pattern,
                # check to prevent conflicts with virt driver owned resources classes
                # will be done after schema validation.
                ^[A-Z0-9_]{1,255}$:
                  type: object
                  properties:
                    # Any optional properties not populated will be given a default value by
                    # placement. If overriding a pre-existing provider values will not be
                    # preserved from the existing inventory.
                    total:
                      type: integer
                    reserved:
                      type: integer
                    min_unit:
                      type: integer
                    max_unit:
                      type: integer
                    step_size:
                      type: integer
                    allocation_ratio:
                      type: number
                  required:
                    - total
                  # The defined properties reflect the current placement data
                  # model. While defining those in the schema and not allowing
                  # additional properties means we will need to bump the schema
                  # version if they change, that is likely to be part of a large
                  # change that may have other impacts anyway. The benefit of
                  # stricter validation of property names outweighs the (small)
                  # chance of having to bump the schema version as described above.
                  additionalProperties: false
              # This ensures only keys matching the pattern above are allowed
              additionalProperties: false
        additionalProperties: true
      provider_traits:
        # Allows the admin to specify various adjectives to create and manage
        # providers' traits. This list of adjectives can be extended in the
        # future as the schema evolves to meet new use cases. As of v1.0, only one
        # adjective, `additional`, is supported.
        type: object
        properties:
          additional:
            type: array
            items:
              # Allows any value matching the trait pattern here, additional
              # validation will be done after schema validation.
              type: string
              pattern: '^[A-Z0-9_]{1,255}$'
        additionalProperties: true

Note

When creating a `provider.yaml` config file it is recommended to use the schema provided by nova to validate the config using a simple jsonschema validator rather than starting the nova compute agent to enable faster iteration.

this page last updated: 2026-06-08 12:33:00

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.

found an error? report a bug