Skip to content

Commit eb757ef

Browse files
nightkrNickLarsenNZ
nightkr
and
NickLarsenNZ
authored
Document how to use with Cert-Manager (#475)
* Document how to use with Cert-Manager Fixes #473 * Update docs/modules/secret-operator/pages/cert-manager.adoc Co-authored-by: Nick <10092581+NickLarsenNZ@users.noreply.github.com> * Update docs/modules/secret-operator/pages/cert-manager.adoc Co-authored-by: Nick <10092581+NickLarsenNZ@users.noreply.github.com> * Drop mention of node scope --------- Co-authored-by: Nick <10092581+NickLarsenNZ@users.noreply.github.com>
1 parent b034d99 commit eb757ef

File tree

6 files changed

+209
-0
lines changed

6 files changed

+209
-0
lines changed

‎docs/modules/secret-operator/examples/cert-manager/certificate.yaml

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
---
2+
apiVersion: cert-manager.io/v1
3+
kind: Certificate
4+
metadata:
5+
name: my-app-tls # <1>
6+
spec:
7+
secretName: my-app-tls # <2>
8+
secretTemplate:
9+
labels:
10+
secrets.stackable.tech/class: tls-cert-manager # <3>
11+
secrets.stackable.tech/service: my-app # <4>
12+
dnsNames:
13+
- my-app # <5>
14+
issuerRef:
15+
kind: Issuer
16+
name: secret-operator-demonstration # <6>

‎docs/modules/secret-operator/examples/cert-manager/issuer.yaml

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
---
2+
apiVersion: cert-manager.io/v1
3+
kind: Issuer
4+
metadata:
5+
name: secret-operator-demonstration # <1>
6+
spec:
7+
ca:
8+
secretName: secret-operator-demonstration-ca
9+
# Create a self-signed CA for secret-operator-demonstration to use
10+
---
11+
apiVersion: cert-manager.io/v1
12+
kind: Certificate
13+
metadata:
14+
name: secret-operator-demonstration-ca
15+
spec:
16+
secretName: secret-operator-demonstration-ca
17+
isCA: true
18+
commonName: Stackable Secret Operator/Cert-Manager Demonstration CA
19+
issuerRef:
20+
kind: Issuer
21+
name: secret-operator-demonstration-ca
22+
---
23+
apiVersion: cert-manager.io/v1
24+
kind: Issuer
25+
metadata:
26+
name: secret-operator-demonstration-ca
27+
spec:
28+
selfSigned: {}

‎docs/modules/secret-operator/examples/cert-manager/pod.yaml

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
---
2+
apiVersion: apps/v1
3+
kind: Deployment
4+
metadata:
5+
name: my-app
6+
spec:
7+
replicas: 1
8+
selector:
9+
matchLabels:
10+
app: my-app
11+
template:
12+
metadata:
13+
labels:
14+
app: my-app
15+
spec:
16+
containers:
17+
- name: nginx
18+
image: nginx
19+
volumeMounts:
20+
- name: tls
21+
mountPath: /tls
22+
- name: config
23+
mountPath: /etc/nginx/conf.d
24+
ports:
25+
- name: https
26+
containerPort: 443
27+
volumes:
28+
- name: tls # <1>
29+
ephemeral:
30+
volumeClaimTemplate:
31+
metadata:
32+
annotations:
33+
secrets.stackable.tech/class: tls-cert-manager # <2>
34+
secrets.stackable.tech/scope: service=my-app # <3>
35+
spec:
36+
storageClassName: secrets.stackable.tech
37+
accessModes:
38+
- ReadWriteOnce
39+
resources:
40+
requests:
41+
storage: "1"
42+
- name: config
43+
configMap:
44+
name: my-app
45+
--- # <4>
46+
apiVersion: v1
47+
kind: ConfigMap
48+
metadata:
49+
name: my-app
50+
data:
51+
default.conf: |
52+
server {
53+
listen 443 ssl;
54+
ssl_certificate /tls/tls.crt;
55+
ssl_certificate_key /tls/tls.key;
56+
location / {
57+
root /usr/share/nginx/html;
58+
index index.html index.htm;
59+
}
60+
}
61+
--- # <5>
62+
apiVersion: v1
63+
kind: Service
64+
metadata:
65+
name: my-app
66+
spec:
67+
selector:
68+
app: my-app
69+
ports:
70+
- name: https
71+
port: 443

‎docs/modules/secret-operator/examples/cert-manager/secretclass.yaml

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
apiVersion: secrets.stackable.tech/v1alpha1
3+
kind: SecretClass
4+
metadata:
5+
name: tls-cert-manager # <1>
6+
spec:
7+
backend:
8+
k8sSearch:
9+
searchNamespace:
10+
pod: {} # <2>

‎docs/modules/secret-operator/pages/cert-manager.adoc

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
= Cert-Manager Integration
2+
3+
https://cert-manager.io/[Cert-Manager] is a common tool to manage certificates in Kubernetes, especially when backed by an external
4+
Certificate Authority (CA) such as https://letsencrypt.org/[Let\'s Encrypt].
5+
6+
The Stackable Secret Operator does not currently support managing Cert-Manager certificates directly, but it can be configured to consume certificates generated by it.
7+
8+
[#caveats]
9+
== Caveats
10+
11+
Cert-Manager is designed to manage relatively long-lived certificates that are stored in Kubernetes Secrets. By contrast,
12+
the Stackable Secret Operator is designed to generate temporary short-lived certificates.
13+
14+
This has a couple of repercussions:
15+
16+
- Longer-lived certificates mean that a leaked certificate has potential to be abused for longer.
17+
- Application teams may have access to read Secrets in their respective applications' Namespaces.
18+
19+
Where possible, we recommend using the xref:secretclass.adoc#backend-autotls[`autoTls` backend] instead.
20+
21+
[#issuer]
22+
== Configuring Cert-Manager
23+
24+
NOTE: We recommend using the xref:secretclass.adoc#backend-autotls[`autoTls` backend] instead for self-signed PKIs. We use Cert-Manager's CA issuer here to show the broader concepts.
25+
26+
To do this, you will first need to teach Cert-Manager how to create your certificates.
27+
28+
In a production setup this will likely use an external CA such as ACME or OpenBao/Vault. However, to make this guide self-contained, Cert-Manager will create
29+
a self-signed CA certificate instead.
30+
31+
[source,yaml]
32+
----
33+
include::example$cert-manager/issuer.yaml[]
34+
----
35+
<1> This is the Issuer that our created certificates will reference later
36+
37+
[#secretclass]
38+
== Creating a SecretClass
39+
40+
The Stackable Secret Operator needs to know how to find the certificates created by Cert-Manager. We do this by creating
41+
a xref:secretclass.adoc[] using the xref:secretclass.adoc#backend-k8ssearch[`k8sSearch` backend], which can find arbitrary
42+
Kubernetes Secret objects that have the correct labels.
43+
44+
[source,yaml]
45+
----
46+
include::example$cert-manager/secretclass.yaml[]
47+
----
48+
<1> Both certificates and Pods will reference this name, to ensure that the correct certificates are found
49+
<2> This informs the Secret Operator that certificates will be found in the same namespace as the Pod using it
50+
51+
[#certificate]
52+
== Requesting a certificate
53+
54+
You can now use Cert-Manager to provision your first certificate. Use labels to inform the Stackable Secret Operator
55+
about which xref:scope.adoc[scopes] the certificate fulfills. Which scopes must be provisioned is going to depend
56+
on the design of the workload. This guide assumes the xref:scope.adoc#service[service] scope.
57+
58+
[source,yaml]
59+
----
60+
include::example$cert-manager/certificate.yaml[]
61+
----
62+
<1> The Certificate name is irrelevant for the Stackable Secret Operator's, but must be unique (within the Namespace)
63+
<2> The Secret name must also be unique within the Namespace
64+
<3> This tells the Stackable Secret Operator that this secret corresponds to the SecretClass created xref:#secretclass[before]
65+
<4> This secret fulfils the xref:scope.adoc#service[service] scope for `my-app`
66+
<5> The list of DNS names that this certificate should apply to.
67+
<6> The Cert-Manager Issuer that should sign this certificate, as created xref:#issuer[before]
68+
69+
[#pod]
70+
== Using the certificate
71+
72+
Finally, we can create and expose a Pod that consumes the certificate!
73+
74+
[source,yaml]
75+
----
76+
include::example$cert-manager/pod.yaml[]
77+
----
78+
<1> A secret xref:volume.adoc[volume] is created, where the certificate will be exposed to the app
79+
<2> The volume references the SecretClass defined xref:#secretclass[before]
80+
<3> The app is designated the scope xref:scope#service[`service=my-app`], matching the xref:#certificate[certificate's scope]
81+
<4> nginx is configured to use the mounted certificate
82+
<5> nginx is exposed as a Kubernetes Service

‎docs/modules/secret-operator/partials/nav.adoc

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,8 @@
66
** xref:secret-operator:secretclass.adoc[]
77
** xref:secret-operator:scope.adoc[]
88
** xref:secret-operator:volume.adoc[]
9+
* Guides
10+
** xref:secret-operator:cert-manager.adoc[]
911
* xref:secret-operator:security.adoc[]
1012
* xref:secret-operator:reference/index.adoc[]
1113
** xref:secret-operator:reference/crds.adoc[]

0 commit comments

Comments
 (0)