mirror of https://github.com/k3d-io/k3d
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
165 lines
5.2 KiB
165 lines
5.2 KiB
# Using Podman instead of Docker
|
|
|
|
Podman has an [Docker API compatibility layer](https://podman.io/blogs/2020/06/29/podman-v2-announce.html#restful-api). k3d uses the Docker API and is compatible with Podman v4 and higher.
|
|
|
|
!!! important "Podman support is experimental"
|
|
k3d is not guaranteed to work with Podman. If you find a bug, do help by [filing an issue](https://github.com/k3d-io/k3d/issues/new?labels=bug&template=bug_report.md&title=%5BBUG%5D+Podman)
|
|
|
|
Tested with podman version:
|
|
```bash
|
|
Client: Podman Engine
|
|
Version: 4.3.1
|
|
API Version: 4.3.1
|
|
```
|
|
|
|
## Using Podman
|
|
|
|
Ensure the Podman system socket is available:
|
|
|
|
```bash
|
|
sudo systemctl enable --now podman.socket
|
|
# or to start the socket daemonless
|
|
# sudo podman system service --time=0 &
|
|
```
|
|
|
|
Disable timeout for podman service:<br>
|
|
See the [podman-system-service (1)](https://docs.podman.io/en/latest/markdown/podman-system-service.1.html) man page for more information.
|
|
```bash
|
|
mkdir -p /etc/containers/containers.conf.d
|
|
echo 'service_timeout=0' > /etc/containers/containers.conf.d/timeout.conf
|
|
```
|
|
|
|
To point k3d at the right Docker socket, create a symbolic link:
|
|
|
|
```bash
|
|
sudo ln -s /run/podman/podman.sock /var/run/docker.sock
|
|
# or install your system podman-docker if available
|
|
sudo k3d cluster create
|
|
```
|
|
|
|
Alternatively, set `DOCKER_HOST` when running k3d:
|
|
|
|
```bash
|
|
export DOCKER_HOST=unix:///run/podman/podman.sock
|
|
export DOCKER_SOCK=/run/podman/podman.sock
|
|
sudo --preserve-env=DOCKER_HOST --preserve-env=DOCKER_SOCK k3d cluster create
|
|
```
|
|
|
|
### Using rootless Podman
|
|
|
|
Ensure the Podman user socket is available:
|
|
|
|
```bash
|
|
systemctl --user enable --now podman.socket
|
|
# or podman system service --time=0 &
|
|
```
|
|
|
|
Set `DOCKER_HOST` when running k3d:
|
|
|
|
```bash
|
|
XDG_RUNTIME_DIR=${XDG_RUNTIME_DIR:-/run/user/$(id -u)}
|
|
export DOCKER_HOST=unix://$XDG_RUNTIME_DIR/podman/podman.sock
|
|
export DOCKER_SOCK=$XDG_RUNTIME_DIR/podman/podman.sock
|
|
k3d cluster create
|
|
```
|
|
|
|
#### Using cgroup (v2)
|
|
|
|
By default, a non-root user can only get memory controller and pids controller to be delegated.
|
|
|
|
To run properly we need to enable CPU, CPUSET, and I/O delegation
|
|
|
|
!!! note "Make sure you're running cgroup v2"
|
|
If `/sys/fs/cgroup/cgroup.controllers` is present on your system, you are using v2, otherwise you are using v1.
|
|
|
|
```bash
|
|
mkdir -p /etc/systemd/system/user@.service.d
|
|
cat > /etc/systemd/system/user@.service.d/delegate.conf <<EOF
|
|
[Service]
|
|
Delegate=cpu cpuset io memory pids
|
|
EOF
|
|
systemctl daemon-reload
|
|
```
|
|
|
|
Reference: [https://rootlesscontaine.rs/getting-started/common/cgroup2/#enabling-cpu-cpuset-and-io-delegation](https://rootlesscontaine.rs/getting-started/common/cgroup2/#enabling-cpu-cpuset-and-io-delegation)
|
|
|
|
### Using remote Podman
|
|
|
|
[Start Podman on the remote host](https://github.com/containers/podman/blob/main/docs/tutorials/remote_client.md), and then set `DOCKER_HOST` when running k3d:
|
|
|
|
```
|
|
export DOCKER_HOST=ssh://username@hostname
|
|
export DOCKER_SOCK=/run/user/1000/podman/podman.sock
|
|
k3d cluster create
|
|
```
|
|
|
|
### macOS
|
|
|
|
Initialize a podman machine if not done already
|
|
|
|
```
|
|
podman machine init
|
|
```
|
|
|
|
Or start an already existing podman machine
|
|
|
|
```
|
|
podman machine start
|
|
```
|
|
|
|
Grab connection details
|
|
> note: root connection details must be used
|
|
|
|
```
|
|
podman system connection ls
|
|
Name URI Identity Default
|
|
podman-machine-default ssh://core@localhost:53685/run/user/501/podman/podman.sock /Users/myusername/.ssh/podman-machine-default true
|
|
podman-machine-default-root ssh://root@localhost:53685/run/podman/podman.sock /Users/myusername/.ssh/podman-machine-default false
|
|
```
|
|
|
|
Edit your OpenSSH config file to specify the IdentityFile
|
|
|
|
```
|
|
vim ~/.ssh/config
|
|
|
|
Host localhost
|
|
IdentityFile /Users/myusername/.ssh/podman-machine-default
|
|
```
|
|
|
|
Export the docker environment variables referenced above and create the cluster
|
|
|
|
```
|
|
export DOCKER_HOST=ssh://root@localhost:53685
|
|
export DOCKER_SOCK=/run/podman/podman.sock
|
|
k3d cluster create
|
|
```
|
|
|
|
### Podman network
|
|
|
|
The default `podman` network has dns disabled. To allow k3d cluster nodes to communicate with dns a new network must be created.
|
|
```bash
|
|
podman network create k3d
|
|
podman network inspect k3d -f '{{ .DNSEnabled }}'
|
|
true
|
|
```
|
|
|
|
## Creating local registries
|
|
|
|
Because Podman does not have a default "bridge" network, you have to specify a network using the `--default-network` flag when creating a local registry:
|
|
|
|
```bash
|
|
k3d registry create --default-network podman mycluster-registry
|
|
```
|
|
|
|
To use this registry with a cluster, pass the `--registry-use` flag:
|
|
|
|
```bash
|
|
k3d cluster create --registry-use mycluster-registry mycluster
|
|
```
|
|
|
|
!!! note "Incompatibility with `--registry-create`"
|
|
Because `--registry-create` assumes the default network to be "bridge", avoid `--registry-create` when using Podman. Instead, always create a registry before creating a cluster.
|
|
|
|
!!! note "Missing cpuset cgroup controller"
|
|
If you experince an error regarding missing cpuset cgroup controller, ensure the user unit `xdg-document-portal.service` is disabled by running `systemctl --user stop xdg-document-portal.service`. See [this issue](https://github.com/systemd/systemd/issues/18293#issuecomment-831397578)
|
|
|
|
|