Migrate from Docker to Podman on macOS

Published on 05/09/2021

8 min read

In category

development

Docker announced the license and subscription plan changes for the Desktop Docker apps. Now at the latest, one can look for alternatives that have been around for a while. This article covers the replacement of Desktop Docker with podman on macOS.

Overview

Overview
Replace toolset
Action
Remove Desktop Docker
Troubleshooting
Summary
References

Docker announced changes and introduction of special plans and subscription for the usage of Desktop Docker. This articles covers the activities to replace Desktop Docker on macOS with podman. Podman is a "a daemonless container engine for developing, managing, and running OCI Containers on your Linux System.". With the virtual machine support in Podman is it also possible to use it on macOS.

Replace toolset

Podman can be installed using brew:

brew install podman

podman machine init

Downloading VM image: fedora-coreos-34.20210821.1.1-qemu.x86_64.qcow2.xz: done
Extracting compressed file

podman machine start

INFO[0000] waiting for clients...
INFO[0000] listening tcp://0.0.0.0:7777
INFO[0000] new connection from  to /var/folders/6z/zxyfpch573122j4nzs9bqfvm0000gn/T/podman/qemu_podman-machine-default.sock
Waiting for VM ...
qemu-system-x86_64: warning: host doesn't support requested feature: CPUID.80000001H:ECX.svm [bit 2]

After the (re)start of the machine, which will use a Fedora VM is the environment available to execute and work with podman.

podman info

host:
  arch: amd64
  buildahVersion: 1.22.3
  cgroupControllers: []
  cgroupManager: systemd
  cgroupVersion: v2
  conmon:
    package: conmon-2.0.29-2.fc34.x86_64
    path: /usr/bin/conmon
...
version:
  APIVersion: 3.3.0
  Built: 1629488174
  BuiltTime: Fri Aug 20 19:36:14 2021
  GitCommit: ""
  GoVersion: go1.16.6
  OsArch: linux/amd64
  Version: 3.3.0

In the processes is the virtual machine - with qemu visible:

ps aux | grep qemu

xxx         78989   1.5  1.6  6621676 274412 s007  S     6:54PM   0:26.64 /usr/local/bin/qemu-system-x86_64 -m 2048 -smp 1 -fw_cfg name=opt/com.coreos/config,file=/Users/xxx/.config/containers/podman/machine/qemu/podman-machine-default.ign -qmp unix://var/folders/6z/zxyfpch573122j4nzs9bqfvm0000gn/T/podman/qmp_podman-machine-default.sock,server=on,wait=off -netdev socket,id=vlan,fd=3 -device virtio-net-pci,netdev=vlan,mac=5a:94:ef:e4:0c:ee -device virtio-serial -chardev socket,path=/var/folders/6z/zxyfpch573122j4nzs9bqfvm0000gn/T/podman/podman-machine-default_ready.sock,server=on,wait=off,id=podman-machine-default_ready -device virtserialport,chardev=podman-machine-default_ready,name=org.fedoraproject.port.0 -machine q35,accel=hvf:tcg -drive if=virtio,file=/Users/xxx/.local/share/containers/podman/machine/qemu/podman-machine-default_fedora-coreos-34.20210821.1.1-qemu.x86_64.qcow2 -display none

Action

Most of the commands and parameters are still the same, replace "only" docker with podman, e.g. to

build
check the existing images
run a container
see which container/processes are running (ps)

podman build -f Dockerfile-custom -t tekton-101-podman:v1
STEP 1/7: FROM node:10
Resolving "node" using unqualified-search registries (/etc/containers/registries.conf)
Trying to pull registry.fedoraproject.org/node:10...
Trying to pull registry.access.redhat.com/node:10...
Trying to pull docker.io/library/node:10...
Getting image source signatures
Copying blob sha256:b800e94e7303e276b8fb4911a40bfe28f46180d997022c69bf1ee02fb7b86721
...
COMMIT tekton-101-podman:v1
--> 8edf0877768
Successfully tagged localhost/tekton-101-podman:v1
8edf0877768ed81b6b65ee0dfe9593d1f6ce49eb34f2bbe82544147f24af5150

podman images
REPOSITORY                   TAG         IMAGE ID      CREATED        SIZE
localhost/tekton-101-podman  v1          8edf0877768e  2 minutes ago  959 MB
docker.io/library/node       10          28dca6642db8  4 months ago   940 MB


podman run --rm -p 49160:5000 -d -e TEKTON_101_ENV_NAME=App1 -e TEKTON_101_ENV_EXAMPLE=Version-0.1 -e TEKTON_101_ENV_DELAY=1 --name tekton-test tekton-101-podman:v1
d30d314dc53426657da200e35dd423a1c10ab732ed89ceaff4240b91185d87c0

podman ps
CONTAINER ID  IMAGE                           COMMAND      CREATED             STATUS                 PORTS                    NAMES
d30d314dc534  localhost/tekton-101-podman:v1  node app.js  12 seconds ago      Up 11 seconds ago      0.0.0.0:49160->5000/tcp  tekton-test


curl localhost:49160
[App1]: Hello from NodeJS Playground! TEKTON_101_ENV_EXAMPLE=Version-0.1

Environment variables:
HOSTNAME=ca865e1cdd2d


Request Headers:
HOST=localhost:43031
USER-AGENT=curl/7.64.1
ACCEPT=*/*

Also the command to enter a container or to retrieve the logs are the same:

podman exec -ti tekton-test /bin/sh
# ls
Dockerfile-custom  README.adoc	dc.yaml       helm-ocp	k8s-compact   ocp-compact  openshift-2	      package.json  route.yaml	svc.yaml
LICENSE		   app.js	devfile.yaml  k8s	node_modules  openshift    package-lock.json  pipelines     static
#

podman logs -f tekton-test
App.Version: undefined
--------------------------------------------------------------------
ENV.TEKTON_101: App1
ENV.TEKTON_101_ENV_EXAMPLE: Version-0.1
ENV.TEKTON_101_ENV_DELAY: 1
ENV.TEKTON_101_ENV_BACKEND_SERVICE:
ENV.TEKTON_101_ENV_BACKEND_SERVICE_DELAY: 0
ENV.TEKTON_101_ENV_TRACING_ENABLED: false
--------------------------------------------------------------------
Node app is running at http://localhost:5000
--------------------------------------------------------------------
user-agent: curl/7.52.1

Other helpful commands

podman rm -f tekton-test2 delete (running) container
podman tag tekton-101-podman:v1 tekton-101-podman:v1.alpha re-tag existing image and tag

Remove Desktop Docker

Select in the Desktop Docker menu

Troubleshoot
Press Clean / Purge data
wait for completion
Again in Troubleshoot press Reset to factory details
Again in Troubleshoot press Uninstall
in Finder > Applications: search for Docker and Move to Bin
Remove the user-specific docker directory rm -rf ~/.docker

Troubleshooting

Invalid format in config.json

podman build -f Dockerfile-custom -t tekton-101-podman:v1
Error: failed to parse query parameter 'X-Registry-Config': "n/a": error storing credentials in temporary auth file (server: "https://index.docker.io/v1/", user: ""): key https://index.docker.io/v1/ contains http[s]:// prefix

Fix/remove the json object in .docker/config.json for the given key (here: https://index.docker.io/v1/).

Short-names

Error: error creating build container: short-name resolution enforced but cannot prompt without a TTY

Docker prefixed the image names in Dockerfiles with docker.io or docker.io/library/ if they relative/short-names. From security purposes is this in podman not the preferred way.

If this advisable and secured configuration is not wanted and smooth migration, with similar weak security settings as with Docker, use the following approach to fix

Change the short-name-mode to permissive in the machine instance of podman (by default: Fedora), set also the registries which will be searched to find the image (parameter unqualified-search-registries) For more detailed information see the following article

podman machine ssh

less /etc/containers/registries.conf | grep 'unqualified-search-registries\|short-name-mode'
unqualified-search-registries = ["registry.fedoraproject.org", "registry.access.redhat.com", "quay.io"]
short-name-mode="enforcing"

sudo vi /etc/containers/registries.conf

less /etc/containers/registries.conf | grep 'unqualified-search-registries\|short-name-mode'
unqualified-search-registries = ["registry.fedoraproject.org", "registry.access.redhat.com", "docker.io", "quay.io"]
short-name-mode="permissive"

Alternatively - and more secured way - use full qualified names in FROM of a Dockerfile.

FROM docker.io/library/node:10

# ...

Port-forwarding not working

podman run --rm -p 49160:5000 ... --name tekton-test tekton-101-podman:v1

podman ps
CONTAINER ID  IMAGE                           COMMAND      CREATED        STATUS            PORTS                    NAMES
d30d314dc534  localhost/tekton-101-podman:v1  node app.js  8 minutes ago  Up 8 minutes ago  0.0.0.0:49160->5000/tcp  tekton-test

curl localhost:49160
curl: (7) Failed to connect to localhost port 49160: Connection refused

Is currently a bug in podman 3.3.1 and will be probably fixed i 3.3.2. Workaround is e.g to enhance locally ~/.config/containers/containers.conf and set rootless_networking = "cni"

less ~/.config/containers/containers.conf
[containers]
  log_size_max = -1
  pids_limit = 2048
  userns_size = 65536
  rootless_networking = "cni"
  ...

But this still not work

podman run --rm -p 49160:5000 -d -e TEKTON_101_ENV_NAME=App1 -e TEKTON_101_ENV_EXAMPLE=Version-0.1 -e TEKTON_101_ENV_DELAY=1 --name tekton-test2 tekton-101-podman:v1
Error: error configuring network namespace for container a107005917b216de76ec20a8e64ca39041ba6140c224a8bb51150eea2729eefc: error adding pod tekton-test2_tekton-test2 to CNI network "podman": something went wrong with the request

It seems that the cni plugin with ports assignment does not work.

Alternative workaround is to use -P to publish all ports without specifying dedicated ports

podman run --rm -P -d -e TEKTON_101_ENV_NAME=App1 -e TEKTON_101_ENV_EXAMPLE=Version-0.1 -e TEKTON_101_ENV_DELAY=1 --name tekton-test2 tekton-101-podman:v1
ca865e1cdd2d2df928890455927a4fa97d4189e9f8c895c10f069eccd595d559

podman ps
CONTAINER ID  IMAGE                           COMMAND      CREATED         STATUS             PORTS                    NAMES
ca865e1cdd2d  localhost/tekton-101-podman:v1  node app.js  15 seconds ago  Up 15 seconds ago  0.0.0.0:43031->5000/tcp  tekton-test2

curl localhost:43031
[App1]: Hello from NodeJS Playground! TEKTON_101_ENV_EXAMPLE=Version-0.1

Environment variables:
HOSTNAME=ca865e1cdd2d


Request Headers:
HOST=localhost:43031
USER-AGENT=curl/7.64.1
ACCEPT=*/*

Summary

The replacement of Docker and Desktop Docker on a macOS through podman is very straightforward with few minor modifications. The transition is also simplified as most of the commands and parameters are still supported and applicable in the same way.

References

Podman - Get started