docs: self-hosted-runners reference reads DinD as optional for ARC — should state it's required

[lpcox]

Summary

Customer feedback indicates that the self-hosted runners reference doc (docs/src/content/docs/reference/self-hosted-runners.md) reads DinD as a conditional/optional ARC configuration rather than a hard requirement. The new ARC DinD guide is clear on this, but the reference doc needs updates to match.

Gaps

1. Docker requirements section reads DinD as one option among peers (lines 170-174)

The three bullet points (Unix socket, Docker group, ARC/Kubernetes) are presented as peer-level items. The ARC bullet says:

If using actions-runner-controller with Docker-in-Docker (dind), the dind sidecar must share the Docker socket via an emptyDir volume.

This reads as "if you happen to use DinD" — not "DinD is the only supported mode for ARC." A reader could conclude that ARC with Kubernetes container mode also works.

Fix: State explicitly that DinD is required for ARC and that containerMode.type="kubernetes" is not supported.

2. ARC section reads DinD as an optional pattern (lines 241-260)

The heading "Docker-in-Docker (dind) sidecar" and the text "The standard ARC dind pattern with a shared emptyDir for the Docker socket is supported" describe DinD as one supported option, not the only option.

Fix: Lead with "GitHub Copilot coding agent requires DinD mode on ARC" and note that Kubernetes container mode is unsupported.

3. No cross-reference from Docker requirements to the ARC guide

The Docker section mentions ARC but doesn't link to the new ARC DinD guide or the ARC section later on the same page.

Fix: Add a cross-reference link.

4. ARC section doesn't mention runner.topology: arc-dind

The ARC section (lines 241-260) discusses pod security and socket sharing but never mentions the frontmatter setting that's required for compiled workflows to enable ARC DinD handling. The earlier "ARC with Docker-in-Docker (DinD)" section (line 20) does mention it, but the bottom ARC section doesn't, which is confusing since they cover related topics.

Fix: Either consolidate the two ARC sections or add a cross-reference and mention runner.topology: arc-dind in the bottom section.

5. "privileged: true on both the dind sidecar and the runner container" is misleading (line 255)

The text says both containers need privileged: true. In practice:

• The DinD sidecar needs privileged mode (for dockerd)
• The runner container needs NET_ADMIN capability (for iptables), not full privileged mode

Saying both need privileged: true could lead operators to over-privilege the runner container.

Fix: Clarify that the runner container needs NET_ADMIN capability, not privileged: true. The DinD sidecar needs privileged mode.

Context

• Customer feedback: the wording reads as conditional rather than stating DinD as a hard requirement
• The new ARC DinD guide is clear — the reference doc should match
• Related: the top "ARC with Docker-in-Docker" section (line 20) was updated in the guide PR but the bottom "ARC (Actions Runner Controller)" section (line 241) was not

[lpcox]

Additional gap: sudo requirements section is partially outdated

The reference doc states (lines 12–18):

Self-hosted runners must allow sudo for agentic workflows. … a non-sudo mode is not supported, including ARC configurations with allowPrivilegeEscalation: false.

This conflates two separate sudo concerns that should be distinguished:

1. AWF (the firewall) — no longer requires sudo or NET_ADMIN on the runner

Since network isolation became the default, AWF runs rootless (awf instead of sudo -E awf). This is controlled by SudoExplicitlyEnabled in sandbox.go — when sudo is not explicitly set to true in frontmatter, NetworkIsolation is set to true and GetAWFCommandPrefix() strips the sudo -E prefix. All topology: arc-dind workflows use this default.

In network isolation mode, egress is enforced via Docker network topology (an internal network with a dual-homed Squid proxy) rather than host iptables. No sudo, no NET_ADMIN, and no host-level iptables are required on the runner. The iptables-init container that sets up NAT rules inside the AWF Docker network has its own NET_ADMIN capability, but that is internal to the Docker Compose stack and invisible to the runner pod.

2. install_copilot_cli.sh — rootless script that escalates via sudo

The Copilot CLI install script runs as the unprivileged runner user but calls sudo for specific file operations:

• sudo chown -R — fix .copilot directory ownership (left root-owned by prior AWF runs)
• sudo find /tmp ... -exec rm -rf — clean stale AWF chroot home directories
• sudo install -m 0755 — install the copilot wrapper into INSTALL_DIR
• sudo tar -xz / sudo chmod — extract tarball and set executable permissions

The script itself is rootless; it escalates only when needed. This is the actual blocker for ARC pods with allowPrivilegeEscalation: false or no-new-privileges — the K8s security context prevents the escalation. A customer hit this on v0.82.3 with the error: sudo: The "no new privileges" flag is set, which prevents sudo from running as root.

Suggested doc fix

Replace the blanket "must allow sudo" statement with something like:

• AWF firewall: Runs without sudo and without NET_ADMIN on the runner in the default network-isolation mode. Egress is enforced via Docker network topology, not host iptables.
• Copilot CLI install: The install_copilot_cli.sh script runs as the runner user but escalates via sudo for specific file operations (chown, tar, chmod, cleanup). ARC pods with allowPrivilegeEscalation: false will fail at this step.

[lpcox]

Additional gap: ARC DinD guide incorrectly states NET_ADMIN is required on the runner container

The merged ARC DinD guide states:

NET_ADMIN is required on the runner container so AWF can apply host-level iptables rules to the DOCKER-USER chain for egress filtering.

And in the requirements table:

| NET_ADMIN capability | Yes | Required on the runner container so AWF can manage host-level DOCKER-USER iptables rules. |

This is incorrect for topology: arc-dind workflows.

Why

topology: arc-dind compiles with sandbox.agent.sudo: false (the default). The compiler sets NetworkIsolation = true, which results in:

1. AWF runs rootless — GetAWFCommandPrefix() strips sudo -E, emitting awf instead of sudo -E awf
2. AWF config gets "isolation": true — maps to --network-isolation CLI flag
3. Egress is enforced via Docker network topology — an internal Docker network (awf-net) with no internet route plus a dual-homed Squid proxy. No host-level iptables rules are created, and the DOCKER-USER chain is never touched.

The DOCKER-USER / host iptables approach is the old sudo mode (sudo -E awf --enable-host-access), which requires NET_ADMIN on the runner. Network isolation mode does not use this path at all.

AWF's own iptables-init container has NET_ADMIN, but that is internal to the Docker Compose stack — it runs in the agent container's network namespace inside the AWF Docker network. The runner pod's security context is not involved.

What to fix

1. Remove NET_ADMIN from the pod spec example in the guide
2. Remove the NET_ADMIN row from the requirements table
3. Update the "How it works" section to describe network isolation (Docker network topology) rather than host iptables
4. The self-hosted-runners reference doc (lines 255-260) also says the runner needs privileged: true for iptables — same correction needed there

[lpcox]

Clarification: who creates the network topology

To be precise about why NET_ADMIN is not needed on the runner container:

In network isolation mode, AWF generates a docker-compose.yml that defines two networks:

• awf-net — an internal Docker network (no internet route)
• awf-ext — an external bridge network

Squid is dual-homed (attached to both), making it the sole egress path. The agent is only on awf-net.

AWF (on the runner container) runs docker compose up, which sends the network/service definitions to the Docker daemon via the Docker API (Unix socket). In ARC/DinD, that daemon is the dind sidecar. The dind sidecar creates the networks, starts the containers, and manages all the network topology — it already runs privileged (required for dockerd).

The runner container is just a Docker API client issuing docker compose commands. It never touches iptables, never manipulates network namespaces, and never needs NET_ADMIN. All network enforcement happens inside the Docker daemon's domain.