lee/container
1
0
Fork 0
mirror of https://github.com/apple/container.git synced 2026-09-24 00:25:43 +00:00
Code Issues Packages Projects Releases Wiki Activity

Replace scattered defaults subcommands with system property. (#604)

Browse Source 
Common subcommands for all defaults.

- Closes #384.
- Replaces `registry default` and `system dns default` subcommands with
`system property`.
- Users can use `system property ls` to see details about each supported
default value.
- `system property set` implements reasonable validation for all
properties.
- NOTE: Probing of the registry for `registry default set` was removed,
which means users will find out about a botched setting when pulling or
pushing.
- Updates docs.

## Type of Change
- [ ] Bug fix
- [x] New feature  
- [x] Breaking change
- [x] Documentation update

## Motivation and Context
See #384.

## Testing
- [x] Tested locally
- [x] Added/updated tests
- [x] Added/updated docs
This commit is contained in:
J Logan
2025-09-16 13:37:55 -07:00
committed by GitHub
parent 386fd87b5d
commit 449f1d23df
19 changed files with 634 additions and 386 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/command-reference.md
+121 -19
View File
@@ -610,16 +610,6 @@ container registry logout SERVER
Only `--version` and `-h`/`--help` are available.
### `container registry default` commands
The `registry default` group allows setting, unsetting, and inspecting the default registry used when no registry is specified on image references.
* `container registry default set [OPTIONS] HOST`: Set the default registry.
* `--scheme <scheme>`: registry scheme. One of (`http`, `https`, `auto`) (default: `auto`)
* **Global**: `--debug`, `--version`, `-h`/`--help`
* `container registry default unset (clear)`: Clears the default registry configuration.
* `container registry default inspect`: Displays the current default registry, if any.
## System Management
System commands manage the container apiserver, logs, DNS settings and kernel. These are only available on macOS hosts.
@@ -725,14 +715,6 @@ container system dns list
No options.
### `container system dns default` commands
Manage the default local DNS domain used by other commands.
* `container system dns default set NAME`: Set the default DNS domain used by `create`/`run`.
* `container system dns default unset (clear)`: Unset the default DNS domain.
* `container system dns default inspect`: Display the current default DNS domain.
### `container system kernel set`
Installs or updates the Linux kernel used by the container runtime on macOS hosts.
@@ -751,4 +733,124 @@ container system kernel set [OPTIONS]
* `--recommended`: Download and install the recommended default kernel for your host
* **Global**: `--debug`, `--version`, `-h`/`--help`
***
### `container system property list (ls)`
Lists all available system properties with their current values, types, and descriptions. Output can be formatted as a table or JSON.
**Usage**
```bash
container system property list [OPTIONS]
```
**Options**
* `-q, --quiet`: Only output the property IDs
* `--format <format>`: Format of the output (values: `json`, `table`; default: `table`)
* **Global**: `--debug`, `--version`, `-h`/`--help`
**Examples**
```bash
# list all properties in table format
container system property list
# get only property IDs
container system property list --quiet
# output as JSON for scripting
container system property list --format json
```
### `container system property get`
Retrieves the current value of a specific system property by its ID.
**Usage**
```bash
container system property get PROPERTY_ID
```
**Arguments**
* `PROPERTY_ID`: The ID of the property to retrieve (use `property list` to see available IDs)
**Global flags**: `--debug`, `--version`, `-h`/`--help`
**Examples**
```bash
# get the default registry domain
container system property get registry.domain
# get the current DNS domain setting
container system property get dns.domain
```
### `container system property set`
Sets the value of a system property. The command validates the value based on the property type (boolean, domain name, image reference, URL, or CIDR address).
**Usage**
```bash
container system property set PROPERTY_ID VALUE
```
**Arguments**
* `PROPERTY_ID`: The ID of the property to set
* `VALUE`: The new value for the property
**Property Types and Validation**
* **Boolean properties** (`build.rosetta`): Accepts `true`, `t`, `false`, `f` (case-insensitive)
* **Domain properties** (`dns.domain`, `registry.domain`): Must be valid domain names
* **Image properties** (`image.builder`, `image.init`): Must be valid OCI image references
* **URL properties** (`kernel.url`): Must be valid URLs
* **Network properties** (`network.subnet`): Must be valid CIDR addresses
* **Path properties** (`kernel.binaryPath`): Accept any string value
**Global flags**: `--debug`, `--version`, `-h`/`--help`
**Examples**
```bash
# enable Rosetta for AMD64 builds on ARM64
container system property set build.rosetta true
# set a custom DNS domain
container system property set dns.domain mycompany.local
# configure a custom registry
container system property set registry.domain registry.example.com
# set a custom builder image
container system property set image.builder myregistry.com/custom-builder:latest
```
### `container system property clear`
Clears (unsets) a system property, reverting it to its default value.
**Usage**
```bash
container system property clear PROPERTY_ID
```
**Arguments**
* `PROPERTY_ID`: The ID of the property to clear
**Global flags**: `--debug`, `--version`, `-h`/`--help`
**Examples**
```bash
# clear custom DNS domain (revert to default)
container system property clear dns.domain
# clear custom registry setting
container system property clear registry.domain
docs/how-to.md
+16 -4
View File
@@ -358,18 +358,30 @@ container run --name nested-virtualization --virtualization --kernel /path/to/a/
[ 0.017893] kvm [1]: Hyp mode initialized successfully
```
## Configure container defaults
## Configure system properties
`container` uses macOS user defaults to store configuration settings that persist between sessions. You can customize various aspects of container behavior, including build settings, default images, and network configuration.
The `container system property` subcommand manages the configuration settings for the `container` CLI and services. You can customize various aspects of container behavior, including build settings, default images, and network configuration.
For a complete list of available configuration options and detailed usage instructions, see the [user defaults documentation](user-defaults.md).
Use `container system property list` to show information for all available properties:
```console
% bin/container system property ls
ID TYPE VALUE DESCRIPTION
build.rosetta Bool true Build amd64 images on arm64 using Rosetta, instead of QEMU.
dns.domain String *undefined* If defined, the local DNS domain to use for containers with unqualified names.
image.builder String ghcr.io/apple/container-builder-shim/... The image reference for the utility container that `container build` uses.
image.init String ghcr.io/apple/containerization/vminit... The image reference for the default initial filesystem image.
kernel.binaryPath String opt/kata/share/kata-containers/vmlinu... If the kernel URL is for an archive, the archive member pathname for the kernel file.
kernel.url String https://github.com/kata-containers/ka... The URL for the kernel file to install, or the URL for an archive containing the kernel file.
network.subnet String *undefined* Default subnet for IP allocation (used on macOS 15 only).
```
### Example: Disable Rosetta for builds
If you want to prevent the use of Rosetta translation during container builds on Apple Silicon Macs:
```bash
defaults write com.apple.container.defaults build.rosetta -bool false
container system property set build.rosetta false
```
This is useful when you want to ensure builds only produce native arm64 images and avoid any x86_64 emulation.
docs/tutorial.md
+12 -12
View File
@@ -98,7 +98,7 @@ Use the `--help` flag to see which abbreviations exist.
```bash
sudo container system dns create test
container system dns default set test
container system property set dns.domain test
```
Enter your administrator password when prompted. The first command requires administrator privileges to create a file containing the domain configuration under the `/etc/resolver` directory, and to tell the macOS DNS resolver to reload its configuration files.
@@ -253,39 +253,39 @@ Push your image to a container registry, publishing it so that you and others ca
### Publish the web server image
To publish your image, you need push images to a registry service that stores the image for future use. Typically, you need to authenticate with a registry to push an image. This example assumes that you have an account at a hypothetical registry named `registry.example.com` with username `fido` and a password or token `my-secret`, and that your personal repository name is the same as your username.
> [!NOTE]
> By default `container` is configured to use Docker Hub.
> You can change the default registry used by running `container registry default set <registry url>`.
> See the other sub commands under `container registry` for more options.
To publish your image, you need push images to a registry service that stores the image for future use. Typically, you need to authenticate with a registry to push an image. This example assumes that you have an account at a hypothetical registry named `some-registry.example.com` with username `fido` and a password or token `my-secret`, and that your personal repository name is the same as your username.
To sign into a secure registry with your login credentials, enter your username and password at the prompts after running:
```bash
container registry login {registry.example.com}
container registry login some-registry.example.com
```
Create another name for your image that includes the registry name, your repository name, and the image name, with the tag `latest`:
```bash
container image tag web-test {registry.example.com/fido}/web-test:latest
container image tag web-test some-registry.example.com/fido/web-test:latest
```
Then, push the image:
```bash
container image push {registry.example.com/fido}/web-test:latest
container image push some-registry.example.com/fido/web-test:latest
```
> [!NOTE]
> By default `container` is configured to use Docker Hub.
> You can change the default registry to another value by running `container system property set registry.domain some-registry.example.com`.
> See the other sub commands under `container registry` for more options.
### Pull and run your image
To validate your published image, stop your current web server container, remove the image that you built, and then run using the remote image:
```bash
container stop my-web-server
container image delete web-test {registry.example.com/fido}/web-test:latest
container run --name my-web-server --detach --rm {registry.example.com/fido}/web-test:latest
container image delete web-test some-registry.example.com/fido/web-test:latest
container run --name my-web-server --detach --rm some-registry.example.com/fido/web-test:latest
```
## Clean up
docs/user-defaults.md
-150
View File
@@ -1,150 +0,0 @@
# User Defaults Configuration
The `container` CLI uses macOS user defaults to store configuration settings. These settings persist between sessions and allow you to customize the behavior of various commands.
## Viewing Current Defaults
To view a specific default value, use the macOS `defaults` command:
```bash
defaults read com.apple.container.defaults <key>
```
## Available User Defaults
### Build Settings
#### build.rosetta
Controls whether Rosetta translation is enabled during container builds. When enabled (default), allows building x86_64 images on Apple Silicon Macs.
**Default:** `true`
**Usage:**
```bash
# Disable Rosetta for builds
defaults write com.apple.container.defaults build.rosetta -bool false
# Enable Rosetta for builds (default)
defaults write com.apple.container.defaults build.rosetta -bool true
# Check current value
defaults read com.apple.container.defaults build.rosetta
```
**Note:** Disabling Rosetta will prevent building x86_64 images on Apple Silicon Macs. This setting only affects the build process and does not impact running containers.
### Image Settings
#### image.builder
Specifies the default BuildKit image used for building containers.
**Default:** `ghcr.io/apple/container-builder-shim/builder:<version>`
**Usage:**
```bash
# Set a custom builder image
defaults write com.apple.container.defaults image.builder "my-registry.com/my-builder:latest"
# Reset to default
defaults delete com.apple.container.defaults image.builder
```
#### image.init
Specifies the default init image used for container initialization.
**Default:** `ghcr.io/apple/containerization/vminit:<version>`
**Usage:**
```bash
# Set a custom init image
defaults write com.apple.container.defaults image.init "my-registry.com/my-init:latest"
```
### Network Settings
#### dns.domain
Sets the default local DNS domain for containers.
**Default:** `test`
**Usage:**
```bash
# Set a custom DNS domain
defaults write com.apple.container.defaults dns.domain "mycompany.local"
# Alternatively, use the container CLI
container system dns default set mycompany.local
```
### Registry Settings
#### registry.domain
Sets the default registry domain for pulling images.
**Default:** `docker.io`
**Usage:**
```bash
# Set a custom default registry
defaults write com.apple.container.defaults registry.domain "ghcr.io"
# Alternatively, use the container CLI
container registry default set ghcr.io
```
### Kernel Settings
#### kernel.url
URL for downloading the default kernel used by containers.
**Default:** `https://github.com/kata-containers/kata-containers/releases/download/3.17.0/kata-static-3.17.0-arm64.tar.xz`
**Usage:**
```bash
# Set a custom kernel URL
defaults write com.apple.container.defaults kernel.url "https://myserver.com/custom-kernel.tar.xz"
```
#### kernel.binaryPath
Path within the kernel archive to the actual kernel binary.
**Default:** `opt/kata/share/kata-containers/vmlinux-6.12.28-153`
**Usage:**
```bash
# Set a custom kernel binary path
defaults write com.apple.container.defaults kernel.binaryPath "path/to/vmlinux"
```
## Resetting Defaults
To reset a specific setting to its default value:
```bash
defaults delete com.apple.container.defaults <key>
```
To reset all container defaults:
```bash
defaults delete com.apple.container.defaults
```
## Platform-Specific Settings
### macOS 15 Network Configuration
On macOS 15, if you experience network connectivity issues, you may need to manually configure the network subnet:
```bash
defaults write com.apple.container.defaults network.subnet 192.168.66.1/24
```
See the [technical overview](technical-overview.md#macos-15-limitations) for more details about macOS 15 limitations.