containerd / containerd/nerdctl

Default generated nerdctl-nat.conflist does not set capabilities.portMappings=true to enable host:container port mappings

Open
#5,157 0 comments 0 reactions 0 assignees View on GitHub
area/network bug platform/Windows/Non-WSL2
Dominant language
Go
Stars
10.4k
Forks
826
Avg merge
1d 23h
Merged PRs (30d)
44

Description

### Description

I've started using containerd 2.3.3 and nerdctl 2.3.4 on Windows Server 2022 and I noticed the default generated `nerdctl-nat.conflist` is not enabling port mapping. The command `Get-Content 'C:\Program Files\containerd\cni\conf\nerdctl-nat.conflist'` gives this:

```json
{
"cniVersion": "1.0.0",
"name": "nat",
"nerdctlID": "d919a100ce6b45524d415d52d088d5817587c6dd8c3691b03b8063c44d043523",
"nerdctlLabels": {
"nerdctl/default-network": "true"
},
"plugins": [
{
"type": "nat",
"master": "Ethernet",
"ipam": {
"routes": [
{
"gateway": "10.4.0.1"
}
],
"subnet": "10.4.0.0/24",
"type": ""
}
}
]
}
```

which is missing the following piece:

```json
"capabilities": {
"portMappings": true,
"dns": true
}
```

By the way, [config examples in https://github.com/microsoft/windows-container-networking](https://github.com/microsoft/windows-container-networking/tree/1d17fb7d38f9e0acef9aadbff69a5a9e0c490c0d/example) seem to be out of date or [broken](https://github.com/microsoft/windows-container-networking/issues/83).

### Steps to reproduce the issue

1. Install containerd
2. Install nerdctl
3. Run `nerdctl run -p 5093:5093/tcp myapp:latest`
4. Observe, the ports are not mapped/forwarded and `myapp` service is not accessible from the host on any of the `http://localhost:5093`, `http://127.0.0.1:5093` or `http://HOST_IP:5093`
5. Observe `wincni.log` generated for the container does not report any mapping created.
6. Add the following snippet to the `nat` network in `C:\Program Files\containerd\cni\conf\nerdctl-nat.conflist` file

```json
"capabilities": {
"portMappings": true,
"dns": true
}
```

6. Run `Restart-Service containerd`
7. Run `nerdctl run -p 5093:5093/tcp myapp:latest`
8. Observe the `myapp` is accessible from the host on `http://127.0.0.1:5093` and `http://HOST_IP:5093`
9. Observe `wincni.log` reports the mapping:

```json
{"level":"debug","msg":"Created raw policy from mapping: {HostPort:5093 ContainerPort:5093 Protocol:udp HostIp:0.0.0.0} --- {Type:EndpointPolicy Data:[123 34 84 121 112 101 34 58 34 80 111 114 116 77 97 112 112 105 110 103 34 44 34 83 101 116 116 105 110 103 115 34 58 123 34 80 114 111 116 111 99 111 108 34 58 49 55 44 34 73 110 116 101 114 110 97 108 80 111 114 116 34 58 53 48 57 51 44 34 69 120 116 101 114 110 97 108 80 111 114 116 34 58 53 48 57 51 44 34 86 73 80 34 58 34 48 46 48 46 48 46 48 34 125 125]}","time":"2026-08-23T15:23:41+01:00"}
...
{"level":"debug","msg":"hcn::HostComputeEndpoint::Create JSON: {\"Name\":\"fde574f85ba7f2015e74e93e547c35caadf2ad8b4cb5c69105b0559d561145b6_nat\",\"HostComputeNetwork\":\"3e2cbcce-4802-4944-8717-e95886a84262\",\"Policies\":[{\"Type\":\"PortMapping\",\"Settings\":{\"Protocol\":6,\"InternalPort\":5093,\"ExternalPort\":5093,\"VIP\":\"0.0.0.0\"}},{\"Type\":\"PortMapping\",\"Settings\":{\"Protocol\":17,\"InternalPort\":5093,\"ExternalPort\":5093,\"VIP\":\"0.0.0.0\"}}],\"Dns\":{},\"Routes\":[{\"NextHop\":\"10.4.0.1\",\"DestinationPrefix\":\"0.0.0.0/0\"}],\"Health\":{\"Extra\":{}},\"SchemaVersion\":{\"Major\":2,\"Minor\":0}}","time":"2026-08-23T15:23:41+01:00"}
```

### Describe the results you received and expected

CNI configuration generated for the default `nat` network does not enablee `nerdctl run -p NNNN:MMMM ...` to be translated into Windows networking rules by the CNI plugin. Without those capabilities, the plugin would ignore those runtime-supplied mappings.

It is valid to assume that containerd/nerdctl users will expect the port mappings to be working out of the box.

### What version of nerdctl are you using?

```
PS> nerdctl version
time="2026-08-23T19:48:54+01:00" level=warning msg="unable to determine runc version" error="exec: \"runc\": executable file not found in %PATH%"
Client:
Version: v2.3.4
OS/Arch: windows/amd64
Git commit: 0ce88b9d78b13f0caebc59c6bb01885d7df24fba
buildctl:
Version: v0.31.2
GitCommit: e42e1bfd389af7203238cce77b1f7dad447285e9

Server:
containerd:
Version: v2.3.3
GitCommit: aad11006b869517fcd3009450b6f82da282e1a9b
runc:
Version:
```

### Are you using a variant of nerdctl? (e.g., Rancher Desktop)

None

### Host information

Windows Server 2022

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by locating the code that generates C:\Program Files\containerd\cni\conf\nerdctl-nat.conflist and inspect how the default nat plugin configuration is assembled. Reproduce with `nerdctl run -p 5093:5093/tcp myapp:latest` on Windows, then verify the generated configuration enables the required capabilities and that wincni.log reports the resulting port mapping.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
networking
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
72/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.