work

Author: gjenkins8

hips/hip-XXXX.md

@@ -0,0 +1,127 @@
+---
+hip: 9999
+title: "registries.conf support for OCI registry management"
+authors: [ "George Jenkins <[email protected]>" ]
+created: "2025-02-16"
+type: "feature"
+status: "draft"
+---
+
+## Abstract
+
+This HIP proposes adding support for `registries.conf`[1] for managing OCI registry configuration.
+
+This HIP focuces on the implementation of supporting `registries.conf`. Further HIPs to be created for exposing functionality based on utilzing `registries.conf`.
+
+## Motivation
+
+`registries.conf` provides much more flexibible support for OCI registry management, than the current Docker CLIs based configuration format Helm uses today.
+
+Including support for authenication prefixes and registry "aliasing". Two features Helm would like to introduce. But is currenly blocked
+
+(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.
+
+`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):
+https://github.com/containers/image/blob/main/docs/containers-registries.conf.5.md#remapping-and-mirroring-registries
+
+
+`registries.conf` will be preferred, either when a `registries.conf` file already exists on the users system.
+Or when in the future Helm exposes functionality that can not be supported by Docker's comnfigurtation file.
+
+<!-- The usage of `registries.conf` will be forced, when 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"
+```
+
+```toml
+# auth.json
+	"auths": {
+        ...
+		"oci.example.com": {
+			"auth": "Zm9vOmJhcgo="
+		},
+    }
+[[registry]]
+prefix = "oci.example.com"
+username = "foo"
+password = "bar"
+```
+
+Helm will use the package TBD for updating (and reading) `registries.conf`.
+
+If when reading a registries configation from `registries.conf` results in configuration Helm doesn't support (e.g. `location` or non-empty URI path in prefix), Helm must error.
+
+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
+
+How to teach users, new and experienced, how to apply the HIP to their work.
+
+## Reference implementation
+
+Link to any existing implementation and details about its state, e.g.
+proof-of-concept.
+
+## 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
+
+Any points that are still being decided/discussed.
+
+## 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