open-nomad/website/content/docs/drivers/podman.mdx

---
layout: docs
page_title: 'Drivers: podman'
sidebar_title: Podman
description: >-
  The Podman task driver uses podman (https://podman.io/) for containerizing
  tasks.
---

# 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)][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][podman-cli].

See the project's [homepage][homepage] for details.

## Client Requirements

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

- Linux host with [`podman`][podman] installed.
- [`nomad-driver-podman`][releases] binary in Nomad's [`plugin_dir`][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](/docs/internals/plugins/task-drivers#capabilities-capabilities-error).

| 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][stderr-logging] and [devices][devices].
Podman recently released [Podman v2](https://podman.io/blogs/2020/06/29/podman-v2-announce.html). 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`][nomad-init] is easily adapted to use Podman instead:

```hcl
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.

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

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

```hcl
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.

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

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

```hcl
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.

```hcl
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.

```hcl
config {
  init = true
}
```

- `init_path` - Path to the container-init binary.

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

- `user` - Run the command as a specific user/uid within the container. See
  [task configuration][task].

- `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.

```hcl
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][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.

```hcl
config {
  memory_swap = "180m"
}
```

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

```hcl
config {
  memory_swappiness = 60
}
```

- `network_mode` - Set the [network mode][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][slirp-issue])

## Networking

Podman supports forwarding and exposing ports like Docker. See [Docker Driver
configuration][docker-ports] 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.

```hcl
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.

```hcl
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.

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

[docker-ports]: /docs/drivers/docker#forwarding-and-exposing-ports
[homepage]: https://github.com/hashicorp/nomad-driver-podman
[memory-value]: /docs/job-specification/resources#memory
[nomad-init]: /docs/commands/job/init
[plugin_dir]: /docs/configuration#plugin_dir
[podman]: https://podman.io/
[podman-cli]: https://podman.io/whatis.html
[releases]: https://releases.hashicorp.com/nomad-driver-podman
[task]: /docs/job-specification/task#user
[network-mode]: http://docs.podman.io/en/latest/markdown/podman-run.1.html#options
[slirp-issue]: https://github.com/containers/libpod/issues/6097
[stderr-logging]: https://github.com/hashicorp/nomad-driver-podman/issues/4
[devices]: https://github.com/hashicorp/nomad-driver-podman/issues/41
[downloaded]: https://releases.hashicorp.com/nomad-driver-podman