diff --git a/README.md b/README.md index 21b9952e..f507e3c9 100644 --- a/README.md +++ b/README.md @@ -76,7 +76,7 @@ To retain your user data so that it is available should you reinstall later, run ## Next steps -- Take [a guided tour of `container`](./docs/tutorial.md) by building, running, and publishing a simple web server image. +- Take [a guided tour of `container`](./docs/tutorials/start-here.md) by building, running, and publishing a simple web server image. - Learn how to [use various `container` features](./docs/how-to.md). - Read a brief description and [technical overview](./docs/technical-overview.md) of `container`. - Browse the [full command reference](./docs/command-reference.md). diff --git a/docs/container-system-config.md b/docs/container-system-config.md new file mode 100644 index 00000000..b1c81c06 --- /dev/null +++ b/docs/container-system-config.md @@ -0,0 +1,114 @@ +# `config.toml` reference + +> [!IMPORTANT] +> This file contains documentation for the CURRENT BRANCH. To find documentation for official releases, find the target release on the [Release Page](https://github.com/apple/container/releases) and click the tag corresponding to your release version. +> +> Example: [release 0.4.1 tag](https://github.com/apple/container/tree/0.4.1) + +For a guided walk-through on setting default values, see [Container system config tutorial](./tutorials/container-system-config-tutorial.md). + +Source of truth: [`Sources/ContainerPersistence/ContainerSystemConfig.swift`](../Sources/ContainerPersistence/ContainerSystemConfig.swift). + +## Top-level schema + +```toml +[build] # builder VM resources and image +[container] # default per-container resources +[dns] # default DNS domain for DNS resolution on host +[kernel] # guest kernel binary path and download URL +[network] # default subnets for new networks +[registry] # default registry domain +[vminit] # default vminitd image to use +[plugin.] # zero or more plugin-scoped sections +``` + +All top-level sections are optional. Omitted sections fall back to their defaults wholesale. + +## `[build]` + +Resources and image used for the builder VM that runs `container build`. + +| Key | Type | Default | Description | +|-----------|-------------|------------------------------------------------------|-----------------------------------------------------------------------------| +| `rosetta` | `Bool` | `true` | Whether the builder VM uses Rosetta translation for non-native architectures. | +| `cpus` | `Int` | `2` | CPU count for the builder VM. | +| `memory` | [MemorySize](#memorysize-format) | `"2048mb"` | RAM allocation for the builder VM. | +| `image` | `String` | `ghcr.io/apple/container-builder-shim/builder:` | Reference for the builder image. The tag segment is taken from the project's bundled `container-builder-shim` version. | + +## `[container]` + +Defaults applied when `container run` / `container create` is invoked without `--cpus` or `--memory`. + +| Key | Type | Default | Description | +|----------|------------|---------|----------------------------------------------------------------------------| +| `cpus` | `Int` | `4` | Default CPU count per container. | +| `memory` | [MemorySize](#memorysize-format) | `"1g"` | Default RAM per container. | + +## `[dns]` + +| Key | Type | Default | Description | +|----------|-----------|---------|----------------------------------------------------------------------------| +| `domain` | `String?` | unset | Local DNS domain appended to container hostnames (e.g. `"test"` makes `my-web-server` resolvable as `my-web-server.test`). When unset, no domain is appended. | + +## `[kernel]` + +Guest kernel used when launching container VMs. Defaults change per release as kernels are bumped — check the [source](../Sources/ContainerPersistence/ContainerSystemConfig.swift) for current values. + +| Key | Type | Default | Description | +|--------------|----------|--------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------| +| `binaryPath` | `String` | `"opt/kata/share/kata-containers/vmlinux-6.18.15-186"` | Path **inside** the downloaded kernel archive that points to the kernel binary. | +| `url` | `URL` | `"https://github.com/kata-containers/kata-containers/releases/download/3.28.0/kata-static-3.28.0-arm64.tar.zst"` | Archive to download when no kernel is installed. Encoded and decoded as a plain string in TOML. | + +## `[network]` + +Default subnets used when creating networks without explicit `--subnet` / `--subnet-v6` flags. + +| Key | Type | Default | Description | +|------------|------------|---------|---------------------------------------------------------------------------------------------------| +| `subnet` | [CIDRv4?](#cidrv4--cidrv6) | unset | IPv4 CIDR (e.g. `"192.168.100.0/24"`). When unset, the system auto-allocates a non-overlapping subnet. | +| `subnetv6` | [CIDRv6?](#cidrv4--cidrv6) | unset | IPv6 CIDR (e.g. `"fd00:abcd::/64"`). When unset, the system auto-allocates. | + +## `[registry]` + +| Key | Type | Default | Description | +|----------|----------|--------------|--------------------------------------------------------------------------------------------------------------| +| `domain` | `String` | `"docker.io"` | Registry assumed when an image reference omits the registry host (e.g. `alpine` → `docker.io/library/alpine`). | + +## `[vminit]` + +| Key | Type | Default | Description | +|---------|----------|--------------------------------------------------------|----------------------------------------------------------------------------------------------------------| +| `image` | `String` | `ghcr.io/apple/containerization/vminit:` | Reference for the `vminitd` image used to boot container VMs. The tag segment is taken from the project's bundled `containerization` version. | + +## `[plugin.]` + +Plugins can ship their own configuration schemas under `[plugin.]`, where `` is the plugin's identifier. Each plugin defines and reads its own section — values under one plugin's section cannot leak into another's. Consult the documentation for the specific plugin you want to configure. + +| Key | Type | Notes | +|--------------------|----------|---------------------------------------------------------------------------------------------| +| `` | varies | Schema is defined by the plugin. TODO: Add tutorial on setting plugin specific values. | + +## Type formats + +### MemorySize format + +Quoted string with a numeric prefix and a binary unit suffix. Parsing is case-insensitive; the suffix may be one of: + +| Suffix family | Unit | Example values | +|---------------------|--------------------------|------------------------| +| `b` | bytes | `"1024b"` | +| `k`, `kb`, `kib` | kibibytes (1024 bytes) | `"512k"`, `"512kb"` | +| `m`, `mb`, `mib` | mebibytes (1024 KiB) | `"2048mb"`, `"2g"` | +| `g`, `gb`, `gib` | gibibytes (1024 MiB) | `"4g"`, `"4gb"` | +| `t`, `tb`, `tib` | tebibytes | `"1t"` | +| `p`, `pb`, `pib` | pebibytes | `"1p"` | + +All units are **binary** (powers of 1024), even when written with `kb`/`mb`/`gb`. The encoded form uses lowercase suffix `b`/`kb`/`mb`/`gb`/`tb`/`pb`, e.g. a value parsed from `"2g"` is emitted as `"2gb"`. + +A bare integer (e.g. `"2048"`) parses as bytes. + +Source: [`Sources/ContainerPersistence/Measurement+Parse.swift`](../Sources/ContainerPersistence/Measurement+Parse.swift). + +### `CIDRv4` / `CIDRv6` + +Quoted string. IPv4 example: `"192.168.100.0/24"`. IPv6 example: `"fd00:abcd::/64"`. The loader rejects invalid CIDR strings at decode time. diff --git a/docs/how-to.md b/docs/how-to.md index b4ca8b8d..615add08 100644 --- a/docs/how-to.md +++ b/docs/how-to.md @@ -62,7 +62,7 @@ total 4 ## Build and run a multiplatform image -Using the [project from the tutorial example](tutorial.md#set-up-a-simple-project), you can create an image to use both on Apple silicon Macs and on x86-64 servers. +Using the [project from the tutorial example](./tutorials/start-here.md#set-up-a-simple-project), you can create an image to use both on Apple silicon Macs and on x86-64 servers. When building the image, just add `--arch` options that direct the builder to create an image supporting both the `arm64` and `amd64` architectures: diff --git a/docs/tutorials/container-system-config-tutorial.md b/docs/tutorials/container-system-config-tutorial.md new file mode 100644 index 00000000..df8a4f79 --- /dev/null +++ b/docs/tutorials/container-system-config-tutorial.md @@ -0,0 +1,94 @@ +# Customize `container` default configuration values + +> [!IMPORTANT] +> This file contains documentation for the CURRENT BRANCH. To find documentation for official releases, find the target release on the [Release Page](https://github.com/apple/container/releases) and click the tag corresponding to your release version. +> +> Example: [release 0.4.1 tag](https://github.com/apple/container/tree/0.4.1) + +Take a guided tour of setting configurations for `container` CLI commands and services. + +## Configuration sources + +The `container` service loads values from these TOML files at startup, with first-match-wins precedence: + +1. Your user file at `~/.config/container/config.toml`. +2. An optional file shipped with the `container` package install at `/etc/container/config.toml`. + +Any key absent from both files falls back to a hardcoded default. For the full schema and defaults, see the [`config.toml` reference](../container-system-config.md). + +## Create a custom user TOML configuration file + +The `container` service reads your file once at startup, so restart the service whenever you want changes to take effect. + +### Open or create your config file + +Your editable config lives at `~/.config/container/config.toml`. Create it if it does not exist: + +```bash +mkdir -p ~/.config/container +touch ~/.config/container/config.toml +``` + +### Set the values you want to customize + +Open the file in the editor of your choice and add only the sections and keys you want to change. + +For this tutorial, increase the default CPU and memory limits used for each new container and set a DNS domain for resolving container IP addresses from the host. + +```toml +[container] +cpus = 8 +memory = "4g" + +[dns] +domain = "test" +``` + +Each top-level table maps directly to a section of [ContainerSystemConfig](../container-system-config.md). + +### Restart the `container` service + +To make your edits take effect, stop and start the system: + +```bash +container system stop +container system start +``` + +### Verify the values are loaded + +Use `container system property list` (alias `ls`) to print the merged configuration that the `container` service is using. + +```console +% container system property list +[build] +cpus = 2 +memory = "2048mb" +rosetta = true +image = "ghcr.io/apple/container-builder-shim/builder:0.11.0" + +[container] +cpus = 8 +memory = "4gb" + +[dns] +domain = "test" + +[kernel] +binaryPath = "opt/kata/share/kata-containers/vmlinux-6.18.15-186" +url = "https://github.com/kata-containers/kata-containers/releases/download/3.28.0/kata-static-3.28.0-arm64.tar.zst" + +[network] + +[registry] +domain = "docker.io" + +[vminit] +image = "ghcr.io/apple/containerization/vminit:0.32.2" +``` + +For machine-readable output, pass `--format json`: + +```bash +container system property list --format json +``` diff --git a/docs/tutorial.md b/docs/tutorials/start-here.md similarity index 100% rename from docs/tutorial.md rename to docs/tutorials/start-here.md