Skip to content

Commit d608e4f

Browse files
jvincent-mongodbjwilliams-mongo
jvincent-mongodb
authored and
jwilliams-mongo
committed
DOCSP-46323 -- Add reference architectures section (#2048)
* DOCSP-46323 -- Add reference architectures section * DOCSP-46323 -- copy review * DOCSP-46323 -- external review * DOCSP-46323 -- external review * DOCSP-46323 -- external review * DOCSP-46323 -- move gke steps to top level * DOCSP-46323 -- change step order * DOCSP-46323 -- add env_variables.sh * DOCSP-46323 -- add env_variables.sh * DOCSP-46323 -- fix output rendering * DOCSP-46323 -- add create gcp project step * DOCSP-46323 -- add required tools section * DOCSP-46323 -- add operator installation to central cluster * DOCSP-46323 -- add operator installation to central cluster * DOCSP-46323 -- add operator installation to central cluster * DOCSP-46323 -- add operator installation to central cluster * DOCSP-46323 -- add service mesh connectivity check procedure * DOCSP-46323 -- fix link * DOCSP-46323 -- add operator details * DOCSP-46323 -- fix spacing * DOCSP-46323 -- external review * DOCSP-46323 -- external review * DOCSP-46323 -- update includes * DOCSP-46323 -- update code samples for MCOM * DOCSP-46323 -- external review * DOCSP-46323 -- fix language in examples * DOCSP-46323 -- WIP * DOCSP-46323 -- fix typo * DOCSP-46323 -- add step descriptions * DOCSP-46323 -- OM credentials update * DOCSP-46323 -- add load balancer reference * DOCSP-46323 -- add MCSC intro * DOCSP-46323 -- add env vars for om deploymjent * DOCSP-46323 -- external review * DOCSP-46323 -- external review * DOCSP-46323 -- external review * DOCSP-46323 -- external review * DOCSP-46323 -- external review * DOCSP-46323 -- external review * DOCSP-46323 -- external review * DOCSP-46323 -- external review * DOCSP-46323 -- external review * DOCSP-46323 -- external review * DOCSP-46323 -- WIP * DOCSP-46323 -- external review * DOCSP-46323 -- external review * DOCSP-46323 -- external review
1 parent 82076eb commit d608e4f

12 files changed

+1121
-0
lines changed

‎snooty.toml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ toc_landing_pages = [
1818
"/om-resources",
1919
"/reference",
2020
"/reference/operator-settings",
21+
"/reference-architectures/multi-cluster",
2122
"/security",
2223
"/tutorial/om-arch",
2324
"/tutorial/om-arch-multi-cluster",
@@ -70,6 +71,8 @@ bic-full = ":bic:`MongoDB Connector for BI </>`"
7071
bic-short = ":bic:`BI Connector </>`"
7172
bic = "BI Connector for Atlas"
7273
bson = ":abbr:`BSON (Binary Javascript Object Notation)`"
74+
ca-cert = "CA Certificate"
75+
ca-certs = "CA Certificates"
7376
certauth = ":abbr:`CA (Certificate Authority)`"
7477
cidr = ":abbr:`CIDR (Classless Inter-Domain Routing)`"
7578
cifs = ":abbr:`CIFS (Common Internet File System)`"

‎source/index.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,7 @@ optimal performance.
6363
Deploy on Multiple Kubernetes Clusters </multi-cluster>
6464
Modify Containers </tutorial/modify-resource-image>
6565
Host on GDC </gdc-hosted>
66+
Reference Architectures </reference-architectures>
6667
Reference </reference>
6768
FAQ </faq.txt>
6869
Release Notes </release-notes>

‎source/reference-architectures.txt‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
.. _reference-architectures:
2+
3+
=======================
4+
Reference Architectures
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+
16+
17+
18+
19+
.. toctree::
20+
:titlesonly:
21+
:hidden:
22+
23+
How to Use a Reference Architecture </reference-architectures/how-to-use>
24+
Multi-Cluster Architecture </reference-architectures/multi-cluster>

‎source/reference-architectures/ca-certs.txt‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
.. _reference-architectures-ca-certs:
2+
3+
================
4+
TLS Certificates
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+
This section provides guidance on the creation of TLS certificates for each
16+
component of MongoDB, and the creation of |k8s| Secrets in each of your |k8s|
17+
clusters to mount the TLS certificates securely into the appropriate |k8s| Pods.
18+
19+
The process outlined below utilizes `Cert Manager <https://cert-manager.io/>`__
20+
for creating the TLS certificates. However, please note that this is an
21+
opinionated guide, and CertManager is not supported by MongoDB. Moreover, CertManager
22+
is only one of many ways in which you can add TLS certificates to your |k8s| clusters.
23+
Additionally, self-signed certificates may not be suitable for production deployments,
24+
depending on the security requirements of your organization. If you require
25+
publicly trusted certificates please configure your `Issuer <https://cert-manager.io/docs/configuration/issuers/>`__ accordingly
26+
or provide the TLS certificate directly. To learn more, see :ref:`<cert-manager-integration>`.
27+
28+
Prerequisites
29+
-------------
30+
31+
Before you begin, perform the following tasks:
32+
33+
- Install ``kubectl``.
34+
- Install `Helm <https://helm.sh/docs/intro/install/>`__.
35+
- Set the ``K8S_CLUSTER_*_CONTEXT_NAME`` environment variables as
36+
explained in the :ref:`GKE Clusters guide <reference-architectures-gke-clusters>`.
37+
38+
Source Code
39+
-----------
40+
41+
You can find all included source code in the `MongoDB Kubernetes Operator repository <https://github.com/mongodb/mongodb-enterprise-kubernetes/tree/${current_branch}/architectures/setup-multi-cluster/setup-gke/setup-cert-manager>`__.
42+
43+
Procedure
44+
----------
45+
46+
.. procedure::
47+
:style: normal
48+
49+
.. step:: Add the Helm charts repo.
50+
51+
.. literalinclude:: /includes/code-examples/reference-architectures/setup-multi-cluster/setup-cert-manager/code_snippets/0215_helm_configure_repo.sh
52+
:language: bash
53+
:linenos:
54+
55+
.. output:: /includes/code-examples/reference-architectures/setup-multi-cluster/setup-cert-manager/output/0215_helm_configure_repo.out
56+
57+
.. step:: Use Helm to install cert-manager.
58+
59+
.. literalinclude:: /includes/code-examples/reference-architectures/setup-multi-cluster/setup-cert-manager/code_snippets/0216_helm_install_cert_manager.sh
60+
:language: bash
61+
:linenos:
62+
63+
.. output:: /includes/code-examples/reference-architectures/setup-multi-cluster/setup-cert-manager/output/0216_helm_install_cert_manager.out
64+
65+
.. step:: Create a certificate issuer.
66+
67+
.. literalinclude:: /includes/code-examples/reference-architectures/setup-multi-cluster/setup-cert-manager/code_snippets/0220_create_issuer.sh
68+
:language: bash
69+
:linenos:
70+
71+
.. step:: Verify creation of the issuer.
72+
73+
.. literalinclude:: /includes/code-examples/reference-architectures/setup-multi-cluster/setup-cert-manager/code_snippets/0221_verify_issuer.sh
74+
:language: bash
75+
:linenos:
76+
77+
.. output:: /includes/code-examples/reference-architectures/setup-multi-cluster/setup-cert-manager/output/0221_verify_issuer.out
78+
79+
.. step:: Create CA configMap.
80+
81+
.. literalinclude:: /includes/code-examples/reference-architectures/setup-multi-cluster/setup-cert-manager/code_snippets/0225_create_ca_configmap.sh
82+
:language: bash
83+
:linenos:

‎source/reference-architectures/deploy-operator.txt‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
.. _reference-architectures-deploy-operator:
2+
3+
=======================================
4+
Deploy the MongoDB Enterprise Operator
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+
16+
In order to deploy multiple instances of MongoDB resources across multiple
17+
|k8s| clusters, you first need to deploy the |k8s-op-short| to one of your
18+
|k8s| clusters. Once the |k8s-op-short| is deployed to a central |k8s| cluster,
19+
you can then create and manage all of your MongoDB resources across all of your
20+
|k8s| clusters by applying updates to your central |k8s| cluster.
21+
22+
Prerequisites
23+
-------------
24+
25+
Before you begin the following procedure, perform the following actions:
26+
27+
- Install ``kubectl``.
28+
- Install `Helm <https://helm.sh/docs/intro/install/>`__.
29+
- Complete the :ref:`GKE Clusters procedure <reference-architectures-gke-clusters>` or the equivalent.
30+
- Complete the :ref:`TLS Certificates procedure <reference-architectures-ca-certs>` or the equivalent.
31+
- Complete the :ref:`Istio Service mesh procedure <reference-architectures-istio-service-mesh>` or the equivalent.
32+
- Install the |kubectl-mongodb|.
33+
To install the |kubectl-mongodb|:
34+
35+
.. include:: /includes/steps/install-kubectl-mongodb-plugin.rst
36+
- Update as needed and set the environment variables defined in the following ``env_variables.sh`` file.
37+
38+
.. literalinclude:: /includes/code-examples/reference-architectures/setup-multi-cluster/setup-operator/env_variables.sh
39+
:language: bash
40+
:linenos:
41+
42+
Source Code
43+
-----------
44+
45+
You can find all included source code in the `MongoDB Kubernetes Operator repository <https://github.com/mongodb/mongodb-enterprise-kubernetes/tree/${current_branch}/architectures/setup-multi-cluster/setup-gke/setup-operator>`__.
46+
47+
Procedure
48+
---------
49+
50+
.. procedure::
51+
:style: normal
52+
53+
.. step:: Create namespaces for the |k8s-op-short|, MongoDB and Ops Manager in each of your |k8s| clusters.
54+
55+
.. literalinclude:: /includes/code-examples/reference-architectures/setup-multi-cluster/setup-operator/code_snippets/0045_create_namespaces.sh
56+
:language: bash
57+
58+
.. step:: Create image pull secrets.
59+
60+
.. literalinclude:: /includes/code-examples/reference-architectures/setup-multi-cluster/setup-operator/code_snippets/0046_create_image_pull_secrets.sh
61+
:language: bash
62+
63+
.. step:: Configure your |k8s| clusters.
64+
65+
Run the following command to configure your |k8s| clusters.
66+
67+
.. io-code-block::
68+
:copyable: true
69+
70+
.. input:: /includes/code-examples/reference-architectures/setup-multi-cluster/setup-operator/code_snippets/0200_kubectl_mongodb_configure_multi_cluster.sh
71+
:language: bash
72+
:linenos:
73+
74+
.. output:: /includes/code-examples/reference-architectures/setup-multi-cluster/setup-operator/output/0200_kubectl_mongodb_configure_multi_cluster.out
75+
:visible: false
76+
77+
.. step:: Add the MongoDB Helm Charts for Kubernetes.
78+
79+
Add the `MongoDB Helm Charts for Kubernetes <https://mongodb.github.io/helm-charts>`__ repository to Helm.
80+
81+
.. io-code-block::
82+
:copyable: true
83+
84+
.. input:: /includes/code-examples/reference-architectures/setup-multi-cluster/setup-operator/code_snippets/0205_helm_configure_repo.sh
85+
:language: bash
86+
:linenos:
87+
88+
.. output:: /includes/code-examples/reference-architectures/setup-multi-cluster/setup-operator/output/0205_helm_configure_repo.out
89+
:visible: false
90+
91+
.. step:: Deploy the |k8s-op-short|.
92+
93+
Use the `MongoDB Helm Charts for Kubernetes <https://mongodb.github.io/helm-charts>`__ to deploy the |k8s-op-short|.
94+
95+
.. io-code-block::
96+
:copyable: true
97+
98+
.. input:: /includes/code-examples/reference-architectures/setup-multi-cluster/setup-operator/code_snippets/0210_helm_install_operator.sh
99+
:language: bash
100+
:linenos:
101+
102+
.. output:: /includes/code-examples/reference-architectures/setup-multi-cluster/setup-operator/output/0210_helm_install_operator.out
103+
:visible: false
104+
105+
.. step:: Check the status of your MongoDB Kubernetes Operator.
106+
107+
.. io-code-block::
108+
:copyable: true
109+
110+
.. input:: /includes/code-examples/reference-architectures/setup-multi-cluster/setup-operator/code_snippets/0211_check_operator_deployment.sh
111+
:language: bash
112+
:linenos:
113+
114+
.. output:: /includes/code-examples/reference-architectures/setup-multi-cluster/setup-operator/output/0211_check_operator_deployment.out
115+
:visible: false

‎source/reference-architectures/gke-clusters.txt‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
.. _reference-architectures-gke-clusters:
2+
3+
============
4+
GKE Clusters
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+
Kubernetes is not vendor specific; however, for the sake of providing explicit
16+
and complete instructions for deploying all elements of a multi-cluster
17+
|k8s-op-short| implementation, this section walks you through the process
18+
of deploying multiple Kubernetes clusters on |gcp| specifically.
19+
20+
Prerequisites
21+
-------------
22+
23+
Before you begin, perform the following actions:
24+
25+
- Create a |gcp| account.
26+
- Prepare a |gcp| project so that you can use it to create |gke| clusters.
27+
- Install the |gcp| `CLI <https://cloud.google.com/sdk/docs/install>`__.
28+
- `Authenticate <https://cloud.google.com/docs/authentication/gcloud>`__ with the ``gcloud auth login`` command.
29+
- Update as needed and set the environment variables defined in the following ``env_variables.sh`` file.
30+
31+
.. literalinclude:: /includes/code-examples/reference-architectures/setup-multi-cluster/setup-gke/env_variables.sh
32+
:language: bash
33+
:linenos:
34+
35+
Source Code
36+
-----------
37+
38+
You can find all included source code in the `MongoDB Kubernetes Operator repository <https://github.com/mongodb/mongodb-enterprise-kubernetes/tree/${current_branch}/architectures/setup-multi-cluster/setup-gke>`__.
39+
40+
Procedure
41+
----------
42+
43+
.. procedure::
44+
:style: normal
45+
46+
.. step:: Set your default gcloud project:
47+
48+
.. literalinclude:: /includes/code-examples/reference-architectures/setup-multi-cluster/setup-gke/code_snippets/0005_gcloud_set_current_project.sh
49+
:language: bash
50+
:linenos:
51+
52+
.. step:: Create |k8s| clusters.
53+
54+
Create three |gke| clusters:
55+
56+
.. literalinclude:: /includes/code-examples/reference-architectures/setup-multi-cluster/setup-gke/code_snippets/0010_create_gke_cluster_0.sh
57+
:language: bash
58+
:linenos:
59+
60+
.. literalinclude:: /includes/code-examples/reference-architectures/setup-multi-cluster/setup-gke/code_snippets/0010_create_gke_cluster_1.sh
61+
:language: bash
62+
:linenos:
63+
64+
.. literalinclude:: /includes/code-examples/reference-architectures/setup-multi-cluster/setup-gke/code_snippets/0010_create_gke_cluster_2.sh
65+
:language: bash
66+
:linenos:
67+
68+
.. step:: Store credentials in your kubeconfig.
69+
70+
Obtain credentials and save contexts to the current ``kubeconfig``
71+
file. By default, this file is located in the ``~/.kube/config`` directory
72+
and referenced by the ``$KUBECONFIG`` :ref:`environment variable <set-env-vars-om-mc>`.
73+
74+
.. literalinclude:: /includes/code-examples/reference-architectures/setup-multi-cluster/setup-gke/code_snippets/0020_get_gke_credentials.sh
75+
:language: bash
76+
:linenos:
77+
78+
All ``kubectl`` commands reference these contexts using the following variables:
79+
80+
- ``$K8S_CLUSTER_0_CONTEXT_NAME``
81+
- ``$K8S_CLUSTER_1_CONTEXT_NAME``
82+
- ``$K8S_CLUSTER_2_CONTEXT_NAME``
83+
84+
.. step:: Verify that ``kubectl`` has access to |k8s| clusters.
85+
86+
.. io-code-block::
87+
:copyable: true
88+
89+
.. input:: /includes/code-examples/reference-architectures/setup-multi-cluster/setup-gke/code_snippets/0030_verify_access_to_clusters.sh
90+
:linenos:
91+
:language: bash
92+
93+
.. output:: /includes/code-examples/reference-architectures/setup-multi-cluster/setup-gke/output/0030_verify_access_to_clusters.out
94+
:linenos:

0 commit comments

Comments
 (0)