Skip to content

Commit f0ba500

Browse files
jdestefano-mongojwilliams-mongo
jdestefano-mongo
authored and
jwilliams-mongo
committed
(DOCSP-5465): Make Object Spec settings linkable. Move the ConfigMap … (#40)
* (DOCSP-5465): Make Object Spec settings linkable. Move the ConfigMap and Credentials to a separate configuration page. * Update source/configuration.txt Co-Authored-By: jdestefano-mongo <[email protected]> * Update source/configuration.txt Co-Authored-By: jdestefano-mongo <[email protected]> * (DOCSP-5465): Copy review edits. * Remove .vscode file. * (DOCSP-5465): Copy review edits. * (DOCSP-5465): Tech review edits. * (DOCSP-5465): Add redirects for the new v0.11 pages * (DOCSP-5465): Fix table widths.
1 parent 5b87e61 commit f0ba500

16 files changed

+388
-313
lines changed

‎conf.py

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,8 @@
5757
pygments_style = 'sphinx'
5858

5959
source_constants = {
60-
'version': version
60+
'version': version,
61+
'k8s-op-short': 'Kubernetes Operator'
6162
}
6263

6364
rst_epilog = '\n'.join([

‎config/redirects

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,3 +18,9 @@ raw: kubernetes-operator/reference/k8s-operator-specification -> ${base}/stable/
1818
raw: kubernetes-operator/reference/known-issues-k8s-beta -> ${base}/stable/reference/known-issues-k8s-beta
1919
raw: kubernetes-operator/reference/troubleshooting -> ${base}/stable/reference/troubleshooting
2020
raw: kubernetes-operator/release-notes -> ${base}/stable/release-notes
21+
22+
# v0.10 and earlier
23+
[*-v0.10]: /${version}/configuration -> ${base}/${version}/tutorial/install-k8s-operator
24+
[*-v0.10]: /${version}/tutorial/upgrade-k8s-operator -> ${base}/${version}/tutorial/install-k8s-operator
25+
[*-v0.10]: /${version}/tutorial/upgrade-k8s-operator-v9-and-earlier -> ${base}/${version}/tutorial/install-k8s-operator
26+
[*-v0.10]: /${version}/installation -> ${base}/${version}/tutorial/install-k8s-operator

‎source/configuration.txt

Lines changed: 265 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,265 @@
1+
.. _configuration:
2+
3+
============================
4+
Configure the |k8s-op-short|
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+
After
16+
:doc:`installing the {+k8s-op-short+} </tutorial/install-k8s-operator>`,
17+
you will need to perform both of the following configurations before
18+
deploying MongoDB database resources:
19+
20+
- :ref:`create-k8s-project`
21+
22+
- :ref:`create-k8s-credentials`
23+
24+
.. _create-k8s-project:
25+
26+
Create your |onprem| Project using a |k8s| |k8s-configmap|
27+
----------------------------------------------------------
28+
29+
The |k8s-op-full| uses a |k8s| |k8s-configmap| to link to your
30+
|onprem| :opsmgr:`Project </tutorial/manage-projects>`. To create a
31+
|k8s-op-short| ConfigMap, you need to edit 4 lines of the
32+
:ref:`example ConfigMap <example-k8s-configmap>` |yaml| file and apply
33+
the ConfigMap:
34+
35+
1. Copy the following :ref:`example ConfigMap <example-k8s-configmap>`.
36+
37+
.. _example-k8s-configmap:
38+
39+
.. literalinclude:: /reference/k8s/example-configmap.yaml
40+
:language: yaml
41+
:emphasize-lines: 5-6, 8-10
42+
43+
#. Open your preferred text editor and paste the example
44+
|k8s-configmap| into a new text file.
45+
46+
#. Change the following four lines:
47+
48+
.. list-table::
49+
:widths: 20 20 40 20
50+
:header-rows: 1
51+
52+
* - Key
53+
- Type
54+
- Description
55+
- Example
56+
57+
* - ``metadata.name``
58+
- string
59+
- Label for a |k8s| |k8s-obj|.
60+
61+
.. seealso::
62+
63+
- :setting:`metadata.name`
64+
- |k8s| documentation on `names <https://kubernetes.io/docs/concepts/overview/working-with-objects/names/>`__.
65+
This name must follow :rfc:`RFC1123 <1123>` naming
66+
conventions, using only lowercase alphanumeric
67+
characters, '-' or '.', and must start and end with an
68+
alphanumeric character.
69+
70+
- ``myconfigmap``
71+
72+
* - ``metadata.namespace``
73+
- string
74+
- Scope of object names. Used to limit what can be managed to
75+
a subset of all |k8s-objs|. The default value is ``mongodb``.
76+
77+
.. important::
78+
The |k8s-op-short|, |k8s-secret|, and |k8s-mdbrsc|\s
79+
*must* be created in the same |k8s-ns|.
80+
81+
.. seealso::
82+
83+
- :setting:`metadata.namespace`
84+
- |k8s| documentation on |k8s-nss|
85+
86+
- ``mongodb``
87+
88+
* - ``data.projectName``
89+
- string
90+
- Label for your |mms|
91+
:opsmgr:`Project </tutorial/manage-projects>`.
92+
93+
.. admonition:: Let |k8s-op-short| create the Project
94+
:class: important
95+
96+
The |k8s-op-short| creates the |mms| Project if it does
97+
not exist. It is **strongly recommended** to use the
98+
Operator to create a new Project for |k8s| to manage. The
99+
Operator adds additional internal information to Projects
100+
that it creates.
101+
102+
If you need or want to use an existing Project, you can find
103+
the ``projectName`` by clicking the :guilabel:`All Clusters`
104+
link at the top left of the screen, then either search by
105+
name in the :guilabel:`Search` box or scroll to find the
106+
name in the list. Each card in this list represents the
107+
combination of one **Organization** and **Project**.
108+
109+
- ``Development``
110+
111+
* - ``data.orgId``
112+
- string
113+
- 24 character hex string that uniquely identifies your
114+
MongoDB :opsmgr:`Organization </tutorial/manage-organizations>`.
115+
You can find the ``orgId`` in your |onprem| |url|:
116+
117+
1. Click the :guilabel:`Context` menu.
118+
2. Select your Organization.
119+
3. View the current |url| in your
120+
browser and copy the value
121+
displayed in the ``<orgId>``
122+
placeholder below:
123+
124+
| ``https://ops.example.com:8443/``
125+
| ``v2#/org/<orgId>/projects``
126+
127+
.. important::
128+
129+
This field is *optional*. If you omit the ``orgId``,
130+
|onprem| creates an Organization called ``projectName``
131+
that contains a Project also called ``projectName``.
132+
133+
You must have the :authrole:`Organization Project Creator`
134+
role to create a new project
135+
*within an existing organization*.
136+
137+
.. admonition:: Limited to Cloud or Ops Manager Organizations
138+
139+
If you set this value, it can be for a Cloud Manager or
140+
an Ops Manager organization only. If you try to use an
141+
Atlas organization, the |k8s-op-short| may not work as
142+
intended.
143+
144+
- | ``5cc9b333dd3e384a625a6615``
145+
146+
* - ``data.baseUrl``
147+
- string
148+
- |url| to your |application| including the |fqdn| and port
149+
number.
150+
151+
.. note::
152+
153+
You may use |cloud-short| for the ``data.baseUrl`` value.
154+
155+
- ``https://ops.example.com:8443``
156+
157+
#. Save this file with a ``.yaml`` file extension.
158+
159+
#. Invoke the following |k8s| command to create your |k8s-configmap|:
160+
161+
.. code-block:: sh
162+
163+
kubectl apply -f <myconfigmap.yaml>
164+
165+
.. important::
166+
167+
All subsequent ``kubectl`` commands you invoke must add the
168+
``-n`` option with the :setting:`metadata.namespace` you
169+
specified in your |k8s-configmap|.
170+
171+
#. Invoke the following |k8s| command to verify your |k8s-configmap|:
172+
173+
.. code-block:: sh
174+
175+
kubectl describe configmaps <myconfigmap> -n <metadata.namespace>
176+
177+
.. admonition:: *Always include the namespace option with* ``kubectl``
178+
:class: important
179+
180+
|kubectl| defaults to an empty namespace if you do not specify
181+
the ``-n`` option, resulting in deployment failures. You must
182+
specify the value of the ``<metadata.namespace>`` field.
183+
The |k8s-op-short|, |k8s-secret|, and |k8s-mdbrsc|\s should
184+
run in the same unique namespace.
185+
186+
This command returns a ConfigMap description in the shell:
187+
188+
.. code-block:: sh
189+
190+
Name: <myconfigmap>
191+
Namespace: <metadata.namespace>
192+
Labels: <none>
193+
Annotations: <none>
194+
195+
.. _create-k8s-credentials:
196+
.. _create-k8s-secret:
197+
198+
Create a |k8s| Secret to Allow the Operator to Manage the Project
199+
-----------------------------------------------------------------
200+
201+
For the |k8s-op-short| to create or update |k8s-objs| in your |onprem|
202+
Project, you need to store your username and
203+
:ref:`Public API Key <generate-public-api-key>` as a |k8s|
204+
|k8s-secret|. Creating a secret stores authentication credentials so
205+
only |k8s| can access them.
206+
207+
Multiple secrets can exist in the same namespace. Each user should
208+
have their own secret.
209+
210+
To create your |k8s| secret:
211+
212+
1. Make sure you have your |onprem| username and Public API Key.
213+
214+
If you do not have your Public API Key, you need to generate a new
215+
:ref:`Public API Key <generate-public-api-key>`.
216+
217+
2. Invoke the following |k8s| command to create your secret:
218+
219+
.. code-block:: sh
220+
221+
kubectl -n <metadata.namespace> \
222+
create secret generic <myCredentials> \
223+
--from-literal="user=<[email protected]>" \
224+
--from-literal="publicApiKey=<my-public-api-key>"
225+
226+
.. note::
227+
228+
The ``-n`` flag limits the |k8s-ns| to which this secret
229+
applies. All MongoDB |k8s| resources must be in the same
230+
namespace with the |k8s-secrets| and |k8s-configmaps|. The
231+
|k8s-op-short| does not use either the secrets or ConfigMaps.
232+
233+
3. Invoke the following |k8s| command to verify your secret:
234+
235+
.. code-block:: sh
236+
237+
kubectl describe secrets/<myCredentials> -n <metadata.namespace>
238+
239+
This command returns a secret description in the shell:
240+
241+
.. code-block:: sh
242+
243+
Name: <myCredentials>
244+
Namespace: <metadata.namespace>
245+
Labels: <none>
246+
Annotations: <none>
247+
248+
Type: Opaque
249+
250+
Data
251+
====
252+
publicApiKey: 31 bytes
253+
user: 22 bytes
254+
255+
Next Steps
256+
----------
257+
258+
Now that you installed the |k8s-op-full|, created your |com| project and
259+
|k8s| |k8s-configmap|, and created your credentials, you are ready to
260+
deploy MongoDB resources. For more information on deploying MongoDB
261+
resources, see:
262+
263+
- :doc:`/tutorial/deploy-standalone`
264+
- :doc:`/tutorial/deploy-replica-set`
265+
- :doc:`/tutorial/deploy-sharded-cluster`

‎source/includes/prereqs-deploy-resource.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
To deploy a |deployment| using a |k8s-obj|, you need to complete the
2+
following procedures:
3+
4+
- :doc:`Install Kubernetes Operator </tutorial/install-k8s-operator>`
5+
6+
- :doc:`/configuration`

‎source/index.txt

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -40,10 +40,9 @@ the rest of the application services. DBAs can work within the familiar
4040
.. toctree::
4141
:titlesonly:
4242

43-
/installation
44-
/deploy
45-
/tutorial
46-
/troubleshooting
43+
Installation </installation>
44+
Configuration </configuration>
45+
Resource Deployment </deploy>
4746
/reference
4847
/specification
4948
Release Notes </release-notes>

‎source/installation.txt

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
:noprevnext:
22

3-
============
4-
Installation
5-
============
3+
==========================
4+
Install the |k8s-op-short|
5+
==========================
66

77
.. default-domain:: mongodb
88

0 commit comments

Comments
 (0)