Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: update podman driver docs with v0.5.0 changes #17824

Merged
merged 1 commit into from
Jul 11, 2023
Merged

docs: update podman driver docs with v0.5.0 changes #17824

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 36 additions & 26 deletions website/content/plugins/drivers/podman.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,31 +10,29 @@ description: >-

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].
containers and its command line tool is meant to be [a drop-in replacement]
[podman-cli] for docker.

Source is on [GitHub][github]

Due to Podman's similarity to Docker, the example job created by
[`nomad init -short`][nomad-init] is easily adapted to use Podman instead:
Download from HashiCorp [releases][releases]

The example job created by [`nomad init -short`][nomad-init] is easily adapted
to use Podman instead:

```hcl
job "redis" {
datacenters = ["dc1"]
type = "service"

group "cache" {
network {
port "redis" { to = 6379 }
}

task "redis" {
driver = "podman"

config {
image = "docker://redis"
image = "docker.io/library/redis:7"
ports = ["redis"]
}
}
Expand All @@ -46,20 +44,17 @@ Refer to the project's [homepage][homepage] for details.

## Client Requirements

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

- [Nomad][nomad_download] 0.12.9+
- Linux host with [`podman`][podman] installed
- For rootless containers you need a system supporting cgroup V2 and a few
- For rootless containers you need a system supporting cgroups v2 and a few
other things, follow [this tutorial][rootless_tutorial].

You need a 3.0.x podman binary and a system socket activation unit, refer to
[https://www.redhat.com/sysadmin/podmans-new-rest-api](https://www.redhat.com/sysadmin/podmans-new-rest-api).

Nomad agent, `nomad-driver-podman` and `podman` will reside on the same client,
so you do not have to worry about the `ssh` aspects of the Podman api.
You need a v3.x or higher podman binary and a system socket [activation unit]
[rest_api]. It is recommended to install podman via your system's package
manager, which will configure systemd for you.

Ensure that Nomad can find the plugin, refer to [`plugin_dir`][plugin_dir].

Expand All @@ -70,10 +65,10 @@ The `podman` driver implements the following [capabilities](/nomad/docs/concepts
| Feature | Implementation |
| -------------------- | ----------------------- |
| `nomad alloc signal` | true |
| `nomad alloc exec` | false |
| `nomad alloc exec` | true |
| filesystem isolation | image |
| network isolation | host, group, task, none |
| volume mounting | none |
| volume mounting | true |

## Task Configuration

Expand All @@ -90,14 +85,16 @@ The `podman` driver implements the following [capabilities](/nomad/docs/concepts
```

- `auth` - (Optional) Authenticate to the image registry using a static
credential.
credential. By setting tlsVerify to false the driver will allow using self-
signed certificates or plain HTTP connections to the registry.

```hcl
config {
image = "your.registry.tld/some/image"
auth {
username = "someuser"
password = "sup3rs3creT"
tlsVerify = false
}
}
```
Expand Down Expand Up @@ -178,6 +175,14 @@ The `podman` driver implements the following [capabilities](/nomad/docs/concepts
}
```

- `extra_hosts` - (Optional) Set additional hosts in the container

```hcl
config {
extra_hosts = ["test4.localhost:127.0.0.2", "test6.localhost:[::1]"]
}
```

- `image_pull_timeout` - (Optional) Time duration for your pull timeout
(default to `"5m"`). Cannot be longer than the [`client_http_timeout`].

Expand Down Expand Up @@ -488,10 +493,13 @@ configuration file.
}
```

- `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.
- `recover_stopped` - (Deprecated) Defaults to `false`. 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.

!> This option may cause Nomad client to hang on startup. It now defaults to
being disabled and may be removed in a future release.

```hcl
plugin "nomad-driver-podman" {
Expand Down Expand Up @@ -550,6 +558,7 @@ configuration file.
}
```

[github]: https://github.com/hashicorp/nomad-driver-podman
[`count`]: /nomad/docs/job-specification/group#count
[`disable_log_collection`]: #disable_log_collection
[docker-ports]: /nomad/docs/drivers/docker#forwarding-and-exposing-ports
Expand Down Expand Up @@ -578,3 +587,4 @@ configuration file.
[short-names]: https://github.com/containers/image/blob/master/docs/containers-registries.conf.5.md#short-name-aliasing
[`command`]: #command
[`client_http_timeout`]: #client_http_timeout
[rest_api]: https://www.redhat.com/sysadmin/podmans-new-rest-api