REFERENCE.md

Reference

Table of Contents

Classes

Public Classes

• apptainer: Manage Apptainer

Private Classes

• apptainer::config: Private class
• apptainer::install::os: Private class
• apptainer::install::package: Private class
• apptainer::install::source: Private class
• apptainer::singularity: Private class

Defined types

• apptainer::plugin: Manage Apptainer plugin

Classes

apptainer

Manage Apptainer

Examples

include ::apptainer

Parameters

The following parameters are available in the apptainer class:

• install_method
• install_setuid
• version
• manage_repo
• remove_singularity
• package_name
• source_dependencies
• manage_go
• rebuild_on_go
• source_base_dir
• source_mconfig_path
• build_flags
• build_env
• prefix
• localstatedir
• sysconfdir
• source_exec_path
• plugins
• config_path
• config_template
• allow_setuid
• max_loop_devices
• allow_pid_ns
• config_passwd
• config_group
• config_resolv_conf
• mount_proc
• mount_sys
• mount_dev
• mount_devpts
• mount_home
• mount_tmp
• mount_hostfs
• bind_paths
• user_bind_control
• enable_fusemount
• enable_overlay
• enable_underlay
• mount_slave
• sessiondir_max_size
• limit_container_owners
• limit_container_groups
• limit_container_paths
• allow_containers
• allow_setuid_mount_encrypted
• allow_setuid_mount_squashfs
• allow_setuid_mount_extfs
• allow_net_users
• allow_net_groups
• allow_net_networks
• always_use_nv
• use_nvidia_container_cli
• always_use_rocm
• root_default_capabilities
• memory_fs_type
• cni_configuration_path
• cni_plugin_path
• binary_path
• mksquashfs_procs
• mksquashfs_mem
• shared_loop_devices
• image_driver
• download_concurrency
• download_part_size
• download_buffer_size
• systemd_cgroups
• apptheus_socket_path
• allow_monitoring
• namespace_users
• namespace_begin_id
• namespace_id_range
• subid_template

install_method

Data type: Enum['package','source','os']

Sets how Apptainer will be installed, package will install the upstream package source from source os will install from standard OS repositories for example from EPEL on RedHat family.

Default value: 'package'

install_setuid

Data type: Boolean

Whether to install the setuid portion of apptainer

Default value: false

version

Data type: String

Version of Apptainer to install

Default value: '1.3.3'

manage_repo

Data type: Boolean

Enable repositories for apptainer packages, e.g. EPEL on RedHat

Default value: true

remove_singularity

Data type: Boolean

Set whether to remove Singularity before installing Apptainer

Default value: false

package_name

Data type: String

Apptainer package name Only used when install_method=package

Default value: 'apptainer'

source_dependencies

Data type: Array

Packages needed to build from source Only used when install_method=source

Default value: []

manage_go

Data type: Boolean

Sets if golang module should be included Only used when install_method=source

Default value: true

rebuild_on_go

Data type: Boolean

Sets if Apptainer should be rebuilt on updates to Go via golang module Only used when install_method=source and manage_go=true

Default value: true

source_base_dir

Data type: Stdlib::Absolutepath

Base directory of where Apptainer source will be extracted Only used when install_method=source

Default value: '/opt'

source_mconfig_path

Data type: Stdlib::Absolutepath

Path to source install mconfig script

Default value: '/usr/local/sbin/apptainer-mconfig.sh'

build_flags

Data type: Hash

Build flags to pass to mconfig when building Apptainer Only used when install_method=source

Default value: {}

build_env

Data type: Hash

Environment variables to use when building from source Only used when install_method=source

Default value: {}

prefix

Data type: Stdlib::Absolutepath

The --prefix value when building from source Only used when install_method=source

Default value: '/usr'

localstatedir

Data type: Stdlib::Absolutepath

The --localstatedir value when building from source Only used when install_method=source

Default value: '/var'

sysconfdir

Data type: Stdlib::Absolutepath

The --sysconfdir value when building from source Only used when install_method=source

Default value: '/etc'

source_exec_path

Data type: String

Set PATH when building from source Only used when install_method=source

Default value: '/usr/local/bin:/bin:/usr/bin:/usr/local/sbin:/usr/sbin:/sbin'

plugins

Data type: Hash

Hash to define apptainer::plugin resources

Default value: {}

config_path

Data type: Stdlib::Absolutepath

Path to apptainer.conf

Default value: '/etc/apptainer/apptainer.conf'

config_template

Data type: String

Template used for apptainer.conf

Default value: 'apptainer/apptainer.conf.erb'

allow_setuid

Data type: Enum['yes','no']

See apptainer.conf: allow setuid

Default value: 'yes'

max_loop_devices

Data type: Integer

See apptainer.conf: max loop devices

Default value: 256

allow_pid_ns

Data type: Enum['yes','no']

See apptainer.conf: allow pid ns

Default value: 'yes'

config_passwd

Data type: Enum['yes','no']

See apptainer.conf: config passwd

Default value: 'yes'

config_group

Data type: Enum['yes','no']

See apptainer.conf: config group

Default value: 'yes'

config_resolv_conf

Data type: Enum['yes','no']

See apptainer.conf: config resolv conf

Default value: 'yes'

mount_proc

Data type: Enum['yes','no']

See apptainer.conf: mount proc

Default value: 'yes'

mount_sys

Data type: Enum['yes','no']

See apptainer.conf: mount sys

Default value: 'yes'

mount_dev

Data type: Enum['yes','no']

See apptainer.conf: mount dev

Default value: 'yes'

mount_devpts

Data type: Enum['yes','no']

See apptainer.conf: mount devpts

Default value: 'yes'

mount_home

Data type: Enum['yes','no']

See apptainer.conf: mount home

Default value: 'yes'

mount_tmp

Data type: Enum['yes','no']

See apptainer.conf: mount tmp

Default value: 'yes'

mount_hostfs

Data type: Enum['yes','no']

See apptainer.conf: mount hostfs

Default value: 'no'

bind_paths

Data type: Array[Stdlib::Absolutepath]

See apptainer.conf: bind paths

Default value: ['/etc/localtime', '/etc/hosts']

user_bind_control

Data type: Enum['yes','no']

See apptainer.conf: user bind control

Default value: 'yes'

enable_fusemount

Data type: Enum['yes','no']

See apptainer.conf: enable fusemount

Default value: 'yes'

enable_overlay

Data type: Enum['yes','no','try','driver']

See apptainer.conf: enable overlay

Default value: 'yes'

enable_underlay

Data type: Enum['yes','no','preferred']

See apptainer.conf: enable underlay

Default value: 'yes'

mount_slave

Data type: Enum['yes','no']

See apptainer.conf: mount slave

Default value: 'yes'

sessiondir_max_size

Data type: Integer

See apptainer.conf: sessiondir max size

Default value: 64

limit_container_owners

Data type: Optional[Array]

See apptainer.conf: limit container owners

Default value: undef

limit_container_groups

Data type: Optional[Array]

See apptainer.conf: limit container groups

Default value: undef

limit_container_paths

Data type: Optional[Array]

See apptainer.conf: limit container paths

Default value: undef

allow_containers

Data type: Hash[String,Enum['yes','no']]

See apptainer.conf: allow containers

Default value:

{
    'sif' => 'yes',
    'encrypted' => 'yes',
    'squashfs' => 'yes',
    'extfs' => 'yes',
    'dir' => 'yes',
  }

allow_setuid_mount_encrypted

Data type: Optional[Enum['yes','no']]

See apptainer.conf allow setuid-mount encrypted

Default value: undef

allow_setuid_mount_squashfs

Data type: Optional[Enum['yes','no','iflimited']]

See apptainer.conf allow setuid-mount squashfs

Default value: undef

allow_setuid_mount_extfs

Data type: Optional[Enum['yes','no']]

See apptainer.conf allow setuid-mount extfs

Default value: undef

allow_net_users

Data type: Array

See apptainer.conf: allow net users

Default value: []

allow_net_groups

Data type: Array

See apptainer.conf: allow net groups

Default value: []

allow_net_networks

Data type: Array

See apptainer.conf: allow net networks

Default value: []

always_use_nv

Data type: Enum['yes','no']

See apptainer.conf: always use nv

Default value: 'no'

use_nvidia_container_cli

Data type: Enum['yes','no']

See apptainer.conf: use nvidia-container-cli

Default value: 'no'

always_use_rocm

Data type: Enum['yes','no']

See apptainer.conf: always use rocm

Default value: 'no'

root_default_capabilities

Data type: Enum['full','file','default','no']

See apptainer.conf: root default capabilities

Default value: 'full'

memory_fs_type

Data type: Enum['tmpfs','ramfs']

See apptainer.conf: memory fs type

Default value: 'tmpfs'

cni_configuration_path

Data type: Optional[Stdlib::Absolutepath]

See apptainer.conf: cni configuration path

Default value: undef

cni_plugin_path

Data type: Optional[Stdlib::Absolutepath]

See apptainer.conf: cni plugin path

Default value: undef

binary_path

Data type: Optional[String[1]]

See apptainer.conf: binary path

Default value: undef

mksquashfs_procs

Data type: Integer[0,default]

See apptainer.conf: mksquashfs procs

Default value: 0

mksquashfs_mem

Data type: Optional[String[1]]

See apptainer.conf: mksquashfs mem

Default value: undef

shared_loop_devices

Data type: Enum['yes','no']

See apptainer.conf: shared loop devices

Default value: 'no'

image_driver

Data type: Optional[String]

See apptainer.conf: image driver

Default value: undef

download_concurrency

Data type: Integer[0,default]

See apptainer.conf: download concurrency

Default value: 3

download_part_size

Data type: Integer[0,default]

See apptainer.conf: download part size

Default value: 5242880

download_buffer_size

Data type: Integer[0,default]

See apptainer.conf: download buffer size

Default value: 32768

systemd_cgroups

Data type: Enum['yes','no']

See apptainer.conf: systemd cgroups

Default value: 'yes'

apptheus_socket_path

Data type: Stdlib::Absolutepath

See apptainer.conf apptheus socket path

Default value: '/run/apptheus/gateway.sock'

allow_monitoring

Data type: Enum['yes','no']

See apptainer.conf allow monitoring

Default value: 'no'

namespace_users

Data type: Array

List of uses to add to /etc/subuid and /etc/subgid to support user namespaces

Default value: []

namespace_begin_id

Data type: Integer

The beginning ID for /etc/subuid and /etc/subgid. The value is incremented For each user by start + namespace_id_range + 1

Default value: 65537

namespace_id_range

Data type: Integer

The range of UIDs/GIDs usable by a user in namespaces

Default value: 65536

subid_template

Data type: String

The template to use for /etc/subuid and /etc/subgid

Default value: 'apptainer/subid.erb'

Defined types

apptainer::plugin

Manage Apptainer plugin

Examples

install log plugin

apptainer::plugin { 'github.com/apptainer/apptainer/log-plugin':
  source_dir => 'examples/plugins/log-plugin',
}

Parameters

The following parameters are available in the apptainer::plugin defined type:

• source_dir
• ensure
• sif_name

source_dir

Data type: Optional[String]

The plugin source directory This path must be relative to Apptainer source directory $apptainer::install::source::source_dir

Default value: undef

ensure

Data type: Enum['present', 'absent']

Whether to install (present) or uninstall (absent) the plugin

Default value: 'present'

sif_name

Data type: Optional[String]

The name of the SIF image to use for install after the plugin is compiled. The default is to use part after last / in the plugin name so plugin examples/plugins/log-plugin will have SIF name of log-plugin.sif.

Default value: undef