Browse Source

Spec: Support OCI image registry with authentication turned on

This specification proposes support for deploying openstack services
using OSH with OCI image registry which has authentication turned on.

Change-Id: I26e34a5a39c06e9d481af58c15fb930d3fe9b1ef
Implements: blueprint support-oci-image-registry-with-authentication-turned-on
Signed-off-by: Angie Wang <angie.wang@windriver.com>
Angie Wang 2 months ago
parent
commit
75f3083d24

+ 204
- 0
doc/source/specs/support-OCI-image-registry-with-authentication-turned-on.rst View File

@@ -0,0 +1,204 @@
1
+..
2
+ This work is licensed under a Creative Commons Attribution 3.0 Unported
3
+ License.
4
+
5
+ http://creativecommons.org/licenses/by/3.0/legalcode
6
+
7
+..
8
+
9
+========================================================
10
+Support OCI image registry with authentication turned on
11
+========================================================
12
+
13
+Blueprint:
14
+support-oci-image-registry-with-authentication-turned-on_
15
+
16
+.. _support-oci-image-registry-with-authentication-turned-on: https://blueprints.launchpad.net/openstack-helm/+spec/support-oci-image-registry-with-authentication-turned-on
17
+
18
+Problem Description
19
+===================
20
+In the current openstack-helm, all charts provide an ``images:`` section in
21
+their ``values.yaml`` that have the container images references. By default,
22
+the container images are all downloaded from a registry hosted by Docker or Quay.
23
+However, the image references can be overridden by operators to download images
24
+from any OCI image registry. In the case that the OCI image registry has
25
+authentication turned on, kubelet would fail to download the images because the
26
+current Openstack-Helm does not provide a way to pass the OCI image registry
27
+credentials to kubernetes when pulling images.
28
+
29
+
30
+Use case
31
+========
32
+Operators should be able to use Openstack-Helm to deploy containerized openstack
33
+services with a docker registry has authentication turned on.
34
+
35
+
36
+Proposed Change
37
+===============
38
+To be able to pull images from an OCI image registry which has the authentication
39
+turned on, kubernetes needs credentials. For each chart, a new ``endpoints:``
40
+entry could be added in ``values.yaml`` to provide image credentials, a secret
41
+needs to be generated to hold the credentials and the ``imagePullSecrets:`` field
42
+should be added in each service account to specify which secret should be used
43
+to get the credentials from when pulling images by kubelet.
44
+
45
+The detailed proposes change are described as following:
46
+
47
+1. For each chart, add a new entry ``oci_image_registry:`` under ``endpoints:`` in
48
+``values.yaml``. The entry ``oci_image_registry:`` has the ``auth:`` section which
49
+provides the credentials for accessing registry images and an option ``enabled:``
50
+to determine whether images authentication is required or not. The registry basic
51
+information would also be included for generating the registry URL by the endpoint
52
+lookup functions. Also add a new entry ``oci_image_registry:`` under ``secrets:``
53
+to indicate the secret name. In order to create the secret that holds the provided
54
+credentials, add a new component ``secret_registry`` in ``manifests:`` section.
55
+For example:
56
+
57
+.. code-block:: yaml
58
+
59
+   secrets:
60
+     oci_image_registry:
61
+       nova: nova-oci-image-registry-key
62
+
63
+   endpoints:
64
+     ...
65
+     oci_image_registry:
66
+       name: oci-image-registry
67
+       namespace: oci-image-registry
68
+       auth:
69
+         enabled: false
70
+         nova:
71
+           username: nova
72
+           password: password
73
+       hosts:
74
+         default: localhost
75
+       host_fqdn_override:
76
+         default: null
77
+       port:
78
+         registry:
79
+           default: 5000
80
+
81
+   manifests:
82
+     secret_registry: true
83
+
84
+The option ``enabled:`` under ``auth:`` and the manifest ``secret_registry:``
85
+provide the ability for operator to determine whether they would like to have
86
+secrets generated and passed to kubernetes for pulling images.
87
+
88
+The secret would not be created with the default option ``enabled: false`` and
89
+``secret_registry: true``. To enable secret creation, operator should override
90
+``enabled:`` to true. The above example shows the default credentials, operator
91
+should override the ``username:`` and ``password:`` under ``auth:`` section to
92
+provide their own credentials.
93
+
94
+Then, add manifest ``secret-registry.yaml`` in ``templates/`` to leverage
95
+the function that will be added in helm-toolkit to create the secret. For example:
96
+
97
+.. code-block:: yaml
98
+
99
+   {{- if and .Values.manifests.secret_registry .Values.endpoints.oci_image_registry.auth.enabled }}
100
+   {{ include "helm-toolkit.manifests.secret_registry" ( dict "envAll" . "registryUser" .Chart.Name ) }}
101
+   {{- end }}
102
+
103
+2. Add a helm-toolkit function ``helm-toolkit.manifests.secret_registry`` to create a
104
+   manifest for secret generation. For example:
105
+
106
+.. code-block:: rst
107
+
108
+   {{- define "helm-toolkit.manifests.secret_registry" -}}
109
+   {{- $envAll := index . "envAll" }}
110
+   {{- $registryUser := index . "registryUser" }}
111
+   {{- $secretName := index $envAll.Values.secrets.oci_image_registry $registryUser }}
112
+   {{- $registryHost := tuple "oci_image_registry" "internal" $envAll | include "helm-toolkit.endpoints.endpoint_host_lookup" }}
113
+   {{- $registryPort := tuple "oci_image_registry" "internal" "registry" $envAll | include "helm-toolkit.endpoints.endpoint_port_lookup" }}
114
+   {{- $imageCredentials := index $envAll.Values.endpoints.oci_image_registry.auth $registryUser }}
115
+   {{- $dockerAuthToken := printf "%s:%s" $imageCredentials.username $imageCredentials.password | b64enc }}
116
+   {{- $dockerAuth := printf "{\"auths\": {\"%s:%s\": {\"auth\": \"%s\"}}}" $registryHost $registryPort $dockerAuthToken | b64enc }}
117
+   ---
118
+   apiVersion: v1
119
+   kind: Secret
120
+   metadata:
121
+     name: {{ $secretName }}
122
+   type: kubernetes.io/dockerconfigjson
123
+   data:
124
+     .dockerconfigjson: {{ $dockerAuth }}
125
+   {{- end }}
126
+
127
+3. Reference the created secret by adding the ``imagePullSecrets:`` field to ServiceAccount
128
+   resource template [2]_ in ``helm-toolkit/snippets/_kubernetes_pod_rbac_serviceaccount.tpl``.
129
+   To handle it as optional, the field is wrapped in a conditional. For example,
130
+
131
+.. code-block:: yaml
132
+
133
+   ---
134
+   apiVersion: v1
135
+   kind: ServiceAccount
136
+   ...
137
+   {{- if $envAll.Values.endpoints.oci_image_registry.auth.enabled }}
138
+   imagePullSecrets:
139
+     - name: {{ index $envAll.Values.secrets.oci_image_registry $envAll.Chart.Name }}
140
+   {{- end }}
141
+
142
+If .Values.endpoints.oci_image_registry.auth.enabled will be set to true, then any
143
+containers created with the current service account will have the ``imagePullSecrets``
144
+automatically added to their spec and the secret will be passed to kubelet to be
145
+used for pulling images.
146
+
147
+
148
+Security Impact
149
+---------------
150
+The credentials for the registry could be exposed by running the kubectl command:
151
+kubectl get secret <secret-name> --output="jsonpath={.data.\.dockerconfigjson}" | base64 --decode
152
+
153
+Authentication should be enabled for normal users to access Kube API server via
154
+either kubectl command or kube REST API call.
155
+
156
+
157
+Performance Impact
158
+------------------
159
+No performance impact
160
+
161
+
162
+Alternatives
163
+------------
164
+Before using Openstack-Helm to deploy openstack services,
165
+
166
+1. Put .docker/config.json in docker/kubelet root directory on all nodes
167
+2. Pre-pulling images on all nodes
168
+
169
+But above alternatives have limitations and security impact. i.e...require root access
170
+to configure on all nodes, all pods can read any configured private registries, all pods
171
+can use any images cached on a node [1]_
172
+
173
+
174
+Implementation
175
+==============
176
+
177
+Assignee(s)
178
+-----------
179
+
180
+Primary assignees:
181
+
182
+* Angie Wang (angiewang)
183
+
184
+
185
+Work Items
186
+----------
187
+#. Provide the credentials and add the manifest across all charts in OSH and OSH-infra
188
+#. Update helm-toolkit to provide manifest to create secret for registry authentication
189
+#. Update helm-toolkit serviceaccount template to pass the secret in a conditional
190
+
191
+
192
+Testing
193
+=======
194
+None
195
+
196
+Documentation Impact
197
+====================
198
+Documentation of how to enable the registry secret generation
199
+
200
+
201
+References
202
+==========
203
+.. [1] https://kubernetes.io/docs/concepts/containers/images
204
+.. [2] https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/#add-imagepullsecrets-to-a-service-account

Loading…
Cancel
Save