Skip to content

Commit 0d918c6

Browse files
jwilliams-mongojwilliams-mongo
committed
DOCSP-22213: Document TLS migration in operator (#924)
1 parent 98de06e commit 0d918c6

File tree

4 files changed

+180
-0
lines changed

4 files changed

+180
-0
lines changed

‎conf.py

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -245,6 +245,7 @@
245245
'wikipedia' : ('https://en.wikipedia.org/wiki%s', ''),
246246
'k8sdocs': ('https://kubernetes.io/docs%s', ''),
247247
'v1.2': ('https://www.mongodb.com/docs/kubernetes-operator/v1.2%s', ''),
248+
'v1.13': ('https://www.mongodb.com/docs/kubernetes-operator/v1.13%s', ''),
248249
'github' : ('https://github.com%s', ''),
249250
'github-raw' : ('https://raw.githubusercontent.com%s', ''),
250251
'mdb-github' : ('https://mongodb.github.io%s', ''),

‎source/includes/steps-migrate-to-new-tls-format.yaml

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
---
2+
title: "Upgrade |k8s-op-short| to its latest version."
3+
level: 4
4+
ref: upgrade-to-latest
5+
content: |
6+
To learn how to upgrade the |k8s-op-short|, see
7+
:ref:`upgrade-k8s-operator`.
8+
9+
---
10+
title: "Wait for the |k8s-op-short| Pods to reach a ``READY`` state."
11+
level: 4
12+
ref: wait-for-ready-resources
13+
content: |
14+
15+
Use the following command to get the status of the Pods in your
16+
cluster:
17+
18+
.. code-block:: sh
19+
20+
kubectl get pods -n <namespace> -w
21+
22+
Inspect the response. In the ``READY`` column for your |k8s-op-short|
23+
Pod, ensure that the value in this column shows that all Pods are
24+
ready. In the following sample output, the single |k8s-op-short| Pod
25+
is ready.
26+
27+
.. code-block:: sh
28+
:copyable: false
29+
:emphasize-lines: 2
30+
31+
NAME READY STATUS RESTARTS AGE
32+
mongodb-enterprise-operator-d7d5d9b7c-p4xl4 1/1 Running 0 7m39s
33+
34+
When all |k8s-op-short| Pods are ``READY``, proceed to the next step.
35+
36+
---
37+
title: "Create new |tls| secrets that contain your existing certificates."
38+
level: 4
39+
ref: create-new-tls-secrets
40+
content: |
41+
Using the certificates stored in your existing secrets, create one new
42+
secret for each component that you want to secure using |tls|.
43+
44+
For more information, see the prerequisites in the |k8s-op-short|
45+
|tls| tutorials:
46+
47+
- :ref:`secure-om-db-tls` for Application Database resources
48+
- :ref:`deploy-om-container` for |onprem| resources
49+
- :ref:`k8s-secure-resources` for database resources
50+
51+
---
52+
title: "Update your CRDs to use the new |tls| secret fields."
53+
level: 4
54+
ref: update-crds
55+
content: |
56+
57+
In each of the resources that you secure with |tls|, update the
58+
following fields, as appropriate, to reference the new |tls| secrets
59+
you created in the previous step:
60+
61+
- Application Database |tls| secrets: :opsmgrkube:`applicationDatabase.security.certsSecretPrefix`
62+
- |onprem| |tls| secrets: :opsmgrkube:`security.certsSecretPrefix`
63+
- Database resource |tls| secrets: :setting:`security.security.certsSecretPrefix`
64+
65+
---
66+
title: "Replace the CRDs in your |k8s| cluster."
67+
level: 4
68+
ref: apply-crds
69+
content: |
70+
For each CRD you updated, run the following command to apply your
71+
changes to the |k8s| cluster:
72+
73+
.. code-block:: sh
74+
75+
kubectl replace -f <resource-crd>.yaml
76+
77+
---
78+
title: "Re-enable internal cluster authentication and X.509 authentication."
79+
level: 4
80+
optional: true
81+
ref: enable-internal-auth-x509
82+
content: |
83+
84+
When all of the resources you updated reach a ``READY`` state, you can
85+
re-enable internal cluster authentication and X.509 authentication if
86+
you disabled it to migrate your |tls| secrets.
87+
88+
...

‎source/tutorial/migrate-to-new-tls-format.txt

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
.. _migrate-to-new-tls-format:
2+
3+
===================================================
4+
Upgrade from |k8s-op-short| 1.12 with |tls| Enabled
5+
===================================================
6+
7+
.. default-domain:: mongodb
8+
9+
.. contents:: On this page
10+
:local:
11+
:backlinks: none
12+
:depth: 1
13+
:class: singlecol
14+
15+
.. include:: /includes/styles/corrections.rst
16+
17+
|k8s-op| 1.13 :v1.13:`introduced several changes
18+
</release-notes/#k8s-op-short>` to how it handles |tls| secrets for
19+
|onprem| and database deployments.
20+
21+
If you installed |k8s-op-short| 1.12 or earlier and you secure access to
22+
your resources using |tls|, complete this task to upgrade to the latest
23+
|k8s-op-short| version and migrate your opaque |tls| secrets to
24+
:k8sdocs:`kubernetes.io/tls
25+
</concepts/configuration/secret/#tls-secrets>` type secrets without
26+
re-creating your MongoDB resources and incurring downtime.
27+
28+
Considerations
29+
--------------
30+
31+
|k8s-op-short| can migrate your |tls| secrets when you
32+
upgrade from 1.12 or earlier to the latest version for as long as 1.12
33+
is supported. After |k8s-op-short| 1.12 reaches End of Life (EOL), you
34+
might not be able to migrate your |tls| secrets automatically when you
35+
upgrade.
36+
37+
Limitations
38+
-----------
39+
40+
|k8s-op-short| doesn't migrate the following |tls| secret
41+
types:
42+
43+
- |tls| secrets that contain X.509 certificates for internal
44+
server authentication
45+
- |tls| secrets that contain {+mdbagent+} X.509 certificates
46+
47+
You must manually migrate these types of |tls| secrets from opaque to
48+
:k8sdocs:`kubernetes.io/tls
49+
</concepts/configuration/secret/#tls-secrets>` type secrets by creating
50+
new secrets that contain the relevant certificates and signing keys. To
51+
learn how to create these secrets, see the following resources:
52+
53+
- :ref:`secure-tls`
54+
- :ref:`secure-internal-auth`
55+
56+
Prerequisites
57+
-------------
58+
59+
- Before you migrate your |tls| secrets and upgrade |k8s-op-short|, your
60+
CRDs must use the following fields to describe your |tls| secrets:
61+
62+
- Application Database |tls| secrets: :opsmgrkube:`applicationDatabase.security.tls.secretRef.prefix`
63+
- |onprem| |tls| secrets: :opsmgrkube:`security.tls.secretRef.prefix`
64+
- Database resource |tls| secrets: :setting:`security.tls.secretRef.prefix`
65+
66+
If your CRDs use any of the following fields to describe your |tls|
67+
secrets, you must first update your CRDs to use the fields listed
68+
above instead:
69+
70+
- Application Database |tls| secrets:
71+
``spec.applicationDatabase.security.tls.secretRef.name``
72+
- |onprem| |tls| secrets: ``spec.security.tls.secretRef.name``
73+
- Database resource |tls| secrets: ``spec.security.tls.secretRef.name``
74+
75+
- You must disable internal cluster and X.509 authentication before you
76+
upgrade |k8s-op-short| to its latest
77+
version.
78+
79+
When the upgrade is complete, you can re-enable internal cluster and
80+
X.509 authentication.
81+
82+
Procedure
83+
---------
84+
85+
.. include:: /includes/steps/migrate-to-new-tls-format.rst

‎source/upgrade.txt

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,10 +20,16 @@ Upgrade the |k8s-op-short| from Prior Versions
2020
:ref:`migrate-to-ent-appdb-version`
2121
Migrate the Application Database to the latest MongoDB version.
2222

23+
:ref:`migrate-to-new-tls-format`
24+
Migrate opaque |tls| secrets from |k8s-op-short| 1.12 or earlier to
25+
secrets of the :k8sdocs:`kubernetes.io/tls
26+
</concepts/configuration/secret/#tls-secrets>` type.
27+
2328
.. class:: hidden
2429

2530
.. toctree::
2631
:titlesonly:
2732

2833
/tutorial/upgrade-k8s-operator
2934
/tutorial/migrate-to-ent-appdb-version
35+
/tutorial/migrate-to-new-tls-format

0 commit comments

Comments
 (0)