Rado Kubiak | Rado x Tech
745cc1813e
- In Alpine Linux containers (commonly used as Docker base images),
standard DNS resolution is provided by **musl**, a lightweight C
standard library (libc). Musl implements DNS lookups via
`getaddrinfo()`, which queries AAAA (IPv6) records first.
- Problem: DNS did not work correctly **inside containers**. Any
system command attempting to resolve hostnames
(e.g., `ping dynamodb-admin`) **failed** when the DNS server
responded NXDOMAIN for AAAA records, even if A (IPv4) records
existed. Explicitly forcing IPv4 (`ping -4dynamodb-admin`) worked
correctly, showing the issue is specific to musl’s IPv6-first behavior.
- Consequence: In IPv4-only environments, Alpine-based containers
cannot resolve hostnames using standard tools or libraries.
Applications relying on `getaddrinfo()` fail with ENOTFOUND,
breaking networking and inter-container communication.
- Root cause: Following RFC 8305 / RFC 6724, musl treats NXDOMAIN
for AAAA as “hostname does not exist” and does not fallback to A
(IPv4) records.
- Fix: The Apple Container DNS engine now behaves as follows:
* If an **A record exists**, AAAA queries return **NOERROR with empty
answer (NODATA)**.
* If neither **A nor AAAA** exist, NXDOMAIN is returned.
This ensures that Alpine-based containers in IPv4-only networks can
correctly resolve hostnames inside containers without modifying
container images or application code.
container
container is a tool that you can use to create and run Linux containers as lightweight virtual machines on your Mac. It's written in Swift, and optimized for Apple silicon.
The tool consumes and produces OCI-compatible container images, so you can pull and run images from any standard container registry. You can push images that you build to those registries as well, and run the images in any other OCI-compatible application.
container uses the Containerization Swift package for low level container, image, and process management.
Get started
Requirements
You need a Mac with Apple silicon to run container. To build it, see the BUILDING document.
container is supported on macOS 26, since it takes advantage of new features and enhancements to virtualization and networking in this release. We do not support older versions of macOS and the container maintainers typically will not address issues that cannot be reproduced on the macOS 26.
Install or upgrade
If you're upgrading, first stop and uninstall your existing container (the -k flag keeps your user data, while -d removes it):
container system stop
uninstall-container.sh -k
Download the latest signed installer package for container from the GitHub release page.
To install the tool, double-click the package file and follow the instructions. Enter your administrator password when prompted, to give the installer permission to place the installed files under /usr/local.
Start the system service with:
container system start
Uninstall
Use the uninstall-container.sh script to remove container from your system. To remove your user data along with the tool, run:
uninstall-container.sh -d
To retain your user data so that it is available should you reinstall later, run:
uninstall-container.sh -k
Next steps
- Take a guided tour of
containerby building, running, and publishing a simple web server image. - Learn how to use various
containerfeatures. - Read a brief description and technical overview of
container. - Browse the full command reference.
- Build and run
containeron your own development system. - View the project API documentation.
Important
The links above are for the CURRENT BRANCH's documentation. To find documentation for official releases, find the target release on the Release Page and click the tag corresponding to your release version.
Example: release 0.4.1 tag
Contributing
Contributions to container are welcomed and encouraged. Please see our main contributing guide for more information.
Project Status
The container project is currently under active development. Its stability, both for consuming the project as a Swift package and the container tool, is only guaranteed within patch versions, such as between 0.1.1 and 0.1.2. Minor version number releases may include breaking changes until we achieve a 1.0.0 release.