Skip to content

Commit 3f14122

Browse files
jeff-allen-mongojwilliams-mongo
jeff-allen-mongo
authored and
jwilliams-mongo
committed
(DOCSP-5850): Adding instructions for creating x.509 certs (#62)
* (DOCSP-5850): Adding instructions for creating x.509 certs * quick fix * Apply suggestions from code review Co-Authored-By: Anthony Sansone <[email protected]> * Updates per Tony's feedback * Apply suggestions from code review Co-Authored-By: Anthony Sansone <[email protected]> * tweaks * Apply suggestions from code review Co-Authored-By: Anthony Sansone <[email protected]> * updates per Tony's feedback
1 parent 3c5263e commit 3f14122

12 files changed

+428
-1
lines changed

‎source/deploy.txt

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
:noprevnext:
22

3+
.. _deploy-resources:
4+
35
================
46
Deploy Resources
57
================

‎source/includes/steps-connect-to-x509-deployment.yaml

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
---
2+
title: "Copy and save the following example |k8s-configmap|."
3+
level: 4
4+
stepnum: 1
5+
ref: copy-k8s-x509-configmap
6+
content: |
7+
8+
Save the following ConfigMap as ``x509-mongodb-user.yaml``:
9+
10+
.. code-block:: none
11+
:linenos:
12+
13+
---
14+
apiVersion: mongodb.com/v1
15+
kind: MongoDBUser
16+
metadata:
17+
name: new-x509-user
18+
spec:
19+
username: "CN=my-x509-authenticated-user, OU=organizationalunit, O=organization"
20+
db: "$external"
21+
project: my-project
22+
roles:
23+
- db: "admin"
24+
name: "clusterAdmin"
25+
26+
This ConfigMap ``.yaml`` file describes a ``MongoDBUser`` custom object. You
27+
can use these custom objects to create MongoDB users.
28+
29+
In this example, the ConfigMap describes the user as an X.509
30+
user that the client can use to connect to MongoDB with the
31+
corresponding X.509 certificate.
32+
---
33+
title: "Create the X.509 MongoDB user."
34+
level: 4
35+
stepnum: 2
36+
ref: create-x509-user
37+
content: |
38+
Run the following command to apply the ConfigMap and create the
39+
X.509 MongoDB user:
40+
41+
.. code-block:: sh
42+
43+
kubectl -n {namespace} apply -f x509-mongodb-user.yaml
44+
45+
You should see an output similar to the following:
46+
47+
.. code-block:: sh
48+
:copyable: false
49+
50+
mongodbuser.mongodb.com/new-x509-user created
51+
---
52+
title: "Verify your newly created user"
53+
level: 4
54+
stepnum: 3
55+
ref: verify-x509-user
56+
content: |
57+
Run the following command to check the state of the ``new-x509-user``:
58+
59+
.. code-block:: sh
60+
61+
kubectl -n {namespace} get mdbu/new-x509-user -o yaml
62+
63+
You should see an output similar to the following:
64+
65+
.. code-block:: sh
66+
:copyable: false
67+
68+
NAME CREATED AT
69+
new-x509-user 8m
70+
---
71+
title: "Use your X.509 user to connect to the MongoDB deployment"
72+
level: 4
73+
stepnum: 4
74+
ref: connect-with-x509-user
75+
content: |
76+
Once you have created your X.509 user, try to connect to the
77+
deployment using the mongo Shell:
78+
79+
.. code-block:: sh
80+
81+
mongo --host {host} --ssl --sslCAFile /var/run/secrets/kubernetes.io/serviceaccount/ca.crt --sslPEMKeyFile x509-full.pem --authenticationMode MONGODB-X509
82+
83+
.. note::
84+
85+
On Kubernetes Pods, the |certauth| file is saved in
86+
``/var/run/secrets/kubernetes.io/serviceaccount/ca.crt``, which
87+
is the file location used for the ``--sslCAFile`` connection
88+
option.

‎source/includes/steps-create-cert-signing-req.yaml

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
---
2+
title: "Create a new directory to complete this tutorial."
3+
level: 4
4+
stepnum: 1
5+
ref: create-new-dire
6+
content: |
7+
Run the following command to create a new directory for
8+
the configuration files used in this tutorial:
9+
10+
.. code-block:: sh
11+
12+
mkdir client-x509-certs-tutorial
13+
---
14+
title: "Enter your newly created directory."
15+
level: 4
16+
stepnum: 2
17+
ref: cd-new-directory
18+
content: |
19+
20+
.. code-block:: sh
21+
22+
cd client-x509-certs-tutorial
23+
---
24+
title: "Copy and save the following example JSON."
25+
level: 4
26+
stepnum: 3
27+
ref: copy-k8s-user-configmap
28+
content: |
29+
30+
In the ``client-x509-certs-tutorial`` directory, save the following
31+
JSON as ``x509_user.json``:
32+
33+
.. code-block:: json
34+
35+
{
36+
"names": [
37+
{"O": "organization"},
38+
{"OU": "organizationalunit"}
39+
],
40+
"CN": "my-x509-authenticated-user",
41+
"key": {
42+
"algo": "rsa",
43+
"size": 4096
44+
}
45+
}
46+
47+
---
48+
title: "Generate a key file."
49+
level: 4
50+
stepnum: 4
51+
ref: gen-key-file
52+
content: |
53+
54+
Run the following command to pass the JSON from the previous step
55+
to ``CFSSL`` and generate a key file:
56+
57+
.. code-block:: sh
58+
59+
cfssl genkey x509_user.json > x509_user_key.json
60+
61+
You should see output similar to the following:
62+
63+
.. code-block:: sh
64+
:copyable: false
65+
66+
2019/06/04 18:12:38 [INFO] generate received request
67+
2019/06/04 18:12:38 [INFO] received CSR
68+
2019/06/04 18:12:38 [INFO] generating key: rsa-4096
69+
2019/06/04 18:12:40 [INFO] encoded CSR
70+
71+
You now have a file called ``x509_user_key.json`` containing
72+
a new private key.
73+
---
74+
title: "Generate the Certificate Signing Request."
75+
level: 4
76+
stepnum: 5
77+
ref: gen-cert-req
78+
content: |
79+
Run the following command to use your ``x509_user_key.json`` key
80+
file to generate a certificate signing request (CSR):
81+
82+
.. code-block:: sh
83+
84+
cfssljson -f x509_user_key.json -bare x509_user
85+
86+
This command generates two files:
87+
88+
- ``x509_user-key.pem``, the private key for the user
89+
90+
- ``x509_user.csr``, the CSR that represents the user
91+
92+
...

‎source/includes/steps-get-cert-from-k8s-ca.yaml

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
---
2+
title: "Generate the X.509 certificate from the :abbr:`CSR (Certificate Signing Request)`."
3+
level: 4
4+
stepnum: 1
5+
ref: save-csr-file
6+
content: |
7+
8+
Run the following command to generate the certificate from the
9+
CSR object to a file called ``client.crt``:
10+
11+
.. code-block:: sh
12+
13+
kubectl get csr x509-user.some-namespace -o jsonpath='{.status.certificate}' | base64 --decode > client.crt
14+
15+
A |mongod| client can use the ``client.crt``
16+
certificate to connect to the X.509-enabled MongoDB deployment.
17+
---
18+
title: "Concatenate the user private key and Kubernetes certificate."
19+
level: 4
20+
stepnum: 2
21+
ref: cat-pem-crt
22+
content: |
23+
You need both the ``x509_user-key.pem`` and ``client.crt`` files
24+
to connect to the deployment. Run the following command to
25+
concatenate the two files into the a new ``.pem`` file:
26+
27+
.. code-block:: sh
28+
29+
cat x509_user-key.pem client.crt > x509-full.pem
30+
31+
...

‎source/includes/steps-submit-cert-request.yaml

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
---
2+
title: "Create a |csr| in Kubernetes."
3+
level: 4
4+
stepnum: 1
5+
ref: create-cert-request-k8s
6+
content: |
7+
8+
Run the following command to create a CSR
9+
in Kubernetes:
10+
11+
.. code-block:: sh
12+
:linenos:
13+
:emphasize-lines: 3
14+
15+
cat <<EOF | kubectl apply -f -
16+
apiVersion: certificates.k8s.io/v1beta1
17+
kind: CertificateSigningRequest
18+
metadata:
19+
name: x509-user.some-namespace
20+
spec:
21+
groups:
22+
- system:authenticated
23+
request: $(cat x509_user.csr | base64 | tr -d '\n')
24+
usages:
25+
- digital signature
26+
- key encipherment
27+
- client auth
28+
EOF
29+
---
30+
title: "View your CSRs."
31+
level: 4
32+
stepnum: 2
33+
ref: view-cert-reqs
34+
content: |
35+
Run the following command to view a list of CSRs:
36+
37+
.. code-block:: sh
38+
39+
kubectl get csr
40+
41+
You should see an output similar to the following:
42+
43+
.. code-block:: sh
44+
:copyable: false
45+
46+
NAME AGE REQUESTOR CONDITION
47+
x509-user.some-namespace 1m system:serviceaccount:some-namespace Pending
48+
---
49+
title: "Approve the CSR."
50+
level: 4
51+
stepnum: 3
52+
ref: approve-cert-req
53+
content: |
54+
55+
The CSR remains in ``Pending`` condition
56+
until Kubernetes approves it. Run the following command to
57+
approve the certificate:
58+
59+
.. code-block:: sh
60+
61+
kubectl certificate approve x509-user.some-namespace
62+
63+
You should see an output similar to the following:
64+
65+
.. code-block:: sh
66+
:copyable: false
67+
68+
certificatesigningrequest.certificates.k8s.io/x509-user.some-namespace approved
69+
---
70+
title: "Verify that your certificate has been approved"
71+
level: 4
72+
stepnum: 4
73+
ref: verify-approval
74+
content: |
75+
Run the following command to verify that the Kubernetes |certauth| has
76+
approved your certificate:
77+
78+
.. code-block:: sh
79+
80+
kubectl get csr
81+
82+
You should see an output similar to the following:
83+
84+
.. code-block:: sh
85+
:copyable: false
86+
87+
NAME AGE REQUESTOR CONDITION
88+
x509-user.some-namespace 45m system:serviceaccount:some-namespace Approved,Issued
89+
90+
...

‎source/includes/toc-installation.yaml

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,13 @@ description: |
1212
Create a |k8s-configmap| to link the |k8s-op-short| to your |com|
1313
Project.
1414
---
15+
file: /tutorial/create-x509-client-certs
16+
description:
17+
Create an X.509 certificate to connect to an X.509-enabled
18+
MongoDB deployment.
19+
---
1520
file: /upgrade
1621
description:
1722
Upgrade from earlier versions of |k8s-op-short|.
23+
1824
...

‎source/installation.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,4 +24,5 @@ Install and Configure the |k8s-op-short|
2424
/tutorial/install-k8s-operator
2525
/tutorial/create-operator-credentials
2626
/tutorial/create-project-using-configmap
27+
/tutorial/create-x509-client-certs
2728
/upgrade

‎source/release-notes.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,7 @@ Release Notes for |k8s-op-full|
5151

5252
- Manages MongoDB users.
5353

54-
- Supports x.509 authentication to your MongoDB databases.
54+
- Supports X.509 authentication to your MongoDB databases.
5555

5656
.. seealso::
5757
To learn how to install and configure the Operator, see :doc:`/installation`.

‎source/tutorial/create-operator-credentials.txt

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,9 @@ only |k8s| can access them.
2222
Multiple secrets can exist in the same namespace. Each user should
2323
have their own secret.
2424

25+
Procedure
26+
---------
27+
2528
To create your |k8s| secret:
2629

2730
1. Make sure you have the Public and Private Keys for your desired
@@ -67,3 +70,6 @@ To create your |k8s| secret:
6770
====
6871
publicApiKey: 31 bytes
6972
user: 22 bytes
73+
74+
Next Steps
75+
----------

0 commit comments

Comments
 (0)