Podman Task Driver

Name: podman

Homepage: https://github.com/hashicorp/nomad-driver-podman

The Podman task driver plugin for Nomad uses the Pod Manager (podman) daemonless container runtime for executing Nomad tasks. Podman supports OCI containers and its command line tool is meant to be a drop-in replacement for Docker's.

See the project's homepage for details.

Client Requirements

The Podman task driver is not builtin to Nomad. It must be downloaded onto the client host in the configured plugin directory.

Linux host with podman installed.
nomad-driver-podman binary in Nomad's plugin_dir.

You need a varlink enabled Podman binary and a system socket activation unit, see https://podman.io/blogs/2019/01/16/podman-varlink.html.

Since the Nomad agent, nomad-driver-podman plugin binary, and Podman will reside on the same host, skip the ssh aspects of the Podman varlink documentation above.

Capabilities

The podman driver implements the following capabilities.

Feature	Implementation
`nomad alloc signal`	true
`nomad alloc exec`	false
filesystem isolation	image
network isolation	host, group, task, none
volume mounting	none

Known Limitations

The Podman task driver is under active development. It currently does not support stderr logging and devices. Podman recently released Podman v2. The task driver currently supports v1 and will be working on supporting v2 in upcoming releases.

Task Configuration

Due to Podman's similarity to Docker, the example job created by nomad init -short is easily adapted to use Podman instead:

job "example" {
  datacenters = ["dc1"]
  network {
    port  "db"  {
      to = 6379
    }
  }

  group "cache" {
    task "redis" {
      driver = "podman"

      config {
        image = "docker://redis:3.2"
        ports = ["db"]
      }

      resources {
        cpu    = 500
        memory = 256
      }
    }
  }
}

image - The image to run.

config {
  image = "docker://redis"
}

command - (Optional) The command to run when starting the container.

config {
  command = "some-command"
}

args - (Optional) A list of arguments to the optional command. If no command is specified, the arguments are passed directly to the container.

config {
  args = [
    "arg1",
    "arg2",
  ]
}

volumes - (Optional) A list of host_path:container_path strings to bind host paths to container paths.

config {
  volumes = [
    "/some/host/data:/container/data"
  ]
}

tmpfs - (Optional) A list of /container_path strings for tmpfs mount points. See podman run --tmpfs options for details.

config {
  tmpfs = [
    "/var"
  ]
}

hostname - (Optional) The hostname to assign to the container. When launching more than one of a task (using count) with this option set, every container the task starts will have the same hostname.
init - Run an init inside the container that forwards signals and reaps processes.

config {
  init = true
}

init_path - Path to the container-init binary.

config {
  init = true
  init_path = "/usr/libexec/podman/catatonit"
}

user - Run the command as a specific user/uid within the container. See task configuration.
memory_reservation - Memory soft limit (unit = b (bytes), k (kilobytes), m (megabytes), or g (gigabytes))

After setting memory reservation, when the system detects memory contention or low memory, containers are forced to restrict their consumption to their reservation. So you should always set the value below --memory, otherwise the hard limit will take precedence. By default, memory reservation will be the same as memory limit.

config {
  memory_reservation = "100m"
}

memory_swap - A limit value equal to memory plus swap. The swap limit should always be larger than the memory value.

Unit can be b (bytes), k (kilobytes), m (megabytes), or g (gigabytes). If you don't specify a unit, b is used. Set LIMIT to -1 to enable unlimited swap.

config {
  memory_swap = "180m"
}

memory_swappiness - Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100.

config {
  memory_swappiness = 60
}

network_mode - Set the network mode for the container. This will be overridden by nomad if a group network is created and passed in by Nomad.
- bridge - (default for rootful) create a network stack on the default bridge
- none - no networking
- container:id - reuse another container's network stack
- host - use the Podman host network stack. Note: the host mode gives the container full access to local system services such as D-bus and is therefore considered insecure.
- slirp4netns - use slirp4netns to create a user network stack. This is the default for rootless containers. Podman currently does not support this option for rootful containers (issue)

Networking

Podman supports forwarding and exposing ports like Docker. See Docker Driver configuration for details.

Plugin Options

The Podman plugin has options which may be customized in the agent's configuration file.

volumes stanza:
- enabled - Defaults to true. Allows tasks to bind host paths (volumes) inside their container.
- selinuxlabel - Allows the operator to set a SELinux label to the allocation and task local bind-mounts to containers. If used with volumes.enabled set to false, the labels will still be applied to the standard binds in the container.

plugin "nomad-driver-podman" {
  config {
    volumes {
      enabled      = true
      selinuxlabel = "z"
    }
  }
}

gc stanza:
- container - Defaults to true. This option can be used to disable Nomad from removing a container when the task exits.

plugin "nomad-driver-podman" {
  config {
    gc {
      container = false
    }
  }
}

recover_stopped - Defaults to true. Allows the driver to start and reuse a previously stopped container after a Nomad client restart. Consider a simple single node system and a complete reboot. All previously managed containers will be reused instead of disposed and recreated.

plugin "nomad-driver-podman" {
  config {
    recover_stopped = false
  }
}