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
configuration file] you can list the `namedCertificates` section in the
60
-
`servingInfo` section so the custom certificate serves up for the
61
-
web console, and in the `servingInfo` section so the custom certificate serves
62
-
up for the CLI and other API calls. Multiple certificates can be configured this
63
-
way and each certificate may be associated with multiple host names or
64
-
wildcards.
62
+
* The `servingInfo.namedCertificates` section serves up custom certificates for the web console.
63
+
* The `servingInfo` section serves up custom certificates for the CLI and other API calls.
64
+
65
+
You can configure multiple certificates this way, and each certificate can be associated with
66
+
xref:configuring-custom-certificates-master[multiple host names], xref:configuring-custom-certificates-master[multiple routers], or the xref:configuring-custom-certificates-registry[{product-title} image registry].
65
67
66
68
A default certificate must be configured in the `servingInfo.certFile` and
67
69
`servingInfo.keyFile` configuration sections in addition to
68
70
`namedCertificates`.
69
71
70
72
[NOTE]
71
73
====
72
-
The `namedCertificates` section should only be configured for the host name
74
+
The `namedCertificates` section should be configured only for the host name
73
75
associated with the `masterPublicURL` and
74
-
`oauthConfig.assetPublicURL` settings. Using a custom serving certificate for
76
+
`oauthConfig.assetPublicURL` settings n the *_/etc/origin/master/master-config.yaml_* file.
77
+
Using a custom serving certificate for
75
78
the host name associated with the `masterURL` will result in TLS errors as
76
79
infrastructure components will attempt to contact the master API using the
<1> Path to certificate and key files for the CLI and other API calls.
108
+
<2> Path to certificate and key files for the web console.
109
+
110
+
The `openshift_master_cluster_public_hostname` and `openshift_master_cluster_hostname` parameters in the xref:../install_config/install/advanced_install.adoc#configuring-ansible[Ansible inventory file], by default `/etc/ansible/hosts`, must be different. If they are the same, the named certificates will fail and you will need to re-install them.
using DNS with {product-title}, see the xref:../install_config/install/prerequisites.adoc#prereq-dns[DNS installation prerequisites].
93
120
94
-
Relative paths are resolved relative to the master configuration file. Restart
121
+
This approach allows you to take advantage of the self-signed certificates generated by {product-title} and add custom trusted certificates to individual components as needed.
122
+
123
+
Note that the internal infrastructure certificates remain self-signed, which might be perceived as bad practice by some security or PKI teams. However, any risk here is minimal, as the only clients that trust these certificates are other components within the cluster. All external users and systems use custom trusted certificates.
124
+
125
+
Relative paths are resolved based on the location of the master configuration file. Restart
95
126
the server to pick up the configuration changes.
96
127
97
-
For the master API or web console, wildcard names are accepted.
128
+
[[configuring-custom-certificates-master]]
129
+
== Configuring a Custom Master Host Certificate
130
+
131
+
In order to facilitate trusted connections with external users of {product-title}, you can provision a named certificate that matches the domain name provided in the `openshift_master_cluster_public_hostname` paramater in the xref:../install_config/install/advanced_install.adoc#configuring-ansible[Ansible inventory file],
132
+
by default `/etc/ansible/hosts`.
133
+
134
+
You must place this certificate in a directory accessible to Ansible and add the path in the
* *certfile* is the path to the file that contains the {product-title} router certificate.
144
+
145
+
* *keyfile* is the path to the file that contains the {product-title} wildcard key.
146
+
147
+
* *names* is the cluster public hostname.
148
+
149
+
// * *cafile* contains the root CA for this key and certificate. If an intermediate CA is in use, it must contain both the intermediate and root CA. "cafile": "/path/to/console.ocp-c1.myorg.com.ca.crt"
150
+
151
+
152
+
The file paths must be local to the system where Ansible runs. Certificates
153
+
are copied to master hosts and are deployed within the
When securing the registry, add the service hostnames and IP addresses to the server certificate for the registry.
157
+
The Subject Alternative Names (SAN) must contain the following.
158
+
159
+
* Two service hostnames:
160
+
+
161
+
----
162
+
docker-registry.default.svc.cluster.local
163
+
docker-registry.default.svc
164
+
----
165
+
166
+
* Service IP address.
167
+
+
168
+
For example:
169
+
+
170
+
----
171
+
172.30.252.46
172
+
----
173
+
+
174
+
Use the following command to get the Docker registry service IP address:
175
+
+
176
+
----
177
+
oc get service docker-registry --template='{{.spec.clusterIP}}'
178
+
----
179
+
180
+
* Public hostname.
181
+
+
182
+
----
183
+
docker-registry-default.apps.example.com
184
+
----
185
+
+
186
+
Use the following command to get the Docker registry public hostname:
187
+
+
188
+
----
189
+
oc get route docker-registry --template '{{.spec.host}}'
190
+
----
191
+
192
+
For example, the server certificate should contain SAN details similar to the following:
193
+
194
+
----
195
+
X509v3 Subject Alternative Name:
196
+
DNS:docker-registry-public.openshift.com, DNS:docker-registry.default.svc, DNS:docker-registry.default.svc.cluster.local, DNS:172.30.2.98, IP Address:172.30.2.98
197
+
----
198
+
199
+
[[configuring-custom-certificates-wildcard]]
200
+
== Configuring a Custom Wildcard Certificate for the Default Router
201
+
202
+
You can configure the {product-title} default router with a default wildcard certificate. A default wildcard certificate provides a convenient way for
203
+
applications that are deployed in {product-title} to use default encryption without needing custom certificates.
204
+
205
+
[NOTE]
206
+
====
207
+
Default wildcard certificates are recommended for non-production environments only.
208
+
====
209
+
210
+
In order to configure a default wildcard certificate, provision a certificate that is valid for `.<app_domain>`, where `<app_domain>` is the value of `openshift_master_default_subdomain` in the xref:../install_config/install/advanced_install.adoc#configuring-ansible[Ansible inventory file], by default `/etc/ansible/hosts`. Once provisioned, place the certificate, key, and ca certificate files on your Ansible host, and add the following line to your Ansible inventory file.
* *certfile* is the path to the file that contains the {product-title} router certificate.
225
+
226
+
* *keyfile* is the path to the file that contains the {product-title} wildcard key.
227
+
228
+
* *cafile* is the path to the file that contains the root CA for this key and certificate. If an intermediate CA is in use, the file should contain both the intermediate and root CA.
229
+
230
+
If these certificate files are new to your {product-title} cluster, run the Ansible *_deploy_cluster.yml_* playbook to add these files to the {product-title} configuration files.
231
+
The playbook adds the certificate files to the *_/etc/origin/master/named_certificates/_* directory.
For this playbook to run, the certificate names must not change. If the certificate names change, rerun the Ansible *_deploy_cluster.yml_* playbook
253
+
as if the certificates were new.
254
+
255
+
[[configuring-custom-certificates-registry]]
256
+
== Configuring a Custom Certificate for the Image Registry
257
+
258
+
The {product-title} image registry is an internal service that facilitates builds and deployments. Most of the communication with the registry is handled by internal components in {product-title}. As such, you should not need to replace the certificate used by the registry service itself.
259
+
260
+
However, by default, the registry uses routes to allow external systems and users to do pulls and pushes of images. You can use a _re-encrypt route_ with a custom certificate that is presented to external users instead of using the internal, self-signed certificate.
261
+
262
+
To configure this, add the xref:../install_config/install/advanced_install.adoc#advanced-install-configuring-docker-route[following lines] of code
263
+
to the [OSEv3:vars] section of the Ansible inventory file, by default /etc/ansible/hosts file.
264
+
Specify the certificates to use with the registry route.
<2> The locations of the *cacert*, *root*, and *cafile* files.
275
+
+
276
+
* *certfile* is the path to the file that contains the {product-title} router certificate.
277
+
278
+
* *keyfile* is the path to the file that contains the {product-title} wildcard key.
279
+
280
+
* *cafile* is the path to the file that contains the root CA for this key and certificate. If an intermediate CA is in use, the file should contain both the intermediate and root CA.
281
+
<3> Specify where encryption is performed:
282
+
+
283
+
* Set to `reencrypt` with a _re-encrypt route_ to terminate encryption at the edge router and re-encrypt it with a new certificate supplied by the destination.
284
+
+
285
+
* Set to `passthrough` to terminate encryption at the destination. The destination is responsible for decrypting traffic.
286
+
287
+
[[configuring-custom-certificates-retrofit]]
288
+
== Retrofit Custom Certificates into a Cluster
289
+
290
+
You can retrofit custom master and custom router certificates into an existing {product-title} cluster by editing the
291
+
the Ansible inventory file, by default *_/etc/ansible/hosts_*, and running a playbook.
0 commit comments