From 1b8955009dc8de73480a60730a48ec936c9be9df Mon Sep 17 00:00:00 2001 From: George Jenkins Date: Thu, 20 Feb 2025 12:25:11 -0800 Subject: [PATCH 1/9] work Signed-off-by: George Jenkins --- hips/hip-XXXX.md | 130 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 130 insertions(+) create mode 100644 hips/hip-XXXX.md diff --git a/hips/hip-XXXX.md b/hips/hip-XXXX.md new file mode 100644 index 000000000..f3ca73f65 --- /dev/null +++ b/hips/hip-XXXX.md @@ -0,0 +1,130 @@ +--- +hip: 9999 +title: "registries.conf support for OCI registry management" +authors: [ "George Jenkins ", "Andy Block " ] +created: "2025-02-16" +type: "feature" +status: "draft" +--- + +## Abstract + +[registries.conf][registries-conf] is a an alternative specification (to Docker's `docker/config.json`) for managing OCI registry configuration. That supports more advanced features, and has been standardized by other container ecosystem CLI tools (podman, buildah, skopeo, etc) + +Support would extend Helm's flexilbity with respect to OCI configuration, including repository prefixes and aliases. This HIP focuces on the implementation of supporting `registries.conf`. Further HIPs to be created for exposing functionality based on utilzing `registries.conf`. + +[registries-conf]: "registries.conf specification" + +## Motivation + +`registries.conf` provides much more flexibible support for OCI registry management than the current Docker CLI based configuration format that Helm uses today. + +Including support for repository prefixes (allowing different credentials for different prefixes), registry mirrors, and registry "aliasing". Features Helm would like to introduce. But is currenly blocked by a lack of mechanism to store detail + +(in particular, the existing registry configuration Helm uses, Docker’s `$HOME/.docker/config.json`, etc do not support registry aliases nor prefixes) + +## Rationale + +Utilizing an existing specification / libraries enables Helm immediate build upon an existing standard. +Rather than Helm inventing its own convention. + +`registries.conf` was picked as being a format intended for consumption beyond the Docker application container ecosystem. + +## Specification + +Helm will utilize the `registries.conf` specification when determinging OCI registry information (authentication credentials, etc): + + + +`registries.conf` will be preferred, either when a `registries.conf` file already exists on the users system. +Or when Helm supports and a user utilizes functionality that can not be supported by Docker's comnfigurtation file in the future. + + + +For example, a registry login command: +```bash +helm registry login "oci.example.com" --username foo --password bar +``` + +Will result in the configration exerpt (if, and only if, `registries.conf` exists on the users local system): +```toml +# registries.conf +[[registry]] +prefix = "oci.example.com" +``` + +```json +# auth.json +"auths": { + ... + "oci.example.com": { + "auth": "Zm9vOmJhcgo=" + } +} +``` + +Helm will use the package TBD for updating (and reading) `registries.conf`. + +If when reading a registries configation from `registries.conf` results in known configuration Helm doesn't support, Helm must error. +e.g. `location` or non-empty URI path in `prefix`. + +An error reading `registries.conf` must result in an error for the user. +Otherwise, users who expect configration from `registries.conf` to be effected, will have a unspected fallback. + +To account for existing configration in Docker’s registry configuration, Helm will prefer `registries.conf` when resolving OCI registries (including credentials). +And fall back to the existing store mechanism if `registries.conf` does not contain an entry for the required OCI registry (including if `registries.conf` does not exist). + +Helm must expect (and even encourage) users to utilize other tooling to manage `registries.conf`. + +## Backwards compatibility + +Helm's fallback to Docker's registry configuration ensures the vast majority of existing user workflows remain the same. + +However, there are three potential incompatibility scenarios: +2. A corrupt `registries.conf` will cause an error for existing workflows +1. An invalid or incompatible with Helm `registries.conf` entry for the given OCI registry will cause the users workflow to fail +3. Helm’s preference for `registries.conf` will break users who assume credentials are stored in Docker’s registry configuration + +The first two can mitigated by users ensuring their systems `registries.conf` is valid, and only includes configuration options Helm supports for the registries they plan to use with Helm. + +The last is mitigated by not using `registries.conf` initially unless it exists on the users system. + +## Security implications + +`registries.conf` introduces a new mechanism for storing OCI credentials, which may introduce credential management vulnerabilities specific to `registries.conf` / `auth.json` + +Transitive dependencies of the TBD package for managing registries.conf may introduce security scanner noise (which tends to be a problem in the container library ecosystem) + +## How to teach this + +Helm's documentation will need to be updated with details of Helm's `registries.conf` support, and fallback to Docker config. + +## Reference implementation + + + +## Rejected ideas + +### Falling back to Docker’s config upon error reading registries.conf + +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. + +Rather than "failing fast" and requring users to ensure their configuration to be valid. + +## Open issues + +- Support for registies.conf in ORAS +- Disucss Helm's/ORAS's usage of registries.conf with owners + +## References + +### ORAS credential store (registry configuration) docs + +https://pkg.go.dev/oras.land/oras-go/v2/registry/remote/credentials#NewStoreFromDocker + +### registries.conf specification +https://github.com/containers/image/blob/main/docs/containers-registries.conf.5.md From 6335ac478f7860fa046bbc77fa34e6b54bab7c1e Mon Sep 17 00:00:00 2001 From: George Jenkins Date: Mon, 3 Nov 2025 14:40:44 -0800 Subject: [PATCH 2/9] rework Signed-off-by: George Jenkins --- hips/hip-XXXX.md | 73 ++++++++++++++++++++++++++---------------------- 1 file changed, 40 insertions(+), 33 deletions(-) diff --git a/hips/hip-XXXX.md b/hips/hip-XXXX.md index f3ca73f65..4977dc97b 100644 --- a/hips/hip-XXXX.md +++ b/hips/hip-XXXX.md @@ -9,44 +9,52 @@ status: "draft" ## Abstract -[registries.conf][registries-conf] is a an alternative specification (to Docker's `docker/config.json`) for managing OCI registry configuration. That supports more advanced features, and has been standardized by other container ecosystem CLI tools (podman, buildah, skopeo, etc) +[registries.conf][registries-conf] is an alternative specification for managing client OCI registry configuration that supports more advanced features, compared to Docker's `docker/config.json` that Helm currently uses today. -Support would extend Helm's flexilbity with respect to OCI configuration, including repository prefixes and aliases. This HIP focuces on the implementation of supporting `registries.conf`. Further HIPs to be created for exposing functionality based on utilzing `registries.conf`. +This HIP focuses on the initial implementation of supporting `registries.conf` within Helm. +Further HIPs will be created to expose additional functionality based on utilizing `registries.conf`. [registries-conf]: "registries.conf specification" ## Motivation -`registries.conf` provides much more flexibible support for OCI registry management than the current Docker CLI based configuration format that Helm uses today. +Helm uses Docker's `docker/config.json` to store client OCI registry configuration today. -Including support for repository prefixes (allowing different credentials for different prefixes), registry mirrors, and registry "aliasing". Features Helm would like to introduce. But is currenly blocked by a lack of mechanism to store detail +`registries.conf` provides much more advanced functionality for client OCI registry management than `docker/config.json`. +Notably: -(in particular, the existing registry configuration Helm uses, Docker’s `$HOME/.docker/config.json`, etc do not support registry aliases nor prefixes) +- support for repository prefixes (allowing different credentials for different prefixes) +- registry mirrors +- registry "aliasing"—features + +Helm would like to introduce features depending on these functionalities. Supporting `registries.conf` would enable them without Helm having to create or implement its own mechanisms. +With `registries.conf` having been standardized by other container ecosystem CLI tools (podman, buildah, skopeo, etc.). ## Rationale -Utilizing an existing specification / libraries enables Helm immediate build upon an existing standard. -Rather than Helm inventing its own convention. +Utilizing an existing specification and libraries enables Helm to immediately build upon an existing standard, rather than inventing its own convention. `registries.conf` was picked as being a format intended for consumption beyond the Docker application container ecosystem. +ORAS (the library Helm uses for supporting OCI functionality) has planned support for `registries.conf` client-side OCI registry management. + ## Specification -Helm will utilize the `registries.conf` specification when determinging OCI registry information (authentication credentials, etc): +Helm will utilize the `registries.conf` specification when determining OCI registry information (authentication credentials, etc.): - -`registries.conf` will be preferred, either when a `registries.conf` file already exists on the users system. -Or when Helm supports and a user utilizes functionality that can not be supported by Docker's comnfigurtation file in the future. +`registries.conf` will be preferred either when a `registries.conf` file already exists on the user's system, or when Helm supports and a user utilizes functionality that cannot be supported by Docker's configuration file in the future. For example, a registry login command: + ```bash helm registry login "oci.example.com" --username foo --password bar ``` -Will result in the configration exerpt (if, and only if, `registries.conf` exists on the users local system): +Will result in the configuration excerpt (if, and only if, `registries.conf` exists on the user's local system): + ```toml # registries.conf [[registry]] @@ -63,16 +71,13 @@ prefix = "oci.example.com" } ``` -Helm will use the package TBD for updating (and reading) `registries.conf`. +Helm will use ORAS v3 for updating (and reading) `registries.conf` (TODO: link to ORAS v3 `registries.conf` implementation). -If when reading a registries configation from `registries.conf` results in known configuration Helm doesn't support, Helm must error. -e.g. `location` or non-empty URI path in `prefix`. +If reading a registry configuration from `registries.conf` results in a known configuration that Helm doesn't support, Helm must report a warning (e.g., `location` or non-empty URI path in `prefix`). -An error reading `registries.conf` must result in an error for the user. -Otherwise, users who expect configration from `registries.conf` to be effected, will have a unspected fallback. +An error reading `registries.conf` must result in an error for the user. Otherwise, users who expect configuration from `registries.conf` to be effective will have an unexpected fallback. -To account for existing configration in Docker’s registry configuration, Helm will prefer `registries.conf` when resolving OCI registries (including credentials). -And fall back to the existing store mechanism if `registries.conf` does not contain an entry for the required OCI registry (including if `registries.conf` does not exist). +To account for existing configuration in Docker’s registry configuration, Helm will prefer `registries.conf` when resolving OCI registries (including credentials), and fall back to the existing storage mechanism if `registries.conf` does not contain an entry for the required OCI registry (including if `registries.conf` does not exist). Helm must expect (and even encourage) users to utilize other tooling to manage `registries.conf`. @@ -81,23 +86,24 @@ Helm must expect (and even encourage) users to utilize other tooling to manage ` Helm's fallback to Docker's registry configuration ensures the vast majority of existing user workflows remain the same. However, there are three potential incompatibility scenarios: -2. A corrupt `registries.conf` will cause an error for existing workflows -1. An invalid or incompatible with Helm `registries.conf` entry for the given OCI registry will cause the users workflow to fail + +1. A corrupt `registries.conf` will cause an error for existing workflows +2. An invalid or incompatible with Helm `registries.conf` entry for the given OCI registry will cause the user's workflow to fail 3. Helm’s preference for `registries.conf` will break users who assume credentials are stored in Docker’s registry configuration -The first two can mitigated by users ensuring their systems `registries.conf` is valid, and only includes configuration options Helm supports for the registries they plan to use with Helm. +The first two can be mitigated by users ensuring their system's `registries.conf` is valid, and only includes configuration options Helm supports for the registries they plan to use with Helm. -The last is mitigated by not using `registries.conf` initially unless it exists on the users system. +The last is mitigated by not using `registries.conf` initially unless it exists on the user's system. ## Security implications `registries.conf` introduces a new mechanism for storing OCI credentials, which may introduce credential management vulnerabilities specific to `registries.conf` / `auth.json` -Transitive dependencies of the TBD package for managing registries.conf may introduce security scanner noise (which tends to be a problem in the container library ecosystem) +Transitive dependencies of the TBD package for managing `registries.conf` may introduce security scanner noise (which tends to be a problem in the container library ecosystem) ## How to teach this -Helm's documentation will need to be updated with details of Helm's `registries.conf` support, and fallback to Docker config. +Helm's documentation will need to be updated with details of Helm's `registries.conf` support and fallback to Docker config. ## Reference implementation @@ -110,21 +116,22 @@ proof-of-concept. ### Falling back to Docker’s config upon error reading registries.conf -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. +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. -Rather than "failing fast" and requring users to ensure their configuration to be valid. +Rather than "failing fast" and requiring users to ensure their configuration is valid. ## Open issues -- Support for registies.conf in ORAS -- Disucss Helm's/ORAS's usage of registries.conf with owners +- ORAS `registries.conf` support: +- Is the release and backwards compatibility plan good enough? +- Discuss Helm's/ORAS's potential usage of `registries.conf` with `registries.conf` owners ## References -### ORAS credential store (registry configuration) docs +### ORAS credential store (Docker registry configuration) docs -https://pkg.go.dev/oras.land/oras-go/v2/registry/remote/credentials#NewStoreFromDocker + ### registries.conf specification -https://github.com/containers/image/blob/main/docs/containers-registries.conf.5.md + + From 7588b79d6dfc2b5e9ea377b7f49431917e060626 Mon Sep 17 00:00:00 2001 From: George Jenkins Date: Fri, 7 Nov 2025 13:48:16 -0800 Subject: [PATCH 3/9] update Signed-off-by: George Jenkins --- hips/hip-XXXX.md | 136 +++++++++++++++++++++++++++++++++-------------- 1 file changed, 96 insertions(+), 40 deletions(-) diff --git a/hips/hip-XXXX.md b/hips/hip-XXXX.md index 4977dc97b..9fbc9780d 100644 --- a/hips/hip-XXXX.md +++ b/hips/hip-XXXX.md @@ -1,24 +1,34 @@ --- hip: 9999 title: "registries.conf support for OCI registry management" -authors: [ "George Jenkins ", "Andy Block " ] +authors: [ "George Jenkins ", "Andrew Block " ] created: "2025-02-16" type: "feature" status: "draft" +helm-version: "4" --- ## Abstract -[registries.conf][registries-conf] is an alternative specification for managing client OCI registry configuration that supports more advanced features, compared to Docker's `docker/config.json` that Helm currently uses today. +[registries.conf][registries-conf] (and related) are an alternative specification for managing client OCI registry configuration that supports more advanced features, compared to Docker's `docker/config.json` that Helm currently uses today. -This HIP focuses on the initial implementation of supporting `registries.conf` within Helm. +This HIP focuses on the initial implementation of supporting `registries.conf` / [auth.json][auth-json] to supersede `docker/config.json` within Helm via ORAS. +Today, `auth.json` provides the equivalent functionality to `docker/config.json` for storing OCI registry credentials. Further HIPs will be created to expose additional functionality based on utilizing `registries.conf`. -[registries-conf]: "registries.conf specification" +[registries-conf]: "registries.conf specification" +[auth-json]: "auth.json specification" + + ## Motivation Helm uses Docker's `docker/config.json` to store client OCI registry configuration today. +Configuration here is limited to mapping a registry domain to authentication credentials. `registries.conf` provides much more advanced functionality for client OCI registry management than `docker/config.json`. Notably: @@ -26,9 +36,11 @@ Notably: - support for repository prefixes (allowing different credentials for different prefixes) - registry mirrors - registry "aliasing"—features +- allowing/denying registries -Helm would like to introduce features depending on these functionalities. Supporting `registries.conf` would enable them without Helm having to create or implement its own mechanisms. -With `registries.conf` having been standardized by other container ecosystem CLI tools (podman, buildah, skopeo, etc.). +Helm intends to introduce features that utilize these functionalities. +Supporting `registries.conf` would enable these features without requiring Helm to create or implement its own mechanisms. +This is possible because `registries.conf` has been standardized by the CNCF-hosted [Podman container tools project](https://www.cncf.io/projects/podman-container-tools/). ## Rationale @@ -36,50 +48,97 @@ Utilizing an existing specification and libraries enables Helm to immediately bu `registries.conf` was picked as being a format intended for consumption beyond the Docker application container ecosystem. -ORAS (the library Helm uses for supporting OCI functionality) has planned support for `registries.conf` client-side OCI registry management. +ORAS (the library Helm uses for supporting OCI functionality) has planned support for `registries.conf` client OCI registry management. + +Helm will fall back or prefer to `docker/config.json` for registry authentication (see below for options) to ensure existing user workflows remain functional. ## Specification -Helm will utilize the `registries.conf` specification when determining OCI registry information (authentication credentials, etc.): - +When enabled, Helm will utilize the `registries.conf` specification when determining OCI registry information and `auth.json` for registry credentials: + + + +Helm will write to `registries.conf` / `auth.json`, should either of these files exist, when performing OCI registry operations that modify client OCI registry configuration (e.g., `helm registry login`). 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 `registries.conf` / `auth.json`. + +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. + +`registries.conf`: + +1. `$HOME/.config/containers/registries.conf` if it exists +2. Otherwise `/etc/containers/registries.conf` + +`auth.json`: + +1. Location specified in environment variable `REGISTRY_AUTH_FILE` if set +2. `${XDG_RUNTIME_DIR}/containers/auth.json` on Linux; `$HOME/.config/containers/auth.json` on Windows and macOS + +Helm will use ORAS v3 for updating (and reading) `registries.conf` / `auth.json`. +Helm must utilize any `credHelpers` specified in `auth.json`. -`registries.conf` will be preferred either when a `registries.conf` file already exists on the user's system, or when Helm supports and a user utilizes functionality that cannot be supported by Docker's configuration file in the future. +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). - +If an error occurs while reading `registries.conf` or `auth.json`, Helm must report an error to the user. Otherwise, users who expect configuration from `registries.conf` / `auth.json` to be effective may encounter unexpected fallback behavior. + +Helm must expect (and even encourage) users to utilize other tooling to manage `registries.conf`. + +## `registries.conf`/`auth.json` vs. `docker/config.json` preference + +To manage the release, Helm will introduce an environment variable `HELM_EXPERIMENTAL_OCI_REGISTRIES_CONF`. +Initially, when unset or set to `false`, Helm will continue to use only `docker/config.json`. +When set to `true`, Helm will enable `registries.conf` / `auth.json` support as described herein. + +Once stable: + +1. Helm will default the unset behavior of `HELM_EXPERIMENTAL_OCI_REGISTRIES_CONF` to enable `registries.conf` / `auth.json` support. +Then eventually remove the environment variable altogether. +2. If necessary, as determined by community feedback, Helm will introduce an environment variable `HELM_OCI_AUTH_CONFIG_PREFERENCE=registriesconf|docker` to control the preference order used when resolving OCI registries configuration (including credentials). +The default value of `HELM_OCI_AUTH_CONFIG_PREFERENCE` will be determined based on community feedback. + +If `docker` is the default, Helm users who expect features from `registries.conf` or `auth.json` to be effective will instead have their configuration determined by `docker/config.json`. +If `registriesconf` is the default, Helm users with erroneous `registries.conf` or `auth.json` configurations will experience authentication failures to OCI registries until they correct their configuration. + +Introducing an `HELM_OCI_AUTH_CONFIG_PREFERENCE` variable will add complexity for Helm users and should only be implemented if necessary. That is, defaulting to `registriesconf` would cause significant user disruption. + +### Example: basic login For example, a registry login command: ```bash -helm registry login "oci.example.com" --username foo --password bar +helm registry login "registry.example.com" --username foo --password bar ``` -Will result in the configuration excerpt (if, and only if, `registries.conf` exists on the user's local system): +Will result in the `auth.json` excerpt: + +```json +# auth.json +"auths": { + ... + "registry.example.com/theprefix": { + "auth": "Zm9vOmJhcgo=" + } +} +``` + + ## Backwards compatibility @@ -87,30 +146,26 @@ Helm's fallback to Docker's registry configuration ensures the vast majority of However, there are three potential incompatibility scenarios: -1. A corrupt `registries.conf` will cause an error for existing workflows -2. An invalid or incompatible with Helm `registries.conf` entry for the given OCI registry will cause the user's workflow to fail -3. Helm’s preference for `registries.conf` will break users who assume credentials are stored in Docker’s registry configuration +1. A corrupt `registries.conf` / `auth.json` will cause an error for existing workflows +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 +3. Helm’s preference for `registries.conf` / `auth.json` will break users who assume credentials are stored in Docker’s registry configuration The first two can be mitigated by users ensuring their system's `registries.conf` is valid, and only includes configuration options Helm supports for the registries they plan to use with Helm. -The last is mitigated by not using `registries.conf` initially unless it exists on the user's system. +The last is mitigated by not using `registries.conf` / `auth.json` initially unless these exist on the user's system. Finally, defaulting to `HELM_OCI_AUTH_CONFIG_PREFERENCE=docker` as the default, if necessary, will retain full compatibility with existing workflows. ## Security implications -`registries.conf` introduces a new mechanism for storing OCI credentials, which may introduce credential management vulnerabilities specific to `registries.conf` / `auth.json` - -Transitive dependencies of the TBD package for managing `registries.conf` may introduce security scanner noise (which tends to be a problem in the container library ecosystem) +`registries.conf` / `auth.json` introduces a new mechanism for storing OCI credentials, which may introduce credential management vulnerabilities specific to `registries.conf` / `auth.json`. ## How to teach this -Helm's documentation will need to be updated with details of Helm's `registries.conf` support and fallback to Docker config. +Helm's documentation will need to be updated with details of Helm's `registries.conf` / `auth.json` support and fallback to `docker/config.json`. ## Reference implementation - +- TODO: link to ORAS v3 `registries.conf` implementation, in progress +- TODO: create experimental PR/branch for Helm implementing this HIP ## Rejected ideas @@ -124,7 +179,7 @@ Rather than "failing fast" and requiring users to ensure their configuration is - ORAS `registries.conf` support: - Is the release and backwards compatibility plan good enough? -- Discuss Helm's/ORAS's potential usage of `registries.conf` with `registries.conf` owners +- ~~Discuss Helm's/ORAS's potential usage of `registries.conf` with `registries.conf` owners~~ ## References @@ -132,6 +187,7 @@ Rather than "failing fast" and requiring users to ensure their configuration is -### registries.conf specification +### `registries.conf` / `auth.json` specifications - + + From 850727af312d9270cc4a5e8a6b8633efab2d8c5d Mon Sep 17 00:00:00 2001 From: George Jenkins Date: Fri, 7 Nov 2025 15:13:22 -0800 Subject: [PATCH 4/9] features Signed-off-by: George Jenkins --- hips/hip-XXXX.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/hips/hip-XXXX.md b/hips/hip-XXXX.md index 9fbc9780d..fa8df3b3c 100644 --- a/hips/hip-XXXX.md +++ b/hips/hip-XXXX.md @@ -76,6 +76,8 @@ Helm will use ORAS v3 for updating (and reading) `registries.conf` / `auth.json` Helm must utilize any `credHelpers` specified in `auth.json`. 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). +As ORAS gains support for additional `registries.conf` features, Helm will also gain support for these features. +Helm must ensure these features do not break backwards compatibility guarantees. If an error occurs while reading `registries.conf` or `auth.json`, Helm must report an error to the user. Otherwise, users who expect configuration from `registries.conf` / `auth.json` to be effective may encounter unexpected fallback behavior. From b96cb0fa65b6033e5dcc951c36eeaedfba2bfb2c Mon Sep 17 00:00:00 2001 From: George Jenkins Date: Fri, 7 Nov 2025 15:15:19 -0800 Subject: [PATCH 5/9] cleanup Signed-off-by: George Jenkins --- hips/hip-XXXX.md | 27 --------------------------- 1 file changed, 27 deletions(-) diff --git a/hips/hip-XXXX.md b/hips/hip-XXXX.md index fa8df3b3c..1337ae39a 100644 --- a/hips/hip-XXXX.md +++ b/hips/hip-XXXX.md @@ -19,12 +19,6 @@ Further HIPs will be created to expose additional functionality based on utilizi [registries-conf]: "registries.conf specification" [auth-json]: "auth.json specification" - - ## Motivation Helm uses Docker's `docker/config.json` to store client OCI registry configuration today. @@ -121,27 +115,6 @@ Will result in the `auth.json` excerpt: } ``` - - ## Backwards compatibility Helm's fallback to Docker's registry configuration ensures the vast majority of existing user workflows remain the same. From b00f3344f5751c22df9b421a38ee270343110c1a Mon Sep 17 00:00:00 2001 From: George Jenkins Date: Sun, 9 Nov 2025 17:27:53 -0500 Subject: [PATCH 6/9] Remove `HELM_OCI_AUTH_CONFIG_PREFERENCE` Signed-off-by: George Jenkins --- hips/hip-XXXX.md | 15 +++------------ 1 file changed, 3 insertions(+), 12 deletions(-) diff --git a/hips/hip-XXXX.md b/hips/hip-XXXX.md index 1337ae39a..e57b0d922 100644 --- a/hips/hip-XXXX.md +++ b/hips/hip-XXXX.md @@ -83,17 +83,8 @@ To manage the release, Helm will introduce an environment variable `HELM_EXPERIM Initially, when unset or set to `false`, Helm will continue to use only `docker/config.json`. When set to `true`, Helm will enable `registries.conf` / `auth.json` support as described herein. -Once stable: - -1. Helm will default the unset behavior of `HELM_EXPERIMENTAL_OCI_REGISTRIES_CONF` to enable `registries.conf` / `auth.json` support. -Then eventually remove the environment variable altogether. -2. If necessary, as determined by community feedback, Helm will introduce an environment variable `HELM_OCI_AUTH_CONFIG_PREFERENCE=registriesconf|docker` to control the preference order used when resolving OCI registries configuration (including credentials). -The default value of `HELM_OCI_AUTH_CONFIG_PREFERENCE` will be determined based on community feedback. - -If `docker` is the default, Helm users who expect features from `registries.conf` or `auth.json` to be effective will instead have their configuration determined by `docker/config.json`. -If `registriesconf` is the default, Helm users with erroneous `registries.conf` or `auth.json` configurations will experience authentication failures to OCI registries until they correct their configuration. - -Introducing an `HELM_OCI_AUTH_CONFIG_PREFERENCE` variable will add complexity for Helm users and should only be implemented if necessary. That is, defaulting to `registriesconf` would cause significant user disruption. +Once stable, Helm will default the unset behavior of `HELM_EXPERIMENTAL_OCI_REGISTRIES_CONF` to enable `registries.conf` / `auth.json` support. +And eventually remove the environment variable altogether. ### Example: basic login @@ -127,7 +118,7 @@ However, there are three potential incompatibility scenarios: The first two can be mitigated by users ensuring their system's `registries.conf` is valid, and only includes configuration options Helm supports for the registries they plan to use with Helm. -The last is mitigated by not using `registries.conf` / `auth.json` initially unless these exist on the user's system. Finally, defaulting to `HELM_OCI_AUTH_CONFIG_PREFERENCE=docker` as the default, if necessary, will retain full compatibility with existing workflows. +The last is mitigated by not using `registries.conf` / `auth.json` initially unless these exist on the user's system. ## Security implications From ec384fb329d6377365a95623873e30f8b3e09e30 Mon Sep 17 00:00:00 2001 From: George Jenkins Date: Mon, 10 Nov 2025 11:38:25 -0500 Subject: [PATCH 7/9] 'container tools' update Signed-off-by: George Jenkins --- hips/hip-XXXX.md | 80 +++++++++++++++++++++++++----------------------- 1 file changed, 42 insertions(+), 38 deletions(-) diff --git a/hips/hip-XXXX.md b/hips/hip-XXXX.md index e57b0d922..8908ac4f8 100644 --- a/hips/hip-XXXX.md +++ b/hips/hip-XXXX.md @@ -1,6 +1,6 @@ --- hip: 9999 -title: "registries.conf support for OCI registry management" +title: "container tools specifications for OCI registry management" authors: [ "George Jenkins ", "Andrew Block " ] created: "2025-02-16" type: "feature" @@ -10,81 +10,88 @@ helm-version: "4" ## Abstract -[registries.conf][registries-conf] (and related) are an alternative specification for managing client OCI registry configuration that supports more advanced features, compared to Docker's `docker/config.json` that Helm currently uses today. +The [container tools][containers-tools-project] project defines an alternative specification for managing client OCI registry configuration that supports more advanced features. Compared to Docker's `docker/config.json` that Helm currently uses today. -This HIP focuses on the initial implementation of supporting `registries.conf` / [auth.json][auth-json] to supersede `docker/config.json` within Helm via ORAS. +Pertainently these include [registries.conf][registries-conf], [auth.json][auth-json], as well as the other specifications in . + +This HIP focuses on the initial implementation using ORAS to supports containers' OCI registry mamagement to supersede `docker/config.json` within Helm. Today, `auth.json` provides the equivalent functionality to `docker/config.json` for storing OCI registry credentials. -Further HIPs will be created to expose additional functionality based on utilizing `registries.conf`. +Further HIPs will be created to expose additional functionality based on utilizing `registries.conf` and other container tools configurations. +[containers-tools-project]: https://github.com/containers "container tools project" [registries-conf]: "registries.conf specification" -[auth-json]: "auth.json specification" +[auth-json]: "auth.json specification" ## Motivation -Helm uses Docker's `docker/config.json` to store client OCI registry configuration today. -Configuration here is limited to mapping a registry domain to authentication credentials. +Helm currently uses Docker's `docker/config.json` to store client OCI registry configuration today. +Limited to mapping a registry domain to authentication credentials only. + +The [CNCF-hosted](https://www.cncf.io/projects/podman-container-tools/) has created several specification for managing client OCI registry configuration. +These are `registries.conf`, `auth.json`, `policy.json`, etc. Which provide much more advanced functionality for client OCI registry management than `docker/config.json`. -`registries.conf` provides much more advanced functionality for client OCI registry management than `docker/config.json`. Notably: - support for repository prefixes (allowing different credentials for different prefixes) - registry mirrors - registry "aliasing"—features - allowing/denying registries +- signing and verification policies -Helm intends to introduce features that utilize these functionalities. -Supporting `registries.conf` would enable these features without requiring Helm to create or implement its own mechanisms. -This is possible because `registries.conf` has been standardized by the CNCF-hosted [Podman container tools project](https://www.cncf.io/projects/podman-container-tools/). +Helm would like to introduce features that utilize these functionalities. +Supporting containers' configuration specifications would enable these features without requiring Helm to create or implement its own mechanisms. ## Rationale Utilizing an existing specification and libraries enables Helm to immediately build upon an existing standard, rather than inventing its own convention. -`registries.conf` was picked as being a format intended for consumption beyond the Docker application container ecosystem. +The container tools project specifications were picked as being a format intended for consumption beyond the Docker application container ecosystem. -ORAS (the library Helm uses for supporting OCI functionality) has planned support for `registries.conf` client OCI registry management. +ORAS (the library Helm uses for supporting OCI functionality) has planned support for `registries.conf`, `auth.json`, etc for client OCI registry management. Helm will fall back or prefer to `docker/config.json` for registry authentication (see below for options) to ensure existing user workflows remain functional. ## Specification -When enabled, Helm will utilize the `registries.conf` specification when determining OCI registry information and `auth.json` for registry credentials: - - +When enabled, Helm will utilize `auth.json` for registry credentials and `registries.conf` for registry feature management: + + -Helm will write to `registries.conf` / `auth.json`, should either of these files exist, when performing OCI registry operations that modify client OCI registry configuration (e.g., `helm registry login`). 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 `registries.conf` / `auth.json`. +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`. 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. -`registries.conf`: - -1. `$HOME/.config/containers/registries.conf` if it exists -2. Otherwise `/etc/containers/registries.conf` - `auth.json`: 1. Location specified in environment variable `REGISTRY_AUTH_FILE` if set 2. `${XDG_RUNTIME_DIR}/containers/auth.json` on Linux; `$HOME/.config/containers/auth.json` on Windows and macOS -Helm will use ORAS v3 for updating (and reading) `registries.conf` / `auth.json`. +`registries.conf`: + +1. `$HOME/.config/containers/registries.conf` if it exists +2. Otherwise `/etc/containers/registries.conf` + +Helm will use ORAS v3 for updating (and reading) `registries.conf` / `auth.json`, working with the ORAS project to build support. +Container tools OCI config support won't move out of experimental until support is deemed sufficent (see below). Helm must utilize any `credHelpers` specified in `auth.json`. 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). -As ORAS gains support for additional `registries.conf` features, Helm will also gain support for these features. +As ORAS gains support for additional `registries.conf`, `auth.json`, etc features, Helm will also gain support for these features. Helm must ensure these features do not break backwards compatibility guarantees. -If an error occurs while reading `registries.conf` or `auth.json`, Helm must report an error to the user. Otherwise, users who expect configuration from `registries.conf` / `auth.json` to be effective may encounter unexpected fallback behavior. +If an error occurs while reading `registries.conf` or `auth.json`, etc, Helm must report an error to the user. +Otherwise, users who expect configuration from `registries.conf` / `auth.json`, etc to be effective may encounter unexpected fallback behavior. -Helm must expect (and even encourage) users to utilize other tooling to manage `registries.conf`. +Helm must expect (and even encourage) users to utilize other tooling to manage `registries.conf`, `auth.json`, etc. ## `registries.conf`/`auth.json` vs. `docker/config.json` preference -To manage the release, Helm will introduce an environment variable `HELM_EXPERIMENTAL_OCI_REGISTRIES_CONF`. +To manage the release, Helm will introduce an environment variable `HELM_EXPERIMENTAL_OCI_CONTAINERS_CONFIG`. Initially, when unset or set to `false`, Helm will continue to use only `docker/config.json`. -When set to `true`, Helm will enable `registries.conf` / `auth.json` support as described herein. +When set to `true`, Helm will enable `registries.conf` / `auth.json`, etc support as described herein. -Once stable, Helm will default the unset behavior of `HELM_EXPERIMENTAL_OCI_REGISTRIES_CONF` to enable `registries.conf` / `auth.json` support. -And eventually remove the environment variable altogether. +Once stable, Helm will default the unset behavior of `HELM_EXPERIMENTAL_OCI_CONTAINERS_CONFIG` to enable `registries.conf` / `auth.json`, etc support. +And eventually remove the environment variable altogether. Potentially requiring Helm v5 (next major version of Helm) to do both. ### Example: basic login @@ -110,15 +117,12 @@ Will result in the `auth.json` excerpt: Helm's fallback to Docker's registry configuration ensures the vast majority of existing user workflows remain the same. -However, there are three potential incompatibility scenarios: +However, there are two potential incompatibility scenarios: -1. A corrupt `registries.conf` / `auth.json` will cause an error for existing workflows +1. A corrupt `registries.conf` / `auth.json`, etc will cause an error for existing workflows 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 -3. Helm’s preference for `registries.conf` / `auth.json` will break users who assume credentials are stored in Docker’s registry configuration - -The first two can be mitigated by users ensuring their system's `registries.conf` is valid, and only includes configuration options Helm supports for the registries they plan to use with Helm. -The last is mitigated by not using `registries.conf` / `auth.json` initially unless these exist on the user's system. +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. ## Security implications @@ -130,7 +134,7 @@ Helm's documentation will need to be updated with details of Helm's `registries. ## Reference implementation -- TODO: link to ORAS v3 `registries.conf` implementation, in progress +- TODO: link to ORAS v3 `registries.conf` / `auth.json` implementation, in progress - TODO: create experimental PR/branch for Helm implementing this HIP ## Rejected ideas @@ -156,4 +160,4 @@ Rather than "failing fast" and requiring users to ensure their configuration is ### `registries.conf` / `auth.json` specifications - + From 7bd9734718fafba8518de813e9ba2812c6f01639 Mon Sep 17 00:00:00 2001 From: George Jenkins Date: Mon, 10 Nov 2025 11:38:25 -0500 Subject: [PATCH 8/9] 'container tools' update Signed-off-by: George Jenkins --- hips/hip-XXXX.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/hips/hip-XXXX.md b/hips/hip-XXXX.md index 8908ac4f8..c759f0d34 100644 --- a/hips/hip-XXXX.md +++ b/hips/hip-XXXX.md @@ -126,7 +126,9 @@ The first two can be mitigated by users ensuring their system's `registries.conf ## Security implications -`registries.conf` / `auth.json` introduces a new mechanism for storing OCI credentials, which may introduce credential management vulnerabilities specific to `registries.conf` / `auth.json`. +- Support for signing and access control policy `policy.json` should improve OCI access management +- `auth.json` introduces a new mechanism for storing OCI credentials, which may introduce credential management vulnerabilities specific to `auth.json` +- `registries.conf` can introduce mirroring and redirection of OCI requests ## How to teach this From 5b21eee79497d9e056af52337d151fe8cffe11cd Mon Sep 17 00:00:00 2001 From: George Jenkins Date: Sat, 15 Nov 2025 13:29:39 -0500 Subject: [PATCH 9/9] more Signed-off-by: George Jenkins --- hips/hip-XXXX.md | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/hips/hip-XXXX.md b/hips/hip-XXXX.md index c759f0d34..bc50500b0 100644 --- a/hips/hip-XXXX.md +++ b/hips/hip-XXXX.md @@ -10,25 +10,26 @@ helm-version: "4" ## Abstract -The [container tools][containers-tools-project] project defines an alternative specification for managing client OCI registry configuration that supports more advanced features. Compared to Docker's `docker/config.json` that Helm currently uses today. +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. -Pertainently these include [registries.conf][registries-conf], [auth.json][auth-json], as well as the other specifications in . +Pertainently including [registries.conf][registries-conf], [auth.json][auth-json], as well as the other specifications in . -This HIP focuses on the initial implementation using ORAS to supports containers' OCI registry mamagement to supersede `docker/config.json` within Helm. +This HIP focuses on the initial implementation using ORAS to supports Container Tools OCI registry mamagement to supersede `docker/config.json` within Helm. Today, `auth.json` provides the equivalent functionality to `docker/config.json` for storing OCI registry credentials. Further HIPs will be created to expose additional functionality based on utilizing `registries.conf` and other container tools configurations. -[containers-tools-project]: https://github.com/containers "container tools project" +[containers-tools-project]: https://github.com/containers "Container Tools project" [registries-conf]: "registries.conf specification" [auth-json]: "auth.json specification" ## Motivation Helm currently uses Docker's `docker/config.json` to store client OCI registry configuration today. -Limited to mapping a registry domain to authentication credentials only. +With `docker/config.json`'s functionality being limited to mapping a registry domain to authentication credentials only. -The [CNCF-hosted](https://www.cncf.io/projects/podman-container-tools/) has created several specification for managing client OCI registry configuration. -These are `registries.conf`, `auth.json`, `policy.json`, etc. Which provide much more advanced functionality for client OCI registry management than `docker/config.json`. +The [CNCF-hosted](https://www.cncf.io/projects/podman-container-tools/) Container Tools project has created several specifications for managing client OCI registry configuration. +These are `registries.conf`, `auth.json`, `policy.json`, etc. +Which enable more advanced functionality for client OCI registry management than `docker/config.json`. Notably: @@ -39,7 +40,7 @@ Notably: - signing and verification policies Helm would like to introduce features that utilize these functionalities. -Supporting containers' configuration specifications would enable these features without requiring Helm to create or implement its own mechanisms. +Helm supporting the various Container Tool configuration specifications would enable these features without requiring Helm to create or implement its own mechanisms. ## Rationale