Skip to content

Commit 4cf1ce6

Browse files
JSticklerJStickler
authored
Merge pull request #51397 from JStickler/OSSMDOC-633
OSSMDOC-633: Document preliminary integration with cert-manager.
2 parents 6b6f30c + c217025 commit 4cf1ce6

File tree

2 files changed

+111
-1
lines changed

2 files changed

+111
-1
lines changed

‎modules/ossm-config-external-ca.adoc

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * service_mesh/v2x/ossm-security.adoc
4+
//
5+
6+
//Original location for the include was at the end of the v2 security Assembly.
7+
//include::modules/ossm-config-external-ca.adoc[leveloffset=+1]
8+
//Could not leave a comment there because asciidoc does not like hidden text at the end of a file.
9+
10+
:_content-type: PROCEDURE
11+
[id="ossm-config-external-ca_{context}"]
12+
= Configuring {SMProductShortName} for an external certificate authority
13+
14+
#DRAFT TOPIC#
15+
#Not part of any assembly#
16+
17+
//This module was created as a draft for OSSMDOC-633, but could not be completed before the original author changed jobs. Checked in to make it easier for the next writer to complete the work for OSSMDOC-633.
18+
19+
Issuers are Kubernetes resources that represent certificate authorities (CAs) that are able to generate signed certificates by honoring certificate signing requests. All cert-manager certificates require a referenced issuer that is in a ready condition to attempt to honor the request.
20+
21+
By default, {SMProductName} generates a self-signed root certificate and key and uses them to sign the workload certificates. You can also use your own certificate provider to generate certificates.
22+
23+
.Prerequisites
24+
25+
//Depending on when the engineering work is completed, the Operator version might change to 2.3.1?
26+
* Configuring {SPShortName} with an external certificate authority was introduced in {SMProductName} 2.3. You must have the {SMProductName} 2.3 Operator installed.
27+
//* If you are using cert-manager as your external certificate authority, it must be installed before you install {SMProductName} by deploying a `ServiceMeshControlPlane`.
28+
* You must have a version 2.3 `ServiceMeshControlPlane` deployed.
29+
30+
The `ServiceMeshControlPlane` resource lets you configure an external certificate authority using the `security.certificateAuthority.custom.address` parameter. This enables {SMProductShortName} to integrate with external certificate authorities (CAs).
31+
32+
Note that when using this method, the pilot server must have its tls context included in a secret that is generated by the external certificate authority. The configuration for this secret is specified in the `security.certificateAuthority.pilotSecretName` parameter in the SMCP.
33+
34+
[NOTE]
35+
====
36+
Red Hat does not support third-party certificate authorities. Contact your CA vendor for support for your certificate provider.
37+
====
38+
39+
.Procedure
40+
41+
. Create a self-signed root certificate named `selfsigned`.
42+
+
43+
.Sample self-signed certificate
44+
[source,yaml]
45+
----
46+
apiVersion: cert-manager.io/v1
47+
kind: Issuer
48+
metadata:
49+
name: selfsigned
50+
spec:
51+
selfSigned: {}
52+
----
53+
+
54+
. Using your certificate authority, create a certificate named named `istio-ca` that references the self-signed certificate that you created in the previous step. This provides the `secretName` needed by {SMProductShortName}.
55+
+
56+
.Example certificate
57+
[source,yaml]
58+
----
59+
apiVersion: cert-manager.io/v1
60+
kind: Certificate
61+
metadata:
62+
name: istio-ca
63+
spec:
64+
isCA: true
65+
duration: 2160h # 90d
66+
secretName: istio-ca #required for tls context
67+
commonName: istio-ca
68+
subject:
69+
organizations:
70+
- cluster.local
71+
- cert-manager
72+
issuerRef:
73+
name: selfsigned
74+
kind: Issuer
75+
group: cert-manager.io
76+
----
77+
+
78+
. Create an Issuer object named `istio-ca` that uses the key/cert that you just generated.
79+
+
80+
.Example istio-ca certificate
81+
[source,yaml]
82+
----
83+
apiVersion: cert-manager.io/v1
84+
kind: Issuer
85+
metadata:
86+
name: istio-ca
87+
spec:
88+
ca:
89+
secretName: istio-ca #required for tls context
90+
----
91+
+
92+
. Configure the `ServiceMeshControlPlane` to allow integration with your certificate authority.
93+
+
94+
.Example configuration for external certificate authority
95+
[source,yaml]
96+
----
97+
apiVersion: maistra.io/v2
98+
kind: ServiceMeshControlPlane
99+
metadata:
100+
name: basic
101+
namespace: istio-system
102+
spec:
103+
security:
104+
certificateAuthority:
105+
cert-manager:
106+
address: cert-manager-istio-csr.cert-manager.svc:443
107+
pilotSecretName: istiod-tls #Should this be "istio-ca" to match the other examples?
108+
rootCAConfigMapName: "istio-ca-root-cert"
109+
type: cert-manager
110+
----

‎modules/ossm-security-cert-manage.adoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
// * service_mesh/v2x/ossm-security.adoc
44

55
[id="ossm-cert-manage_{context}"]
6-
= Adding an external certificate authority key and certificate
6+
= Using a user-defined certificate and key
77

88
By default, {SMProductName} generates a self-signed root certificate and key and uses them to sign the workload certificates. You can also use the user-defined certificate and key to sign workload certificates with user-defined root certificate. This task demonstrates an example to plug certificates and key into {SMProductShortName}.
99

0 commit comments

Comments
 (0)