Quadlets

Overview

Manages Podman and Podman Quadlets in particular

Example

Simple rootful centos.service Running a Container

quadlets::quadlet { 'centos.container':
  ensure          => present,
  unit_entry      => {
    'Description' => 'Trivial Container that will be very lazy',
  },
  service_entry   => {
    'TimeoutStartSec' => '900',
  },
  container_entry => {
    'Image' => 'quay.io/centos/centos:latest',
    'Exec'  => 'sh -c "sleep inf"',
  },
  install_entry   => {
    'WantedBy' => 'default.target',
  },
  active          => true,
}

Simple rootless centos.service Running a Container

The quadlet file will be maintained at /home/santa/.config/containers/systemd/centos.container

quadlets::user { 'santa':
  create_dir    => true,
  manage_user   => true,
  manage_linger => true,
  homedir       => "/home/santa",

}
quadlets::quadlet { "centos.container":
   ensure          => present,
   user            => 'santa',
   unit_entry      => {
     'Description' => 'Trivial Container that will be very lazy',
   },
   container_entry => {
     'Image' => 'quay.io/centos/centos:latest',
     'Exec'  => 'sh -c "sleep inf"',
   },
   install_entry   => {
     'WantedBy' => 'default.target',
   },
   active          => true,
   require         => Quadlets::User['santa'],
 }

Simple rootless centos.service Running a Container with a Network

The quadlet files will be maintained in /etc/containers/systemd/users/<uid of santa>

This particular case of a system located quadlet path will require up to two puppet runs. The first run will populate the configuration of quadlets.users fact for the particular user.

quadlets::user { 'santa':
  create_dir    => true,
  manage_user   => true,
  manage_linger => true,
  homedir       => "/home/santa",

}

# Set defaults for all the quadlets belonging to "santa".
Quadlets::Quadlet {
  ensure   => 'present',
  location => 'system',
  user     => 'santa',
  active   => true,
}

quadlets::quadlet { "centos.container":
  unit_entry      => {
    'Description' => 'Trivial Container that will be very lazy',
  },
  container_entry => {
    'Image'   => 'quay.io/centos/centos:latest',
    'Exec'    => 'sh -c "sleep inf"',
    'Network' => 'centos.network',
  },
  install_entry   => {
    'WantedBy' => 'default.target',
  },
  require         => Quadlets::Quadlet['centos.network'],
}

quadlets::quadlet { "centos.network":
  unit_entry      => {
    'Description' => 'Trivial Network',
  },
  network_entry => {
    'Subnet'  => '192.168.30.0/24',
    'Gateway' => '192.168.30.1',
  },
  install_entry   => {
    'WantedBy' => 'default.target',
  },
}

Build a Local Image and Run It as a Container

The .build quadlet type builds a container image from a local Containerfile and makes it available to other quadlet units. The build service runs once and subsequent restarts are fast due to image layer caching.

quadlets::quadlet { 'myapp.build':
  ensure      => present,
  build_entry => {
    'ImageTag'            => 'localhost/myapp:latest',
    'SetWorkingDirectory' => 'unit',
  },
}

quadlets::quadlet { 'myapp.container':
  ensure          => present,
  container_entry => {
    'Image' => 'myapp.build',
    'Exec'  => '/usr/bin/myapp',
  },
  install_entry   => {
    'WantedBy' => 'default.target',
  },
  active          => true,
  require         => Quadlets::Quadlet['myapp.build'],
}

Hiera Representation Of User setup and Quadlet deployment

quadlets::users_hash:
  charlie: {}
  lucy:
    homedir: '/opt/lucy'

quadlets::quadlets_hash:
  centos.container:
    user: 'charlie'
    location: 'system'
    container_entry:
      Image: 'quay.io/centos/centos:latest'
      Exec: 'sh -c "sleep inf"'
      Network: 'centos.network'
    require: 'Quadlets::Quadlet[centos.network]'
  centos.network:
    user: 'charlie'
    location: 'system'
    network_entry:
      Subnet: '192.168.30.0/24'
      Gateway: '192.168.30.1'
  busybox.image:
    user: 'lucy'
    homedir: '/opt/lucy'
    unit_entry:
      Description: 'Busybox Image'
    image_entry:
      Image: 'docker.io/busybox'

Migrating from version 3 to version 4

Version 4 fixes a bug #112 that may require some manual cleanup.

Only rootless quadlets located in the system location may be affected e.g.

quadlets::quadlet {'alice.container:
  ensure          => 'present',
  location        => 'system',
  user            => 'santa',
  active          => 'true',
  container_entry => {
    'Image' => 'myapp.build',
    'Exec'  => '/usr/bin/myapp',
  },
}

In version 3 the quadlet file was created in /etc/containers/systemd/users/santa which will have generated a container for ALL users with a systemd --user process.

In version 4 the quadlet will be correctly located in /etc/containers/systemd/users/<uid of santa> and only be generated for user santa as was requested.

After update to v4 verify that no undesirable containers are running. A system reboot is a reliable way to ensure correctness as all container start-up files will be generated correctly from nothing.

Migrating from version 2 to version 3

With version 3 the method for defining rootless containers has changed in a completely backwards incompatible way. For rootful containers the situation is unchanged.

• The type Quadlets::Quadlet_user is completely removed.
• The quadlets::user definition is as above.
• The qaudlets::quadlet parameters now expects the user parameter as a user name and can have the group and homedir provided if something is required beyond the default behaviour.

The motivation for migration was to make the module more obvious and easier to document.

By example:

# Old v2 configuration
$_user = {
  name          => 'container',
  homedir       => '/nfs/home/cont'
  manage_linger => true,
}

quadlets::user{'container':
  user => $_user,
}

quadlets::quadlet{ 'my.pod':
  ensure  => 'present',
  user    => $_user,
  unit    => {
    'Description' => 'Simple Pod',
  }
  require => Quadlet::Quadlet['container'],
}

now becomes

# New v3 configuration
quadlets::user{'container':
  homedir       => '/nfs/home/cont',
  manage_linger => true,
}

quadlets::quadlet{ 'my.pod':
  ensure  => 'present',
  user    => 'container',
  homedir => '/nfs/home/cont',
  unit    => {
    'Description' => 'Simple Pod',
  },
  require => Quadlet::Quadlet['container'],
}

The end result is identical.

Quadlets Fact

The podman version can be accessed via the quadlets fact.

facter quadlets
{
  podman_version => "5.4.0"
  users => {
    alice => {
      uid => 1234,
    },
    bob => {
      uid => 1234,
    },

  }
}

The users tree is only populated for any user for which a quadlets::user or a rootless quadlets::quadlet has been defined. The tree will only be populated on the 2nd run of puppet. Deploying a rootless quadlets:quadlet in the system path will require two puppet runs.

Reference

The reference of the quadlet module see REFERENCE.md