Skip to content

Commit 0e33bbe

Browse files
gjenkins8gjenkins8
committed
HIP for Container Tools OCI registry configuration support
Signed-off-by: George Jenkins <gvjenkins@gmail.com>
1 parent 82cca09 commit 0e33bbe

1 file changed

Lines changed: 166 additions & 0 deletions

File tree

‎hips/hip-XXXX.md‎

Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
1+
---
2+
hip: 9999
3+
title: "container tools specifications for OCI registry management"
4+
authors: [ "George Jenkins <gvjenkins@gmail.com>", "Andrew Block <andy.block@gmail.com>" ]
5+
created: "2025-02-16"
6+
type: "feature"
7+
status: "draft"
8+
helm-version: "4"
9+
---
10+
11+
## Abstract
12+
13+
The [Container Tools][containers-tools-project] project defines an alternative specification for managing client OCI registry configuration. Supporting more advanced features compared to Docker's `.docker/config.json` that Helm currently uses today.
14+
15+
Pertainently including [registries.conf][registries-conf], [auth.json][auth-json], as well as the other specifications in <https://github.com/containers/container-libs/blob/main/image/docs/>.
16+
17+
This HIP focuses on the initial implementation using ORAS to supports Container Tools OCI registry mamagement to supersede `.docker/config.json` within Helm.
18+
Today, `auth.json` provides the equivalent functionality to `.docker/config.json` for storing OCI registry credentials.
19+
Further HIPs will be created to expose additional functionality based on utilizing `registries.conf` and other container tools configurations.
20+
21+
[containers-tools-project]: https://github.com/containers "Container Tools project"
22+
[registries-conf]: <https://github.com/containers/container-libs/blob/main/image/docs/containers-registries.conf.5.md> "registries.conf specification"
23+
[auth-json]: <https://github.com/containers/container-libs/blob/main/image/docs/containers-auth.json.5.md> "auth.json specification"
24+
25+
## Motivation
26+
27+
Helm currently uses Docker's `.docker/config.json` file to store client OCI registry configuration today.
28+
The functionality of the `.docker/config.json` file is limited to mapping a registry domain to authentication credentials only.
29+
30+
The [CNCF-hosted](https://www.cncf.io/projects/podman-container-tools/) Container Tools project has created several specifications for managing client OCI registry configuration.
31+
These include `registries.conf`, `auth.json`, `policy.json`, etc
32+
which enable more advanced functionality for client OCI registry management than `.docker/config.json`.
33+
34+
Notably:
35+
36+
- support for repository prefixes (allowing different credentials for different prefixes)
37+
- registry mirrors
38+
- registry "aliasing"—features
39+
- allowing/denying registries
40+
- signing and verification policies
41+
42+
Helm would like to introduce features that utilize these functionalities.
43+
Helm supporting the various Container Tool configuration specifications would enable these features without requiring Helm to create or implement its own mechanisms.
44+
45+
## Rationale
46+
47+
Utilizing an existing specification and libraries enables Helm to immediately build upon an existing standard, rather than inventing its own convention.
48+
49+
The container tools project specifications were picked as being a format intended for consumption beyond the Docker application container ecosystem.
50+
51+
ORAS (the library Helm uses for supporting OCI functionality) has planned support for `registries.conf`, `auth.json`, etc for client OCI registry management.
52+
53+
Helm will fall back or prefer to `.docker/config.json` for registry authentication (see below for options) to ensure existing user workflows remain functional.
54+
55+
## Specification
56+
57+
When enabled, Helm will utilize `auth.json` for registry credentials and `registries.conf` for registry feature management:
58+
<https://github.com/containers/container-libs/blob/main/image/docs/containers-auth.json.5.md>
59+
<https://github.com/containers/container-libs/blob/main/image/docs/containers-registry.conf.json.5.md>
60+
61+
Helm will write to `auth.json` when performing OCI registry operations that modify client OCI registry configuration (e.g., `helm registry login`). And as long as the operation can be supported by `.docker/config.json`, Helm will dual-write to `.docker/config.json` for compatibility purposes. Dual-write will be removed in a future version of Helm, and Helm will write only to `auth.json`.
62+
63+
Helm will use the same filepath ordering when searching for matching OCI entries in `registries.conf` and credentials in `auth.json` as described in the respective specifications.
64+
65+
`auth.json`:
66+
67+
1. Location specified in environment variable `REGISTRY_AUTH_FILE` if set
68+
2. `${XDG_RUNTIME_DIR}/containers/auth.json` on Linux; `$HOME/.config/containers/auth.json` on Windows and macOS
69+
70+
`registries.conf`:
71+
72+
1. `$HOME/.config/containers/registries.conf` if it exists
73+
2. Otherwise `/etc/containers/registries.conf`
74+
75+
Helm will use ORAS v3 for updating (and reading) `registries.conf` / `auth.json`, working with the ORAS project to build support.
76+
Container tools OCI config support won't move out of experimental until support is deemed sufficent (see below).
77+
Helm must utilize any `credHelpers` specified in `auth.json`.
78+
79+
If reading a registry configuration from `registries.conf` or `auth.json` results in a configuration that Helm does not support, Helm must ignore that entry (e.g., a `location` field or non-empty URI path).
80+
As ORAS gains support for additional `registries.conf`, `auth.json`, etc features, Helm will also gain support for these features.
81+
Helm must ensure these features do not break backwards compatibility guarantees.
82+
83+
If an error occurs while reading `registries.conf` or `auth.json`, etc, Helm must report an error to the user.
84+
Otherwise, users who expect configuration from `registries.conf` / `auth.json`, etc to be effective may encounter unexpected fallback behavior.
85+
86+
Helm must expect (and even encourage) users to utilize other tooling to manage `registries.conf`, `auth.json`, etc.
87+
88+
## `registries.conf`/`auth.json` vs. `.docker/config.json`
89+
90+
To manage the release, Helm will introduce an environment variable `HELM_EXPERIMENTAL_OCI_CONTAINERS_CONFIG`.
91+
Initially, when unset or set to `false`, Helm will continue to use only `.docker/config.json`.
92+
When set to `true`, Helm will enable `registries.conf` / `auth.json`, etc support as described herein.
93+
94+
Once stable, Helm will default the unset behavior of `HELM_EXPERIMENTAL_OCI_CONTAINERS_CONFIG` to enable `registries.conf` / `auth.json`, etc support.
95+
And eventually remove the environment variable altogether. Potentially requiring Helm v5 (next major version of Helm) to do both.
96+
97+
### Example: basic login
98+
99+
For example, a registry login command:
100+
101+
```bash
102+
helm registry login "registry.example.com" --username foo --password bar
103+
```
104+
105+
Will result in the `auth.json` excerpt:
106+
107+
```json
108+
# auth.json
109+
"auths": {
110+
...
111+
"registry.example.com/theprefix": {
112+
"auth": "Zm9vOmJhcgo="
113+
}
114+
}
115+
```
116+
117+
## Backwards compatibility
118+
119+
Helm's fallback to Docker's registry configuration ensures the vast majority of existing user workflows remain the same.
120+
121+
However, there are two potential incompatibility scenarios:
122+
123+
1. A corrupt `registries.conf` / `auth.json`, etc will cause an error for existing workflows
124+
2. An invalid or incompatible with Helm `registries.conf` / `auth.json` entry for the given OCI registry will cause the user's workflow to fail
125+
126+
The first two can be mitigated by users ensuring their system's `registries.conf` / `auth.json` are valid, and only including configuration options Helm supports for the registries they plan to use with Helm.
127+
128+
## Security implications
129+
130+
- Support for signing and access control policy `policy.json` should improve OCI access management
131+
- `auth.json` introduces a new mechanism for storing OCI credentials, which may introduce credential management vulnerabilities specific to `auth.json`
132+
- `registries.conf` can introduce mirroring and redirection of OCI requests
133+
134+
## How to teach this
135+
136+
Helm's documentation will need to be updated with details of Helm's `registries.conf` / `auth.json` support and fallback to `.docker/config.json`.
137+
138+
## Reference implementation
139+
140+
- TODO: link to ORAS v3 `registries.conf` / `auth.json` implementation, in progress
141+
- TODO: create experimental PR/branch for Helm implementing this HIP
142+
143+
## Rejected ideas
144+
145+
### Falling back to Docker’s config upon error reading registries.conf
146+
147+
Falling back upon error means users who expect their configuration to be taken from `registries.conf` will unexpectedly have OCI configuration taken from Docker, potentially resulting in difficult to diagnose failures authenticating to the repository.
148+
149+
Rather than "failing fast" and requiring users to ensure their configuration is valid.
150+
151+
## Open issues
152+
153+
- ORAS `registries.conf` support: <https://github.com/oras-project/oras-go/issues/918>
154+
- Is the release and backwards compatibility plan good enough?
155+
- ~~Discuss Helm's/ORAS's potential usage of `registries.conf` with `registries.conf` owners~~
156+
157+
## References
158+
159+
### ORAS credential store (Docker registry configuration) docs
160+
161+
<https://pkg.go.dev/oras.land/oras-go/v2/registry/remote/credentials#NewStoreFromDocker>
162+
163+
### `registries.conf` / `auth.json` specifications
164+
165+
<https://github.com/containers/container-libs/blob/main/image/docs/containers-registries.conf.5.md>
166+
<https://github.com/containers/container-libs/blob/main/image/docs/containers-auth.json.5.md>

0 commit comments

Comments
 (0)