You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: hips/hip-XXXX.md
+40-33Lines changed: 40 additions & 33 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,44 +9,52 @@ status: "draft"
9
9
10
10
## Abstract
11
11
12
-
[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)
12
+
[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.
13
13
14
-
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`.
14
+
This HIP focuses on the initial implementation of supporting `registries.conf` within Helm.
15
+
Further HIPs will be created to expose additional functionality based on utilizing `registries.conf`.
`registries.conf` provides much more flexibible support for OCI registry management than the current Docker CLI based configuration format that Helm uses today.
21
+
Helm uses Docker's `docker/config.json` to store client OCI registry configuration today.
21
22
22
-
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
23
+
`registries.conf` provides much more advanced functionality for client OCI registry management than `docker/config.json`.
24
+
Notably:
23
25
24
-
(in particular, the existing registry configuration Helm uses, Docker’s `$HOME/.docker/config.json`, etc do not support registry aliases nor prefixes)
26
+
- support for repository prefixes (allowing different credentials for different prefixes)
27
+
- registry mirrors
28
+
- registry "aliasing"—features
29
+
30
+
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.
31
+
With `registries.conf` having been standardized by other container ecosystem CLI tools (podman, buildah, skopeo, etc.).
25
32
26
33
## Rationale
27
34
28
-
Utilizing an existing specification / libraries enables Helm immediate build upon an existing standard.
29
-
Rather than Helm inventing its own convention.
35
+
Utilizing an existing specification and libraries enables Helm to immediately build upon an existing standard, rather than inventing its own convention.
30
36
31
37
`registries.conf` was picked as being a format intended for consumption beyond the Docker application container ecosystem.
32
38
39
+
ORAS (the library Helm uses for supporting OCI functionality) has planned support for `registries.conf` client-side OCI registry management.
40
+
33
41
## Specification
34
42
35
-
Helm will utilize the `registries.conf` specification when determinging OCI registry information (authentication credentials, etc):
43
+
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.
40
-
Or when Helm supports and a user utilizes functionality that can not be supported by Docker's comnfigurtation file in the future.
46
+
`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.
41
47
42
48
<!-- The usage of `registries.conf` will be forced, when in the future -->
43
49
44
50
For example, a registry login command:
51
+
45
52
```bash
46
53
helm registry login "oci.example.com" --username foo --password bar
47
54
```
48
55
49
-
Will result in the configration exerpt (if, and only if, `registries.conf` exists on the users local system):
56
+
Will result in the configuration excerpt (if, and only if, `registries.conf` exists on the user's local system):
57
+
50
58
```toml
51
59
# registries.conf
52
60
[[registry]]
@@ -63,16 +71,13 @@ prefix = "oci.example.com"
63
71
}
64
72
```
65
73
66
-
Helm will use the package TBD for updating (and reading) `registries.conf`.
74
+
Helm will use ORAS v3 for updating (and reading) `registries.conf` (TODO: link to ORAS v3 `registries.conf` implementation).
67
75
68
-
If when reading a registries configation from `registries.conf` results in known configuration Helm doesn't support, Helm must error.
69
-
e.g. `location` or non-empty URI path in `prefix`.
76
+
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`).
70
77
71
-
An error reading `registries.conf` must result in an error for the user.
72
-
Otherwise, users who expect configration from `registries.conf` to be effected, will have a unspected fallback.
78
+
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.
73
79
74
-
To account for existing configration in Docker’s registry configuration, Helm will prefer `registries.conf` when resolving OCI registries (including credentials).
75
-
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).
80
+
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).
76
81
77
82
Helm must expect (and even encourage) users to utilize other tooling to manage `registries.conf`.
78
83
@@ -81,23 +86,24 @@ Helm must expect (and even encourage) users to utilize other tooling to manage `
81
86
Helm's fallback to Docker's registry configuration ensures the vast majority of existing user workflows remain the same.
82
87
83
88
However, there are three potential incompatibility scenarios:
84
-
2. A corrupt `registries.conf` will cause an error for existing workflows
85
-
1. An invalid or incompatible with Helm `registries.conf` entry for the given OCI registry will cause the users workflow to fail
89
+
90
+
1. A corrupt `registries.conf` will cause an error for existing workflows
91
+
2. An invalid or incompatible with Helm `registries.conf` entry for the given OCI registry will cause the user's workflow to fail
86
92
3. Helm’s preference for `registries.conf` will break users who assume credentials are stored in Docker’s registry configuration
87
93
88
-
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.
94
+
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.
89
95
90
-
The last is mitigated by not using `registries.conf` initially unless it exists on the users system.
96
+
The last is mitigated by not using `registries.conf` initially unless it exists on the user's system.
91
97
92
98
## Security implications
93
99
94
100
`registries.conf` introduces a new mechanism for storing OCI credentials, which may introduce credential management vulnerabilities specific to `registries.conf` / `auth.json`
95
101
96
-
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)
102
+
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)
97
103
98
104
## How to teach this
99
105
100
-
Helm's documentation will need to be updated with details of Helm's `registries.conf` support, and fallback to Docker config.
106
+
Helm's documentation will need to be updated with details of Helm's `registries.conf` support and fallback to Docker config.
101
107
102
108
## Reference implementation
103
109
@@ -110,21 +116,22 @@ proof-of-concept.
110
116
111
117
### Falling back to Docker’s config upon error reading registries.conf
112
118
113
-
Falling back upon error means users who expect their configuration to be taken from `registries.conf` will unexpectedly have OCI configuration taken from Docker.
114
-
Potentially resulting in difficult to diagnose failures authenticating to the repository.
119
+
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.
115
120
116
-
Rather than "failing fast" and requring users to ensure their configuration to be valid.
121
+
Rather than "failing fast" and requiring users to ensure their configuration is valid.
117
122
118
123
## Open issues
119
124
120
-
- Support for registies.conf in ORAS
121
-
- Disucss Helm's/ORAS's usage of registries.conf with owners
0 commit comments