feat: add Podman support as drop-in replacement for Docker

Author: ZPascal

.github/workflows/kind-cats.yaml

@@ -31,7 +31,7 @@ jobs:
             --privileged \
             --pid host \
             -v /lib/modules:/lib/modules:ro \
-            alpine sh -c "sysctl -w fs.inotify.max_user_instances=512 && modprobe nfs && modprobe nfsd"
+            alpine sh -c "sysctl -w fs.inotify.max_user_instances=512 && sysctl -w net.ipv4.ip_unprivileged_port_start=80 && modprobe nfs && modprobe nfsd"
       - name: Install dependencies
         if: steps.check_changes.outputs.skip != 'true'
         run: |

.github/workflows/kind-smoke.yaml

@@ -42,10 +42,8 @@ jobs:
       - name: Set kernel settings
         if: steps.check_changes.outputs.skip != 'true'
         run: |
-          docker run --rm \
-            --privileged \
-            --pid host \
-            alpine sh -c "sysctl -w fs.inotify.max_user_instances=512"
+          sudo sysctl -w fs.inotify.max_user_instances=512
+          sudo sysctl -w net.ipv4.ip_unprivileged_port_start=80
       - name: Install dependencies
         if: steps.check_changes.outputs.skip != 'true'
         run: |
@@ -66,11 +64,14 @@ jobs:
       - name: Run make up (default)
         if: steps.check_changes.outputs.skip != 'true' && github.event_name == 'pull_request'
         run: make up
+        env:
+          CONTAINER_RUNTIME: docker
       - name: Run make up
         if: steps.check_changes.outputs.skip != 'true' && github.event_name != 'pull_request'
         run: make up
         env:
-          INSTALL_OPTIONAL_COMPONENTS: ${{ inputs.minimal }}  
+          CONTAINER_RUNTIME: docker
+          INSTALL_OPTIONAL_COMPONENTS: ${{ inputs.minimal }}
       - name: Login
         if: steps.check_changes.outputs.skip != 'true'
         run: make login
@@ -119,3 +120,140 @@ jobs:
         with:
           name: report.json
           path: ./cf-smoke-tests/report.json
+
+  kind-smoke-podman:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - name: Check if only ignored paths changed
+        id: check_changes
+        run: |
+          if [ "${{ github.event_name }}" == "pull_request" ]; then
+            CHANGED_FILES=$(git diff --name-only ${{ github.event.pull_request.base.sha }} ${{ github.sha }})
+            RELEVANT_FILES=$(echo "$CHANGED_FILES" | grep -v -E '.*\.Dockerfile|^releases/.*/files/|^\.github/|^docs/|\.md$|^renovate\.json$' || true)
+            if [ -z "$RELEVANT_FILES" ]; then
+              echo "Only ignored paths were changed. Skipping workflow."
+              echo "skip=true" >> $GITHUB_OUTPUT
+            else
+              echo "skip=false" >> $GITHUB_OUTPUT
+            fi
+          else
+            echo "skip=false" >> $GITHUB_OUTPUT
+          fi
+      - name: Set kernel settings
+        if: steps.check_changes.outputs.skip != 'true'
+        run: |
+          sudo sysctl -w fs.inotify.max_user_instances=512
+          sudo sysctl -w net.ipv4.ip_unprivileged_port_start=80
+          # Mount BPF filesystem on the host (needed by kindnet on some kernels)
+          sudo mount bpffs /sys/fs/bpf -t bpf -o nosuid,nodev,noexec,relatime || true
+      - name: Install podman-compose
+        if: steps.check_changes.outputs.skip != 'true'
+        run: |
+          sudo apt-get update -qq
+          sudo apt-get install -y podman-compose
+          # Ensure podman-compose is used instead of the docker-compose plugin shim
+          sudo ln -sf /usr/bin/podman-compose /usr/local/bin/podman-compose
+      - name: Install dependencies
+        if: steps.check_changes.outputs.skip != 'true'
+        run: |
+          mkdir -p $HOME/.local/bin && echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+          curl -L https://kind.sigs.k8s.io/dl/v${KIND_VERSION}/kind-linux-amd64 -o $HOME/.local/bin/kind
+          chmod +x $HOME/.local/bin/kind
+          curl -L https://github.com/helmfile/helmfile/releases/download/v${HELMFILE_VERSION}/helmfile_${HELMFILE_VERSION}_linux_amd64.tar.gz | tar -zx
+          mv helmfile $HOME/.local/bin/helmfile
+          curl -L "https://packages.cloudfoundry.org/stable?release=linux64-binary&version=${CF_CLI_VERSION}&source=github" | tar -zx
+          mv cf8 $HOME/.local/bin/cf
+        env:
+          # renovate: dataSource=github-releases depName=cloudfoundry/cli
+          CF_CLI_VERSION: "8.18.3"
+          # renovate: dataSource=github-releases depName=kubernetes-sigs/kind
+          KIND_VERSION: "0.31.0"
+          # renovate: dataSource=github-releases depName=helmfile/helmfile
+          HELMFILE_VERSION: "1.5.1"
+      - name: Run make up (default)
+        if: steps.check_changes.outputs.skip != 'true' && github.event_name == 'pull_request'
+        run: make up
+        env:
+          CONTAINER_RUNTIME: podman
+      - name: Run make up
+        if: steps.check_changes.outputs.skip != 'true' && github.event_name != 'pull_request'
+        run: make up
+        env:
+          CONTAINER_RUNTIME: podman
+          INSTALL_OPTIONAL_COMPONENTS: ${{ inputs.minimal }}
+      - name: Login
+        if: steps.check_changes.outputs.skip != 'true'
+        run: make login
+      - name: Init
+        if: steps.check_changes.outputs.skip != 'true'
+        run: make bootstrap-complete
+      - name: setup CF tests
+        if: steps.check_changes.outputs.skip != 'true'
+        uses: ./.github/actions/setup-cf-tests
+        with:
+          test-repo: cf-smoke-tests
+          test-branch: main
+          config-template: ./.github/smoke-config.tpl
+          config-output: ./.github/smoke-config.json
+      - name: run smoke test
+        if: steps.check_changes.outputs.skip != 'true'
+        env:
+          CONFIG: "${{ github.workspace }}/.github/smoke-config.json"
+          GINKGO_NO_COLOR: "true"
+        run: |
+          ./cf-smoke-tests/bin/test --no-color --github-output --timeout=30m --procs=4 --json-report report.json
+      - name: debug events
+        if: failure()
+        run: kubectl get events -A --sort-by='.lastTimestamp'
+      - name: debug cilium
+        if: failure()
+        run: |
+          echo "===== CILIUM PODS ====="
+          kubectl get pod -n kube-system -l k8s-app=cilium -o wide
+          echo "===== CILIUM AGENT LOGS (all pods) ====="
+          for pod in $(kubectl get pod -n kube-system -l k8s-app=cilium -o jsonpath='{.items[*].metadata.name}'); do
+            echo "--- $pod ---"
+            kubectl logs -n kube-system "$pod" --all-containers=true --previous 2>/dev/null || kubectl logs -n kube-system "$pod" --all-containers=true 2>/dev/null || true
+          done
+          echo "===== CILIUM OPERATOR LOGS ====="
+          kubectl logs -n kube-system -l name=cilium-operator --all-containers=true 2>/dev/null || true
+          echo "===== CILIUM STATUS ====="
+          kubectl exec -n kube-system $(kubectl get pod -n kube-system -l k8s-app=cilium -o jsonpath='{.items[0].metadata.name}' 2>/dev/null) -- cilium status 2>/dev/null || true
+      - name: debug pods
+        if: failure()
+        run: |
+          echo "===== CLOUD_CONTROLLER ====="
+          kubectl get pod -l app.kubernetes.io/name=cloud-controller -o wide
+          kubectl get pod -l app.kubernetes.io/name=cloud-controller -o jsonpath='{.status.containerStatuses[*].state}' | jq
+          kubectl logs -l app.kubernetes.io/name=cloud-controller --all-containers=true
+          echo "===== CC_WORKER ====="
+          kubectl get pod -l app.kubernetes.io/name=cc-worker -o wide
+          kubectl logs -l app.kubernetes.io/name=cc-worker
+          echo "===== CC_UPLOADER ====="
+          kubectl get pod -l app=cc-uploader -o wide
+          kubectl logs -l app=cc-uploader
+          echo "===== CC_DEPLOYMENT_UPDATER ====="
+          kubectl get pod -l app.kubernetes.io/name=cc-deployment-updater -o wide
+          kubectl logs -l app.kubernetes.io/name=cc-deployment-updater
+          echo "===== CC_WORKER_CLOCK ====="
+          kubectl get pod -l app.kubernetes.io/name=cc-worker-clock -o wide
+          kubectl logs -l app.kubernetes.io/name=cc-worker-clock
+          echo "===== CF_TCP_ROUTER ====="
+          kubectl get pod -n cf-system -l app=cf-tcp-router -o wide
+          kubectl get pod -n cf-system -l app=cf-tcp-router -o jsonpath='{.items[*].status.containerStatuses[*].state}' | jq 2>/dev/null || true
+          kubectl logs -n cf-system -l app=cf-tcp-router --all-containers=true 2>/dev/null || true
+          echo "===== ROUTING_API ====="
+          kubectl get pod -n cf-system -l app=routing-api -o wide
+          kubectl logs -n cf-system -l app=routing-api --all-containers=true 2>/dev/null || true
+      - uses: actions/upload-artifact@v7
+        if: always()
+        with:
+          name: report-podman.json
+          path: ./cf-smoke-tests/report.json
+

Makefile

@@ -3,15 +3,31 @@ TARGET_ARCH ?= $(if $(filter true,$(LOCAL)),$(shell go env GOARCH),amd64)
 # renovate: dataSource=github-releases depName=helmfile/helmfile
 HELMFILE_VERSION ?= "1.5.1"
 
+# Build all images for the local architecture (arm64 on Apple Silicon, amd64 elsewhere).
+# This ensures Go binaries like storage-cli are native – not run under Rosetta,
+# which causes 'taggedPointerPack' panics with high memory addresses.
+build:
+	@ . ./scripts/detect-runtime.sh; \
+	if [ "$$CONTAINER_RUNTIME" = "podman" ]; then \
+		echo "Building with Podman is not yet supported via docker-bake.hcl."; \
+		echo "Use 'podman build' manually with the Dockerfiles in releases/."; \
+		exit 1; \
+	fi; \
+	docker buildx bake --file docker-bake.hcl --set "*.platform=linux/$(TARGET_ARCH)" $(BAKE_TARGETS)
+
 init: temp/certs/ca.key temp/certs/ca.crt temp/certs/ssh_key temp/certs/ssh_key.pub temp/secrets.sh temp/secrets.env
 
 temp/certs/ca.key temp/certs/ca.crt temp/certs/ssh_key temp/certs/ssh_key.pub temp/secrets.sh temp/secrets.env:
 	@ ./scripts/init.sh
 
 install:
-	kind get kubeconfig --name cfk8s > temp/kubeconfig
-	docker run --rm --net=host --env-file temp/secrets.env \
+	@ . ./scripts/detect-runtime.sh; \
+	if [ "$$IS_PODMAN" = "true" ]; then export SKIP_CILIUM="true"; fi; \
+	kind get kubeconfig --name cfk8s > temp/kubeconfig; \
+	$$CONTAINER_RUNTIME run --rm --net=host --env-file temp/secrets.env \
 		--env INSTALL_OPTIONAL_COMPONENTS \
+		--env CILIUM_EXTRA_VALUES \
+		--env SKIP_CILIUM \
 		-v "$$PWD/temp/certs:/certs" -v "$$PWD/temp/kubeconfig:/helm/.kube/config:ro" -v "$$PWD:/wd" --workdir /wd ghcr.io/helmfile/helmfile:v$(HELMFILE_VERSION) helmfile sync
 
 login:
@@ -33,7 +49,7 @@ create-org:
 bootstrap: create-org
 	@ ./scripts/upload_buildpacks.sh
 
-bootstrap-complete: create-org 
+bootstrap-complete: create-org
 	@ ALL_BUILDPACKS=true ./scripts/upload_buildpacks.sh
 
 up: create-kind init install

README.md

@@ -6,13 +6,16 @@ This repository provides a simple and fast way to run Cloud Foundry locally. It
 
 The following tools need to be installed:
 
-- [`docker`](https://docs.docker.com/engine/install/)
+- [`docker`](https://docs.docker.com/engine/install/) or [`podman`](https://podman.io/docs/installation) (v4.0 or higher)
+- [`docker-compose`](https://docs.docker.com/compose/install) or [`podman-compose`](https://github.com/containers/podman-compose) (v1.0 or higher)
 - [`kind`](https://kind.sigs.k8s.io/docs/user/quick-start/#installing-from-release-binaries) (v0.31.0 or higher)
 - [`kubectl`](https://kubernetes.io/docs/tasks/tools/#kubectl) (v1.35.1 or higher)
 - `make`:
   - It should be already installed on MacOS and Linux.
   - For Windows installation see: <https://gnuwin32.sourceforge.net/packages/make.htm>
 
+The container runtime is auto-detected. Set `CONTAINER_RUNTIME=docker` or `CONTAINER_RUNTIME=podman` to override.
+
 ## Run the Installation
 
 ```bash
@@ -48,6 +51,40 @@ You can configure the installation by setting the environment variable `INSTALL_
 
 `bosh-dns`, `cf-tcp-router`, `credhub`, `loggregator`, `nfsbroker`, `policy-agent`, `policy-server`, `routing-api`, `service-discovery-controller`
 
+## Podman Support
+
+Podman is supported as a drop-in replacement for Docker. The runtime is detected automatically; no aliasing is required.
+
+### Linux (rootless Podman)
+
+Rootless Podman is fully supported on Linux. The following kernel settings must be applied before running `make up` — either manually or via your system's sysctl configuration:
+
+```bash
+sudo sysctl -w fs.inotify.max_user_instances=512
+sudo sysctl -w net.ipv4.ip_unprivileged_port_start=80
+```
+
+The first setting prevents inotify exhaustion under heavy workloads. The second allows the kind node containers and pods to bind privileged ports (80, 443, 2222) without root.
+
+### macOS / Windows (Podman Desktop)
+
+A Podman machine is created and configured automatically by `make up`. The machine is created in rootful mode with 4 CPUs, 8 GB RAM, and 60 GB disk. No manual configuration is needed.
+
+### Limitations
+
+- **CNI:** Cilium is skipped under rootless Podman (Linux CI / rootless desktop) because Cilium 1.18.x requires `CAP_NET_ADMIN` in the host user namespace, which rootless containers cannot provide. [kindnet](https://github.com/aojea/kindnet) is used instead, providing full pod-to-pod connectivity without eBPF privileges. Cilium network policies are therefore not enforced in this mode.
+- **Image builds:** `make build` (which uses `docker buildx bake`) is not supported with Podman. Use `podman build` directly with the Dockerfiles in `releases/` for local image development.
+
+## ARM / Apple Silicon Limitations
+
+The CF stack (`cflinuxfs4`) and all buildpacks are **x86-64 (amd64) only**. CF applications run inside `cflinuxfs4` rootfs containers, which are amd64 images and require x86 emulation on ARM hosts.
+
+- **Docker Desktop on Apple Silicon:** Enable Rosetta emulation (Settings → General → Use Rosetta for x86_64/amd64 emulation). This is the recommended and well-tested path.
+- **Podman on Apple Silicon:** The Podman machine is created with `--rootful` and runs under QEMU/Rosetta. Functional, but noticeably slower than Docker Desktop with Rosetta.
+- **Linux ARM64:** Not supported. The `cflinuxfs4` stack image and pre-compiled buildpack zip files are amd64-only. CF app staging and execution will fail on a native ARM64 host without kernel-level x86 emulation (`binfmt_misc` with QEMU).
+
+The CF platform components themselves (gorouter, diego, CAPI, etc.) are built for the local architecture (`make build` targets the native arch), so control-plane operations are native-speed on ARM. Only the **application workload layer** (buildpacks, cflinuxfs4 rootfs) is restricted to amd64.
+
 ## Unsupported Features
 
 - Routing isolation segments are not fully feature complete since this relies on more than one gateway which is not possible to realize in a local kind setup (see [FAQ](./docs/faq.md))
@@ -61,4 +98,4 @@ You can configure the installation by setting the environment variable `INSTALL_
 
 Please check our [contributing guidelines](/CONTRIBUTING.md).
 
-This project follows [Cloud Foundry Code of Conduct](https://www.cloudfoundry.org/code-of-conduct/).
+This project follows [Cloud Foundry Code of Conduct](https://www.cloudfoundry.org/code-of-conduct/)

assets/base-chart/templates/network-policy.yaml

@@ -1,3 +1,4 @@
+{{- if .Values.ciliumNetworkPolicies.enabled }}
 ---
 apiVersion: cilium.io/v2
 kind: CiliumClusterwideNetworkPolicy
@@ -85,3 +86,4 @@ spec:
         - ports:
             - port: "8443"
               protocol: TCP
+{{- end }}

assets/base-chart/values.yaml

@@ -2,3 +2,7 @@ caCert: ""
 caKey: ""
 tlsCert: ""
 tlsKey: ""
+# Set to false when Cilium is not installed (e.g. rootless Podman CI).
+# CiliumClusterwideNetworkPolicy CRDs won't exist without Cilium.
+ciliumNetworkPolicies:
+  enabled: true

assets/values/cilium-podman.yaml

@@ -0,0 +1,62 @@
+ipam:
+  mode: kubernetes
+envoy:
+  enabled: false
+# kube-proxy replacement via eBPF requires privileges not available in
+# rootless Podman containers (used in CI). Fall back to standard kube-proxy mode.
+kubeProxyReplacement: false
+k8sServiceHost: cfk8s-control-plane
+k8sServicePort: 6443
+operator:
+  replicas: 1
+# Use VXLAN tunnel instead of native routing (required without elevated privileges)
+routingMode: tunnel
+tunnelProtocol: vxlan
+# Disable all eBPF features that require CAP_BPF / kernel privileges
+# not available inside rootless Podman-spawned KinD nodes.
+bpf:
+  masquerade: false
+  # Disable automatic BPF filesystem mounting – the host already has bpffs mounted
+  # at /sys/fs/bpf and the init-container mount syscall fails inside Podman containers.
+  autoMount:
+    enabled: false
+  preallocateMaps: false
+hostServices:
+  enabled: false
+nodePort:
+  enabled: false
+socketLB:
+  enabled: false
+externalIPs:
+  enabled: false
+# Disable Hubble to reduce resource usage and avoid additional eBPF probes
+hubble:
+  enabled: false
+# Tell Cilium where the cgroup root is (since we can't auto-mount)
+cgroup:
+  autoMount:
+    enabled: false
+  hostRoot: /sys/fs/cgroup
+# Disable bandwidth manager (requires eBPF)
+bandwidthManager:
+  enabled: false
+localRedirectPolicy: false
+# Use iptables for masquerading instead of eBPF
+enableIPv4Masquerade: true
+# Disable DSR which requires eBPF
+loadBalancer:
+  mode: snat
+# Disable sysctl override file creation – Cilium tries to write
+# /etc/sysctl.d/99-zzz-override_cilium.conf which fails in rootless
+# Podman KinD nodes that lack CAP_SYS_ADMIN / write access to /etc/sysctl.d/.
+sysctlfix:
+  enabled: false
+# Disable host firewall – requires loading BPF programs into cgroup hooks
+# (CGroupSock, CGroupSockAddr, etc.) which fail with EPERM in rootless Podman.
+hostFirewall:
+  enabled: false
+# Disable session affinity – it triggers CGroupSock BPF helper probing
+# (FnSetRetval) which fails with EPERM in rootless Podman KinD nodes.
+sessionAffinity: false
+# Disable EnvoyConfig CRD processing to avoid additional BPF probes
+enableEnvoyConfig: false