Skip to content

Commit 39ffb4d

Browse files
gwynnemonahangwynnemonahan
committed
OSSM-3352: Split ossm-security-cert-manage file into 3 ossm-cert-cleanup, ossm-cert-manage-add, ossm-cert-manage-verify to bring file into compliance with current doc practices. No review is needed as only architectural change. Content has been previously reviewed and approved.
1 parent a37602c commit 39ffb4d

File tree

5 files changed

+186
-167
lines changed

5 files changed

+186
-167
lines changed

‎modules/ossm-cert-cleanup.adoc

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * service_mesh/v2x/ossm-security.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="ossm-cert-cleanup_{context}"]
7+
== Removing the certificates
8+
9+
To remove the certificates you added, follow these steps.
10+
11+
. Remove the secret `cacerts`. In this example, `istio-system` is the name of the {SMProductShortName} control plane project.
12+
+
13+
[source,terminal]
14+
----
15+
$ oc delete secret cacerts -n istio-system
16+
----
17+
+
18+
. Redeploy {SMProductShortName} with a self-signed root certificate in the `ServiceMeshControlPlane` resource.
19+
+
20+
[source,yaml]
21+
----
22+
apiVersion: maistra.io/v2
23+
kind: ServiceMeshControlPlane
24+
spec:
25+
security:
26+
dataPlane:
27+
mtls: true
28+
----

‎modules/ossm-cert-manage-add-cert-key.adoc

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * service_mesh/v2x/ossm-security.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="ossm-cert-manage-add-cert-key_{context}"]
7+
== Adding an existing certificate and key
8+
9+
To use an existing signing (CA) certificate and key, you must create a chain of trust file that includes the CA certificate, key, and root certificate. You must use the following exact file names for each of the corresponding certificates. The CA certificate is named `ca-cert.pem`, the key is `ca-key.pem`, and the root certificate, which signs `ca-cert.pem`, is named `root-cert.pem`. If your workload uses intermediate certificates, you must specify them in a `cert-chain.pem` file.
10+
11+
. Save the example certificates from the link:https://github.com/maistra/istio/tree/maistra-{MaistraVersion}/samples/certs[Maistra repository] locally and replace `<path>` with the path to your certificates.
12+
13+
. Create a secret named `cacert` that includes the input files `ca-cert.pem`, `ca-key.pem`, `root-cert.pem` and `cert-chain.pem`.
14+
+
15+
[source,terminal]
16+
----
17+
$ oc create secret generic cacerts -n istio-system --from-file=<path>/ca-cert.pem \
18+
--from-file=<path>/ca-key.pem --from-file=<path>/root-cert.pem \
19+
--from-file=<path>/cert-chain.pem
20+
----
21+
+
22+
. In the `ServiceMeshControlPlane` resource set `spec.security.dataPlane.mtls true` to `true` and configure the `certificateAuthority` field as shown in the following example. The default `rootCADir` is `/etc/cacerts`. You do not need to set the `privateKey` if the key and certs are mounted in the default location. {SMProductShortName} reads the certificates and key from the secret-mount files.
23+
+
24+
[source,yaml]
25+
----
26+
apiVersion: maistra.io/v2
27+
kind: ServiceMeshControlPlane
28+
spec:
29+
security:
30+
dataPlane:
31+
mtls: true
32+
certificateAuthority:
33+
type: Istiod
34+
istiod:
35+
type: PrivateKey
36+
privateKey:
37+
rootCADir: /etc/cacerts
38+
----
39+
40+
. After creating/changing/deleting the `cacert` secret, the {SMProductShortName} control plane `istiod` and `gateway` pods must be restarted so the changes go into effect. Use the following command to restart the pods:
41+
+
42+
[source,terminal]
43+
----
44+
$ oc -n istio-system delete pods -l 'app in (istiod,istio-ingressgateway, istio-egressgateway)'
45+
----
46+
+
47+
The Operator will automatically recreate the pods after they have been deleted.
48+
49+
. Restart the bookinfo application pods so that the sidecar proxies pick up the secret changes. Use the following command to restart the pods:
50+
+
51+
[source,terminal]
52+
----
53+
$ oc -n bookinfo delete pods --all
54+
----
55+
+
56+
You should see output similar to the following:
57+
+
58+
59+
[source,terminal]
60+
----
61+
pod "details-v1-6cd699df8c-j54nh" deleted
62+
pod "productpage-v1-5ddcb4b84f-mtmf2" deleted
63+
pod "ratings-v1-bdbcc68bc-kmng4" deleted
64+
pod "reviews-v1-754ddd7b6f-lqhsv" deleted
65+
pod "reviews-v2-675679877f-q67r2" deleted
66+
pod "reviews-v3-79d7549c7-c2gjs" deleted
67+
----
68+
69+
. Verify that the pods were created and are ready with the following command:
70+
+
71+
72+
[source,terminal]
73+
----
74+
$ oc get pods -n bookinfo
75+
----

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

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * service_mesh/v2x/ossm-security.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="ossm-cert-manage-verify-cert_{context}"]
7+
== Verifying your certificates
8+
9+
Use the Bookinfo sample application to verify that the workload certificates are signed by the certificates that were plugged into the CA. This requires you have `openssl` installed on your machine
10+
11+
. To extract certificates from bookinfo workloads use the following command:
12+
+
13+
[source,terminal]
14+
----
15+
$ sleep 60
16+
$ oc -n bookinfo exec "$(oc -n bookinfo get pod -l app=productpage -o jsonpath={.items..metadata.name})" -c istio-proxy -- openssl s_client -showcerts -connect details:9080 > bookinfo-proxy-cert.txt
17+
$ sed -n '/-----BEGIN CERTIFICATE-----/{:start /-----END CERTIFICATE-----/!{N;b start};/.*/p}' bookinfo-proxy-cert.txt > certs.pem
18+
$ awk 'BEGIN {counter=0;} /BEGIN CERT/{counter++} { print > "proxy-cert-" counter ".pem"}' < certs.pem
19+
----
20+
+
21+
After running the command, you should have three files in your working directory: `proxy-cert-1.pem`, `proxy-cert-2.pem` and `proxy-cert-3.pem`.
22+
23+
. Verify that the root certificate is the same as the one specified by the administrator. Replace `<path>` with the path to your certificates.
24+
+
25+
[source,terminal]
26+
----
27+
$ openssl x509 -in <path>/root-cert.pem -text -noout > /tmp/root-cert.crt.txt
28+
----
29+
+
30+
Run the following syntax at the terminal window.
31+
+
32+
[source,terminal]
33+
----
34+
$ openssl x509 -in ./proxy-cert-3.pem -text -noout > /tmp/pod-root-cert.crt.txt
35+
----
36+
+
37+
Compare the certificates by running the following syntax at the terminal window.
38+
+
39+
[source,terminal]
40+
----
41+
$ diff -s /tmp/root-cert.crt.txt /tmp/pod-root-cert.crt.txt
42+
----
43+
+
44+
You should see the following result:
45+
`Files /tmp/root-cert.crt.txt and /tmp/pod-root-cert.crt.txt are identical`
46+
47+
48+
. Verify that the CA certificate is the same as the one specified by the administrator. Replace `<path>` with the path to your certificates.
49+
+
50+
[source,terminal]
51+
----
52+
$ openssl x509 -in <path>/ca-cert.pem -text -noout > /tmp/ca-cert.crt.txt
53+
----
54+
Run the following syntax at the terminal window.
55+
+
56+
[source,terminal]
57+
----
58+
$ openssl x509 -in ./proxy-cert-2.pem -text -noout > /tmp/pod-cert-chain-ca.crt.txt
59+
----
60+
Compare the certificates by running the following syntax at the terminal window.
61+
+
62+
[source,terminal]
63+
----
64+
$ diff -s /tmp/ca-cert.crt.txt /tmp/pod-cert-chain-ca.crt.txt
65+
----
66+
You should see the following result:
67+
`Files /tmp/ca-cert.crt.txt and /tmp/pod-cert-chain-ca.crt.txt are identical.`
68+
69+
. Verify the certificate chain from the root certificate to the workload certificate. Replace `<path>` with the path to your certificates.
70+
+
71+
[source,terminal]
72+
----
73+
$ openssl verify -CAfile <(cat <path>/ca-cert.pem <path>/root-cert.pem) ./proxy-cert-1.pem
74+
----
75+
You should see the following result:
76+
`./proxy-cert-1.pem: OK`

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

Lines changed: 1 addition & 167 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22
//
33
// * service_mesh/v2x/ossm-security.adoc
44

5+
:_content-type: CONCEPT
56
[id="ossm-cert-manage_{context}"]
67
= Adding an external certificate authority key and certificate
78

@@ -13,170 +14,3 @@ By default, {SMProductName} generates a self-signed root certificate and key and
1314
* This example uses the certificates from the link:https://github.com/maistra/istio/tree/maistra-{MaistraVersion}/samples/certs[Maistra repository]. For production, use your own certificates from your certificate authority.
1415
* Deploy the Bookinfo sample application to verify the results with these instructions.
1516
* OpenSSL is required to verify certificates.
16-
17-
[id="ossm-cert-manage-add-cert-key_{context}"]
18-
== Adding an existing certificate and key
19-
20-
To use an existing signing (CA) certificate and key, you must create a chain of trust file that includes the CA certificate, key, and root certificate. You must use the following exact file names for each of the corresponding certificates. The CA certificate is named `ca-cert.pem`, the key is `ca-key.pem`, and the root certificate, which signs `ca-cert.pem`, is named `root-cert.pem`. If your workload uses intermediate certificates, you must specify them in a `cert-chain.pem` file.
21-
22-
. Save the example certificates from the link:https://github.com/maistra/istio/tree/maistra-{MaistraVersion}/samples/certs[Maistra repository] locally and replace `<path>` with the path to your certificates.
23-
24-
. Create a secret named `cacert` that includes the input files `ca-cert.pem`, `ca-key.pem`, `root-cert.pem` and `cert-chain.pem`.
25-
+
26-
[source,terminal]
27-
----
28-
$ oc create secret generic cacerts -n istio-system --from-file=<path>/ca-cert.pem \
29-
--from-file=<path>/ca-key.pem --from-file=<path>/root-cert.pem \
30-
--from-file=<path>/cert-chain.pem
31-
----
32-
+
33-
. In the `ServiceMeshControlPlane` resource set `spec.security.dataPlane.mtls true` to `true` and configure the `certificateAuthority` field as shown in the following example. The default `rootCADir` is `/etc/cacerts`. You do not need to set the `privateKey` if the key and certs are mounted in the default location. {SMProductShortName} reads the certificates and key from the secret-mount files.
34-
+
35-
[source,yaml]
36-
----
37-
apiVersion: maistra.io/v2
38-
kind: ServiceMeshControlPlane
39-
spec:
40-
security:
41-
dataPlane:
42-
mtls: true
43-
certificateAuthority:
44-
type: Istiod
45-
istiod:
46-
type: PrivateKey
47-
privateKey:
48-
rootCADir: /etc/cacerts
49-
----
50-
51-
. After creating/changing/deleting the `cacert` secret, the {SMProductShortName} control plane `istiod` and `gateway` pods must be restarted so the changes go into effect. Use the following command to restart the pods:
52-
+
53-
[source,terminal]
54-
----
55-
$ oc -n istio-system delete pods -l 'app in (istiod,istio-ingressgateway, istio-egressgateway)'
56-
----
57-
+
58-
The Operator will automatically recreate the pods after they have been deleted.
59-
60-
. Restart the bookinfo application pods so that the sidecar proxies pick up the secret changes. Use the following command to restart the pods:
61-
+
62-
[source,terminal]
63-
----
64-
$ oc -n bookinfo delete pods --all
65-
----
66-
+
67-
You should see output similar to the following:
68-
+
69-
70-
[source,terminal]
71-
----
72-
pod "details-v1-6cd699df8c-j54nh" deleted
73-
pod "productpage-v1-5ddcb4b84f-mtmf2" deleted
74-
pod "ratings-v1-bdbcc68bc-kmng4" deleted
75-
pod "reviews-v1-754ddd7b6f-lqhsv" deleted
76-
pod "reviews-v2-675679877f-q67r2" deleted
77-
pod "reviews-v3-79d7549c7-c2gjs" deleted
78-
----
79-
80-
. Verify that the pods were created and are ready with the following command:
81-
+
82-
83-
[source,terminal]
84-
----
85-
$ oc get pods -n bookinfo
86-
----
87-
88-
[id="ossm-cert-manage-verify-cert_{context}"]
89-
== Verifying your certificates
90-
91-
Use the Bookinfo sample application to verify that the workload certificates are signed by the certificates that were plugged into the CA. This requires you have `openssl` installed on your machine
92-
93-
. To extract certificates from bookinfo workloads use the following command:
94-
+
95-
[source,terminal]
96-
----
97-
$ sleep 60
98-
$ oc -n bookinfo exec "$(oc -n bookinfo get pod -l app=productpage -o jsonpath={.items..metadata.name})" -c istio-proxy -- openssl s_client -showcerts -connect details:9080 > bookinfo-proxy-cert.txt
99-
$ sed -n '/-----BEGIN CERTIFICATE-----/{:start /-----END CERTIFICATE-----/!{N;b start};/.*/p}' bookinfo-proxy-cert.txt > certs.pem
100-
$ awk 'BEGIN {counter=0;} /BEGIN CERT/{counter++} { print > "proxy-cert-" counter ".pem"}' < certs.pem
101-
----
102-
+
103-
After running the command, you should have three files in your working directory: `proxy-cert-1.pem`, `proxy-cert-2.pem` and `proxy-cert-3.pem`.
104-
105-
. Verify that the root certificate is the same as the one specified by the administrator. Replace `<path>` with the path to your certificates.
106-
+
107-
[source,terminal]
108-
----
109-
$ openssl x509 -in <path>/root-cert.pem -text -noout > /tmp/root-cert.crt.txt
110-
----
111-
+
112-
Run the following syntax at the terminal window.
113-
+
114-
[source,terminal]
115-
----
116-
$ openssl x509 -in ./proxy-cert-3.pem -text -noout > /tmp/pod-root-cert.crt.txt
117-
----
118-
+
119-
Compare the certificates by running the following syntax at the terminal window.
120-
+
121-
[source,terminal]
122-
----
123-
$ diff -s /tmp/root-cert.crt.txt /tmp/pod-root-cert.crt.txt
124-
----
125-
+
126-
You should see the following result:
127-
`Files /tmp/root-cert.crt.txt and /tmp/pod-root-cert.crt.txt are identical`
128-
129-
130-
. Verify that the CA certificate is the same as the one specified by the administrator. Replace `<path>` with the path to your certificates.
131-
+
132-
[source,terminal]
133-
----
134-
$ openssl x509 -in <path>/ca-cert.pem -text -noout > /tmp/ca-cert.crt.txt
135-
----
136-
Run the following syntax at the terminal window.
137-
+
138-
[source,terminal]
139-
----
140-
$ openssl x509 -in ./proxy-cert-2.pem -text -noout > /tmp/pod-cert-chain-ca.crt.txt
141-
----
142-
Compare the certificates by running the following syntax at the terminal window.
143-
+
144-
[source,terminal]
145-
----
146-
$ diff -s /tmp/ca-cert.crt.txt /tmp/pod-cert-chain-ca.crt.txt
147-
----
148-
You should see the following result:
149-
`Files /tmp/ca-cert.crt.txt and /tmp/pod-cert-chain-ca.crt.txt are identical.`
150-
151-
. Verify the certificate chain from the root certificate to the workload certificate. Replace `<path>` with the path to your certificates.
152-
+
153-
[source,terminal]
154-
----
155-
$ openssl verify -CAfile <(cat <path>/ca-cert.pem <path>/root-cert.pem) ./proxy-cert-1.pem
156-
----
157-
You should see the following result:
158-
`./proxy-cert-1.pem: OK`
159-
160-
[id="ossm-cert-cleanup_{context}"]
161-
== Removing the certificates
162-
163-
To remove the certificates you added, follow these steps.
164-
165-
. Remove the secret `cacerts`. In this example, `istio-system` is the name of the {SMProductShortName} control plane project.
166-
+
167-
[source,terminal]
168-
----
169-
$ oc delete secret cacerts -n istio-system
170-
----
171-
+
172-
. Redeploy {SMProductShortName} with a self-signed root certificate in the `ServiceMeshControlPlane` resource.
173-
+
174-
[source,yaml]
175-
----
176-
apiVersion: maistra.io/v2
177-
kind: ServiceMeshControlPlane
178-
spec:
179-
security:
180-
dataPlane:
181-
mtls: true
182-
----

‎service_mesh/v2x/ossm-security.adoc

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,3 +31,9 @@ include::modules/ossm-security-auth-policy.adoc[leveloffset=+1]
3131
include::modules/ossm-security-cipher.adoc[leveloffset=+1]
3232

3333
include::modules/ossm-security-cert-manage.adoc[leveloffset=+1]
34+
35+
include::modules/ossm-cert-manage-add-cert-key.adoc[leveloffset=+1]
36+
37+
include::modules/ossm-cert-manage-verify-cert.adoc[leveloffset=+1]
38+
39+
include::modules/ossm-cert-cleanup.adoc[leveloffset=+1]

0 commit comments

Comments
 (0)