Skip to content

Commit f9d7208

Browse files
jwilliams-mongojwilliams-mongo
committed
(DOCSP-8692): Tutorial about different installation modes for the Operator (#195)
* (DOCSP-8692): Tutorial about different installation modes for the Operator * (DOCSP-8692): minor updates mentioned in jira ticket * (DOCSP-8692): may -> might * (DOCSP-8692): copy review feedback * (DOCSP-8692): tech review feedback * (DOCSP-8692): fix indentation
1 parent dda7577 commit f9d7208

File tree

7 files changed

+175
-90
lines changed

7 files changed

+175
-90
lines changed

‎config/redirects

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,3 +47,6 @@ raw: kubernetes-operator/release-notes -> ${base}/stable/release-notes
4747
[*-v1.2]: kubernetes-operator/${version}/tutorial/secure-tls -> ${base}/${version}/deploy
4848
[*-v1.2]: kubernetes-operator/${version}/tutorial/secure-x509-auth -> ${base}/${version}/deploy
4949
[*-v1.2]: kubernetes-operator/${version}/tutorial/secure-internal-auth -> ${base}/${version}/deploy
50+
51+
# v1.3 and earlier
52+
[*-v1.3]: kubernetes-operator/${version}/tutorial/plan-k8s-operator-install -> ${base}/${version}/tutorial/install-k8s-operator

‎source/includes/admonitions/fact-create-service-account-namespaces.rst

Lines changed: 4 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,6 @@
11
.. important::
22

3-
You must create a service account
4-
``mongodb-enterprise-database-pods`` in each namespace the
5-
|k8s-op-short| watches other than the default to create
6-
|k8s-mdbrsc| in these namespaces:
7-
8-
.. code-block:: sh
9-
10-
kubectl create serviceaccount mongodb-enterprise-database-pods -n <namespace>
3+
To watch |onprem| and |k8s-mdbrscs| in a different |k8s-ns| to which
4+
you deploy the |k8s-op-short|, see :ref:`k8s-deployment-scopes` for
5+
values you must use and additional steps you might have to perform.
6+

‎source/includes/list-tables/k8s-kubectl-install-options.rst

Lines changed: 1 addition & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -66,14 +66,7 @@
6666

6767
Default value is: ``<metadata.namespace>``.
6868

69-
.. include:: /includes/admonitions/fact-create-service-account-namespaces.rst
70-
71-
.. admonition:: One Namespace or All Namespaces
72-
:class: note
73-
74-
If you need to watch more than one namespace, set the value
75-
of ``WATCH_NAMESPACE`` to ``*`` (all). This environment
76-
variable can watch one namespace or all namespaces.
69+
.. include:: /includes/admonitions/fact-create-service-account-namespaces.rst
7770

7871
You can set the following pair of values:
7972

‎source/includes/list-tables/k8s-oc-install-options.rst

Lines changed: 0 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -66,13 +66,6 @@
6666

6767
Default value is: ``<metadata.namespace>``.
6868

69-
.. admonition:: One Namespace or All Namespaces
70-
:class: note
71-
72-
If you need to watch more than one namespace, set the value
73-
of ``WATCH_NAMESPACE`` to ``*`` (all). This environment
74-
variable can watch one namespace or all namespaces.
75-
7669
.. include:: /includes/admonitions/fact-create-service-account-namespaces.rst
7770

7871
You can set the following pair of values:

‎source/installation.txt

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,10 @@ Install and Configure the |k8s-op-short|
1212
:depth: 1
1313
:class: singlecol
1414

15+
:ref:`plan-k8s-operator-install`
16+
Review |k8s-op-short| deployment scopes, considerations, and
17+
prerequisites.
18+
1519
:ref:`install-k8s`
1620
Install the |k8s-op-full|.
1721

@@ -23,5 +27,6 @@ Install and Configure the |k8s-op-short|
2327
.. toctree::
2428
:titlesonly:
2529

30+
/tutorial/plan-k8s-operator-install
2631
/tutorial/install-k8s-operator
2732
/upgrade

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

Lines changed: 12 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -16,84 +16,29 @@ Install the |k8s-op-full|
1616

1717
.. include:: /includes/styles/corrections.rst
1818

19-
Use the |k8s-op-full| to deploy:
19+
Prerequisites and Considerations
20+
--------------------------------
2021

21-
- Ops Manager resources
22-
- MongoDB standalone, replica set, and sharded cluster resources
22+
Before you install the |k8s-op-short|, make sure you
23+
:ref:`plan for your installation <plan-k8s-operator-install>`:
2324

24-
.. include:: /includes/admonitions/note-k8s-supported-in-om4.rst
25-
26-
To deploy MongoDB resources with the |k8s-op-short|, you need an
27-
|onprem| instance. Deploy this instance to |k8s| using the Operator or
28-
outside |k8s| using
29-
:opsmgr:`traditional installation methods </installation>`. The
30-
Operator uses |onprem| |api| methods to deploy then manage MongoDB
31-
resources.
25+
- Choose a :ref:`deployment topology <k8s-deployment-scopes>`.
26+
- Read the :ref:`Considerations <k8s-considerations>`.
27+
- Complete the :ref:`Prerequisites <k8s-prerequisites>`.
3228

3329
.. note::
3430

3531
This tutorial presumes some knowledge of |k8s|, but does link to
3632
relevant |k8s| documentation where possible. If you are unfamiliar
3733
with |k8s|, please review that documentation first.
3834

39-
.. _k8s-prerequisites:
40-
41-
Prerequisites
42-
-------------
43-
44-
.. include:: /includes/install/install-prereqs.rst
45-
46-
Considerations
47-
--------------
48-
49-
|k8s| Compatibility
50-
~~~~~~~~~~~~~~~~~~~
51-
52-
|k8s-op-full| is compatible with |k8s| v1.13 or later.
53-
54-
55-
Docker Container Details
56-
~~~~~~~~~~~~~~~~~~~~~~~~
57-
58-
MongoDB builds the container images from the latest builds of the
59-
following operating systems:
60-
61-
.. list-table::
62-
:header-rows: 1
63-
:widths: 50 50
64-
65-
* - If you get your |k8s-op-short| from...
66-
- ...the Container uses
67-
68-
* - `quay.io <https://quay.io/repository/mongodb/mongodb-enterprise-operator?tag=latest&tab=tags>`__
69-
or :gh:`GitHub </mongodb/mongodb-enterprise-kubernetes>`
70-
- `Ubuntu 16.04 <https://www.ubuntu.com/containers>`__
71-
72-
* - `OpenShift <https://access.redhat.com/containers/?tab=tags#/registry.connect.redhat.com/mongodb/enterprise-operator>`__
73-
- `Red Hat Enterprise Linux 7 <https://www.redhat.com/en/topics/containers>`__
74-
75-
MongoDB, Inc. updates all packages on these images before releasing
76-
them every three weeks.
77-
78-
Only One Operator per Namespace
79-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
80-
81-
The |k8s-op-full| can only exist in one |k8s-ns|. Your deployment can
82-
have:
83-
84-
- One cluster-wide |k8s-op-short| or
85-
- Multiple Kubernetes Operators in their own namespaces
86-
87-
Do not try to deploy more than one Kubernetes Operator in the same
88-
namespace as another Operator. Multiple Operators cannot coordinate
89-
with one another within the same namespace.
90-
91-
.. _default namespace: https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/#viewing-namespaces
92-
9335
.. _install-k8s-operator:
9436

95-
Install the |k8s-op-full|
96-
-------------------------
37+
Procedure
38+
---------
39+
40+
The following steps vary depending on how you want to configure your
41+
environment:
9742

9843
.. tabs::
9944

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

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
.. _plan-k8s-operator-install:
2+
3+
====================================
4+
Plan your |k8s-op-full| Installation
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+
Use the |k8s-op-full| to deploy:
18+
19+
- Ops Manager resources
20+
- MongoDB standalone, replica set, and sharded cluster resources
21+
22+
.. include:: /includes/admonitions/note-k8s-supported-in-om4.rst
23+
24+
To deploy MongoDB resources with the |k8s-op-short|, you need an
25+
|onprem| instance. Deploy this instance to |k8s| using the Operator or
26+
outside |k8s| using
27+
:opsmgr:`traditional installation methods </installation>`. The
28+
Operator uses |onprem| |api| methods to deploy then manage MongoDB
29+
resources.
30+
31+
.. _k8s-considerations:
32+
33+
Considerations
34+
--------------
35+
36+
|k8s| Compatibility
37+
~~~~~~~~~~~~~~~~~~~
38+
39+
|k8s-op-full| is compatible with |k8s| v1.13 or later.
40+
41+
Docker Container Details
42+
~~~~~~~~~~~~~~~~~~~~~~~~
43+
44+
MongoDB builds the container images from the latest builds of the
45+
following operating systems:
46+
47+
.. list-table::
48+
:header-rows: 1
49+
:widths: 50 50
50+
51+
* - If you get your |k8s-op-short| from...
52+
- ...the Container uses
53+
54+
* - `quay.io <https://quay.io/repository/mongodb/mongodb-enterprise-operator?tag=latest&tab=tags>`__
55+
or :gh:`GitHub </mongodb/mongodb-enterprise-kubernetes>`
56+
- `Ubuntu 16.04 <https://www.ubuntu.com/containers>`__
57+
58+
* - `OpenShift <https://access.redhat.com/containers/?tab=tags#/registry.connect.redhat.com/mongodb/enterprise-operator>`__
59+
- `Red Hat Enterprise Linux 7 <https://www.redhat.com/en/topics/containers>`__
60+
61+
MongoDB, Inc. updates all packages on these images before releasing
62+
them every three weeks.
63+
64+
.. _k8s-deployment-scopes:
65+
66+
|k8s-op-short| Deployment Scopes
67+
--------------------------------
68+
69+
You can deploy the |k8s-op-short| with different scopes based on where
70+
you want to deploy |onprem| and |k8s-mdbrscs| resources:
71+
72+
- :ref:`ns-scope-same-ns` *(Default)*
73+
- :ref:`ns-scope-different-ns`
74+
- :ref:`cluster-wide-scope`
75+
76+
.. _ns-scope-same-ns:
77+
78+
Operator in Same Namespace as Resources
79+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
80+
You scope the |k8s-op-short| to a namespace. The |k8s-op-short| watches
81+
|onprem| and |k8s-mdbrscs| in that same |k8s-ns|.
82+
83+
This is the default scope when you install the |k8s-op-short| using the
84+
:ref:`installation instructions <install-k8s-operator>`.
85+
86+
.. _ns-scope-different-ns:
87+
88+
Operator in Different Namespace Than Resources
89+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
90+
91+
You scope the |k8s-op-short| to a namespace. The |k8s-op-short| watches
92+
|onprem| and |k8s-mdbrscs| in the |k8s-ns| you specify.
93+
94+
You must use ``helm`` to install the |k8s-op-short| with this scope.
95+
Follow the relevant ``helm`` :ref:`installation instructions <install-k8s-operator>`,
96+
but use the following command to set the namespace for the
97+
|k8s-op-short| to watch:
98+
99+
.. code-block:: sh
100+
101+
helm template --set operator.watchNamespace=<namespace> \
102+
helm_chart | kubectl apply -f -
103+
104+
Setting the namespace ensures that:
105+
106+
- The namespace you want the |k8s-op-short| to watch has the correct
107+
roles and role bindings.
108+
- The |k8s-op-short| can watch and create resources in the namespace.
109+
110+
.. _cluster-wide-scope:
111+
112+
Cluster-Wide Scope
113+
~~~~~~~~~~~~~~~~~~
114+
115+
You scope the |k8s-op-short| to a cluster. The |k8s-op-short| watches
116+
|onprem| and |k8s-mdbrscs| in all |k8s-nss| in the |k8s| cluster.
117+
118+
.. important::
119+
120+
You can deploy only one Operator with a cluster-wide scope per |k8s|
121+
cluster.
122+
123+
You must use ``helm`` to install the |k8s-op-short| with this scope.
124+
Follow the relevant ``helm`` :ref:`installation instructions <install-k8s-operator>`,
125+
but make the following adjustments:
126+
127+
1. Use the following command to set the |k8s-op-short| to watch all
128+
namespaces:
129+
130+
.. code-block:: sh
131+
132+
helm template --set operator.watchNamespace=* \
133+
helm_chart | kubectl apply -f -
134+
135+
2. Create the required service accounts for each namespace where you
136+
want to deploy |onprem| and |k8s-mdbrscs|:
137+
138+
.. code-block:: sh
139+
140+
helm template --set namespace=<namespace> \
141+
helm_chart -x templates/database-roles.yaml | kubectl apply -f -
142+
143+
.. _k8s-prerequisites:
144+
145+
Prerequisites
146+
-------------
147+
148+
.. include:: /includes/install/install-prereqs.rst
149+
150+

0 commit comments

Comments
 (0)