Skip to content

Quadlet Options

builds

Reference

Type:

attribute set of (submodule)

Default value:

{ }

Declared in:

builds.<name>.Install

Install section of quadlet file, same syntax as SystemD install sections.

Warning

This is not transformed, so your keys have to start with capital letters for example.

Type:

attribute set

Default value:

{ }

Example value:

{
  WantedBy = "multi-user.target";
}

Declared in:

builds.<name>.Quadlet

Some quadlet specific configuration is shared between different unit types. Those settings can be configured in the [Quadlet] section.

Reference

Type:

attribute set

Default value:

{ }

Example value:

{
  DefaultDependencies = false;
}

Declared in:

builds.<name>.Service

Service section of quadlet file, same syntax as SystemD service sections.

Warning

This is not transformed, so your keys have to start with capital letters for example.

Type:

attribute set

Default value:

{ }

Example value:

{
  Restart = "always";
  TimeoutStartSec = 300;
}

Declared in:

builds.<name>.Unit

Unit section of quadlet file, same syntax as SystemD unit sections.

Warning

This is not transformed, so your keys have to start with capital letters for example.

Type:

attribute set

Default value:

{ }

Example value:

{
  After = [
    "database.service"
  ];
  Description = "Hello world";
}

Declared in:

builds.<name>.addGroups

Assign additional groups to the primary user running within the container process. Also supports the keep-groups special flag.

CLI:

--group-add

Property:

GroupAdd

Type:

list of string

Default value:

[ ]

Example value:

[
  "keep-groups"
]

Declared in:

builds.<name>.annotations

Add an image annotation (e.g. annotation=value) to the image metadata.

CLI:

--annotation

Property:

Annotation

Type:

attribute set of string

Default value:

{ }

Example value:

{
  annotation = "value";
}

Declared in:

builds.<name>.arch

Override the architecture, defaults to hosts', of the image to be built.

CLI:

--arch

Property:

Arch

Type:

null or string

Default value:

null

Example value:

"aarch64"

Declared in:

builds.<name>.authFile

Path of the authentication file.

CLI:

--authfile

Property:

AuthFile

Type:

null or string

Default value:

null

Example value:

"/etc/registry/auth.json"

Declared in:

builds.<name>.buildArg

Specifies a build argument and its value in the same way environment variables are (e.g., env=value), but it is not added to the environment variable list in the resulting image’s configuration.

CLI:

--build-arg

Property:

BuildArg

Type:

attribute set of string

Default value:

{ }

Declared in:

builds.<name>.dns

Set network-scoped DNS resolver/nameserver for the build container.

CLI:

--dns

Property:

DNS

Type:

list of string

Default value:

[ ]

Example value:

[
  "192.168.55.1"
]

Declared in:

builds.<name>.dnsOption

Set custom DNS options.

CLI:

--dns-option

Property:

DNSOption

Type:

list of string

Default value:

[ ]

Example value:

[
  "ndots:1"
]

Declared in:

builds.<name>.dnsSearch

Set custom DNS search domains. Use DNSSearch=. (dnsSearch = ["."]; in Nix) to remove the search domain.

CLI:

--dns-search

Property:

DNSSearch

Type:

list of string

Default value:

[ ]

Example value:

[
  "foo.com"
]

Declared in:

builds.<name>.environment

Add a value (e.g. env=value) to the built image. This uses the same format as services in systemd and can be listed multiple times.

CLI:

--env

Property:

Environment

Type:

attribute set of string

Default value:

{ }

Example value:

{
  foo = "bar";
}

Declared in:

builds.<name>.file

Specifies a Containerfile which contains instructions for building the image. A URL starting with http(s):// allows you to specify a remote Containerfile to be downloaded. Note that for a given relative path to a Containerfile, or when using a http(s):// URL, you also must set SetWorkingDirectory= in order for podman build to find a valid context directory for the resources specified in the Containerfile.

Note that setting a File= field is mandatory for a .build file, unless SetWorkingDirectory (or a WorkingDirectory in the Service group) has also been set.

CLI:

--file

Property:

File

Type:

null or string

Default value:

null

Example value:

"/path/to/Containerfile"

Declared in:

builds.<name>.forceRm

Always remove intermediate containers after a build, even if the build fails (default true).

CLI:

--force-rm

Property:

ForceRM

Type:

null or boolean

Default value:

null

Declared in:

builds.<name>.globalArgs

This key contains a list of arguments passed directly between podman and kube in the generated file. It can be used to access Podman features otherwise unsupported by the generator. Since the generator is unaware of what unexpected interactions can be caused by these arguments, it is not recommended to use this option.

Property:

GlobalArgs

Type:

list of string

Default value:

[ ]

Example value:

[
  "--log-level=debug"
]

Declared in:

builds.<name>.ignoreFile

Path to an alternate .containerignore file to use when building the image. Note that when using a relative path you should also set SetWorkingDirectory=.

CLI:

--ignorefile

Property:

IgnoreFile

Type:

null or string

Default value:

null

Example value:

"/tmp/.containerignore"

Declared in:

builds.<name>.labels

Add an image label (e.g. label=value) to the image metadata.

CLI:

--label

Property:

Label

Type:

attribute set of string

Default value:

{ }

Example value:

{
  foo = "bar";
}

Declared in:

builds.<name>.modules

Load the specified containers.conf(5) module.

CLI:

--module

Property:

ContainersConfModule

Type:

list of string

Default value:

[ ]

Example value:

[
  "/etc/nvd.conf"
]

Declared in:

builds.<name>.networks

Specify a custom network for the container. This has the same format as the --network option to podman kube play. For example, use host to use the host network in the container, or none to not set up networking in the container.

Special case

If the name of the network ends with .network, a Podman network called systemd-$name is used, and the generated systemd service contains a dependency on the $name-network.service. Such a network can be automatically created by using a $name.network Quadlet file.

Note: the corresponding .network file must exist.

CLI:

--network

Property:

Network

Type:

list of string

Default value:

[ ]

Example value:

[
  "host"
]

Declared in:

builds.<name>.podmanArgs

This key contains a list of arguments passed directly to the end of the podman kube play command in the generated file (right before the path to the yaml file in the command line). It can be used to access Podman features otherwise unsupported by the generator. Since the generator is unaware of what unexpected interactions can be caused by these arguments, is not recommended to use this option.

Property:

PodmanArgs

Type:

list of string

Default value:

[ ]

Example value:

[
  "--add-host foobar"
]

Declared in:

builds.<name>.pull

Set the image pull policy.

CLI:

--pull

Property:

Pull

Type:

null or string

Default value:

null

Example value:

"never"

Declared in:

builds.<name>.ref

Reference to this build from other quadlets.

Quadlet resolves this to object (e.g. container) names and sets up appropriate systemd dependencies.

This is recognized for most quadlet native options, but not by Podman command line. Using this inside podmanArgs will therefore unlikely work.

Type:

unspecified value

Default value:

"<quadnix project if set>-‹name›.build"

Declared in:

builds.<name>.retry

Number of times to retry the image pull when a HTTP error occurs.

CLI:

--retry

Property:

Retry

Type:

null or signed integer

Default value:

null

Example value:

5

Declared in:

builds.<name>.retryDelay

Delay between retries.

CLI:

--retry-delay

Property:

RetryDelay

Type:

null or string

Default value:

null

Example value:

"5s"

Declared in:

builds.<name>.secrets

Pass secret information used in Containerfile build stages in a safe way.

This generally has the form secret[,opt=opt ...].

CLI:

--secret

Property:

Secret

Type:

list of string

Default value:

[ ]

Example value:

[
  "secret[,opt=opt …]"
]

Declared in:

builds.<name>.tags

Specifies the name which is assigned to the resulting image if the build process completes successfully.

This key can be listed multiple times. The first instance will be used as the name of the created artifact when the .build file is referenced by another Quadlet unit.

CLI:

--tag

Property:

ImageTag

Type:

list of string

Default value:

[ ]

Example value:

[
  "localhost/imagename"
]

Declared in:

builds.<name>.target

Set the target build stage to build. Commands in the Containerfile after the target stage are skipped.

CLI:

--target

Property:

Target

Type:

null or string

Default value:

null

Example value:

"my-app"

Declared in:

builds.<name>.tlsVerify

Require HTTPS and verification of certificates when contacting registries.

CLI:

--tls-verify

Property:

TLSVerify

Type:

null or boolean

Default value:

null

Declared in:

builds.<name>.variant

Override the default architecture variant of the container image to be built.

CLI:

--variant

Property:

Variant

Type:

null or string

Default value:

null

Example value:

"arm/v7"

Declared in:

builds.<name>.volumes

Mount a volume in the container. This generally has the form [[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]].

If SOURCE-VOLUME starts with ., Quadlet resolves the path relative to the location of the unit file.

Special case

If SOURCE-VOLUME ends with .volume, a Podman named volume called systemd-$name is used as the source, and the generated systemd service contains a dependency on the $name-volume.service. Note that the corresponding .volume file must exist.

CLI:

--volume

Property:

Volume

Type:

list of string

Default value:

[ ]

Example value:

[
  "/source:/dest"
]

Declared in:

builds.<name>.workdir

Provide context (a working directory) to podman build. Supported values are a path, a URL, or the special keys file or unit to set the context directory to the parent directory of the file from the File= key or to that of the Quadlet .build unit file, respectively. This allows Quadlet to resolve relative paths.

When using one of the special keys (file or unit), the WorkingDirectory field of the Service group of the Systemd service unit will also be set to accordingly. Alternatively, users can explicitly set the WorkingDirectory field of the Service group in the .build file. Please note that if the WorkingDirectory field of the Service group is set by the user, Quadlet will not overwrite it even if SetWorkingDirectory is set to file or unit.

By providing a URL to SetWorkingDirectory= you can instruct podman build to clone a Git repository or download an archive file extracted to a temporary location by podman build as build context. Note that in this case, the WorkingDirectory of the Systemd service unit is left untouched by Quadlet.

Note

Providing context directory is mandatory for a .build file, unless a File= key has also been provided.

Property:

SetWorkingDirectory

Type:

null or string

Default value:

null

Example value:

"file"

Declared in:

containers

Reference

Type:

attribute set of (submodule)

Default value:

{ }

Declared in:

containers.<name>.Install

Install section of quadlet file, same syntax as SystemD install sections.

Warning

This is not transformed, so your keys have to start with capital letters for example.

Type:

attribute set

Default value:

{ }

Example value:

{
  WantedBy = "multi-user.target";
}

Declared in:

containers.<name>.Quadlet

Some quadlet specific configuration is shared between different unit types. Those settings can be configured in the [Quadlet] section.

Reference

Type:

attribute set

Default value:

{ }

Example value:

{
  DefaultDependencies = false;
}

Declared in:

containers.<name>.Service

Service section of quadlet file, same syntax as SystemD service sections.

Warning

This is not transformed, so your keys have to start with capital letters for example.

Type:

attribute set

Default value:

{ }

Example value:

{
  Restart = "always";
  TimeoutStartSec = 300;
}

Declared in:

containers.<name>.Unit

Unit section of quadlet file, same syntax as SystemD unit sections.

Warning

This is not transformed, so your keys have to start with capital letters for example.

Type:

attribute set

Default value:

{ }

Example value:

{
  After = [
    "database.service"
  ];
  Description = "Hello world";
}

Declared in:

containers.<name>.addCapabilities

Add these capabilities, in addition to the default Podman capability set, to the container.

This is a space separated list of capabilities. This key can be listed multiple times.

CLI:

--cap-add

Property:

AddCapability

Type:

list of string

Default value:

[ ]

Example value:

[
  "CAP_DAC_OVERRIDE"
  "CAP_IPC_OWNER"
]

Declared in:

containers.<name>.addGroups

Assign additional groups to the primary user running within the container process. Also supports the keep-groups special flag.

CLI:

--group-add

Property:

GroupAdd

Type:

list of string

Default value:

[ ]

Example value:

[
  "keep-groups"
]

Declared in:

containers.<name>.annotations

Set one or more OCI annotations on the container.

CLI:

--annotation

Property:

Annotation

Type:

attribute set of string

Default value:

{ }

Example value:

{
  annotation = "value";
}

Declared in:

containers.<name>.appArmor

Sets the apparmor confinement profile for the container. A value of unconfined turns off apparmor confinement.

Property:

AppArmor

Type:

null or string

Default value:

null

Example value:

"unconfined"

Declared in:

containers.<name>.autoUpdate

Indicates whether the container will be auto-updated (podman-auto-update(1)). The following values are supported:

  • registry: Requires a fully-qualified image reference (e.g., quay.io/podman/stable:latest) to be used to create the container. This enforcement is necessary to know which image to actually check and pull. If an image ID was used, Podman does not know which image to check/pull anymore.
  • local: Tells Podman to compare the image a container is using to the image with its raw name in local storage. If an image is updated locally, Podman simply restarts the systemd unit executing the container.

CLI:

--label "io.containers.autoupdate=..."

Property:

AutoUpdate

Type:

null or one of "registry", "local"

Default value:

null

Example value:

"registry"

Declared in:

containers.<name>.cgroupsMode

The cgroups mode of the Podman container.

By default, the cgroups mode of the container created by Quadlet is split, which differs from the default (enabled) used by the Podman CLI.

If the container joins a pod (i.e. Pod= is specified), you may want to change this to no-conmon or enabled, so that pod level cgroup resource limits can take effect.

CLI:

--cgroups

Property:

CgroupsMode

Type:

null or string

Default value:

null

Example value:

"no-conmon"

Declared in:

containers.<name>.containerName

The (optional) name of the Podman container. If this is not specified, the default value of systemd-%N is used, which is the same as the service name but with a systemd- prefix to avoid conflicts with user-managed containers.

CLI:

--name

Property:

ContainerName

Type:

null or string

Default value:

null

Example value:

"foo"

Declared in:

containers.<name>.devices

Adds a device node from the host into the container. The format of this is HOST-DEVICE[:CONTAINER-DEVICE][:PERMISSIONS], where HOST-DEVICE is the path of the device node on the host, CONTAINER-DEVICE is the path of the device node in the container, and PERMISSIONS is a list of permissions combining r for read, w for write, and m for mknod(2). The - prefix tells Quadlet to add the device only if it exists on the host.

CLI:

--device

Property:

AddDevice

Type:

list of string

Default value:

[ ]

Example value:

[
  "/dev/foo"
]

Declared in:

containers.<name>.dns

Set network-scoped DNS resolver/nameserver for containers in this network.

CLI:

--dns

Property:

DNS

Type:

list of string

Default value:

[ ]

Example value:

[
  "192.168.55.1"
]

Declared in:

containers.<name>.dnsOption

Set custom DNS options.

CLI:

--dns-option

Property:

DNSOption

Type:

list of string

Default value:

[ ]

Example value:

[
  "ndots:1"
]

Declared in:

containers.<name>.dnsSearch

Set custom DNS search domains. Use DNSSearch=. to remove the search domain (dnsSearch = ["."]; in Nix).

CLI:

--dns-search

Property:

DNSSearch

Type:

list of string

Default value:

[ ]

Example value:

[
  "foo.com"
]

Declared in:

containers.<name>.dropCapabilities

Drop these capabilities from the default podman capability set, or all to drop all capabilities.

CLI:

--cap-drop

Property:

DropCapability

Type:

list of string

Default value:

[ ]

Example value:

[
  "CAP_DAC_OVERRIDE"
  "CAP_IPC_OWNER"
]

Declared in:

containers.<name>.entrypoint

Override the default ENTRYPOINT from the image. Specify multi option commands in the form of a JSON string.

CLI:

--entrypoint

Property:

Entrypoint

Type:

null or string or list of string

Default value:

null

Example value:

"/foo.sh"

Declared in:

containers.<name>.environmentFiles

Use a line-delimited file to set environment variables in the container. The path may be absolute or relative to the location of the unit file. This key may be used multiple times, and the order persists when passed to podman run.

CLI:

--env-file

Property:

EnvironmentFile

Type:

list of string

Default value:

[ ]

Example value:

[
  "/tmp/env"
]

Declared in:

containers.<name>.environmentHost

Use the host environment inside of the container.

CLI:

--env-host

Property:

EnvironmentHost

Type:

null or boolean

Default value:

null

Declared in:

containers.<name>.environments

Set an environment variable in the container. This uses the same format as services in systemd and can be listed multiple times.

CLI:

--env

Property:

Environment

Type:

attribute set of string

Default value:

{ }

Example value:

{
  FOO = "bar";
}

Declared in:

containers.<name>.exec

Additional arguments for the container; this has exactly the same effect as passing more arguments after a podman run <image> <arguments> invocation.

The format is the same as for systemd command lines, however, unlike the usage scenario for similarly-named systemd ExecStart= verb which operates on the ambient root filesystem, it is very common for container images to have their own ENTRYPOINT or CMD metadata which this interacts with.

The default expectation for many images is that the image will include an ENTRYPOINT with a default binary, and this field will add arguments to that entrypoint.

Another way to describe this is that it works the same way as the args field in a Kubernetes pod.

Property:

Exec

Type:

null or string or list of string

Default value:

null

Example value:

"/usr/bin/command"

Declared in:

containers.<name>.exposePorts

Exposes a port, or a range of ports (e.g. 50-59), from the host to the container.

CLI:

--expose

Property:

ExposeHostPort

Type:

list of string

Default value:

[ ]

Example value:

[
  "50-59"
]

Declared in:

containers.<name>.gidMaps

Run the container in a new user namespace using the supplied GID mapping.

CLI:

--gidmap

Property:

GIDMap

Type:

list of string

Default value:

[ ]

Example value:

[
  "0:10000:10"
]

Declared in:

containers.<name>.globalArgs

This key contains a list of arguments passed directly between podman and run in the generated file. It can be used to access Podman features otherwise unsupported by the generator. Since the generator is unaware of what unexpected interactions can be caused by these arguments, it is not recommended to use this option.

Property:

GlobalArgs

Type:

list of string

Default value:

[ ]

Example value:

[
  "--log-level=debug"
]

Declared in:

containers.<name>.group

The (numeric) GID to run as inside the container. This does not need to match the GID on the host, which can be modified with UserNS, but if that is not specified, this GID is also used on the host.

Note

When both User= and Group= are specified, they are combined into a single --user USER:GROUP argument passed to Podman. Using Group= without User= will result in an error.

CLI:

--user UID:...

Property:

Group

Type:

null or string

Default value:

null

Example value:

"1234"

Declared in:

containers.<name>.healthCmd

Set or alter a healthcheck command for a container. A value of none disables existing healthchecks.

CLI:

--health-cmd

Property:

HealthCmd

Type:

null or string

Default value:

null

Example value:

"/usr/bin/command"

Declared in:

containers.<name>.healthInterval

Set an interval for the healthchecks. An interval of disable results in no automatic timer setup.

CLI:

--health-interval

Property:

HealthInterval

Type:

null or string

Default value:

null

Example value:

"2m"

Declared in:

containers.<name>.healthLogDestination

Set the destination of the HealthCheck log.

  • local: (default) HealthCheck logs are stored in overlay containers. (For example: $runroot/healthcheck.log)
  • directory: creates a log file named <container-ID>-healthcheck.log with HealthCheck logs in the specified directory.
  • events_logger: The log will be written with logging mechanism set by events_logger. It also saves the log to a default directory, for performance on a system with a large number of logs.

CLI:

--health-log-destination

Property:

HealthLogDestination

Type:

null or string

Default value:

null

Example value:

"/foo/log"

Declared in:

containers.<name>.healthMaxLogCount

Set maximum number of attempts in the HealthCheck log file. 0 value means an infinite number of attempts in the log file. Default: 5 attempts

CLI:

--health-max-log-count

Property:

HealthMaxLogCount

Type:

null or signed integer

Default value:

null

Example value:

5

Declared in:

containers.<name>.healthMaxLogSize

Set maximum length in characters of stored HealthCheck log. 0 value means an infinite log length. Default: 500 characters

CLI:

--health-max-log-size

Property:

HealthMaxLogSize

Type:

null or signed integer

Default value:

null

Example value:

500

Declared in:

containers.<name>.healthOnFailure

Action to take once the container transitions to an unhealthy state. The kill action in combination integrates best with systemd. Once the container turns unhealthy, it gets killed, and systemd restarts the service.

CLI:

--health-on-failure

Property:

HealthOnFailure

Type:

null or string

Default value:

null

Example value:

"kill"

Declared in:

containers.<name>.healthRetries

The number of retries allowed before a healthcheck is considered to be unhealthy.

CLI:

--health-retries

Property:

HealthRetries

Type:

null or signed integer

Default value:

null

Example value:

5

Declared in:

containers.<name>.healthStartPeriod

The initialization time needed for a container to bootstrap.

CLI:

--health-start-period

Property:

HealthStartPeriod

Type:

null or string

Default value:

null

Example value:

"1m"

Declared in:

containers.<name>.healthStartupCmd

Set a startup healthcheck command for a container.

CLI:

--health-startup-cmd

Property:

HealthStartupCmd

Type:

null or string

Default value:

null

Example value:

"/usr/bin/command"

Declared in:

containers.<name>.healthStartupInterval

Set an interval for the startup healthcheck. An interval of disable results in no automatic timer setup.

CLI:

--health-startup-interval

Property:

HealthStartupInterval

Type:

null or string

Default value:

null

Example value:

"1m"

Declared in:

containers.<name>.healthStartupRetries

The number of attempts allowed before the startup healthcheck restarts the container.

CLI:

--health-startup-retries

Property:

HealthStartupRetries

Type:

null or signed integer

Default value:

null

Example value:

8

Declared in:

containers.<name>.healthStartupSuccess

The number of successful runs required before the startup healthcheck succeeds and the regular healthcheck begins.

CLI:

--health-startup-success

Property:

HealthStartupSuccess

Type:

null or signed integer

Default value:

null

Example value:

2

Declared in:

containers.<name>.healthStartupTimeout

The maximum time a startup healthcheck command has to complete before it is marked as failed.

CLI:

--health-startup-timeout

Property:

HealthStartupTimeout

Type:

null or string

Default value:

null

Example value:

"1m33s"

Declared in:

containers.<name>.healthTimeout

The maximum time allowed to complete the healthcheck before an interval is considered failed.

CLI:

--health-timeout

Property:

HealthTimeout

Type:

null or string

Default value:

null

Example value:

"20s"

Declared in:

containers.<name>.hostname

Sets the host name that is available inside the container.

CLI:

--hostname

Property:

HostName

Type:

null or string

Default value:

null

Example value:

"new-host-name"

Declared in:

containers.<name>.hosts

Add host-to-IP mapping to /etc/hosts. The format is hostname:ip.

CLI:

--add-host

Property:

AddHost

Type:

list of string

Default value:

[ ]

Example value:

[
  "hostname:192.168.10.11"
]

Declared in:

containers.<name>.httpProxy

Controls whether proxy environment variables (http_proxy, https_proxy, ftp_proxy, no_proxy) are passed from the Podman process into the container during image pulls and builds.

Set to true to enable proxy inheritance (default Podman behavior) or false to disable it. This option is particularly useful on systems that require proxy configuration for internet access but don't want proxy settings passed to the container runtime.

CLI:

--http-proxy

Property:

HttpProxy

Type:

null or boolean

Default value:

null

Example value:

true

Declared in:

containers.<name>.image

The image to run in the container. It is recommended to use a fully qualified image name rather than a short name, both for performance and robustness reasons.

The format of the name is the same as when passed to podman pull. So, it supports using :tag or digests to guarantee the specific image version.

Special Cases

  • If the name of the image ends with .image, Quadlet will use the image pulled by the corresponding .image file, and the generated systemd service contains a dependency on the $name-image.service (or the service name set in the .image file). Note that the corresponding .image file must exist.

  • If the name of the image ends with .build, Quadlet will use the image built by the corresponding .build file, and the generated systemd service contains a dependency on the $name-build.service. Note: the corresponding .build file must exist.

Property:

Image

Type:

null or string

Default value:

null

Example value:

"docker.io/library/nginx:latest"

Declared in:

containers.<name>.ip

Specify a static IPv4 address for the container.

CLI:

--ip

Property:

IP

Type:

null or string

Default value:

null

Example value:

"10.88.64.128"

Declared in:

containers.<name>.ip6

Specify a static IPv6 address for the container.

CLI:

--ip6

Property:

IP6

Type:

null or string

Default value:

null

Example value:

"fd46:db93:aa76:ac37::10"

Declared in:

containers.<name>.labels

Set one or more OCI labels on the container.

CLI:

--label

Property:

Label

Type:

attribute set of string

Default value:

{ }

Example value:

{
  foo = "bar";
}

Declared in:

containers.<name>.logDriver

Set the log-driver used by Podman when running the container.

CLI:

--log-driver

Property:

LogDriver

Type:

null or string

Default value:

null

Example value:

"journald"

Declared in:

containers.<name>.logOptions

Set the log-opt (logging options) used by Podman when running the container.

CLI:

--log-opt

Property:

LogOpt

Type:

list of string

Default value:

[ ]

Example value:

[
  "path=/var/log/mykube.json"
]

Declared in:

containers.<name>.mask

Specify the paths to mask separated by a colon (Mask=/path/1:/path/2). A masked path cannot be accessed inside the container.

CLI:

--security-opt mask=...

Property:

Mask

Type:

null or string

Default value:

null

Example value:

"/proc/sys/foo:/proc/sys/bar"

Declared in:

containers.<name>.memory

Specify the amount of memory for the container.

CLI:

--memory

Property:

Memory

Type:

null or string

Default value:

null

Example value:

"20g"

Declared in:

containers.<name>.modules

Load the specified containers.conf(5) module.

CLI:

--module

Property:

ContainersConfModule

Type:

list of string

Default value:

[ ]

Example value:

[
  "/etc/nvd.conf"
]

Declared in:

containers.<name>.mounts

Attach a filesystem mount to the container. This generally has the form type=TYPE,TYPE-SPECIFIC-OPTION[,...].

Special cases

  • For type=volume, if source ends with .volume, the Podman named volume generated by the corresponding .volume file is used.
  • For type=image, if source ends with .image, the image generated by the corresponding .image file is used.

In both cases, the generated systemd service will contain a dependency on the service generated for the corresponding unit. Note: the corresponding .volume or .image file must exist.

CLI:

--mount

Property:

Mount

Type:

list of string

Default value:

[ ]

Example value:

[
  "type=..."
]

Declared in:

containers.<name>.networkAliases

Add a network-scoped alias for the container. Aliases can be used to group containers together in DNS resolution: for example, setting NetworkAlias=web on multiple containers will make a DNS query for web resolve to all the containers with that alias.

CLI:

--network-alias

Property:

NetworkAlias

Type:

list of string

Default value:

[ ]

Example value:

[
  "name"
]

Declared in:

containers.<name>.networks

Specify a custom network for the container. For example, use host to use the host network in the container, or none to not set up networking in the container.

Special cases

  • If the name of the network ends with .network, a Podman network called systemd-$name is used, and the generated systemd service contains a dependency on the $name-network.service. Such a network can be automatically created by using a $name.network Quadlet file. Note: the corresponding .network file must exist.
  • If the name ends with .container, the container will reuse the network stack of another container created by $name.container. The generated systemd service contains a dependency on $name.service. Note: the corresponding .container file must exist.

CLI:

--network

Property:

Network

Type:

list of string

Default value:

[ ]

Example value:

[
  "host"
]

Declared in:

containers.<name>.noNewPrivileges

If enabled, this disables the container processes from gaining additional privileges via things like setuid and file capabilities. (Default: false)

CLI:

--security-opt no-new-privileges

Property:

NoNewPrivileges

Type:

null or boolean

Default value:

null

Declared in:

containers.<name>.notify

By default, Podman is run in such a way that the systemd startup notify command is handled by the container runtime. In other words, the service is deemed started when the container runtime starts the child in the container. However, if the container application supports sd_notify, then setting Notify to true passes the notification details to the container allowing it to notify of startup on its own.

In addition, setting Notify to healthy will postpone startup notifications until such time as the container is marked healthy, as determined by Podman healthchecks. Note that this requires setting up a container healthcheck, see the HealthCmd option for more.

CLI:

--sdnotify container

Property:

Notify

Type:

one of <null>, true, false, "healthy"

Default value:

null

Declared in:

containers.<name>.pidsLimit

Tune the container's pids limit.

CLI:

--pids-limit

Property:

PidsLimit

Type:

null or signed integer

Default value:

null

Example value:

10000

Declared in:

containers.<name>.pod

Specify a Quadlet .pod unit to link the container to. The value must take the form of <name>.pod and the .pod unit must exist.

Quadlet will add all the necessary parameters to link between the container and the pod and between their corresponding services.

CLI:

--pod

Property:

Pod

Type:

null or string

Default value:

null

Declared in:

containers.<name>.podmanArgs

This key contains a list of arguments passed directly to the end of the podman kube play command in the generated file (right before the path to the yaml file in the command line). It can be used to access Podman features otherwise unsupported by the generator. Since the generator is unaware of what unexpected interactions can be caused by these arguments, is not recommended to use this option.

Property:

PodmanArgs

Type:

list of string

Default value:

[ ]

Example value:

[
  "--add-host foobar"
]

Declared in:

containers.<name>.publishPorts

Exposes a port, or a range of ports (e.g. 50-59), from the container to the host. Equivalent to the podman kube play's --publish option. The format is similar to the Podman options, which is of the form ip:hostPort:containerPort, ip::containerPort, hostPort:containerPort or containerPort, where the number of host and container ports must be the same (in the case of a range).

If the IP is set to 0.0.0.0 or not set at all, the port is bound on all IPv4 addresses on the host; use [::] for IPv6.

The list of published ports specified in the unit file is merged with the list of ports specified in the Kubernetes YAML file. If the same container port and protocol is specified in both, the entry from the unit file takes precedence

CLI:

--publish

Property:

PublishPort

Type:

list of string

Default value:

[ ]

Example value:

[
  "8080:80"
]

Declared in:

containers.<name>.pull

Set the image pull policy.

CLI:

--pull

Property:

Pull

Type:

null or string

Default value:

null

Example value:

"never"

Declared in:

containers.<name>.readOnly

If enabled, makes the image read-only. (Default: false)

CLI:

--read-only

Property:

ReadOnly

Type:

null or boolean

Default value:

null

Declared in:

containers.<name>.readOnlyTmpfs

If ReadOnly is set to true, mount a read-write tmpfs on /dev, /dev/shm, /run, /tmp, and /var/tmp. (Default: false)

CLI:

--read-only-tmpfs

Property:

ReadOnlyTmpfs

Type:

null or boolean

Default value:

null

Declared in:

containers.<name>.ref

Reference to this container from other quadlets.

Quadlet resolves this to object (e.g. container) names and sets up appropriate systemd dependencies.

This is recognized for most quadlet native options, but not by Podman command line. Using this inside podmanArgs will therefore unlikely work.

Type:

unspecified value

Default value:

"<quadnix project if set>-‹name›.container"

Declared in:

containers.<name>.reloadCmd

Add ExecReload line to the Service that runs podman exec with this command in this container.

In order to execute the reload run systemctl reload <Service>.

Mutually exclusive with ReloadSignal.

Property:

ReloadCmd

Type:

null or string or list of string

Default value:

null

Example value:

"/usr/bin/command"

Declared in:

containers.<name>.reloadSignal

Add ExecReload line to the Service that runs podman kill with this signal which sends the signal to the main container process.

In order to execute the reload run systemctl reload <Service>.

Mutually exclusive with ReloadCmd.

Property:

ReloadSignal

Type:

null or string

Default value:

null

Example value:

"SIGHUP"

Declared in:

containers.<name>.retry

Number of times to retry the image pull when a HTTP error occurs.

CLI:

--retry

Property:

Retry

Type:

null or signed integer

Default value:

null

Example value:

5

Declared in:

containers.<name>.retryDelay

Delay between retries.

CLI:

--retry-delay

Property:

RetryDelay

Type:

null or string

Default value:

null

Example value:

"5s"

Declared in:

containers.<name>.rootfs

The rootfs to use for the container. Rootfs points to a directory on the system that contains the content to be run within the container. This option conflicts with the Image option.

The format of the rootfs is the same as when passed to podman run --rootfs, so it supports overlay mounts as well.

Note

On SELinux systems, the rootfs needs the correct label, which is by default unconfined_u:object_r:container_file_t:s0.

CLI:

--rootfs

Property:

Rootfs

Type:

null or string

Default value:

null

Example value:

"/var/lib/rootfs"

Declared in:

containers.<name>.runInit

If enabled, the container has a minimal init process inside the container that forwards signals and reaps processes. (Default false)

CLI:

--init

Property:

RunInit

Type:

null or boolean

Default value:

null

Declared in:

containers.<name>.seccompProfile

Set the seccomp profile to use in the container. If unset, the default podman profile is used. Set to either the pathname of a JSON file, or unconfined to disable the seccomp filters.

CLI:

--security-opt seccomp=...

Property:

SeccompProfile

Type:

null or string

Default value:

null

Example value:

"/tmp/s.json"

Declared in:

containers.<name>.secrets

Use a Podman secret in the container either as a file or an environment variable. This generally has the form secret[,opt=opt ...].

CLI:

--secret

Property:

Secret

Type:

list of string

Default value:

[ ]

Example value:

[
  "secret[,opt=opt …]"
]

Declared in:

containers.<name>.securityLabelDisable

Turn off label separation for the container.

CLI:

--security-opt label=disable

Property:

SecurityLabelDisable

Type:

null or boolean

Default value:

null

Declared in:

containers.<name>.securityLabelFileType

Set the label file type for the container files.

CLI:

--security-opt label=filetype:...

Property:

SecurityLabelFileType

Type:

null or string

Default value:

null

Example value:

"usr_t"

Declared in:

containers.<name>.securityLabelLevel

Set the label process level for the container processes.

CLI:

--security-opt label=level:s0:c1,c2

Property:

SecurityLabelLevel

Type:

null or string

Default value:

null

Example value:

"s0:c1,c2"

Declared in:

containers.<name>.securityLabelNested

Allow SecurityLabels to function within the container. This allows separation of containers created within the container.

CLI:

--security-opt label=nested

Property:

SecurityLabelNested

Type:

null or boolean

Default value:

null

Declared in:

containers.<name>.securityLabelType

Set the label process type for the container processes.

CLI:

--security-opt label=type:...

Property:

SecurityLabelType

Type:

null or string

Default value:

null

Example value:

"spc_t"

Declared in:

containers.<name>.shmSize

Size of /dev/shm.

CLI:

--shm-size

Property:

ShmSize

Type:

null or string

Default value:

null

Example value:

"100m"

Declared in:

containers.<name>.startWithPod

Start the container after the associated pod is created. Default to true.

If true, container will be started/stopped/restarted alongside the pod.

If false, the container will not be started when the pod starts. The container will be stopped with the pod. Restarting the pod will also restart the container as long as the container was also running before.

Note

The container can still be started manually or through a target by configuring the [Install] section. The pod will be started as needed in any case.

Property:

StartWithPod

Type:

null or boolean

Default value:

null

Declared in:

containers.<name>.stopSignal

Signal to stop a container. Default is SIGTERM.

CLI:

--stop-signal

Property:

StopSignal

Type:

null or string

Default value:

null

Example value:

"SIGINT"

Declared in:

containers.<name>.stopTimeout

Seconds to wait before forcibly stopping the container.

Note

This value should be lower than the actual systemd unit timeout to make sure the podman rm command is not killed by systemd.

CLI:

--stop-timeout

Property:

StopTimeout

Type:

null or signed integer

Default value:

null

Example value:

20

Declared in:

containers.<name>.subGIDMap

Run the container in a new user namespace using the map with name in the /etc/subgid file.

CLI:

--subgidname

Property:

SubGIDMap

Type:

null or string

Default value:

null

Example value:

"gtest"

Declared in:

containers.<name>.subUIDMap

Run the container in a new user namespace using the map with name in the /etc/subuid file.

CLI:

--subuidname

Property:

SubUIDMap

Type:

null or string

Default value:

null

Example value:

"utest"

Declared in:

containers.<name>.sysctl

Configures namespaced kernel parameters for the container.

CLI:

--sysctl

Property:

Sysctl

Type:

attribute set of string

Default value:

{ }

Example value:

{
  "net.ipv6.conf.all.disable_ipv6" = 1;
  "net.ipv6.conf.all.use_tempaddr" = 1;
}

Declared in:

containers.<name>.timezone

The timezone to run the container in. (if unset uses system-configured default)

CLI:

--tz

Property:

Timezone

Type:

null or string

Default value:

null

Example value:

"local"

Declared in:

containers.<name>.tmpfs

Mount a tmpfs in the container. This generally has the form CONTAINER-DIR[:OPTIONS].

CLI:

--tmpfs

Property:

Tmpfs

Type:

list of string

Default value:

[ ]

Example value:

[
  "/work"
]

Declared in:

containers.<name>.uidMaps

Run the container in a new user namespace using the supplied UID mapping.

CLI:

--uidmap

Property:

UIDMap

Type:

list of string

Default value:

[ ]

Example value:

[
  "0:10000:10"
]

Declared in:

containers.<name>.ulimits

Ulimit options. Sets the ulimits values inside of the container.

CLI:

--ulimit

Property:

Ulimit

Type:

list of string

Default value:

[ ]

Example value:

[
  "nofile=1000:10000"
]

Declared in:

containers.<name>.unmask

Specify the paths to unmask separated by a colon. unmask=ALL or /path/1:/path/2, or shell expanded paths (/proc/*):

If set to ALL, Podman will unmask all the paths that are masked or made read-only by default.

The default masked paths are /proc/acpi, /proc/kcore, /proc/keys, /proc/latency_stats, /proc/sched_debug, /proc/scsi, /proc/timer_list, /proc/timer_stats, /sys/firmware, and /sys/fs/selinux.

The default paths that are read-only are /proc/asound, /proc/bus, /proc/fs, /proc/irq, /proc/sys, /proc/sysrq-trigger, /sys/fs/cgroup.

CLI:

--security-opt unmask=...

Property:

Unmask

Type:

null or string

Default value:

null

Example value:

"ALL"

Declared in:

containers.<name>.user

The (numeric) UID to run as inside the container. This does not need to match the UID on the host, which can be modified with UserNS, but if that is not specified, this UID is also used on the host.

Note

When both User= and Group= are specified, they are combined into a single --user USER:GROUP argument passed to Podman.

CLI:

--user

Property:

User

Type:

null or string

Default value:

null

Example value:

"bin"

Declared in:

containers.<name>.userns

Set the user namespace mode for the container. This generally has the form MODE[:OPTIONS,...].

CLI:

--userns

Property:

UserNS

Type:

null or string

Default value:

null

Example value:

"keep-id:uid=200,gid=210"

Declared in:

containers.<name>.volumes

Mount a volume in the container. This generally has the form [[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]].

If SOURCE-VOLUME starts with ., Quadlet resolves the path relative to the location of the unit file.

Special case

If SOURCE-VOLUME ends with .volume, a Podman named volume called systemd-$name is used as the source, and the generated systemd service contains a dependency on the $name-volume.service. Note that the corresponding .volume file must exist.

CLI:

--volume

Property:

Volume

Type:

list of string

Default value:

[ ]

Example value:

[
  "/source:/dest"
]

Declared in:

containers.<name>.workdir

Working directory inside the container.

The default working directory for running binaries within a container is the root directory (/). The image developer can set a different default with the WORKDIR instruction. This option overrides the working directory by using the -w option.

CLI:

--workdir

Property:

WorkingDir

Type:

null or string

Default value:

null

Example value:

"$HOME"

Declared in:

files

Extra files to copy to the quadlet's directory.

Type:

attribute set of (package or string)

Default value:

{ }

Example value:

{
  "config.json" = <derivation config.json>;
  "config.yaml" = "hello: world";
}

Declared in:

finalOutput

Directory containing the output files, like example.container.

Type:

package

Default value:

<derivation quadlet>

Declared in:

images

Reference

Type:

attribute set of (submodule)

Default value:

{ }

Declared in:

images.<name>.Install

Install section of quadlet file, same syntax as SystemD install sections.

Warning

This is not transformed, so your keys have to start with capital letters for example.

Type:

attribute set

Default value:

{ }

Example value:

{
  WantedBy = "multi-user.target";
}

Declared in:

images.<name>.Quadlet

Some quadlet specific configuration is shared between different unit types. Those settings can be configured in the [Quadlet] section.

Reference

Type:

attribute set

Default value:

{ }

Example value:

{
  DefaultDependencies = false;
}

Declared in:

images.<name>.Service

Service section of quadlet file, same syntax as SystemD service sections.

Warning

This is not transformed, so your keys have to start with capital letters for example.

Type:

attribute set

Default value:

{ }

Example value:

{
  Restart = "always";
  TimeoutStartSec = 300;
}

Declared in:

images.<name>.Unit

Unit section of quadlet file, same syntax as SystemD unit sections.

Warning

This is not transformed, so your keys have to start with capital letters for example.

Type:

attribute set

Default value:

{ }

Example value:

{
  After = [
    "database.service"
  ];
  Description = "Hello world";
}

Declared in:

images.<name>.allTags

All tagged images in the repository are pulled.

CLI:

--all-tags

Property:

AllTags

Type:

null or boolean

Default value:

null

Declared in:

images.<name>.arch

Override the architecture, defaults to hosts, of the image to be pulled.

CLI:

--arch

Property:

Arch

Type:

null or string

Default value:

null

Example value:

"aarch64"

Declared in:

images.<name>.authFile

Path of the authentication file.

CLI:

--authfile

Property:

AuthFile

Type:

null or string

Default value:

null

Example value:

"/etc/registry/auth.json"

Declared in:

images.<name>.certDir

Use certificates at path (.crt, .cert, *.key) to connect to the registry.

CLI:

--cert-dir

Property:

CertDir

Type:

null or string

Default value:

null

Example value:

"/etc/registry/certs"

Declared in:

images.<name>.creds

The [username[:password]] to use to authenticate with the registry, if required.

CLI:

--creds

Property:

Creds

Type:

null or string

Default value:

null

Example value:

"myname:mypassword"

Declared in:

images.<name>.decryptionKey

The [key[:passphrase]] to be used for decryption of images.

CLI:

--decryption-key

Property:

DecryptionKey

Type:

null or string

Default value:

null

Example value:

"/etc/registry.key"

Declared in:

images.<name>.globalArgs

This key contains a list of arguments passed directly between podman and kube in the generated file. It can be used to access Podman features otherwise unsupported by the generator. Since the generator is unaware of what unexpected interactions can be caused by these arguments, it is not recommended to use this option.

Property:

GlobalArgs

Type:

list of string

Default value:

[ ]

Example value:

[
  "--log-level=debug"
]

Declared in:

images.<name>.image

The image to pull. It is recommended to use a fully qualified image name rather than a short name, both for performance and robustness reasons.

The format of the name is the same as when passed to podman pull. So, it supports using :tag or digests to guarantee the specific image version.

Property:

Image

Type:

null or string

Default value:

null

Example value:

"docker.io/library/nginx:latest"

Declared in:

images.<name>.modules

Load the specified containers.conf(5) module.

CLI:

--module

Property:

ContainersConfModule

Type:

list of string

Default value:

[ ]

Example value:

[
  "/etc/nvd.conf"
]

Declared in:

images.<name>.os

Override the OS, defaults to hosts, of the image to be pulled.

CLI:

--os

Property:

OS

Type:

null or string

Default value:

null

Example value:

"windows"

Declared in:

images.<name>.podmanArgs

This key contains a list of arguments passed directly to the end of the podman kube play command in the generated file (right before the path to the yaml file in the command line). It can be used to access Podman features otherwise unsupported by the generator. Since the generator is unaware of what unexpected interactions can be caused by these arguments, is not recommended to use this option.

Property:

PodmanArgs

Type:

list of string

Default value:

[ ]

Example value:

[
  "--add-host foobar"
]

Declared in:

images.<name>.policy

The pull policy to use when pulling the image.

CLI:

--policy

Property:

Policy

Type:

null or string

Default value:

null

Example value:

"always"

Declared in:

images.<name>.ref

Reference to this image from other quadlets.

Quadlet resolves this to object (e.g. container) names and sets up appropriate systemd dependencies.

This is recognized for most quadlet native options, but not by Podman command line. Using this inside podmanArgs will therefore unlikely work.

Type:

unspecified value

Default value:

"<quadnix project if set>-‹name›.image"

Declared in:

images.<name>.retry

Number of times to retry the image pull when a HTTP error occurs.

CLI:

--retry

Property:

Retry

Type:

null or signed integer

Default value:

null

Example value:

5

Declared in:

images.<name>.retryDelay

Delay between retries.

CLI:

--retry-delay

Property:

RetryDelay

Type:

null or string

Default value:

null

Example value:

"5s"

Declared in:

images.<name>.tag

Actual FQIN of the referenced Image. Only meaningful when source is a file or directory archive.

For example, an image saved into a docker-archive with the following Podman command:

podman image save --format docker-archive --output /tmp/archive-file.tar quay.io/podman/stable:latest

requires setting:

  • Image=docker-archive:/tmp/archive-file.tar
  • ImageTag=quay.io/podman/stable:latest

Property:

ImageTag

Type:

null or string

Default value:

null

Example value:

"localhost/imagename"

Declared in:

images.<name>.tlsVerify

Require HTTPS and verification of certificates when contacting registries.

CLI:

--tls-verify

Property:

TLSVerify

Type:

null or boolean

Default value:

null

Declared in:

images.<name>.variant

Override the default architecture variant of the container image.

CLI:

--variant

Property:

Variant

Type:

null or string

Default value:

null

Example value:

"arm/v7"

Declared in:

kubes

Reference

Type:

attribute set of (submodule)

Default value:

{ }

Declared in:

kubes.<name>.Install

Install section of quadlet file, same syntax as SystemD install sections.

Warning

This is not transformed, so your keys have to start with capital letters for example.

Type:

attribute set

Default value:

{ }

Example value:

{
  WantedBy = "multi-user.target";
}

Declared in:

kubes.<name>.Quadlet

Some quadlet specific configuration is shared between different unit types. Those settings can be configured in the [Quadlet] section.

Reference

Type:

attribute set

Default value:

{ }

Example value:

{
  DefaultDependencies = false;
}

Declared in:

kubes.<name>.Service

Service section of quadlet file, same syntax as SystemD service sections.

Warning

This is not transformed, so your keys have to start with capital letters for example.

Type:

attribute set

Default value:

{ }

Example value:

{
  Restart = "always";
  TimeoutStartSec = 300;
}

Declared in:

kubes.<name>.Unit

Unit section of quadlet file, same syntax as SystemD unit sections.

Warning

This is not transformed, so your keys have to start with capital letters for example.

Type:

attribute set

Default value:

{ }

Example value:

{
  After = [
    "database.service"
  ];
  Description = "Hello world";
}

Declared in:

kubes.<name>.autoUpdates

Indicates whether containers will be auto-updated (podman-auto-update(1)). AutoUpdate can be specified multiple times. The following values are supported:

  • registry: Requires a fully-qualified image reference (e.g., quay.io/podman/stable:latest) to be used to create the container. This enforcement is necessary to know which images to actually check and pull. If an image ID was used, Podman does not know which image to check/pull anymore.

  • local: Tells Podman to compare the image a container is using to the image with its raw name in local storage. If an image is updated locally, Podman simply restarts the systemd unit executing the Kubernetes Quadlet.

  • name/(local|registry): Tells Podman to perform the local or registry autoupdate on the specified container name.

CLI:

--annotation "io.containers.autoupdate=<val>"

Property:

AutoUpdate

Type:

null or string or list of string

Default value:

null

Example value:

"registry"

Declared in:

kubes.<name>.configMaps

Pass the Kubernetes ConfigMap YAML path to podman kube play via the --configmap argument. Unlike the configmap argument, the value may contain only one path but it may be absolute or relative to the location of the unit file.

CLI:

--config-map

Property:

ConfigMap

Type:

list of string

Default value:

[ ]

Example value:

[
  "/tmp/config.map"
]

Declared in:

kubes.<name>.exitCodePropagation

Control how the main PID of the systemd service should exit. The following values are supported:

  • all: exit non-zero if all containers have failed (i.e., exited non-zero)
  • any: exit non-zero if any container has failed
  • none: exit zero and ignore failed containers

The current default value is none.

Property:

ExitCodePropagation

Type:

one of "all", "any", "none"

Default value:

"none"

Example value:

"any"

Declared in:

kubes.<name>.globalArgs

This key contains a list of arguments passed directly between podman and kube in the generated file. It can be used to access Podman features otherwise unsupported by the generator. Since the generator is unaware of what unexpected interactions can be caused by these arguments, it is not recommended to use this option.

Property:

GlobalArgs

Type:

list of string

Default value:

[ ]

Example value:

[
  "--log-level=debug"
]

Declared in:

kubes.<name>.kubeDownForce

Remove all resources, including volumes, when calling podman kube down.

CLI:

--force

Property:

KubeDownForce

Type:

null or boolean

Default value:

null

Example value:

true

Declared in:

kubes.<name>.logDriver

Set the log-driver Podman uses when running the container.

CLI:

--log-driver

Property:

LogDriver

Type:

null or string

Default value:

null

Example value:

"journald"

Declared in:

kubes.<name>.modules

Load the specified containers.conf(5) module.

CLI:

--module

Property:

ContainersConfModule

Type:

list of string

Default value:

[ ]

Example value:

[
  "/etc/nvd.conf"
]

Declared in:

kubes.<name>.networks

Specify a custom network for the container. This has the same format as the --network option to podman kube play. For example, use host to use the host network in the container, or none to not set up networking in the container.

Special case

If the name of the network ends with .network, a Podman network called systemd-$name is used, and the generated systemd service contains a dependency on the $name-network.service. Such a network can be automatically created by using a $name.network Quadlet file.

Note: the corresponding .network file must exist.

CLI:

--network

Property:

Network

Type:

list of string

Default value:

[ ]

Example value:

[
  "host"
]

Declared in:

kubes.<name>.podmanArgs

This key contains a list of arguments passed directly to the end of the podman kube play command in the generated file (right before the path to the yaml file in the command line). It can be used to access Podman features otherwise unsupported by the generator. Since the generator is unaware of what unexpected interactions can be caused by these arguments, is not recommended to use this option.

Property:

PodmanArgs

Type:

list of string

Default value:

[ ]

Example value:

[
  "--add-host foobar"
]

Declared in:

kubes.<name>.publishPorts

Exposes a port, or a range of ports (e.g. 50-59), from the container to the host. Equivalent to the podman kube play's --publish option. The format is similar to the Podman options, which is of the form ip:hostPort:containerPort, ip::containerPort, hostPort:containerPort or containerPort, where the number of host and container ports must be the same (in the case of a range).

If the IP is set to 0.0.0.0 or not set at all, the port is bound on all IPv4 addresses on the host; use [::] for IPv6.

The list of published ports specified in the unit file is merged with the list of ports specified in the Kubernetes YAML file. If the same container port and protocol is specified in both, the entry from the unit file takes precedence

CLI:

--publish

Property:

PublishPort

Type:

list of string

Default value:

[ ]

Example value:

[
  "8080:80"
]

Declared in:

kubes.<name>.ref

Reference to this kube from other quadlets.

Quadlet resolves this to object (e.g. container) names and sets up appropriate systemd dependencies.

This is recognized for most quadlet native options, but not by Podman command line. Using this inside podmanArgs will therefore unlikely work.

Type:

unspecified value

Default value:

"<quadnix project if set>-‹name›.kube"

Declared in:

kubes.<name>.setWorkingDirectory

Set the WorkingDirectory field of the Service group of the Systemd service unit file. Used to allow podman kube play to correctly resolve relative paths. Supported values are yaml and unit to set the working directory to that of the YAML or Quadlet Unit file respectively.

Alternatively, users can explicitly set the WorkingDirectory field of the Service group in the .kube file. Please note that if the WorkingDirectory field of the Service group is set, Quadlet will not set it even if SetWorkingDirectory is set.

Special case

If multiple Yaml path are provided only unit is supported.

Property:

SetWorkingDirectory

Type:

null or one of "yaml", "unit"

Default value:

null

Example value:

"yaml"

Declared in:

kubes.<name>.userNS

Set the user namespace mode for the container. This is equivalent to the Podman --userns option and generally has the form MODE[:OPTIONS,...].

CLI:

--userns

Property:

UserNS

Type:

null or string

Default value:

null

Example value:

"keep-id:uid=200,gid=210"

Declared in:

kubes.<name>.yamls

The path, absolute or relative to the location of the unit file, to the Kubernetes YAML file to use.

CLI:

podman kube play /tmp/kube.yaml

Property:

Yaml

Type:

list of string

Default value:

[ ]

Example value:

[
  "/tmp/kube.yaml"
]

Declared in:

networks

Reference

Type:

attribute set of (submodule)

Default value:

{ }

Declared in:

networks.<name>.Install

Install section of quadlet file, same syntax as SystemD install sections.

Warning

This is not transformed, so your keys have to start with capital letters for example.

Type:

attribute set

Default value:

{ }

Example value:

{
  WantedBy = "multi-user.target";
}

Declared in:

networks.<name>.Quadlet

Some quadlet specific configuration is shared between different unit types. Those settings can be configured in the [Quadlet] section.

Reference

Type:

attribute set

Default value:

{ }

Example value:

{
  DefaultDependencies = false;
}

Declared in:

networks.<name>.Service

Service section of quadlet file, same syntax as SystemD service sections.

Warning

This is not transformed, so your keys have to start with capital letters for example.

Type:

attribute set

Default value:

{ }

Example value:

{
  Restart = "always";
  TimeoutStartSec = 300;
}

Declared in:

networks.<name>.Unit

Unit section of quadlet file, same syntax as SystemD unit sections.

Warning

This is not transformed, so your keys have to start with capital letters for example.

Type:

attribute set

Default value:

{ }

Example value:

{
  After = [
    "database.service"
  ];
  Description = "Hello world";
}

Declared in:

networks.<name>.disableDns

If enabled, disables the DNS plugin for this network.

CLI:

--disable-dns

Property:

DisableDNS

Type:

null or boolean

Default value:

null

Declared in:

networks.<name>.dns

Set network-scoped DNS resolver/nameserver for containers in this network.

CLI:

--dns

Property:

DNS

Type:

list of string

Default value:

[ ]

Example value:

[
  "192.168.55.1"
]

Declared in:

networks.<name>.driver

Driver to manage the network. Currently bridge, macvlan and ipvlan are supported.

CLI:

--driver

Property:

Driver

Type:

null or one of "bridge", "macvlan", "ipvlan"

Default value:

null

Example value:

"bridge"

Declared in:

networks.<name>.gateways

Define a gateway for the subnet. If you want to provide a gateway address, you must also provide a subnet option.

CLI:

--gateway

Property:

Gateway

Type:

list of string

Default value:

[ ]

Example value:

[
  "192.168.55.3"
]

Declared in:

networks.<name>.globalArgs

This key contains a list of arguments passed directly between podman and network in the generated file. It can be used to access Podman features otherwise unsupported by the generator. Since the generator is unaware of what unexpected interactions can be caused by these arguments, it is not recommended to use this option.

Property:

GlobalArgs

Type:

list of string

Default value:

[ ]

Example value:

[
  "--log-level=debug"
]

Declared in:

networks.<name>.interfaceName

This option maps the network_interface option in the network config, see podman network inspect. Depending on the driver, this can have different effects; for bridge, it uses the bridge interface name. For macvlan and ipvlan, it is the parent device on the host. It is the same as --opt parent=....

CLI:

--interface-name

Property:

InterfaceName

Type:

null or string

Default value:

null

Declared in:

networks.<name>.internal

Restrict external access of this network.

CLI:

--internal

Property:

Internal

Type:

boolean

Default value:

false

Declared in:

networks.<name>.ipRanges

Allocate container IP from a range. The range must be a either a complete subnet in CIDR notation or be in the `<startIP>-<endIP> syntax which allows for a more flexible range compared to the CIDR subnet. The ip-range option must be used with a subnet option.

CLI:

--ip-range

Property:

IPRange

Type:

list of string

Default value:

[ ]

Example value:

[
  "192.168.55.128/25"
]

Declared in:

networks.<name>.ipamDriver

Set the ipam driver (IP Address Management Driver) for the network. Currently host-local, dhcp and none are supported.

CLI:

--ipam-driver

Property:

IPAMDriver

Type:

null or one of "host-local", "dhcp", "none"

Default value:

null

Example value:

"dhcp"

Declared in:

networks.<name>.ipv6

Enable IPv6 (Dual Stack) networking.

CLI:

--ipv6

Property:

IPv6

Type:

null or boolean

Default value:

null

Declared in:

networks.<name>.labels

Set one or more OCI labels on the network.

CLI:

--label

Property:

Label

Type:

attribute set of string

Default value:

{ }

Example value:

{
  foo = "bar";
}

Declared in:

networks.<name>.modules

Load the specified containers.conf(5) module.

CLI:

--module

Property:

ContainersConfModule

Type:

list of string

Default value:

[ ]

Example value:

[
  "/etc/nvd.conf"
]

Declared in:

networks.<name>.networkDeleteOnStop

When set to true the network is deleted when the service is stopped

Property:

NetworkDeleteOnStop

Type:

null or boolean

Default value:

null

Declared in:

networks.<name>.networkName

The (optional) name of the Podman network. If this is not specified, the default value is the same name as the unit, but with a systemd- prefix, i.e. a $name.network file creates a systemd-$name Podman network to avoid conflicts with user-managed network.

Property:

NetworkName

Type:

null or string

Default value:

null

Example value:

"foo"

Declared in:

networks.<name>.options

Set driver specific options.

CLI:

--opt

Property:

Options

Type:

attribute set of string

Default value:

{ }

Example value:

{
  isolate = "true";
}

Declared in:

networks.<name>.podmanArgs

This key contains a list of arguments passed directly to the end of the podman network create command in the generated file (right before the name of the network in the command line). It can be used to access Podman features otherwise unsupported by the generator. Since the generator is unaware of what unexpected interactions can be caused by these arguments, it is not recommended to use this option.

Property:

PodmanArgs

Type:

list of string

Default value:

[ ]

Example value:

[
  "--dns=192.168.55.1"
]

Declared in:

networks.<name>.ref

Reference to this network from other quadlets.

Quadlet resolves this to object (e.g. container) names and sets up appropriate systemd dependencies.

This is recognized for most quadlet native options, but not by Podman command line. Using this inside podmanArgs will therefore unlikely work.

Type:

unspecified value

Default value:

"<quadnix project if set>-‹name›.network"

Declared in:

networks.<name>.subnets

The subnet in CIDR notation.

CLI:

--subnet

Property:

Subnet

Type:

list of string

Default value:

[ ]

Example value:

[
  "192.5.0.0/16"
]

Declared in:

pods

Reference

Type:

attribute set of (submodule)

Default value:

{ }

Declared in:

pods.<name>.Install

Install section of quadlet file, same syntax as SystemD install sections.

Warning

This is not transformed, so your keys have to start with capital letters for example.

Type:

attribute set

Default value:

{ }

Example value:

{
  WantedBy = "multi-user.target";
}

Declared in:

pods.<name>.Quadlet

Some quadlet specific configuration is shared between different unit types. Those settings can be configured in the [Quadlet] section.

Reference

Type:

attribute set

Default value:

{ }

Example value:

{
  DefaultDependencies = false;
}

Declared in:

pods.<name>.Service

Service section of quadlet file, same syntax as SystemD service sections.

Warning

This is not transformed, so your keys have to start with capital letters for example.

Type:

attribute set

Default value:

{ }

Example value:

{
  Restart = "always";
  TimeoutStartSec = 300;
}

Declared in:

pods.<name>.Unit

Unit section of quadlet file, same syntax as SystemD unit sections.

Warning

This is not transformed, so your keys have to start with capital letters for example.

Type:

attribute set

Default value:

{ }

Example value:

{
  After = [
    "database.service"
  ];
  Description = "Hello world";
}

Declared in:

pods.<name>.addHosts

Add host-to-IP mapping to /etc/hosts. The format is hostname:ip.

CLI:

--add-host

Property:

AddHost

Type:

list of string

Default value:

[ ]

Example value:

[
  "hostname:192.168.10.11"
]

Declared in:

pods.<name>.dns

Set network-scoped DNS resolver/nameserver for containers in this pod.

CLI:

--dns

Property:

DNS

Type:

list of string

Default value:

[ ]

Example value:

[
  "192.168.55.1"
]

Declared in:

pods.<name>.dnsOptions

Set custom DNS options.

CLI:

--dns-option

Property:

DNSOption

Type:

list of string

Default value:

[ ]

Example value:

[
  "ndots:1"
]

Declared in:

pods.<name>.dnsSearches

Set custom DNS search domains. Use DNSSearch=. (dnsSearches = ["."] in Nix) to remove the search domain.

CLI:

--dns-search

Property:

DNSSearch

Type:

list of string

Default value:

[ ]

Example value:

[
  "foo.com"
]

Declared in:

pods.<name>.exitPolicy

Set the exit policy of the pod when the last container exits. Default for quadlets is stop.

To keep the pod active, set ExitPolicy=continue.

Property:

ExitPolicy

Type:

null or string

Default value:

null

Declared in:

pods.<name>.gidMaps

CLI:

--gidmap

Property:

GIDMap

Type:

list of string

Default value:

[ ]

Example value:

[
  "0:10000:10"
]

Declared in:

pods.<name>.globalArgs

This key contains a list of arguments passed directly between podman and kube in the generated file. It can be used to access Podman features otherwise unsupported by the generator. Since the generator is unaware of what unexpected interactions can be caused by these arguments, it is not recommended to use this option.

Property:

GlobalArgs

Type:

list of string

Default value:

[ ]

Example value:

[
  "--log-level=debug"
]

Declared in:

pods.<name>.hostname

Set the pod’s hostname inside all containers.

The given hostname is also added to the /etc/hosts file using the container's primary IP address (also see the --add-host option).

CLI:

--hostname

Property:

HostName

Type:

null or string

Default value:

null

Example value:

"new-host-name"

Declared in:

pods.<name>.ip

Specify a static IPv4 address for the pod.

CLI:

--ip

Property:

IP

Type:

null or string

Default value:

null

Example value:

"10.88.64.128"

Declared in:

pods.<name>.ip6

Specify a static IPv6 address for the pod.

CLI:

--ip6

Property:

IP6

Type:

null or string

Default value:

null

Example value:

"fd46:db93:aa76:ac37::10"

Declared in:

pods.<name>.labels

Set one or more OCI labels on the pod. The format is a list of key=value items, similar to Environment.

CLI:

--label

Property:

Label

Type:

attribute set of string

Default value:

{ }

Example value:

{
  foo = "bar";
}

Declared in:

pods.<name>.modules

Load the specified containers.conf(5) module.

CLI:

--module

Property:

ContainersConfModule

Type:

list of string

Default value:

[ ]

Example value:

[
  "/etc/nvd.conf"
]

Declared in:

pods.<name>.networkAliases

Add a network-scoped alias for the container. Aliases can be used to group containers together in DNS resolution: for example, setting NetworkAlias=web on multiple containers will make a DNS query for web resolve to all the containers with that alias.

CLI:

--network-alias

Property:

NetworkAlias

Type:

list of string

Default value:

[ ]

Example value:

[
  "name"
]

Declared in:

pods.<name>.networks

Specify a custom network for the container. This has the same format as the --network option to podman kube play. For example, use host to use the host network in the container, or none to not set up networking in the container.

Special case

If the name of the network ends with .network, a Podman network called systemd-$name is used, and the generated systemd service contains a dependency on the $name-network.service. Such a network can be automatically created by using a $name.network Quadlet file.

Note: the corresponding .network file must exist.

CLI:

--network

Property:

Network

Type:

list of string

Default value:

[ ]

Example value:

[
  "host"
]

Declared in:

pods.<name>.podName

The (optional) name of the Podman pod. If this is not specified, the default value is the same name as the unit, but with a systemd- prefix, i.e. a $name.pod file creates a systemd-$name Podman pod to avoid conflicts with user-managed pods.

Please note that pods and containers cannot have the same name. So, if PodName is set, it must not conflict with any container.

CLI:

--name

Property:

PodName

Type:

null or string

Default value:

null

Example value:

"name"

Declared in:

pods.<name>.podmanArgs

This key contains a list of arguments passed directly to the end of the podman kube play command in the generated file (right before the path to the yaml file in the command line). It can be used to access Podman features otherwise unsupported by the generator. Since the generator is unaware of what unexpected interactions can be caused by these arguments, is not recommended to use this option.

Property:

PodmanArgs

Type:

list of string

Default value:

[ ]

Example value:

[
  "--add-host foobar"
]

Declared in:

pods.<name>.publishPorts

Exposes a port, or a range of ports (e.g. 50-59), from the pod to the host. The format is similar to the Podman options, which is of the form ip:hostPort:containerPort, ip::containerPort, hostPort:containerPort or containerPort, where the number of host and container ports must be the same (in the case of a range).

If the IP is set to 0.0.0.0 or not set at all, the port is bound on all IPv4 addresses on the host; use [::] for IPv6.

Note that not listing a host port means that Podman automatically selects one, and it may be different for each invocation of service. This makes that a less useful option. The allocated port can be found with the podman port command.

When using host networking via Network=host, the PublishPort= option cannot be used.

CLI:

--publish

Property:

PublishPort

Type:

list of string

Default value:

[ ]

Example value:

[
  "50-59"
]

Declared in:

pods.<name>.ref

Reference to this pod from other quadlets.

Quadlet resolves this to object (e.g. container) names and sets up appropriate systemd dependencies.

This is recognized for most quadlet native options, but not by Podman command line. Using this inside podmanArgs will therefore unlikely work.

Type:

unspecified value

Default value:

"<quadnix project if set>-‹name›.pod"

Declared in:

pods.<name>.serviceName

By default, Quadlet will name the systemd service unit by appending -pod to the name of the Quadlet. Setting this key overrides this behavior by instructing Quadlet to use the provided name.

Note, the name should not include the .service file extension

Property:

ServiceName

Type:

null or string

Default value:

null

Example value:

"foo"

Declared in:

pods.<name>.shmSize

Size of /dev/shm.

CLI:

--shm-size

Property:

ShmSize

Type:

null or string

Default value:

null

Example value:

"100m"

Declared in:

pods.<name>.stopTimeout

Sets the time in seconds to wait for the pod to gracefully stop. This value is equivalent to the --time argument in the podman pod stop command when the service is stopped. After this period expires, any running containers in the pod are forcibly killed.

CLI:

--time

Property:

StopTimeout

Type:

null or signed integer

Default value:

null

Example value:

5

Declared in:

pods.<name>.subGIDMap

Create the pod in a new user namespace using the map with name in the /etc/subgid file.

CLI:

--subgidname

Property:

SubGIDMap

Type:

null or string

Default value:

null

Example value:

"gtest"

Declared in:

pods.<name>.subUIDMap

Create the pod in a new user namespace using the map with name in the /etc/subuid file.

CLI:

--subuidname

Property:

SubUIDMap

Type:

null or string

Default value:

null

Example value:

"utest"

Declared in:

pods.<name>.uidMaps

Create the pod in a new user namespace using the supplied UID mapping.

CLI:

--uidmap

Property:

UIDMap

Type:

list of string

Default value:

[ ]

Example value:

[
  "0:10000:10"
]

Declared in:

pods.<name>.userNS

Set the user namespace mode for the pod. This generally has the form MODE[:OPTIONS,...].

CLI:

--userns

Property:

UserNS

Type:

null or string

Default value:

null

Example value:

"keep-id:uid=200,gid=210"

Declared in:

pods.<name>.volumes

Mount a volume in the container. This generally has the form [[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]].

If SOURCE-VOLUME starts with ., Quadlet resolves the path relative to the location of the unit file.

Special case

If SOURCE-VOLUME ends with .volume, a Podman named volume called systemd-$name is used as the source, and the generated systemd service contains a dependency on the $name-volume.service. Note that the corresponding .volume file must exist.

CLI:

--volume

Property:

Volume

Type:

list of string

Default value:

[ ]

Example value:

[
  "/source:/dest"
]

Declared in:

quadnix.project

Project to prepend to every resource.

Type:

string

Default value:

""

Declared in:

volumes

Reference

Type:

attribute set of (submodule)

Default value:

{ }

Declared in:

volumes.<name>.Install

Install section of quadlet file, same syntax as SystemD install sections.

Warning

This is not transformed, so your keys have to start with capital letters for example.

Type:

attribute set

Default value:

{ }

Example value:

{
  WantedBy = "multi-user.target";
}

Declared in:

volumes.<name>.Quadlet

Some quadlet specific configuration is shared between different unit types. Those settings can be configured in the [Quadlet] section.

Reference

Type:

attribute set

Default value:

{ }

Example value:

{
  DefaultDependencies = false;
}

Declared in:

volumes.<name>.Service

Service section of quadlet file, same syntax as SystemD service sections.

Warning

This is not transformed, so your keys have to start with capital letters for example.

Type:

attribute set

Default value:

{ }

Example value:

{
  Restart = "always";
  TimeoutStartSec = 300;
}

Declared in:

volumes.<name>.Unit

Unit section of quadlet file, same syntax as SystemD unit sections.

Warning

This is not transformed, so your keys have to start with capital letters for example.

Type:

attribute set

Default value:

{ }

Example value:

{
  After = [
    "database.service"
  ];
  Description = "Hello world";
}

Declared in:

volumes.<name>.copy

If enabled, the content of the image located at the mountpoint of the volume is copied into the volume on the first run.

CLI:

--opt copy

Property:

Copy

Type:

boolean

Default value:

true

Declared in:

volumes.<name>.device

The path of a device which is mounted for the volume.

CLI:

--opt device=...

Property:

Device

Type:

null or string

Default value:

null

Example value:

"tmpfs"

Declared in:

volumes.<name>.driver

Specify the volume driver name. When set to image, the Image key must also be set.

CLI:

--driver

Property:

Driver

Type:

null or string

Default value:

null

Example value:

"image"

Declared in:

volumes.<name>.globalArgs

This key contains a list of arguments passed directly between podman and volume in the generated file. It can be used to access Podman features otherwise unsupported by the generator. Since the generator is unaware of what unexpected interactions can be caused by these arguments, it is not recommended to use this option.

Property:

GlobalArgs

Type:

list of string

Default value:

[ ]

Example value:

[
  "--log-level=debug"
]

Declared in:

volumes.<name>.group

The host (numeric) GID, or group name to use as the group for the volume

CLI:

--opt group=...

Property:

Group

Type:

null or signed integer or string

Default value:

null

Example value:

192

Declared in:

volumes.<name>.image

Specifies the image the volume is based on when Driver is set to image. It is recommended to use a fully qualified image name rather than a short name, both for performance and robustness reasons.

The format of the name is the same as when passed to podman pull. So, it supports using :tag or digests to guarantee the specific image version.

Special case

If the name of the image ends with .image, Quadlet will use the image pulled by the corresponding .image file, and the generated systemd service contains a dependency on the $name-image.service (or the service name set in the .image file).

Note: the corresponding .image file must exist.

CLI:

--opt image=...

Property:

Image

Type:

null or string

Default value:

null

Example value:

"quay.io/centos/centos:latest"

Declared in:

volumes.<name>.labels

Set one or more OCI labels on the volume.

CLI:

--label

Property:

Label

Type:

(list of string) or attribute set of string

Default value:

{ }

Example value:

{
  foo = "bar";
}

Declared in:

volumes.<name>.modules

Load the specified containers.conf(5) module.

CLI:

--module

Property:

ContainersConfModule

Type:

list of string

Default value:

[ ]

Example value:

[
  "/etc/nvd.conf"
]

Declared in:

volumes.<name>.options

The mount options to use for a filesystem as used by the mount(8) command -o option.

CLI:

--opt o=...

Property:

Options

Type:

null or string

Default value:

null

Declared in:

volumes.<name>.podmanArgs

This key contains a list of arguments passed directly to the end of the podman volume create command in the generated file (right before the name of the volume in the command line). It can be used to access Podman features otherwise unsupported by the generator. Since the generator is unaware of what unexpected interactions can be caused by these arguments, it is not recommended to use this option.

Property:

PodmanArgs

Type:

list of string

Default value:

[ ]

Example value:

[
  "--driver=image"
]

Declared in:

volumes.<name>.ref

Reference to this volume from other quadlets.

Quadlet resolves this to object (e.g. container) names and sets up appropriate systemd dependencies.

This is recognized for most quadlet native options, but not by Podman command line. Using this inside podmanArgs will therefore unlikely work.

Type:

unspecified value

Default value:

"<quadnix project if set>-‹name›.volume"

Declared in:

volumes.<name>.type

The filesystem type of Device as used by the mount(8) commands -t option.

CLI:

--opt type=...

Property:

Type

Type:

null or string

Default value:

null

Declared in:

volumes.<name>.user

The host (numeric) UID, or user name to use as the owner for the volume

CLI:

--opt uid=...

Property:

User

Type:

null or signed integer or string

Default value:

null

Example value:

123

Declared in:

volumes.<name>.volumeName

The (optional) name of the Podman volume. If this is not specified, the default value is the same name as the unit, but with a systemd- prefix, i.e. a $name.volume file creates a systemd-$name Podman volume to avoid conflicts with user-managed volumes.

Property:

VolumeName

Type:

null or string

Default value:

null

Example value:

"foo"

Declared in: