Chapter 18. Managing containers by using the podman RHEL system role

With the podman RHEL system role, you can manage Podman configuration, containers, and systemd services that run Podman containers.

18.1. Variables of the podman RHEL system role

The parameters used for the podman RHEL system role are the following:

VariableDescription

podman_kube_specs

Describes a Podman pod and the corresponding systemd unit.

  • state: (default: created) - denotes an operation to be executed with systemd services and pods:

    • created: create the pods and systemd service, but do not run them
    • started: create the pods and systemd services, and start them
    • absent: remove the pods and systemd services

  • run_as_user: (default: podman_run_as_user) - a per-pod user. If you do not specify a user, it uses root.

    Note

    The user must already exist.

  • run_as_group (default: podman_run_as_group) - a per-pod group. If you do not specify a user, it uses root.

    Note

    The group must already exist.

  • systemd_unit_scope (default: podman_systemd_unit_scope) - scope to use for the systemd unit. If you do not not specify, it uses system is for root containers, and user for user containers.

  • kube_file_src - name of a Kubernetes YAML file on the controller node which will be copied to kube_file on the managed node

    Note

    Do not specify the kube_file_src variable if you specify the kube_file_content variable. The kube_file_content takes precedence over kube_file_src.

  • kube_file_content - string in Kubernetes YAML format or a dict in Kubernetes YAML format. It specifies the contents of kube_file on the managed node.

    Note

    Do not specify the kube_file_content variable if you specify kube_file_src variable. The kube_file_content takes precedence over kube_file_src.

  • kube_file - a file name on the managed node that contains the Kubernetes specification of the container or pod. You typically do not have to specify the kube_file variable unless you need to copy the kube_file file to the managed node outside of the role. If you specify either kube_file_src or kube_file_content, you do not have to specify this.

    Note

    It is highly recommended to omit kube_file and instead specify either kube_file_src or kube_file_content and let the role manage the file path and name.

    • The file basename will be the metadata.name value from the K8s yaml, with a .yml suffix appended to it.
    • The directory is /etc/containers/ansible-kubernetes.d for system services.
    • The directory is $HOME/.config/containers/ansible-kubernetes.d for user services.
    • This will be copied to the file /etc/containers/ansible-kubernetes.d/<application_name>.yml on the managed node.

podman_quadlet_specs

List of Quadlet specifications.

Warning

Quadlets work only with rootful containers on RHEL 8. Quadlets work with rootless containers only on RHEL 9.

Quadlet is defined by a name and type of a unit. Types of a unit can be the following: container, kube, network, volume. You can either pass in name and type explicitly, or the name and type will be derived from the file name given in file, file_src, or template_src.

  • The root containers files are in /etc/containers/systemd/$name.$type on the managed node.
  • The rootless containers files are in $HOME/.config/containers/systemd/$name.$type on the managed node.

When a Quadlet specification depends on some other file, for example quadlet.kube that depends on the Yaml file or a ConfigMap, then that file must be specified in the podman_quadlet_specs list before the file that uses it. For example, if you have a my-app.kube file: 

[Kube]
ConfigMap=my-app-config.yml
Yaml=my-app.yml
...

Then you must specify my-app-config.yml and my-app.yml before my-app.kube: 

podman_quadlet_specs:
  - file_src: my-app-config.yml
  - file_src: my-app.yml
  - file_src: my-app.kube

Most of the parameters for each Quadlet specification are the same as for podman_kube_spec above, except that the kube parameters are not supported. The following parameters are supported:

  • name - name of the unit. If you do not specify a name, it is derived from file, file_src, or template_src.

    • For example, if you specify file_src: /path/to/my-container.container then the name is my-container.

  • type - type of a unit can be the following: container, kube, network, volume. If you do not specify a name, it is derived from file, file_src, or template_src.

    • For example, if you specify file_src: /path/to/my-container.container then the type is container.

      Note

      If this file is in the Quadlet unit format and has a valid Quadlet unit suffix, it is used as a Quadlet unit, otherwise, it is just copied.

  • file_src - name of the file on the control node to copy to the managed node to use as the source of the Quadlet unit.

    Note

    If this file is in the Quadlet unit format and has a valid Quadlet unit suffix, it is used as a Quadlet unit, otherwise, it is just copied.

  • file - name of the file on the managed node to use as the source of the Quadlet unit.

    Note

    If this file is in the Quadlet unit format and has a valid Quadlet unit suffix, it is used as a Quadlet unit, otherwise, it is just copied.

  • file_content - the contents of a file to copy to the managed node, in string format. This is useful to pass in short files that can easily be specified inline. You must specify name and type.

  • template_src - the name of the file on the control node which will be processed as a Jinja * template file, then copied to the managed node to use as the source of the Quadlet unit.

    Note

    If this file is in the Quadlet unit format and has a valid Quadlet unit suffix, it is used as a Quadlet unit, otherwise, it is just copied. If the file has a .j2 suffix, that suffix will be removed to determine the quadlet file type.

    • For example, if you specify: 

      podman_quadlet_specs:
  - template_src: my-app.container.j2

      Then the local file templates/my-app.container.j2 will be processed as a Jinja template file, then copied to /etc/containers/systemd/my-app.container as a Quadlet container unit specification on the managed node.

podman_secrets

List of secret specs in the same format as used by podman_secret, except that there is an additional field run_as_user used to create the secret in the account of a specified user. If this is not specified, then the secret will be created in the account specified by podman_run_as_user, and the default value of that is "root" Use Ansible Vault to encrypt the value of the data field.

podman_create_host_directories

If true, the role ensures host directories specified in host mounts in volumes.hostPath specifications in the Kubernetes YAML given in podman_kube_specs. The default value is false.

Note

To ensure that the role manages the directories, you must specify directories as absolute paths for root containers, or paths relative to the home directory, for non-root containers.

The role applies its default ownership or permissions to the directories. If you need to set ownership or permissions, see podman_host_directories.

podman_host_directories

It is a dict. If using podman_create_host_directories to tell the role to create host directories for volume mounts, and you need to specify permissions or ownership that apply to these created host directories, use podman_host_directories. Each key is the absolute path of the host directory to manage. The value is in the format of the parameters to the file module. If you do not specify a value, the role will use its built-in default values. If you want to specify a value to be used for all host directories, use the special key DEFAULT.

podman_firewall

It is a list of dict. Specifies ports that you want the role to manage in the firewall. This uses the same format as used by the firewall RHEL system role.

podman_selinux_ports

It is a list of dict. Specifies ports that you want the role to manage the SELinux policy for ports used by the role. This uses the same format as used by the selinux RHEL system role.

podman_run_as_user

Specifies the name of the user to use for all rootless containers. You can also specify per-container/unit/secret username with run_as_user in podman_kube_specs, podman_quadlet_specs, or podman_secrets. .

Note

The user must already exist.

podman_run_as_group

Specifies the name of the group to use for all rootless containers. You can also specify a per-container or unit group name with run_as_group in podman_kube_specs or podman_quadlet_specs.

Note

The group must already exist.

podman_systemd_unit_scope

Defines the systemd scope to use by default for all systemd units. You can also specify per-container or unit scope with systemd_unit_scope in podman_kube_specs and podman_quadlet_specs. By default, rootless containers use user and root containers use system.

podman_containers_conf

Defines the containers.conf(5) settings as a dict. The setting is provided in a drop-in file in the containers.conf.d directory. If running as root, the system settings are managed. See podman_run_as_user.Otherwise, the user settings are managed. See the containers.conf man page for the directory locations.

podman_registries_conf

Defines the containers-registries.conf(5) settings as a dict. The setting is provided in a drop-in file in the registries.conf.d directory. If running as root, the system settings are managed. See podman_run_as_user. Otherwise, the user settings are managed. See the registries.conf man page for the directory locations.

podman_storage_conf

Defines the containers-storage.conf(5) settings as a dict. If running as root, the system settings are managed. See podman_run_as_user. Otherwise, the user settings are managed. See the storage.conf man page for the directory locations.

podman_policy_json

Defines the containers-policy.conf(5) settings as a dict. If running as root (see podman_run_as_user), the system settings are managed. Otherwise, the user settings are managed. See the policy.json man page for the directory locations.

Additional resources

  • /usr/share/ansible/roles/rhel-system-roles.podman/README.md file
  • /usr/share/doc/rhel-system-roles/podman/ directory