Resource definition: the type

A type is a definition of a resource that Puppet can manage. The definition contains the resource’s configurable properties and the parameters used to access it.

To make the resource known to the Puppet ecosystem, its definition, or type needs to be registered with Puppet. For example:

Puppet::ResourceApi.register_type(
  name: 'apt_key',
  desc: <<-EOS,
    This type provides Puppet with the capabilities to manage GPG keys needed
    by apt to perform package validation. Apt has it's own GPG keyring that can
    be manipulated through the `apt-key` command.

    apt_key { '6F6B15509CF8E59E6E469F327F438280EF8D349F':
      source => 'http://apt.puppet.com/pubkey.gpg'
    }

    **Autorequires**:
    If Puppet is given the location of a key file which looks like an absolute
    path this type will autorequire that file.
  EOS
  attributes: {
    ensure: {
      type: 'Enum[present, absent]',
      desc: 'Whether this apt key should be present or absent on the target system.'
    },
    id: {
      type:      'Variant[Pattern[/\A(0x)?[0-9a-fA-F]{8}\Z/], Pattern[/\A(0x)?[0-9a-fA-F]{16}\Z/], Pattern[/\A(0x)?[0-9a-fA-F]{40}\Z/]]',
      behaviour: :namevar,
      desc:      'The ID of the key you want to manage.',
    },
    source: {
      type: 'String',
      desc: 'Where to retrieve the key from, can be a HTTP(s) URL, or a local file. Files get automatically required.',
    },
    # ...
    created: {
      type:      'String',
      behaviour: :read_only,
      desc:      'Date the key was created, in ISO format.',
    },
  },
  autorequire: {
    file:    '$source', # evaluates to the value of the `source` attribute
    package: 'apt',
  },
)

The Puppet::ResourceApi.register_type(options) function takes the following keyword arguments:

• name: the name of the resource type.

• desc: a doc string that describes the overall working of the resource type, provides examples, and explains prerequisites and known issues.

• attributes: a hash mapping attribute names to their details. Each attribute is described by a hash containing the Puppet 4 data type, a desc string, a default value, and the behavior of the attribute: namevar, read_only, init_only, or a parameter.

  • type: the Puppet 4 data type allowed in this attribute.

  • desc: a string describing this attribute. This is used in creating the automated API docs with puppet-strings.

  • default: a default value that the runtime environment uses when you don't specify a value.

  • behavior/behaviour: how the attribute behaves. Currently available values:

    • namevar: marks an attribute as part of the "primary key" or "identity" of the resource. A given set of namevar values needs to distinctively identify an instance.

    • init_only: this attribute can only be set when creating the resource. Its value is reported going forward, but trying to change it later leads to an error. For example, the base image for a VM or the UID of a user.

    • read_only: values for this attribute are returned by get(), but set() is not able to change them. Values for this should never be specified in a manifest. For example, the checksum of a file, or the MAC address of a network interface.

    • parameter: these attributes influence how the provider behaves, and cannot be read from the target system. For example, the target file on inifile, or the credentials to access an API.

• autorequire, autobefore, autosubscribe, and autonotify: a hash mapping resource types to titles. The titles must either be constants, or, if the value starts with a dollar sign, a reference to the value of an attribute. If the specified resources exist in the catalog, Puppet creates the relationships that are requested here.

• features: a list of API feature names, specifying which optional parts of this spec the provider supports. Currently defined features: canonicalize, simple_get_filter, and supports_noop. See provider types for details.

Composite namevars (title_patterns)

Each resource being managed must be identified by a unique title. Usually this is straightforward and a single attribute can be used to act as an identifier. But sometimes you need a composite of two attributes to uniquely identify the resource you want to manage.

If multiple attributes are defined with the namevar behavior, the type specifies title_patterns that tell the Resource API how to get at the attributes from the title. If title_patterns is not specified, a default pattern is applied and matches against the first declared namevar.

Each title pattern contains:

• pattern, which is a Ruby regular expression containing named captures. The names of the captures must be that of the namevar attributes.

• desc, a short description of what the pattern matches for.

For example:

Puppet::ResourceApi.register_type(
  name: 'software',
  docs: <<-DOC,
    This type provides Puppet with the capabilities to manage ...
  DOC
  title_patterns: [
    {
      pattern: %r{^(?<package>.*[^-])-(?<manager>.*)$},
      desc: 'Where the package and the manager are provided with a hyphen seperator',
    },
    {
      pattern: %r{^(?<package>.*)$},
      desc: 'Where only the package is provided',
    },
  ],
  attributes: {
    ensure: {
      type:    'Enum[present, absent]',
      desc:    'Whether this resource should be present or absent on the target system.',
      default: 'present',
    },
    package: {
      type:      'String',
      desc:      'The name of the package you want to manage.',
      behaviour: :namevar,
    },
    manager: {
      type:      'String',
      desc:      'The system used to install the package.',
      behaviour: :namevar,
    },
  },
)

These match the first title pattern:

software { php-yum:
  ensure=>'present'
}

software { php-gem:
  ensure=>'absent'
}

This matches the second title pattern:

software { php:
  manager='yum'
  ensure=>'present'
}