Skip to content

Commit 6a743b8

Browse files
sarahsimpersjwilliams-mongo
sarahsimpers
authored and
jwilliams-mongo
committed
(DOCSP-18168) Adds HashiCorp Vault integration and secret stores info (#770) (#782)
* (DOCSP-18168) Adds HashiCorp Vault integration and secret stores info * Adds more details to configure page * Adds more changes to the secret store page * Changes steps * Changes steps * Changes steps based on notes from engineering, adds notes to affected pages * Moves section on migrating secrets, adds steps * Updates code example * Adds steps, changes code examples * Reconfigures steps and cleans up everything but the roles section * Adds roles steps and cleanup * Adds roles steps and cleanup * Adds roles steps and cleanup * Adds roles steps and cleanup * Adds roles steps and cleanup * Adds roles steps and cleanup * Includes changes from copy review * Makes first round of tech review changes * Changes code examples for binding policies in Vault * Adds note on configuration of other applications * Fixes errors caused by replacements etc
1 parent e6faccb commit 6a743b8

10 files changed

+436
-3
lines changed

‎conf.py‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -120,6 +120,7 @@
120120
'.. |global-write-cluster| replace:: Global Cluster',
121121
'.. |global-write| replace:: Global Writes',
122122
'.. |hardlink| replace:: https://docs.mongodb.com/kubernetes-operator/',
123+
'.. |hashicorp-vault| replace:: `HashiCorp Vault <https://www.vaultproject.io/>`__',
123124
'.. |https| replace:: :abbr:`HTTPS (Hypertext Transfer Protocol Secure)`',
124125
'.. |http| replace:: :abbr:`HTTP (Hypertext Transfer Protocol)`',
125126
'.. |iana| replace:: :abbr:`IANA (Internet Assigned Numbers Authority)`',
@@ -201,6 +202,8 @@
201202
'.. |rest| replace:: :abbr:`REST (Representational State Transfer)`',
202203
'.. |san-dns| replace:: :abbr:`SAN (Subject Alternative Name)`',
203204
'.. |s3| replace:: :abbr:`S3 (Simple Storage Service)`',
205+
'.. |secret-store| replace:: secret storage tool',
206+
'.. |secret-stores| replace:: secret storage tools',
204207
'.. |service-fullname| replace:: MongoDB Atlas',
205208
'.. |service-pricing| replace:: Atlas pricing page',
206209
'.. |service| replace:: Atlas',
@@ -222,6 +225,7 @@
222225
'.. |uri| replace:: :abbr:`URI (Uniform Resource Identifier)`',
223226
'.. |url| replace:: :abbr:`URL (Uniform Resource Locator)`',
224227
'.. |utc| replace:: :abbr:`UTC (Coordinated Universal Time)`',
228+
'.. |vault-short| replace:: Vault',
225229
'.. |vpc| replace:: :abbr:`VPC (Virtual Private Cloud)`',
226230
'.. |yaml| replace:: :abbr:`YAML (Yet Another Markup Language)`',
227231
])

‎source/includes/facts/fact-can-change-secret-storage-tool.rst‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
This |k8s| |k8s-secret|, along with other |k8s-secrets| that |k8s-op-short|
2+
creates, can later be migrated to a different :ref:`secret storage tool <k8s-set-secret-storage-tool>`
3+
to avoid storing secrets in |k8s|.

‎source/includes/steps-use-vault.yaml‎

Lines changed: 292 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,292 @@
1+
stepnum: 1
2+
level: 4
3+
ref: vault-add-policies
4+
title: "Add the |vault-short| policies for the |k8s-op-short| and its components."
5+
content: |
6+
7+
Write the policies for |k8s-op-short|, MongoDB database, |onprem|, and AppDB resources
8+
to |vault-short| using the following command, replacing the variables with the values in the table:
9+
10+
.. list-table::
11+
:widths: 30 70
12+
:header-rows: 1
13+
14+
* - Placeholder
15+
- Description
16+
17+
* - {PolicyName}
18+
- Human-readable label that identifies the policy you're creating in |vault-short|.
19+
20+
* - {PathToPolicyFile}
21+
- The absolute path to the policy file you downloaded.
22+
23+
.. code-block:: sh
24+
25+
vault policy write {PolicyName} {PathToPolicyFile}
26+
27+
Repeat the command for all the resources you're adding to |vault-short|.
28+
29+
---
30+
31+
stepnum: 2
32+
level: 4
33+
ref: vault-add-roles
34+
title: "Bind the |vault-short| roles to the |vault-short| policies for the |k8s-op-short| and its components."
35+
content: |
36+
37+
Bind |vault-short| roles to the policies for |k8s-op-short|, MongoDB database,
38+
|onprem|, and AppDB resources using the following four commands, replacing the
39+
variables with the values in the table:
40+
41+
.. list-table::
42+
:widths: 30 70
43+
:header-rows: 1
44+
45+
* - Placeholder
46+
- Description
47+
48+
* - {OperatorPolicyName}
49+
- A human-readable label that identifies the |k8s-op-short| policy in |vault-short|.
50+
51+
* - {DatabasePolicyName}
52+
- A human-readable label that identifies the MongoDB database policy in |vault-short|.
53+
54+
* - {OpsManagerPolicyName}
55+
- A human-readable label that identifies the |onprem| policy in |vault-short|.
56+
57+
* - {AppDBPolicyName}
58+
- A human-readable label that identifies the AppDB policy in |vault-short|.
59+
60+
* - {ServiceAccountNamespace}
61+
- Label that identifies the namespace for the service account bound to your pod.
62+
63+
.. code-block:: sh
64+
65+
vault write auth/kubernetes/role/{OperatorPolicyName}
66+
bound_service_account_names=enterprise-operator bound_service_account_namespaces={ServiceAccountNamespace}
67+
68+
.. code-block:: sh
69+
70+
vault write auth/kubernetes/role/{DatabasePolicyName}
71+
bound_service_account_names=mongodb-enterprise-database-pods bound_service_account_namespaces={ServiceAccountNamespace}
72+
73+
.. code-block:: sh
74+
75+
vault write auth/kubernetes/role/{OpsManagerPolicyName}
76+
bound_service_account_names=mongodb-enterprise-ops-manager bound_service_account_namespaces={ServiceAccountNamespace}
77+
78+
.. code-block:: sh
79+
80+
vault write auth/kubernetes/role/{AppDBPolicyName}
81+
bound_service_account_names=mongodb-enterprise-appdb bound_service_account_namespaces={ServiceAccountNamespace}
82+
83+
These commands ensure that each component's pods have only the access specified in their
84+
policy.
85+
86+
.. note::
87+
88+
This step grants the |k8s-op-short| access to
89+
|vault-short|. To use |vault-short| with applications that the
90+
|k8s-op-short| doesn't manage, you must write and bind |vault-short| policies for those
91+
applications.
92+
93+
You can adapt the commands in this step to bind other policies by
94+
replacing the name of the |k8s-service-accounts|. To configure other
95+
applications to use |vault-short|, replace the
96+
{ServiceAccountName} in the following command with the service account used
97+
for the application's pod:
98+
99+
.. code-block:: sh
100+
101+
vault write auth/kubernetes/role/{PolicyName}
102+
bound_service_account_names={ServiceAccountName} bound_service_account_namespaces={ServiceAccountNamespace}
103+
104+
105+
---
106+
stepnum: 3
107+
level: 4
108+
ref: vault-add-annotations
109+
title: "Add the annotations to the |k8s| deployment file."
110+
content: |
111+
112+
Add the following highlighted lines to the ``spec.template.metadata.annotations`` section of your
113+
|k8s-op-short| deployment file. For most users, this file's name is ``mongodb-enterprise.yaml`` or
114+
``mongodb-enterprise-openshift.yaml``.
115+
116+
.. note::
117+
118+
If you installed the |k8s-op-short| using Helm, the |k8s-op-short| already
119+
added these annotations. You can proceed to the next step.
120+
121+
.. code-block:: sh
122+
:emphasize-lines: 11-12
123+
124+
apiVersion: apps/v1
125+
kind: Deployment
126+
metadata:
127+
name: mongodb-enterprise-operator
128+
namespace: production
129+
spec:
130+
replicas: 1
131+
template:
132+
metadata:
133+
annotations:
134+
vault.hashicorp.com/agent-inject: "true"
135+
vault.hashicorp.com/role: "mongodbenterprise"
136+
137+
If you're running |vault-short| in |tls| mode, you must also add the following
138+
highlighted line to the file, replacing {TLSSecret} with the name of the secret
139+
containing a ``ca.crt`` entry. The content of the ``ca.crt`` entry must match
140+
the certificate of the |certauth| used to generate the |vault-short| TLS certificates.
141+
142+
.. code-block:: sh
143+
:emphasize-lines: 4-5
144+
145+
annotations:
146+
vault.hashicorp.com/agent-inject: "true"
147+
vault.hashicorp.com/role: "mongodbenterprise"
148+
vault.hashicorp.com/tls-secret: {TLSSecret}
149+
vault.hashicorp.com/ca-cert: /vault/tls/ca.crt
150+
151+
---
152+
stepnum: 4
153+
level: 4
154+
ref: vault-define-environment-variable
155+
title: "Define the environment variable in |k8s|."
156+
content: |
157+
158+
Add the following highlighted lines to the ``spec.env`` section of your
159+
|k8s-op-short| deployment file. For most users, this file's name is ``mongodb-enterprise.yaml`` or
160+
``mongodb-enterprise-openshift.yaml``.
161+
162+
.. code-block:: sh
163+
:emphasize-lines: 10-11
164+
165+
apiVersion: apps/v1
166+
kind: Deployment
167+
metadata:
168+
name: mongodb-enterprise-operator
169+
namespace: production
170+
spec:
171+
env:
172+
- name: OPERATOR_ENV
173+
value: ENVIRONMENT_NAME
174+
- name: SECRET_BACKEND
175+
value: VAULT_BACKEND
176+
177+
This `defines the environment variable <https://kubernetes.io/docs/tasks/inject-data-application/define-environment-variable-container/>`__
178+
for |vault-short| in |k8s|.
179+
---
180+
stepnum: 5
181+
level: 4
182+
ref: vault-create-file
183+
title: "Create a file with the |vault-short| configuration information."
184+
content: |
185+
186+
Using your preferred text editing application, create a file named ``config``.
187+
Paste the following text into the file:
188+
189+
.. code-block:: sh
190+
191+
apiVersion: v1
192+
kind: ConfigMap
193+
metadata:
194+
name: secret-configuration
195+
namespace: {Namespace}
196+
data:
197+
VAULT_SERVER_ADDRESS: {VaultServerAddress}
198+
OPERATOR_SECRET_BASE_PATH: mongodbenterprise/operator
199+
DATABASE_SECRET_BASE_PATH: mongodbenterprise/database
200+
OPS_MANAGER_SECRET_BASE_PATH: mongodbenterprise/opsmanager
201+
APPDB_SECRET_BASE_PATH: mongodbenterprise/appdb
202+
203+
The paths in this file are the default paths. You can replace them with your
204+
base paths if you customized your |k8s-op-short| configuration.
205+
206+
If you're running |vault-short| in |tls| mode, you must also add the following
207+
highlighted line to the file:
208+
209+
.. code-block:: sh
210+
:emphasize-lines: 3
211+
212+
OPS_MANAGER_SECRET_BASE_PATH: mongodbenterprise/opsmanager
213+
APPDB_SECRET_BASE_PATH: mongodbenterprise/appdb
214+
TLS_SECRET_REF: {TLSSecret}
215+
216+
---
217+
stepnum: 6
218+
level: 4
219+
ref: vault-update-file-placeholders
220+
title: "Replace the placeholders in the |vault-short| configuration information."
221+
content: |
222+
223+
Replace the placeholders in the ``config`` file with these values. Save
224+
the file with a |yaml| file type by replacing the ``.txt`` file extension with
225+
``.yaml``.
226+
227+
.. list-table::
228+
:widths: 30 70
229+
:header-rows: 1
230+
231+
* - Placeholder
232+
- Description
233+
234+
* - {Namespace}
235+
- The :ref:`namespace you created <k8s-prerequisites>`
236+
for the |k8s-op-short|. The default namespace is ``mongodb``.
237+
238+
* - {VaultServerAddress}
239+
- The address that the |k8s-op-short| should use to connect to
240+
|vault-short|.
241+
242+
* - {TLSSecret}
243+
- Name of a secret containing a ``ca.crt`` entry. The content of the
244+
``ca.crt`` entry must match the certificate of the |certauth| used to generate
245+
the |vault-short| TLS certificates.
246+
247+
---
248+
stepnum: 7
249+
level: 4
250+
ref: vault-create-configmap
251+
title: "Create a ConfigMap with the |vault-short| configuration."
252+
content: |
253+
254+
Issue the following command to create a |k8s-configmap| containing the |vault-short| information:
255+
256+
.. code-block:: sh
257+
258+
kubectl create configmap secret-configuration --from-file=config.yaml
259+
260+
This creates a |k8s-configmap| named ``secret-configuration``. This
261+
|k8s-configmap| contains the contents of the ``config`` file.
262+
263+
---
264+
stepnum: 8
265+
level: 4
266+
ref: vault-manually-migrate-secrets
267+
title: "Manually migrate secrets that don't migrate automatically"
268+
content: |
269+
270+
You must manually migrate the following secrets to store them in |vault-short|:
271+
272+
- Any existing user-created secrets, including :ref:`Operator credentials stored as Kubernetes secrets <create-k8s-secret>`,
273+
if applicable
274+
- :ref:`The gen-key secret <om-rsrc-considerations-encrypt-key>`
275+
|k8s-op-short| creates
276+
- The |onprem| :ref:`admin credentials/admin key <om-arch-steps>`
277+
|k8s-op-short| creates
278+
- TLS secrets
279+
280+
To manually migrate secrets, `add them to Vault <https://www.vaultproject.io/docs/secrets/kv/kv-v2#usage>`__.
281+
After you add them to |vault-short|, you can remove them from |k8s|.
282+
283+
All other secrets migrate automatically, and |k8s-op-short| uses
284+
|vault-short| for new secrets.
285+
286+
.. note::
287+
288+
cert-manager automatically recreates the |k8s| |k8s-secrets| that
289+
it generates if you delete them from |k8s|. You must manually manage the
290+
removal of these secrets or stop using cert-manager to avoid storing
291+
the secrets in |k8s|.
292+
...

‎source/reference/helm-operator-settings.txt‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -420,6 +420,8 @@ registry.appDb
420420
registry:
421421
appDb: registry.connect.redhat.com/mongodb
422422

423+
.. _imagePullSecrets:
424+
423425
registry.imagePullSecrets
424426
-------------------------
425427

‎source/reference/k8s-operator-om-specification.txt‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,8 @@ resources.
8888
the |onprem| admin user. When you deploy the |onprem| resource,
8989
|k8s-op-short| creates a user with these credentials.
9090

91+
.. include:: /includes/facts/fact-can-change-secret-storage-tool.rst
92+
9193
The admin user is granted the
9294
:opsmgr:`Global Owner </reference/user-roles/#global-automation-admin-role>`
9395
role.

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

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -15,19 +15,22 @@ Create Credentials for the |k8s-op-short|
1515

1616
For the |k8s-op-short| to create or update |k8s-objs| in your |com|
1717
Project, you need to store your :ref:`Programmatic API Key
18-
<create-org-app-api-key>` as a |k8s| |k8s-secret|. Creating a secret
19-
stores authentication credentials so only |k8s| can access them.
18+
<create-org-app-api-key>` in your :doc:`secret storage tool </tutorial/secret-storage>`.
2019

2120
Multiple secrets can exist in the same namespace. Each user should
2221
have their own secret.
2322

2423
You can follow the :ref:`create-k8s-secret-procedure` below to
25-
manually set up the secret. Alternatively, you can use the |cloud|
24+
manually store the :ref:`Programmatic API Key
25+
<create-org-app-api-key>` as a |k8s| |k8s-secret|. Alternatively, you can use the |cloud|
2626
:cloudmgr:`UI </tutorial/nav/k8s-config-for-mdb-resource/>` or the
2727
|onprem| :opsmgr:`UI </tutorial/nav/k8s-config-for-mdb-resource/>` to
2828
automatically generate the Kubernetes secret YAML file, which you can
2929
then apply to your Kubernetes environment.
3030

31+
To use a different |secret-store|, see :doc:`Configure Secret Storage </tutorial/secret-storage>`. You
32+
don't need to complete the following procedure if you use a different |secret-store|.
33+
3134
Prerequisites
3235
-------------
3336

‎source/tutorial/om-arch.txt‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -150,11 +150,15 @@ changes to the ``MongoDBOpsManager`` |k8s-crd|.
150150
Custom Resource Definition
151151
:figwidth: 600px
152152

153+
.. _om-arch-steps:
154+
153155
1. The |k8s-op-short| creates or updates the
154156
``<om_resource_name>-db-config`` Secret. This secret contains
155157
the configurations that the {+mdbagent+} uses to start the
156158
Application Database replica set.
157159

160+
.. include:: /includes/facts/fact-can-change-secret-storage-tool.rst
161+
158162
2. The |k8s-op-short| creates or updates the ``<om_resource_name>-db``
159163
Application Database StatefulSet. This StatefulSet contains at
160164
least three |k8s-pods|.
@@ -188,6 +192,8 @@ changes to the ``MongoDBOpsManager`` |k8s-crd|.
188192
``<om_resource_name>-admin-key`` Secret. The |k8s-op-short|
189193
uses these credentials for all other |onprem| API invocations.
190194

195+
.. include:: /includes/facts/fact-can-change-secret-storage-tool.rst
196+
191197
.. note::
192198

193199
This reconciliation step happens only once: when you use the

‎source/tutorial/plan-k8s-operator-install.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,5 +56,6 @@ resources.
5656
Compatibility </tutorial/plan-k8s-op-compatibility>
5757
Container Images </tutorial/plan-k8s-op-container-images>
5858
Set Deployment Scope </tutorial/set-scope-k8s-operator>
59+
/tutorial/secret-storage
5960
/tutorial/plan-k8s-op-considerations
6061
/tutorial/plan-k8s-op-prerequisites

0 commit comments

Comments
 (0)