apple / apple/container

Expose the container ID to workloads running inside the guest

Open
#1,430 3 comments 0 reactions 0 assignees View on GitHub
Dominant language
Swift
Stars
49.9k
Forks
1.8k
Avg merge
1d 20h
Merged PRs (30d)
22

Description

## Problem

Tools that run inside a container and need a stable, unique identifier for the host they are running on (diagnostics agents, telemetry pipelines, license managers, host-identity libraries) currently have no reliable way to obtain the container's authoritative ID from within an Apple `container` guest.

The container ID (as shown by `container inspect .id`, stored in `config.id`, and embedded in the XPC service name `com.apple.container.container-runtime-linux.`) is exposed to the guest only via `hostname`. By default that ID is a UUIDv4 (`Utility.createContainerID` in [`Sources/Services/ContainerAPIService/Client/Utility.swift`](https://github.com/apple/container/blob/main/Sources/Services/ContainerAPIService/Client/Utility.swift#L35-L40)); with `--name ` it is the user-supplied string. In either case, `--name` (being the only way to set a hostname today) overwrites the hostname with that string, so a container that wants both a human-readable hostname *and* programmatic access to the ID cannot have both — there is no `--hostname` flag, and no secondary channel (env var, metadata file, sysfs entry) carries the ID.

Additionally, there is no documented way for a guest to positively detect that it is running under Apple `container`. The only signal we have been able to find is the substring `init=/sbin/vminitd` in `/proc/cmdline`, which is an internal implementation detail rather than a stable API. Compare with `container=lxc` in `/proc/1/environ` for LXC/LXD, or `systemd-detect-virt` recognition.

## How other runtimes handle this

- **Docker** exposes the 64-char container ID inside the guest through cgroup and overlay-FS paths visible in `/proc/self/cgroup` and `/proc/self/mountinfo` (e.g. `/docker/`, `…/containers//…`). Hostname is set independently via `--hostname`; by default it is the first 12 chars of the ID, but the full ID remains discoverable from the filesystem paths regardless of `--hostname`. See [moby/moby#3506](https://github.com/moby/moby/issues/3506) for the long-running discussion of this surface.
- **Podman** similarly exposes the full ID through `containers/` and `libpod` tokens in `/proc/self/mountinfo`, supports `--hostname` independently of `--name`, and sets `container=podman` on PID 1's environment as a positive runtime marker. See [containers/podman#14236](https://github.com/containers/podman/issues/14236).

In both runtimes, an unprivileged process inside the container can recover the authoritative container ID regardless of how the user configured the hostname.

## Context

We hit this while adding Apple `container` support to a host-identity library. The workaround we landed on (detect via `init=/sbin/vminitd`, extract via `gethostname()`) works for the default case but collapses to a user-supplied string, not an ID, whenever `--name` is used — and it relies on a detection signal that is not a documented contract.

Full analysis, source-code citations, and observed vs. source-code behavioural drift:
https://github.com/dekobon/host-identity/issues/2

We are filing this upstream to surface the gap; we do not have a preferred design.

Contributor guide

Open the contributing guide

Research direction

Start by reading Utility.swift, especially Utility.createContainerID, then trace how the ID is stored in config.id, shown by container inspect, embedded in the XPC service name, and exposed to the guest as hostname. Done means agreeing on and documenting a stable guest-visible container ID and a positive Apple container runtime signal that remain available when --name is used.

Written by the indexing model from the issue text.

Assessment

Tech stack
swift
Domain
infrastructure, operating-systems
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.