Skip to content

Commit ec89df7

Browse files
AkihiroSudaAkihiroSuda
authored
Merge pull request #2956 from AkihiroSuda/docs-containers
website: enhance container examples
2 parents a816fd5 + 39156ed commit ec89df7

File tree

12 files changed

+336
-8
lines changed

12 files changed

+336
-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/_index.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/_index.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
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+
- If you have installed Lima by [`make install`](../../../installation/source.md), the `nerdctl.lima` command is also available as `nerdctl`.
22+
- If you have installed Lima by [`brew install lima`](../../../installation/_index.md), you may make an alias (or a symlink) by yourself:
23+
`alias nerdctl=nerdctl.lima`
24+
{{% /tab %}}
25+
{{% tab header="Rootful" %}}
26+
```bash
27+
limactl start --containerd=system
28+
lima sudo nerdctl run -d --name nginx -p 127.0.0.1:8080:80 nginx:alpine
29+
```
30+
{{% /tab %}}
31+
{{< /tabpane >}}
32+
33+
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).
34+
35+
## Disabling containerd
36+
37+
To disable containerd, start an instance with `--containerd=none`:
38+
39+
```bash
40+
limactl start --containerd=none
41+
```

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

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
---
2+
title: Advanced
3+
weight: 1
4+
---

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

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
---
2+
title: Accelerating rootless networking with bypass4netns
3+
linkTitle: bypass4netns
4+
weight: 2
5+
---
6+
7+
[bypass4netns](https://github.com/rootless-containers/bypass4netns) is an experimental accelerator for rootless networking.
8+
9+
On macOS hosts, it is highly recommended to use the [vzNAT](../../../../config/network/vmnet.md#vznat) networking in conjunction
10+
to reduce the overhead of Lima's user-mode networking:
11+
12+
```bash
13+
limactl start --network vzNAT
14+
```
15+
16+
To enable bypass4netns, the daemon process (`bypass4netnsd`) has to be installed in the VM as follows:
17+
<!-- TODO: install by default -->
18+
```bash
19+
lima containerd-rootless-setuptool.sh install-bypass4netnsd
20+
```
21+
22+
Then run a container with an annotation `nerdctl/bypass4netns=true`:
23+
24+
```bash
25+
# 192.168.64.1 is the IP address of the "bridge100" interface on the macOS host
26+
lima nerdctl run --annotation nerdctl/bypass4netns=true alpine \
27+
sh -euc 'apk add iperf3 && iperf3 -c 192.168.64.1'
28+
```
29+
30+
Benchmark result:
31+
32+
| Mode | Throughput |
33+
|-------------------------------|----------------|
34+
| Rootless without bypass4netns | 2.30 Gbits/sec |
35+
| Rootless with bypass4netns | 86.0 Gbits/sec |
36+
| Rootful | 90.3 Gbits/sec |
37+
38+
<details>
39+
<summary>Benchmarking environment</summary>
40+
<p>
41+
42+
- Lima version: 2.0.0-alpha.2
43+
- nerdctl 2.1.6
44+
- containerd 2.1.4
45+
- bypass4netns 0.4.2
46+
- Container: Alpine Linux 3.22.2
47+
- iperf 3.19.1-r0 (apk)
48+
- Guest: Ubuntu 25.04
49+
- Host: macOS 26.0.1
50+
- iperf 3.19.1 (Homebrew)
51+
- Hardware: MacBook Pro 2024 (M4 Max, 128 GiB)
52+
53+
</p>
54+
</details>

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

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
title: Enhanced supply chain security with gomodjail
3+
linkTitle: gomodjail
4+
weight: 1
5+
---
6+
7+
[gomodjail](https://github.com/AkihiroSuda/gomodjail) is an experimental library sandbox for Go modules.
8+
9+
gomodjail imposes syscall restrictions on a specific set of Go modules, so as to mitigate their potential vulnerabilities and supply chain attack vectors.
10+
A restricted module is hindered to access files and execute commands.
11+
12+
gomodjail can be enabled for nerdctl by using the `nerdctl.gomodjail` binary.
13+
14+
```bash
15+
lima nerdctl.gomodjail ...
16+
```
17+
18+
For the gomodjail policy applied to `nerdctl.gomodjail`, see <https://github.com/containerd/nerdctl/blob/main/go.mod>.

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

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
---
2+
title: Accelerating start-up time with eStargz
3+
linkTitle: eStargz
4+
weight: 3
5+
---
6+
7+
[eStargz](https://github.com/containerd/stargz-snapshotter) is an OCI-compatible container image format
8+
that reduces start-up latency using lazy-pulling technique.
9+
10+
The support for eStargz is available by default for `ubuntu-24.04` instances:
11+
12+
```bash
13+
limactl start --name=default template://ubuntu-24.04
14+
```
15+
16+
The latest Ubuntu will be supported too in [a future release](https://github.com/containerd/stargz-snapshotter/issues/2144).
17+
18+
{{% alert title="Hint" color=success %}}
19+
ARM Mac users need to run `limactl start` with `--rosetta` to allow [running AMD64 binaries](../../../../config/multi-arch.md).
20+
This is not an architectural limitation of eStargz, however, Rosetta is needed because the example Python image below
21+
is currently [only available for AMD64](https://github.com/containerd/stargz-snapshotter/issues/2143).
22+
{{% /alert %}}
23+
24+
Without eStargz:
25+
26+
```console
27+
$ time lima nerdctl run --platform=amd64 ghcr.io/stargz-containers/python:3.13-org python3 -c 'print("hi")'
28+
[...]
29+
hi
30+
31+
real 0m23.767s
32+
user 0m0.025s
33+
sys 0m0.020s
34+
```
35+
36+
With eStargz:
37+
38+
```console
39+
$ time lima nerdctl --snapshotter=stargz run --platform=amd64 ghcr.io/stargz-containers/python:3.13-esgz python3 -c 'print("hi")'
40+
[...]
41+
hi
42+
43+
real 0m13.365s
44+
user 0m0.026s
45+
sys 0m0.021s
46+
```
47+
48+
Examples of eStargz images can be found at
49+
<https://github.com/containerd/stargz-snapshotter/blob/main/docs/pre-converted-images.md>.
50+
51+
See also:
52+
- https://github.com/containerd/stargz-snapshotter
53+
- https://github.com/containerd/nerdctl/blob/main/docs/stargz.md

‎website/content/en/docs/examples/containers/docker/_index.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 >}}

0 commit comments

Comments
 (0)