---
title: "Apple's Native Container Runtime & Kubernetes on Mac: Complete DevOps Guide to container cluster"
description: "Hands-on DevOps guide to Apple's open-source container runtime and experimental Kubernetes cluster support on Apple Silicon: micro-VM architecture, exact CLI commands, Cilium CNI setup, --shared-image-store security trade-offs, and comparison vs Docker Desktop and OrbStack."
author: Aleksei Aleinikov
date: 2026-11-19
lang: en
tags: [apple container kubernetes, container cluster create, apple container vs docker desktop, kubernetes on mac apple silicon, apple container cilium, shared-image-store, virtualization framework kubernetes]
canonical: https://www.alekseialeinikov.com/en/blog/topics/devops/apple-container-kubernetes-mac-cluster-guide
source: alekseialeinikov.com
---

# Apple's Native Container Runtime & Kubernetes on Mac: Complete DevOps Guide to container cluster

Apple's open-source **`apple/container`** project started as a minimal Swift-based runtime for running Linux containers as lightweight micro-VMs on Apple Silicon. With the addition of **`container cluster`** (originally introduced as `container k8s` and promoted to `container cluster` in release `1.6.1`), Apple quietly shipped native, zero-Docker-Desktop Kubernetes clusters on macOS.

Most social posts stop at *"Apple killed Docker Desktop."* For DevOps and Platform Engineers, the real story is in the engineering details: **how the micro-VM node topology works, how heterogeneous worker sizing and Cilium CNI work, why `--shared-image-store` carries a sharp security warning from Apple itself, and where experimental limitations still bite.**

![Apple Container & Kubernetes on Mac editorial cover: machined aluminum plinth with hovering translucent container micro-VM cubes and cobalt-blue Kubernetes prism in bright studio daylight.](https://media.alekseialeinikov.com/devops/e91b4c7a2d5f/cover-1200.ff9f8c7bf4b87c6e.webp)

> [!NOTE]
> **Verified against upstream source.** All CLI commands, flags (`container cluster`, `--workers`, `--shared-image-store`, `--cni`, `--node-image`), default resource formulas and security warnings in this guide come directly from [Apple's official `apple/container` repository](https://github.com/apple/container/blob/main/docs/cluster.md) and release notes (current release `1.7.1`).

> [!KEY]
> **The short DevOps verdict.** `container cluster` is fast, native, and refreshingly clean for **ephemeral multi-node Kubernetes testing**, custom CNI labs (like Cilium), and multi-version `kindest/node` validation on **Apple Silicon + macOS 26+**. Just don't treat it as a stateful pet VM yet: **stopped clusters cannot be resumed** and must be recreated, and `--shared-image-store` should stay off if you test untrusted manifests.

## How Apple's Architecture Differs from Docker Desktop and Lima

Traditional Mac container tools (Docker Desktop, Colima, Lima, Rancher Desktop) boot **one large Linux VM** and run `containerd`/Docker inside it. If you spin up a 3-node `kind` cluster there, you are nesting Kubernetes nodes as containers *inside* that single shared VM.

`apple/container` flips that model using macOS's native **`Virtualization.framework`** and Apple's Swift **`Containerization`** package (the same micro-VM isolation philosophy we compared in [microVMs: Firecracker vs gVisor](https://www.alekseialeinikov.com/en/blog/topics/devops/microvms-firecracker-vs-gvisor-secure-workloads-2026)):

![Architecture comparison between traditional single-VM Docker Desktop + kind and Apple's native apple/container cluster where each Kubernetes control-plane and worker node runs as its own isolated Linux micro-VM on macOS Virtualization.framework.](https://media.alekseialeinikov.com/devops/e91b4c7a2d5f/apple-container-k8s-architecture-1200.6594b63de3eaf9f8.webp)

- **Micro-VM per node (`vminitd`, zero idle VM tax):** Each Kubernetes node (control plane and every worker) boots as an isolated lightweight Linux micro-VM directly on `Virtualization.framework` using Apple's minimal Swift init (`vminitd`) — no QEMU, no Lima wrapper, no shared kernel between nodes, and no monolithic background VM holding 2–4 GB of RAM idle when nothing is running.
- **Hidden from accidental `container stop`:** Although each node is technically a container, `container list` hides cluster nodes even with `--all`. Running `container stop` or `container delete` against a cluster node returns "not found" so you don't break your control plane by mistake. (Read-only debugging tools like `container logs`, `container exec`, `container inspect` and `container stats` still work on node names.)
- **Standard `kindest/node` compatibility:** By default, clusters boot `kindest/node:v1.35.5` and automatically merge credentials into `~/.kube/config`, so `kubectl`, `helm`, and `k9s` work immediately.

## Prerequisites and Setup (Commands That Actually Work)

Apple explicitly scopes `apple/container` to **Apple Silicon Macs running macOS 26 or later** — Intel Macs and older macOS releases are unsupported because the runtime depends on macOS 26 virtualization and networking APIs.

### 1. Install and start the runtime

Download the signed `.pkg` installer from the [apple/container releases page](https://github.com/apple/container/releases), install it under `/usr/local`, and start the system service:

```bash
container system start
```

### 2. Spin up your first cluster

```bash
# Create the default cluster (named "cluster-dev")
container cluster create

# Inspect cluster status (add --nodes for per-node rows)
container cluster list --nodes

# Verify kubectl context auto-configuration
kubectl --context cluster-dev get nodes -o wide
```

By default, a single node acts as both control plane and worker, allocated **1/4 of your host CPUs (minimum 2)** and **1/4 of your host memory (minimum 2GB)**.

### 3. Multi-node clusters with custom heterogeneous workers

This is where `container cluster` shines for platform engineers testing real scheduling rules, taints, and affinity. As soon as `--workers` is greater than `0`, **`apple/container` automatically taints the control-plane node** so application pods only schedule onto worker nodes:

```bash
# Control plane (2 vCPU, 4GB) + 2 beefy workers + 1 small worker
container cluster create --name staging \
  --cpus 2 --memory 4g \
  --workers count=2,cpus=4,memory=8g \
  --workers count=1,cpus=2,memory=4g

# Verify taints and node sizing
kubectl --context staging get nodes -o wide

# Debug a cluster node directly (read-only/exec commands work; stop/delete are blocked)
container stats staging-worker-1
container logs staging-control-plane
```

Worker nodes are named `<cluster-name>-worker-<n>` and inherit the control plane's `--node-image`. For throwaway CI-style runs on your laptop, add `--rm` (`container cluster create --name temp --rm`) so node containers auto-remove when stopped. Apple also publishes a reference three-tier Gateway API setup in its official [`container-cluster-gateway` example](https://github.com/apple/container-examples/tree/main/container-cluster-gateway).

### 4. Side-by-side Kubernetes version testing

Need to validate a Helm chart or CRD deprecation across Kubernetes minor versions? Override `--node-image`:

```bash
container cluster create --name k8s-134 --node-image docker.io/kindest/node:v1.34.11
container cluster create --name k8s-135 --node-image docker.io/kindest/node:v1.35.5

kubectl config get-contexts
```

## Replacing kindnet with Cilium CNI

By default, `container cluster` installs **kindnet** for pod networking. If you run [Cilium in production](https://www.alekseialeinikov.com/en/blog/topics/devops/cilium-vs-calico-kubernetes-cni) and want eBPF NetworkPolicy or Hubble parity locally, you can pass any plain Kubernetes YAML manifest via `--cni`.

**Important catch:** `--cni` expects a rendered YAML file (not a Helm chart), and Cilium's default `cluster-pool` IPAM (`10.0.0.0/8`) collides with kubeadm's pod/service CIDRs. Render the template with `ipam.mode=kubernetes` first:

```bash
helm repo add cilium https://helm.cilium.io/
helm repo update

helm template cilium cilium/cilium \
  --version 1.20.1 \
  --namespace kube-system \
  --set ipam.mode=kubernetes > cilium.yaml

container cluster create --name cilium-lab --cni ./cilium.yaml
kubectl --context cilium-lab get pods -n kube-system
```

## The `--shared-image-store` Security Trap (Read Before Using)

One of the headline conveniences in `apple/container` is running images you built locally (`container build`) inside Kubernetes without pushing them to Docker Hub, GHCR, or a local registry.

To enable that, you pass `--shared-image-store` at creation time:

```bash
container cluster create --name dev --shared-image-store
container build -t my-service:dev .
kubectl --context dev run my-service --image=my-service:dev
```

![Security and pull-policy flow for --shared-image-store in apple/container: default mode isolates nodes via registry pulls, while shared-image-store exposes every local private image to privileged or hostPath pods and overrides registry tags regardless of imagePullSecrets.](https://media.alekseialeinikov.com/devops/e91b4c7a2d5f/apple-container-shared-store-security-1200.6c4237c4dfba67de.webp)

Notice **sharing is OFF by default** for a very good reason. Apple's own documentation highlights two subtle security and correctness traps when `--shared-image-store` is enabled:

1. **All local private images become readable by root on any node:** Any privileged pod or pod with a `hostPath` mount can read **every image** in your Mac's local `container` image store — including private images you previously pulled using your corporate registry credentials.
2. **Local tags silently shadow registry pulls:** If your local store has an image matching a pod's image name, the node uses the local image **before** checking the registry — regardless of `imagePullPolicy` and **without validating `imagePullSecrets`**.
3. **Tag reuse pitfall:** If you rebuild `my-service:dev` with the same tag, existing nodes keep their cached copy under `imagePullPolicy: IfNotPresent`. Bump the tag or set `imagePullPolicy: Always`.

**Rule of thumb:** Keep `--shared-image-store` enabled only in trusted inner-loop dev clusters where you control every manifest. When testing third-party Helm charts or untrusted workloads, omit it and pull from a registry.

## Honest Comparison: `apple/container` vs OrbStack vs Docker Desktop + kind vs Lima

How does `apple/container` stack up against the tools DevOps teams already use on macOS (or rootless alternatives like [Podman](https://www.alekseialeinikov.com/en/blog/topics/devops/podman-2026-rootless-daemonless-containers-without-docker))?

| Dimension | **`apple/container` (`cluster`)** | **OrbStack** | **Docker Desktop + `kind`** | **Lima / Colima** |
|---|---|---|---|---|
| **Isolation Model** | Micro-VM per Kubernetes node (`Virtualization.framework`) | Single ultra-fast shared Linux VM | Single heavy Linux VM + nested `kind` containers | Single Linux VM (VZ or QEMU) |
| **OS Requirement** | **Apple Silicon + macOS 26+** | macOS 12.3+ (Apple Silicon & Intel) | macOS 12+ | macOS 12+ |
| **Multi-node & Sizing** | Native `--workers count=...,cpus=...,memory=...` + auto-taint | Single-node built-in K8s | Multi-node via `kind` config | Single VM (multi-node via `kind`) |
| **Custom CNI (Cilium)** | Native `--cni ./cilium.yaml` | Limited built-in K8s customization | Supported via `kind` (`disableDefaultCNI`) | Supported via `k3s` / `kind` |
| **Stop / Resume Persistence** | **No** (stopped cluster must be deleted & recreated) | **Yes** (instant pause/resume) | **Yes** (cluster survives restarts) | **Yes** |
| **License & Maturity** | Open Source (Apache 2.0) · **Experimental** | Commercial (free for personal use) · Mature | Commercial (paid for teams >250 / >\$10M) · Mature | Open Source (Apache 2.0 / MIT) · Mature |

![DevOps comparison matrix for local Kubernetes on macOS: apple/container cluster vs OrbStack, Docker Desktop + kind, and Lima/Colima across isolation, multi-node support, custom CNI, cluster persistence, and licensing.](https://media.alekseialeinikov.com/devops/e91b4c7a2d5f/apple-container-k8s-comparison-1200.7290b6f45146df66.webp)

## Real-World Limitations to Know Before Migrating

Before deleting Docker Desktop or OrbStack across your engineering team, factor in four hard boundaries:

1. **No cluster pause/resume yet:** If you run `container system stop`, reboot, or your control-plane node stops, you cannot restart the cluster in place. You must run `container cluster delete` and `container cluster create` again — and `--rm` clusters leave a `stopped` stub entry until deleted or overwritten.
2. **Experimental CLI stability:** Apple explicitly warns that features marked *experimental* (specifically `container cluster`) may introduce breaking CLI changes between releases (as already happened when `container k8s` was renamed to `container cluster` in `1.6.1`).
3. **macOS 26+ hard floor:** Mixed engineering teams with Intel Macs or developers waiting to upgrade macOS cannot standardize on `apple/container` yet.
4. **No managed LoadBalancer / Ingress controller (or native Compose) out of the box:** Like bare `kind`, you get a clean cluster and `kindnet` (or your `--cni`), so exposing services beyond `kubectl port-forward` requires installing Envoy Gateway, ingress-nginx, or community wrappers like `kiac`. Similarly, `apple/container` has no built-in `docker compose` equivalent yet (requiring third-party wrappers like `container-compose` outside Kubernetes).

## What Developers Actually Report in Practice

Across **Reddit (`r/MacOS`, `r/kubernetes`, `r/docker`)**, **Dev.to**, and **Substack** engineering write-ups, early adopters of `apple/container` consistently highlight the same split between excitement and rough edges:

- **What engineers praise:** Leaving behind Docker Desktop licensing and heavy idle VM overhead, fast micro-VM boot times on Apple Silicon, clean node-level kernel isolation that feels closer to production clusters, and how quickly community tooling like **`kiac`** (multi-node k3s/kubeadm with Cilium eBPF and built-in LoadBalancer) and **`rke2-silicon`** grew on top of it.
- **What frustrates early adopters:** Host-to-container networking and volume-mount quirks compared to OrbStack's seamless Mac integration, the inability to pause and resume a cluster across reboots, and breaking CLI changes while `cluster` remains experimental (such as `container k8s` renaming to `container cluster` in `1.6.1`).

## When You Should Adopt It Now

- **Use `apple/container cluster` today** for ephemeral CI-like validation on your Mac: testing Kubernetes upgrades (`v1.34` vs `v1.35`), debugging multi-node scheduling/taints, experimenting with Cilium manifests, and fast inner-loop builds when you don't want Docker Desktop licensing overhead.
- **Stick with OrbStack or Colima + `kind`** if you keep stateful local Kubernetes stacks running across reboots, need Intel/older macOS support, or rely on Compose + K8s workflows that can't tolerate experimental CLI churn.
