Skip to content

Commit 44c2545

Browse files
bergerhofferbergerhoffer
committed
OSDOCS-4923: Docs for cert-manager operator GA
1 parent c9bfd83 commit 44c2545

16 files changed

+557
-24
lines changed

‎_topic_maps/_topic_map.yml

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -949,7 +949,10 @@ Topics:
949949
File: cert-manager-operator-release-notes
950950
- Name: Installing the cert-manager Operator for Red Hat OpenShift
951951
File: cert-manager-operator-install
952-
# For GA release, add details here on requesting certificates, etc.
952+
- Name: Managing certificates with an ACME issuer
953+
File: cert-manager-operator-issuer-acme
954+
- Name: Configuring the egress proxy for the cert-manager Operator for Red Hat OpenShift
955+
File: cert-manager-operator-proxy
953956
- Name: Uninstalling the cert-manager Operator for Red Hat OpenShift
954957
File: cert-manager-operator-uninstall
955958
- Name: Viewing audit logs

‎modules/cert-manager-acme-about.adoc

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * security/cert_manager_operator/cert-manager-operator-issuer-acme.adoc
4+
5+
:_content-type: CONCEPT
6+
[id="cert-manager-acme-about_{context}"]
7+
= About ACME issuers
8+
9+
The ACME issuer type for the {cert-manager-operator} represents an Automated Certificate Management Environment (ACME) certificate authority (CA) server. ACME CA servers rely on a _challenge_ to verify that a client owns the domain names that the certificate is being requested for. If the challenge is successful, the {cert-manager-operator} can issue the certificate. If the challenge fails, the {cert-manager-operator} does not issue the certificate.

‎modules/cert-manager-acme-challenges-types.adoc

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * security/cert_manager_operator/cert-manager-operator-issuer-acme.adoc
4+
5+
:_content-type: CONCEPT
6+
[id="cert-manager-acme-challenges-types_{context}"]
7+
= Supported ACME challenges types
8+
9+
The {cert-manager-operator} supports the following challenge types for ACME issuers:
10+
11+
HTTP-01:: With the HTTP-01 challenge type, you provide a computed key at an HTTP URL endpoint in your domain. If the ACME CA server can get the key from the URL, it can validate you as the owner of the domain.
12+
+
13+
For more information, see link:https://cert-manager.io/docs/configuration/acme/http01/[HTTP01] in the upstream cert-manager documentation.
14+
15+
DNS-01:: With the DNS-01 challenge type, you provide a computed key at a DNS TXT record. If the ACME CA server can get the key by DNS lookup, it can validate you as the owner of the domain.
16+
+
17+
For more information, see link:https://cert-manager.io/docs/configuration/acme/dns01/[DNS01] in the upstream cert-manager documentation.

‎modules/cert-manager-acme-dns-providers.adoc

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * security/cert_manager_operator/cert-manager-operator-issuer-acme.adoc
4+
5+
:_content-type: CONCEPT
6+
[id="cert-manager-acme-dns-providers_{context}"]
7+
= Supported DNS-01 providers
8+
9+
The {cert-manager-operator} supports the following DNS-01 providers for ACME issuers:
10+
11+
* Amazon Route 53
12+
* Azure DNS
13+
+
14+
[NOTE]
15+
====
16+
The {cert-manager-operator} does not support using Azure Active Directory (Azure AD) pod identities to assign a managed identity to a pod.
17+
====
18+
* Google Cloud DNS
19+
+
20+
[NOTE]
21+
====
22+
The {cert-manager-operator} does not support using Google workload identity federation.
23+
====

‎modules/cert-manager-acme-dns01-aws.adoc

Lines changed: 170 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,170 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * security/cert_manager_operator/cert-manager-operator-issuer-acme.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="cert-manager-acme-dns01-aws_{context}"]
7+
= Configuring an ACME issuer to solve DNS-01 challenges
8+
9+
You can use {cert-manager-operator} to set up an ACME issuer to solve DNS-01 challenges. This procedure uses _Let's Encrypt_ as the ACME CA server and shows how to solve DNS-01 challenges with Amazon Route 53.
10+
11+
[NOTE]
12+
====
13+
Private DNS zones are not supported.
14+
====
15+
16+
.Prerequisites
17+
18+
* You have access to the {product-title} cluster as a user with the `cluster-admin` role.
19+
* You have set up an IAM role for Amazon Route 53. For more information, see link:https://cert-manager.io/docs/configuration/acme/dns01/route53/[Route53] in the upstream cert-manager documentation.
20+
+
21+
[NOTE]
22+
====
23+
If your cluster is _not_ configured to use the AWS Security Token Service (STS), you must provide explicit `accessKeyID` and `secretAccessKey` credentials. If you cluster uses AWS STS, you can use implicit ambient credentials.
24+
====
25+
26+
.Procedure
27+
28+
. Optional: Override the nameserver settings for the DNS-01 self check:
29+
+
30+
This step is required only when the target public-hosted zone overlaps with the cluster's default private-hosted zone.
31+
32+
.. Edit the `CertManager` resource by running the following command:
33+
+
34+
[source,terminal]
35+
----
36+
$ oc edit certmanager cluster
37+
----
38+
39+
.. Add a `spec.controllerConfig` section with the following override arguments:
40+
+
41+
[source,yaml]
42+
----
43+
apiVersion: operator.openshift.io/v1alpha1
44+
kind: CertManager
45+
metadata:
46+
name: cluster
47+
...
48+
spec:
49+
...
50+
controllerConfig: <1>
51+
overrideArgs:
52+
- '--dns01-recursive-nameservers=1.1.1.1:53' <2>
53+
- '--dns01-recursive-nameservers-only' <3>
54+
----
55+
<1> Add the `spec.controllerConfig` section.
56+
<2> Provide a comma-separated list of `<host>:<port>` nameservers to query for the DNS-01 self check.
57+
<3> Specify to only use recursive nameservers instead of checking the authoritative nameservers associated with that domain.
58+
59+
.. Save the file to apply the changes.
60+
61+
. Optional: Create a namespace for the issuer.
62+
63+
.. Create a YAML file that defines a `Namespace` object:
64+
+
65+
.Example `namespace.yaml` file
66+
[source,yaml]
67+
----
68+
apiVersion: v1
69+
kind: Namespace
70+
metadata:
71+
name: my-issuer-namespace <1>
72+
----
73+
<1> Specify the namespace for the issuer.
74+
75+
.. Create the `Namespace` object by running the following command:
76+
+
77+
[source,terminal]
78+
----
79+
$ oc create -f namespace.yaml
80+
----
81+
82+
. Create a secret to store your AWS credentials in by running the following command:
83+
+
84+
[source,terminal]
85+
----
86+
$ oc create secret generic aws-secret --from-literal=awsSecretAccessKey=<aws_secret_access_key> \ <1>
87+
-n my-issuer-namespace
88+
----
89+
<1> Replace `<aws_secret_access_key>` with your AWS secret access key.
90+
91+
. Create an issuer.
92+
93+
.. Create a YAML file that defines the `Issuer` object:
94+
+
95+
.Example `issuer.yaml` file
96+
[source,yaml]
97+
----
98+
apiVersion: cert-manager.io/v1
99+
kind: Issuer
100+
metadata:
101+
name: letsencrypt-staging <1>
102+
namespace: my-issuer-namespace <2>
103+
spec:
104+
acme:
105+
server: https://acme-staging-v02.api.letsencrypt.org/directory <3>
106+
email: "<email_address>" <4>
107+
privateKeySecretRef:
108+
name: <secret_private_key> <5>
109+
solvers:
110+
- dns01:
111+
route53:
112+
accessKeyID: <aws_key_id> <6>
113+
hostedZoneID: <hosted_zone_id> <7>
114+
region: us-east-1
115+
secretAccessKeySecretRef:
116+
name: "aws-secret" <8>
117+
key: "awsSecretAccessKey" <9>
118+
----
119+
<1> Provide a name for the issuer.
120+
<2> Specify the namespace that you created for the issuer.
121+
<3> Specify the URL to access the ACME server's `directory` endpoint. This example uses the _Let's Encrypt_ staging environment.
122+
<4> Replace `<email_address>` with your email address.
123+
<5> Replace `<secret_private_key>` with the name of the secret to store the ACME account private key in.
124+
<6> Replace `<aws_key_id>` with your AWS key ID.
125+
<7> Replace `<hosted_zone_id>` with your hosted zone ID.
126+
<8> Specify the name of the secret you created.
127+
<9> Specify the key in the secret you created that stores your AWS secret access key.
128+
129+
.. Create the `Issuer` object by running the following command:
130+
+
131+
[source,terminal]
132+
----
133+
$ oc create -f issuer.yaml
134+
----
135+
136+
. Create a certificate.
137+
138+
.. Create a YAML file that defines the `Certificate` object:
139+
+
140+
.Example `certificate.yaml` file
141+
[source,yaml]
142+
----
143+
apiVersion: cert-manager.io/v1
144+
kind: Certificate
145+
metadata:
146+
name: my-tls-cert <1>
147+
namespace: my-issuer-namespace <2>
148+
spec:
149+
isCA: false
150+
commonName: '<common_name>' <3>
151+
secretName: my-tls-cert <4>
152+
dnsNames:
153+
- '<domain_name>' <5>
154+
issuerRef:
155+
name: letsencrypt-staging <6>
156+
kind: Issuer
157+
----
158+
<1> Provide a name for the certificate.
159+
<2> Specify the namespace that you created for the issuer.
160+
<3> Replace `<common_name>` with your common name (CN).
161+
<4> Specify the name of the secret to create that will contain the certificate.
162+
<5> Replace `<domain_name>` with your domain name.
163+
<6> Specify the name of the issuer that you created.
164+
165+
.. Create the `Certificate` object by running the following command:
166+
+
167+
[source,terminal]
168+
----
169+
$ oc create -f certificate.yaml
170+
----

‎modules/cert-manager-acme-http01.adoc

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * security/cert_manager_operator/cert-manager-operator-issuer-acme.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="cert-manager-acme-http01_{context}"]
7+
= Configuring an ACME issuer to solve HTTP-01 challenges
8+
9+
You can use {cert-manager-operator} to set up an ACME issuer to solve HTTP-01 challenges. This procedure uses Let's Encrypt as the ACME CA server.
10+
11+
.Prerequisites
12+
13+
* You have access to the cluster as a user with the `cluster-admin` role.
14+
* You have a service that you want to expose. In this procedure, the service is named `sample-workload`.
15+
16+
.Procedure
17+
18+
. Create an ACME cluster issuer.
19+
20+
.. Create a YAML file that defines the `ClusterIssuer` object:
21+
+
22+
.Example `acme-cluster-issuer.yaml` file
23+
[source,yaml]
24+
----
25+
apiVersion: cert-manager.io/v1
26+
kind: ClusterIssuer
27+
metadata:
28+
name: letsencrypt-staging <1>
29+
spec:
30+
acme:
31+
preferredChain: ""
32+
privateKeySecretRef:
33+
name: <secret_for_private_key> <2>
34+
server: https://acme-staging-v02.api.letsencrypt.org/directory <3>
35+
solvers:
36+
- http01:
37+
ingress:
38+
class: openshift-default <4>
39+
----
40+
<1> Provide a name for the cluster issuer.
41+
<2> Replace `<secret_private_key>` with the name of secret to store the ACME account private key in.
42+
<3> Specify the URL to access the ACME server's `directory` endpoint. This example uses the Let's Encrypt staging environment.
43+
<4> Specify the Ingress class.
44+
45+
.. Create the `ClusterIssuer` object by running the following command:
46+
+
47+
[source,terminal]
48+
----
49+
$ oc create -f acme-cluster-issuer.yaml
50+
----
51+
52+
. Create an Ingress to expose the service of the user workload.
53+
54+
.. Create a YAML file that defines a `Namespace` object:
55+
+
56+
.Example `namespace.yaml` file
57+
[source,yaml]
58+
----
59+
apiVersion: v1
60+
kind: Namespace
61+
metadata:
62+
name: my-ingress-namespace <1>
63+
----
64+
<1> Specify the namespace for the Ingress.
65+
66+
.. Create the `Namespace` object by running the following command:
67+
+
68+
[source,terminal]
69+
----
70+
$ oc create -f namespace.yaml
71+
----
72+
73+
.. Create a YAML file that defines the `Ingress` object:
74+
+
75+
.Example `ingress.yaml` file
76+
[source,yaml]
77+
----
78+
apiVersion: networking.k8s.io/v1
79+
kind: Ingress
80+
metadata:
81+
name: sample-ingress <1>
82+
namespace: my-ingress-namespace <2>
83+
annotations:
84+
cert-manager.io/cluster-issuer: letsencrypt-staging <3>
85+
acme.cert-manager.io/http01-ingress-class: openshift-default <4>
86+
spec:
87+
ingressClassName: openshift-default <5>
88+
tls:
89+
- hosts:
90+
- <hostname> <6>
91+
secretName: sample-tls <7>
92+
rules:
93+
- host: <hostname> <8>
94+
http:
95+
paths:
96+
- path: /
97+
pathType: Prefix
98+
backend:
99+
service:
100+
name: sample-workload <9>
101+
port:
102+
number: 80
103+
----
104+
<1> Specify the name of the Ingress.
105+
<2> Specify the namespace that you created for the Ingress.
106+
<3> Specify the cluster issuer that you created.
107+
<4> Specify the Ingress class.
108+
<5> Specify the Ingress class.
109+
<6> Replace `<hostname>` with the Subject Alternative Name to be associated with the certificate. This name is used to add DNS names to the certificate.
110+
<7> Specify the secret to store the created certificate in.
111+
<8> Replace `<hostname>` with the hostname. You can use the `<host_name>.<cluster_ingress_domain>` syntax to take advantage of the `*.<cluster_ingress_domain>` wildcard DNS record and serving certificate for the cluster. For example, you might use `apps.<cluster_base_domain>`. Otherwise, you must ensure that a DNS record exists for the chosen hostname.
112+
<9> Specify the name of the service to expose. This example uses a service named `sample-workload`.
113+
114+
.. Create the `Ingress` object by running the following command:
115+
+
116+
[source,terminal]
117+
----
118+
$ oc create -f ingress.yaml
119+
----

‎modules/cert-manager-install-console.adoc

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -24,12 +24,11 @@ You can use the web console to install the {cert-manager-operator}.
2424
. Select the *{cert-manager-operator}* and click *Install*.
2525

2626
. On the *Install Operator* page:
27-
.. The *Update channel* is set to *tech-preview*, which installs the latest Technology Preview release of the {cert-manager-operator}.
28-
.. The *Installation Mode* is set to *All namespaces on the cluster (default)*. This mode installs the Operator in the Operator-recommended `openshift-cert-manager-operator` namespace to watch and be made available to all namespaces in the cluster.
29-
.. Choose the *Installed Namespace* for the Operator. The default Operator recommended namespace is `openshift-cert-manager-operator`.
27+
.. Update the *Update channel*, if necessary. The channel defaults to *stable-v1*, which installs the latest stable release of the {cert-manager-operator}.
28+
.. Choose the *Installed Namespace* for the Operator. The default Operator namespace is `cert-manager-operator`.
3029
+
31-
If the `openshift-cert-manager-operator` namespace does not exist, it is created for you.
32-
.. Click the *Enable Operator recommended cluster monitoring on the Namespace* checkbox to enable cluster monitoring for the Operator.
30+
If the `cert-manager-operator` namespace does not exist, it is created for you.
31+
3332
.. Select an *Update approval* strategy.
3433
+
3534
* The *Automatic* strategy allows Operator Lifecycle Manager (OLM) to automatically update the Operator when a new version is available.
@@ -41,4 +40,4 @@ If the `openshift-cert-manager-operator` namespace does not exist, it is created
4140
.Verification
4241

4342
. Navigate to *Operators* -> *Installed Operators*.
44-
. Verify that *{cert-manager-operator}* is listed with a *Status* of *Succeeded*.
43+
. Verify that *{cert-manager-operator}* is listed with a *Status* of *Succeeded* in the `cert-manager-operator` namespace.

‎modules/cert-manager-issuer-types.adoc

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * security/cert_manager_operator/index.adoc
4+
5+
:_content-type: CONCEPT
6+
[id="cert-manager-issuer-types_{context}"]
7+
= Supported issuer types
8+
9+
The {cert-manager-operator} supports the following issuer types:
10+
11+
* Automated Certificate Management Environment (ACME)
12+
* Certificate authority (CA)
13+
* Self-signed

0 commit comments

Comments
 (0)