Skip to content

Commit d08a20a

Browse files
AkihiroSudaAkihiroSuda
committed
website: enhance container examples
Signed-off-by: Akihiro Suda <akihiro.suda.cz@hco.ntt.co.jp>
1 parent 66cf250 commit d08a20a

File tree

8 files changed

+325
-8
lines changed

8 files changed

+325
-8
lines changed

‎website/content/en/docs/_index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ Lima launches Linux virtual machines with automatic file sharing and port forwar
1111

1212
✅ Automatic port forwarding
1313

14-
✅ Built-in support for [containerd](https://containerd.io) ([Other container engines can be used too](./templates))
14+
✅ Built-in support for [containerd](https://containerd.io) ([Other container engines can be used too]({{< ref "/docs/examples/containers" >}}))
1515

1616
✅ Intel on Intel
1717

‎website/content/en/docs/examples/_index.md‎

Lines changed: 3 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -54,20 +54,16 @@ docker run -d --name nginx -p 127.0.0.1:8080:80 nginx:alpine
5454
```bash
5555
limactl start template://k8s
5656
export KUBECONFIG=$(limactl list k8s --format 'unix://{{.Dir}}/copied-from-guest/kubeconfig.yaml')
57-
kubectl apply -f ...
57+
kubectl create deployment nginx --image nginx:alpine
58+
kubectl create service nodeport nginx --node-port=31080 --tcp=80:80
5859
```
5960
{{% /tab %}}
6061

6162
{{< /tabpane >}}
6263

6364
- <http://127.0.0.1:8080> is accessible from the host, as well as from the VM.
6465

65-
- For the usage of containerd and nerdctl (contaiNERD ctl), visit <https://github.com/containerd/containerd>
66-
and <https://github.com/containerd/nerdctl>.
67-
68-
- If you have installed Lima by `make install`, the `nerdctl.lima` command is also available as `nerdctl`.
69-
If you have installed Lima by `brew install lima`, you may make an alias (or a symlink) by yourself:
70-
`alias nerdctl=nerdctl.lima`
66+
- See more [examples](./containers/).
7167

7268
## Advanced configuration
7369

‎website/content/en/docs/examples/containers/_index.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
title: Containers
3+
weight: 3
4+
---
5+
6+
Lima was designed to facilitate running containers inside a virtual machine, with automatic
7+
[filesystem sharing](../../config/mount.md) and [port forwarding](../../config/port.md).
8+
9+
The original motivation of Lima was to promote [containerd](./containerd) for macOS users, however,
10+
the current version of Lima supports other container engines too, and does not depend on macOS hosts.

‎website/content/en/docs/examples/containers/apptainer.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
title: Apptainer
3+
weight: 90
4+
---
5+
6+
{{< tabpane text=true >}}
7+
{{% tab header="Rootless" %}}
8+
```bash
9+
limactl start template://apptainer
10+
limactl shell apptainer apptainer run -u -B $HOME:$HOME docker://alpine
11+
```
12+
{{% /tab %}}
13+
{{% tab header="Rootful" %}}
14+
```bash
15+
limactl start template://apptainer-rootful
16+
limactl shell apptainer-rootful apptainer run -u -B $HOME:$HOME docker://alpine
17+
```
18+
{{% /tab %}}
19+
{{< /tabpane >}}
20+
21+
See also <https://apptainer.org/docs/user/latest/>.

‎website/content/en/docs/examples/containers/containerd.md‎

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
---
2+
title: containerd (Default)
3+
weight: 1
4+
---
5+
6+
Lima comes with the built-in integration for [containerd](https://containerd.io) and
7+
[nerdctl](https://github.com/containerd/nerdctl) (contaiNERD CTL):
8+
9+
{{< tabpane text=true >}}
10+
{{% tab header="Rootless" %}}
11+
```bash
12+
lima nerdctl run -d --name nginx -p 127.0.0.1:8080:80 nginx:alpine
13+
```
14+
15+
or
16+
17+
```bash
18+
nerdctl.lima run -d --name nginx -p 127.0.0.1:8080:80 nginx:alpine
19+
```
20+
21+
22+
- If you have installed Lima by [`make install`](../../installation/source.md), the `nerdctl.lima` command is also available as `nerdctl`.
23+
- If you have installed Lima by [`brew install lima`](../../installation/_index.md), you may make an alias (or a symlink) by yourself:
24+
`alias nerdctl=nerdctl.lima`
25+
{{% /tab %}}
26+
{{% tab header="Rootful" %}}
27+
```bash
28+
limactl start --containerd=system
29+
lima sudo nerdctl run -d --name nginx -p 127.0.0.1:8080:80 nginx:alpine
30+
```
31+
{{% /tab %}}
32+
{{< /tabpane >}}
33+
34+
The usage of the `nerdctl` command is similar to the `docker` command. See the [Command Reference](https://github.com/containerd/nerdctl/blob/main/docs/command-reference.md).
35+
36+
## Advanced features
37+
### Enhanced supply chain security with gomodjail
38+
39+
[gomodjail](https://github.com/AkihiroSuda/gomodjail) is an experimental library sandbox for Go modules.
40+
41+
gomodjail imposes syscall restrictions on a specific set of Go modules, so as to mitigate their potential vulnerabilities and supply chain attack vectors.
42+
A restricted module is hindered to access files and execute commands.
43+
44+
gomodjail can be enabled for nerdctl by using the `nerdctl.gomodjail` binary.
45+
46+
```bash
47+
lima nerdctl.gomodjail ...
48+
```
49+
50+
For the gomodjail policy applied to `nerdctl.gomodjail`, see <https://github.com/containerd/nerdctl/blob/main/go.mod>.
51+
52+
### Accelerating rootless networking with bypass4netns
53+
54+
[bypass4netns](https://github.com/rootless-containers/bypass4netns) is an experimental accelerator for rootless networking.
55+
56+
On macOS hosts, it is highly recommended to use the [vzNAT](../../config/network/vmnet.md#vznat) networking in conjunction
57+
to reduce the overhead of Lima's user-mode networking:
58+
59+
```bash
60+
limactl start --network vzNAT
61+
```
62+
63+
To enable bypass4netns, the daemon process (`bypass4netnsd`) has to be installed in the VM as follows:
64+
<!-- TODO: install by default -->
65+
```bash
66+
lima containerd-rootless-setuptool.sh install-bypass4netnsd
67+
```
68+
69+
Then run a container with an annotation `nerdctl/bypass4netns=true`:
70+
71+
```bash
72+
# 192.168.64.1 is the IP address of the "bridge100" interface on the macOS host
73+
lima nerdctl run --annotation nerdctl/bypass4netns=true alpine \
74+
sh -euc 'apk add iperf3 && iperf3 -c 192.168.64.1'
75+
```
76+
77+
Benchmark result:
78+
79+
| Mode | Throughput |
80+
|-------------------------------|----------------|
81+
| Rootless without bypass4netns | 2.30 Gbits/sec |
82+
| Rootless with bypass4netns | 86.0 Gbits/sec |
83+
| Rootful | 90.3 Gbits/sec |
84+
85+
<details>
86+
<summary>Benchmarking environment</summary>
87+
<p>
88+
89+
- Lima version: 2.0.0-alpha.2
90+
- nerdctl 2.1.6
91+
- containerd 2.1.4
92+
- bypass4netns 0.4.2
93+
- Container: Alpine Linux 3.22.2
94+
- iperf 3.19.1-r0 (apk)
95+
- Guest: Ubuntu 25.04
96+
- Host: macOS 26.0.1
97+
- iperf 3.19.1 (Homebrew)
98+
- Hardware: MacBook Pro 2024 (M4 Max, 128 GiB)
99+
100+
</p>
101+
</details>
102+
103+
### Accelerating start-up time with eStargz
104+
105+
[eStargz](https://github.com/containerd/stargz-snapshotter) is an OCI-compatible container image format
106+
that reduces start-up latency using lazy-pulling technique.
107+
108+
The support for eStargz is available by default for `ubuntu-24.04` instances:
109+
110+
```bash
111+
limactl start --name=default template://ubuntu-24.04
112+
```
113+
114+
The latest Ubuntu will be supported too in [a future release](https://github.com/containerd/stargz-snapshotter/issues/2144).
115+
116+
{{% alert title="Hint" color=success %}}
117+
ARM Mac users need to run `limactl start` with `--rosetta` to allow [running AMD64 binaries](../../config/multi-arch.md).
118+
This is not an architectural limitation of eStargz, however, Rosetta is needed because the example Python image below
119+
is currently [only available for AMD64](https://github.com/containerd/stargz-snapshotter/issues/2143).
120+
{{% /alert %}}
121+
122+
Without eStargz:
123+
124+
```console
125+
$ time lima nerdctl run --platform=amd64 ghcr.io/stargz-containers/python:3.13-org python3 -c 'print("hi")'
126+
[...]
127+
hi
128+
129+
real 0m23.767s
130+
user 0m0.025s
131+
sys 0m0.020s
132+
```
133+
134+
With eStargz:
135+
136+
```console
137+
$ time lima nerdctl --snapshotter=stargz run --platform=amd64 ghcr.io/stargz-containers/python:3.13-esgz python3 -c 'print("hi")'
138+
[...]
139+
hi
140+
141+
real 0m13.365s
142+
user 0m0.026s
143+
sys 0m0.021s
144+
```
145+
146+
Examples of eStargz images can be found at
147+
<https://github.com/containerd/stargz-snapshotter/blob/main/docs/pre-converted-images.md>.
148+
149+
See also:
150+
- https://github.com/containerd/stargz-snapshotter
151+
- https://github.com/containerd/nerdctl/blob/main/docs/stargz.md
152+
153+
## Disabling containerd
154+
155+
To disable containerd, start an instance with `--containerd=none`:
156+
157+
```bash
158+
limactl start --containerd=none
159+
```

‎website/content/en/docs/examples/containers/docker.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
title: Docker
3+
weight: 2
4+
---
5+
6+
{{< tabpane text=true >}}
7+
{{% tab header="Rootless" %}}
8+
```bash
9+
limactl start template://docker
10+
export DOCKER_HOST=$(limactl list docker --format 'unix://{{.Dir}}/sock/docker.sock')
11+
docker run -d --name nginx -p 127.0.0.1:8080:80 nginx:alpine
12+
```
13+
{{% /tab %}}
14+
{{% tab header="Rootful" %}}
15+
```bash
16+
limactl start template://docker-rootful
17+
export DOCKER_HOST=$(limactl list docker-rootful --format 'unix://{{.Dir}}/sock/docker.sock')
18+
docker run -d --name nginx -p 127.0.0.1:8080:80 nginx:alpine
19+
```
20+
{{% /tab %}}
21+
{{< /tabpane >}}

‎website/content/en/docs/examples/containers/kubernetes.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
---
2+
title: Kubernetes
3+
weight: 4
4+
---
5+
6+
## Single-node
7+
8+
{{< tabpane text=true >}}
9+
{{% tab header="kubeadm" %}}
10+
```bash
11+
limactl start template://k8s
12+
export KUBECONFIG=$(limactl list k8s --format 'unix://{{.Dir}}/copied-from-guest/kubeconfig.yaml')
13+
kubectl create deployment nginx --image nginx:alpine
14+
kubectl create service nodeport nginx --node-port=31080 --tcp=80:80
15+
```
16+
17+
Modify [`templates/k8s.yaml`](https://github.com/lima-vm/lima/blob/master/templates/k8s.yaml) to change
18+
the kubeadm configuration.
19+
20+
See also <https://kubernetes.io/docs/reference/setup-tools/kubeadm/>.
21+
{{% /tab %}}
22+
{{% tab header="k3s" %}}
23+
```bash
24+
limactl start template://k3s
25+
export KUBECONFIG=$(limactl list k3s --format 'unix://{{.Dir}}/copied-from-guest/kubeconfig.yaml')
26+
kubectl create deployment nginx --image nginx:alpine
27+
kubectl create service nodeport nginx --node-port=31080 --tcp=80:80
28+
```
29+
30+
See also <https://docs.k3s.io>.
31+
{{% /tab %}}
32+
{{% tab header="k0s" %}}
33+
```bash
34+
limactl start template://k0s
35+
export KUBECONFIG=$(limactl list k0s --format 'unix://{{.Dir}}/copied-from-guest/kubeconfig.yaml')
36+
kubectl create deployment nginx --image nginx:alpine
37+
kubectl create service nodeport nginx --node-port=31080 --tcp=80:80
38+
```
39+
40+
See also <https://docs.k0sproject.io/>.
41+
{{% /tab %}}
42+
{{% tab header="Usernetes" %}}
43+
```bash
44+
limactl start template://experimental/u7s
45+
export KUBECONFIG=$(limactl list u7s --format 'unix://{{.Dir}}/copied-from-guest/kubeconfig.yaml')
46+
kubectl create deployment nginx --image nginx:alpine
47+
# NodePorts are not available by default in the case of Usernetes
48+
kubectl port-forward deployments/nginx 8080:80
49+
```
50+
51+
See also <https://github.com/rootless-containers/usernetes>.
52+
{{% /tab %}}
53+
{{< /tabpane >}}
54+
55+
## Multi-node
56+
57+
A multi-node cluster can be created by creating multiple VMs connected via the ([`lima:user-v2`](../../config/network/user-v2.md) network.
58+
59+
```bash
60+
limactl create --name k8s-0 --network lima:user-v2
61+
limactl create --name k8s-1 --network lima:user-v2
62+
```
63+
64+
The cluster has to be set up manually, as the built-in templates do not support multi-node mode yet.
65+
Support for multi-node template is tracked in <https://github.com/lima-vm/lima/issues/4100>.

‎website/content/en/docs/examples/containers/podman.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
---
2+
title: Podman
3+
weight: 3
4+
---
5+
6+
{{< tabpane text=true >}}
7+
{{% tab header="Rootless" %}}
8+
To use `podman` command in the VM:
9+
```bash
10+
limactl start template://podman
11+
limactl shell podman podman run -d --name nginx -p 127.0.0.1:8080:80 docker.io/library/nginx:alpine
12+
```
13+
14+
To use `podman` command on the host:
15+
```bash
16+
export CONTAINER_HOST=$(limactl list podman --format 'unix://{{.Dir}}/sock/podman.sock')
17+
podman --remote run -d --name nginx -p 127.0.0.1:8080:80 docker.io/library/nginx:alpine
18+
```
19+
20+
To use `docker` command on the host:
21+
```bash
22+
export DOCKER_HOST=$(limactl list podman --format 'unix://{{.Dir}}/sock/podman.sock')
23+
docker run -d --name nginx -p 127.0.0.1:8080:80 docker.io/library/nginx:alpine
24+
```
25+
{{% /tab %}}
26+
{{% tab header="Rootful" %}}
27+
To use `podman` command in the VM:
28+
```bash
29+
limactl start template://podman-rootful
30+
limactl shell podman-rootful sudo podman run -d --name nginx -p 127.0.0.1:8080:80 docker.io/library/nginx:alpine
31+
```
32+
33+
To use `podman` command on the host:
34+
```bash
35+
export CONTAINER_HOST=$(limactl list podman-rootful --format 'unix://{{.Dir}}/sock/podman.sock')
36+
podman --remote run -d --name nginx -p 127.0.0.1:8080:80 docker.io/library/nginx:alpine
37+
```
38+
39+
To use `docker` command on the host:
40+
```bash
41+
export DOCKER_HOST=$(limactl list podman-rootful --format 'unix://{{.Dir}}/sock/podman.sock')
42+
docker run -d --name nginx -p 127.0.0.1:8080:80 docker.io/library/nginx:alpine
43+
```
44+
{{% /tab %}}
45+
{{< /tabpane >}}

0 commit comments

Comments
 (0)