Skip to content

Commit 3d39f5d

Browse files
jeff-allen-mongojwilliams-mongo
jeff-allen-mongo
authored and
jwilliams-mongo
committed
Tutorial for connecting to k8s deployment from outside of k8s (#81)
* WIP * (DOCSP-6830): Adding tutorial for connecting to k8s deployment from outside of k8s * specify -> set * slight refactoring for toc updates * Updates per Jon's feedback * adding missing lines at eof * Updates per Jon's feedback pt 2 * Updates per Cian's feedback * slight reformatting
1 parent f4ed339 commit 3d39f5d

8 files changed

+199
-2
lines changed

‎source/includes/fact-get-external-dns.rst

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
.. tip::
2+
3+
To obtain the external :abbr:`DNS (Domain Name System)` of your
4+
Kubernetes cluster, you can run the following command:
5+
6+
.. code-block:: sh
7+
8+
kubectl describe nodes
9+
10+
This command displays the external DNS in the
11+
``Addresses.ExternalDNS`` section of the output.
12+
13+
Alternatively, you can output the external DNS directly by running:
14+
15+
.. code-block:: sh
16+
17+
kubectl get nodes -o jsonpath='{ $.items[*].status.addresses[?(@.type=="ExternalDNS")].address }'

‎source/includes/steps-deploy-k8s-sharded-cluster.yaml

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ stepnum: 2
1919
level: 4
2020
ref: paste-k8s-example
2121
---
22-
title: "Configure the settings highlighted in the preceeding step as follows."
22+
title: "Configure the settings highlighted in the preceding step as follows."
2323
stepnum: 3
2424
level: 4
2525
ref: change-k8s-values
@@ -212,6 +212,7 @@ content: |
212212
|k8s-obj| specification file for a :term:`sharded cluster`
213213
deployment:
214214
215+
- :setting:`spec.exposedExternally`
215216
- :setting:`spec.logLevel`
216217
- :setting:`spec.featureCompatibilityVersion`
217218

‎source/includes/steps-deploy-k8s-standalone.yaml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -161,6 +161,7 @@ content: |
161161
You can also add any of the following optional settings to the
162162
|k8s-obj| specification file for a Standalone deployment:
163163
164+
- :setting:`spec.exposedExternally`
164165
- :setting:`spec.logLevel`
165166
- :setting:`spec.featureCompatibilityVersion`
166167
- :setting:`spec.podSpec.cpu`

‎source/includes/toc-connect.yaml

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,9 @@ file: /tutorial/connect-from-inside-k8s
22
description: |
33
Connect to a MongoDB resource deployed by |k8s| from inside of
44
the |k8s| cluster.
5+
---
6+
file: /tutorial/connect-from-outside-k8s
7+
description: |
8+
Connect to a MongoDB resource deployed by |k8s| from outside of
9+
the |k8s| cluster.
510
...

‎source/reference/k8s/example-exposed-sharded.yaml

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
---
2+
apiVersion: mongodb.com/v1
3+
kind: MongoDB
4+
metadata:
5+
name: shardedcluster
6+
namespace: <metadata.namespace> # Should match metadata.namespace in
7+
# your configmap file.
8+
spec:
9+
version: 4.0.6
10+
project: <myconfigmap> # Should match metadata.name in your
11+
# configmap file.
12+
shardCount: 2
13+
mongodsPerShardCount: 3
14+
mongosCount: 2
15+
configServerCount: 3
16+
credentials: my-secret
17+
type: ShardedCluster
18+
persistent: true
19+
exposedExternally: true
20+
...

‎source/reference/k8s/example-exposed-standalone.yaml

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
---
2+
apiVersion: mongodb.com/v1
3+
kind: MongoDB
4+
metadata:
5+
name: standalone
6+
namespace: <metadata.namespace> # Should match metadata.namespace in
7+
# your configmap file.
8+
spec:
9+
version: 4.0.6
10+
project: <myconfigmap> # Should match metadata.name in your
11+
# configmap file.
12+
credentials: <mycredentials>
13+
type: Standalone
14+
persistent: true
15+
exposedExternally: true
16+
...

‎source/tutorial/connect-from-inside-k8s.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
.. _connect-from-outside-k8s:
1+
.. _connect-from-inside-k8s:
22

33
====================================================
44
Connect to a MongoDB Resource from Inside Kubernetes

‎source/tutorial/connect-from-outside-k8s.txt

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
.. _connect-from-outside-k8s:
2+
3+
=====================================================
4+
Connect to a MongoDB Resource from Outside Kubernetes
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+
The following procedure describes how to connect to a MongoDB resource
16+
deployed by |k8s| from outside of the |k8s| cluster.
17+
18+
.. important::
19+
20+
You can only connect to a :doc:`standalone
21+
</tutorial/deploy-standalone>` or a :doc:`sharded cluster
22+
</tutorial/deploy-sharded-cluster>` resource from outside of the
23+
|k8s| cluster.
24+
25+
Procedure
26+
---------
27+
28+
To connect to a MongoDB resource deployed by |k8s| from outside of
29+
the |k8s| cluster, you must set the resource's
30+
:setting:`spec.exposedExternally` flag to ``true``.
31+
32+
When this flag is set to ``true``, the |k8s-op-short| creates a
33+
`NodePort service
34+
<https://kubernetes.io/docs/concepts/services-networking/service/>`__.
35+
The NodePort service exposes the deployment as a network service,
36+
thereby enabling access from outside of the |k8s| cluster.
37+
38+
Example Deployment Configurations
39+
---------------------------------
40+
41+
.. tabs-deployments::
42+
43+
.. tab::
44+
:tabid: standalone
45+
46+
The following example standalone configuration object exposes
47+
the deployment outside of the |k8s| cluster by setting
48+
``spec.exposedExternally`` to ``true``:
49+
50+
.. literalinclude:: /reference/k8s/example-exposed-standalone.yaml
51+
:language: yaml
52+
:emphasize-lines: 15
53+
54+
Once your standalone instance is deployed in |com|, run the
55+
following command to get information on the NodePort service
56+
created by the Operator:
57+
58+
.. code-block:: sh
59+
60+
kubectl get services -n <namespace>
61+
62+
The list output by this command should contain an entry
63+
similar to the following:
64+
65+
.. code-block:: sh
66+
:copyable: false
67+
68+
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
69+
70+
standalone-svc-external NodePort 10.102.27.116 <none> 27017:30994/TCP 8m30s
71+
72+
In this case, the :binary:`~bin.mongod` is exposed on port
73+
``27017`` in the |k8s| container, and the NodePort service
74+
exposes the ``mongod`` via port ``30994``.
75+
76+
When you connect to your deployment, you must specify the external
77+
:abbr:`DNS (Domain Name System)` of a node in the |k8s| cluster as
78+
the ``--host`` option in your ``mongo`` command. If a node in the
79+
|k8s| cluster has an external DNS of
80+
``ec2-54-212-23-143.us-west-2.compute.amazonaws.com``, you
81+
can connect to this standalone instance from outside of |k8s|
82+
using the following command:
83+
84+
.. code-block:: sh
85+
86+
mongo --host ec2-54-212-23-143.us-west-2.compute.amazonaws.com --port 30994
87+
88+
.. include:: /includes/fact-get-external-dns.rst
89+
90+
.. tab::
91+
:tabid: shard
92+
93+
The following example sharded cluster configuration object exposes
94+
the deployment outside of the |k8s| cluster by setting
95+
``spec.exposedExternally`` to ``true``:
96+
97+
.. literalinclude:: /reference/k8s/example-exposed-sharded.yaml
98+
:language: yaml
99+
:emphasize-lines: 19
100+
101+
Once your sharded cluster is deployed in |com|, run the
102+
following command to get information on the NodePort service
103+
created by the Operator:
104+
105+
.. code-block:: sh
106+
107+
kubectl get services -n <namespace>
108+
109+
The list output by this command should contain an entry
110+
similar to the following:
111+
112+
.. code-block:: sh
113+
:copyable: false
114+
115+
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
116+
117+
shardedcluster-svc-external NodePort 10.106.44.30 <none> 27017:30078/TCP 10s
118+
119+
In this case, the :binary:`~bin.mongos` is exposed on port
120+
``27017`` in the |k8s| container, and the NodePort service
121+
exposes the ``mongos`` via port ``30078``.
122+
123+
When you connect to your deployment, you must specify the external
124+
:abbr:`DNS (Domain Name System)` of a node in the |k8s| cluster as
125+
the ``--host`` option in your ``mongo`` command. If a node in the
126+
|k8s| cluster has an external DNS of
127+
``ec2-54-212-23-143.us-west-2.compute.amazonaws.com``, you
128+
can connect to this standalone instance from outside of |k8s|
129+
using the following command:
130+
131+
.. code-block:: sh
132+
133+
mongo --host ec2-54-212-23-143.us-west-2.compute.amazonaws.com --port 30078
134+
135+
.. include:: /includes/fact-get-external-dns.rst
136+
137+

0 commit comments

Comments
 (0)