Skip to content

Commit a2e687b

Browse files
davidhou17davidhou17
authored
(DOCSP-28872): Improve external connectivity docs for single cluster (replica sets) (#1289)
* Improve external connectivity for single cluster * Apply copy review feedback
1 parent 4fddd0b commit a2e687b

File tree

6 files changed

+122
-117
lines changed

6 files changed

+122
-117
lines changed

‎source/includes/code-examples/yaml-files/example-replica-set.yaml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -380,7 +380,7 @@ START-horizon-addcert-replset-random-ports
380380
...
381381
END-horizon-addcert-replset-random-ports
382382

383-
START-horizon-addcert-replset-lower-nodeports
383+
START-horizon-addcert-replset-lower-external-service
384384
security:
385385
tls:
386386
enabled: true
@@ -390,7 +390,7 @@ START-horizon-addcert-replset-lower-nodeports
390390
- "example-website": "web2.example.com:32350"
391391
- "example-website": "web3.example.com:31185"
392392
...
393-
END-horizon-addcert-replset-lower-nodeports
393+
END-horizon-addcert-replset-lower-external-service
394394

395395
START-tls-replset-full-custom
396396
---

‎source/includes/steps-create-external-services.yaml

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
---
2+
stepnum: 0
3+
level: 4
4+
ref: create-external-services
5+
title: "Create an external service for each of the Pods."
6+
content: |
7+
To connect to your {{k8sResource}} from an external resource, configure the
8+
:ref:`spec.externalAccess <multi-spec-externalaccess>` setting:
9+
10+
.. code-block:: yaml
11+
12+
externalAccess: {}
13+
14+
This setting instructs the |k8s-op-short| to create an external :k8sdocs:`LoadBalancer
15+
</concepts/services-networking/service/#loadbalancer>` service for each Pod in your
16+
{{k8sResource}}. The external service provides an entry point for external connections.
17+
Adding this setting with no values creates an external service with the following default
18+
values:
19+
20+
.. include:: /includes/list-tables/external-service-default.rst
21+
22+
Optionally, if you need to add values to the service or override the default values,
23+
specify:
24+
25+
- Annotations specific to your cloud provider, in {{annotations}}
26+
27+
- Overrides for the service specification, in {{overrides}}.
28+
29+
For example, the following settings override the default values for the external service
30+
to configure your {{k8sResource}} to create a :k8sdocs:`NodePort service
31+
</concepts/services-networking/service/#type-nodeport>` that exposes the {{k8sResource}}:
32+
33+
.. code-block:: yaml
34+
35+
externalAccess:
36+
externalService:
37+
annotations:
38+
# cloud-specific annotations for the service
39+
spec:
40+
type: NodePort # default is LoadBalancer
41+
port: 27017
42+
# you can specify other spec overrides if necessary
43+
44+
.. tip::
45+
46+
To learn more, see
47+
:k8sdocs:`Annotations </concepts/overview/working-with-objects/annotations/>`
48+
and :k8sdocs:`ServiceSpec </reference/kubernetes-api/service-resources/service-v1/#ServiceSpec>`
49+
in the |k8s| documentation.
50+
51+
---
52+
stepnum: 0
53+
level: 4
54+
ref: verify-external-services
55+
title: "Verify the external services."
56+
content: |
57+
In {{deployment}}, run the following command to verify that the external services
58+
have been created.
59+
60+
.. code-block:: sh
61+
62+
$ kubectl get services
63+
64+
The command returns a list of services similar to the following output.
65+
For each database Pod in the cluster, the |k8s-op-short| creates an external service
66+
named ``<pod-name>-svc-external``. This service is configured according to the values
67+
and overrides you provide in the :ref:`external service specification <k8s-specification>`.
68+
69+
.. code-block:: sh
70+
:copyable: false
71+
72+
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
73+
{{example}} LoadBalancer 10.102.27.116 1.2.3.4 27017:27017/TCP 8m30s
74+
75+
...

‎source/includes/steps-enable-split-horizon.yaml

Lines changed: 22 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -14,48 +14,33 @@ content: |
1414
:setting:`spec.security.tls.ca`.
1515
1616
---
17-
title: "Add Subject Alternate Names to your |tls| certificates."
18-
level: 4
17+
ref: create-external-services-single-cluster
1918
stepnum: 2
20-
ref: add-san-to-cert
21-
content: |
22-
23-
Add each external |dns| name to the certificate |san-dns|.
24-
19+
inherit:
20+
file: steps-create-external-services.yaml
21+
ref: create-external-services
22+
replacement:
23+
k8sResource: replica set
24+
annotations: :setting:`spec.externalAccess.externalService.annotations`
25+
overrides: :setting:`spec.externalAccess.externalService.spec`
2526
---
26-
title: "Create a NodePort for each |k8s-pod|."
27+
title: "Add Subject Alternate Names to your |tls| certificates."
2728
level: 4
2829
stepnum: 3
29-
ref: k8s-ext-rs-create-nodeports
30+
ref: add-san-to-cert
3031
content: |
3132
32-
Invoke the following commands to create the NodePorts:
33-
34-
.. code-block:: sh
35-
36-
kubectl expose pod/<my-replica-set>-0 --type="NodePort" --port 27017
37-
kubectl expose pod/<my-replica-set>-1 --type="NodePort" --port 27017
38-
kubectl expose pod/<my-replica-set>-2 --type="NodePort" --port 27017
33+
Add each external |dns| name to the certificate |san-dns|.
3934
4035
---
41-
title: "Discover the dynamically assigned NodePorts."
42-
level: 4
4336
stepnum: 4
44-
ref: k8s-ext-rs-discover-nodeports
45-
content: |
46-
47-
Discover the dynamically assigned NodePorts:
48-
49-
.. code-block:: sh
50-
:copyable: false
51-
52-
$ kubectl get svc | grep <my-replica-set>
53-
<my-replica-set>-0 NodePort 172.30.39.228 <none> 27017:30907/TCP 16m
54-
<my-replica-set>-1 NodePort 172.30.185.136 <none> 27017:32350/TCP 16m
55-
<my-replica-set>-2 NodePort 172.30.84.192 <none> 27017:31185/TCP 17m
56-
<my-replica-set>-svc ClusterIP None <none> 27017/TCP 38m
57-
58-
NodePorts range from 30000 to 32767, inclusive.
37+
ref: verify-external-services-single-cluster
38+
inherit:
39+
file: steps-create-external-services.yaml
40+
ref: verify-external-services
41+
replacement:
42+
deployment: your replica set
43+
example: my-replica-set-0-svc-external
5944
---
6045
title: "Open your replica set resource |yaml| file."
6146
level: 4
@@ -107,7 +92,7 @@ content: |
10792
.. include:: /includes/list-tables/resource-keys-split-horizons.rst
10893
10994
---
110-
title: "Confirm the external hostnames and NodePort values in your replica set resource."
95+
title: "Confirm the external hostnames and external service values in your replica set resource."
11196
level: 4
11297
stepnum: 9
11398
ref: k8s-ext-rs-confirm-hostnames
@@ -121,14 +106,14 @@ content: |
121106
routing if the pod runs on another node.
122107
123108
Set the ports in :setting:`spec.connectivity.replicaSetHorizons` to
124-
the NodePort values that you discovered.
109+
the external service values.
125110
126111
.. example::
127112
128113
.. literalinclude:: /includes/code-examples/yaml-files/example-replica-set.yaml
129114
:language: yaml
130-
:start-after: START-horizon-addcert-replset-lower-nodeports
131-
:end-before: END-horizon-addcert-replset-lower-nodeports
115+
:start-after: START-horizon-addcert-replset-lower-external-service
116+
:end-before: END-horizon-addcert-replset-lower-external-service
132117
:linenos:
133118
:lineno-start: 15
134119
:emphasize-lines: 6-8

‎source/includes/steps-multi-cluster-enable-split-horizon.yaml

Lines changed: 16 additions & 75 deletions
Original file line numberDiff line numberDiff line change
@@ -18,58 +18,15 @@ content: |
1818
- The custom |certauth| certificate in :setting:`spec.security.tls.ca`.
1919
2020
---
21-
title: "Create an external service for each of the Pods in different clusters."
22-
level: 4
21+
ref: create-external-services-multi-cluster
2322
stepnum: 3
24-
ref: external-services-replicaset
25-
content: |
26-
27-
To connect to your |multi-cluster| from an external resource, configure the
28-
:ref:`spec.externalAccess <multi-spec-externalaccess>` setting:
29-
30-
.. code-block:: yaml
31-
32-
externalAccess: {}
33-
34-
This setting instructs the |k8s-op-short| to create an external :k8sdocs:`LoadBalancer
35-
</concepts/services-networking/service/#loadbalancer>` service for each Pod in your
36-
|multi-cluster|. The external service provides an entry point for external connections.
37-
Adding this setting with no values creates an external service with the following default
38-
values:
39-
40-
.. include:: /includes/list-tables/external-service-default.rst
41-
42-
Optionally, if you need to add values to the service or override the default values,
43-
specify:
44-
45-
- Annotations specific to your cloud provider, in :ref:`spec.externalAccess.externalService.annotations
46-
<multi-spec-externalaccess-externalservice-annotations>`.
47-
48-
- Overrides for the service specification, in :ref:`spec.externalAccess.externalService.spec
49-
<multi-spec-externalaccess-externalservice-spec>`.
50-
51-
For example, the following settings override the default values for the external service
52-
to configure your |multi-cluster| to create a :k8sdocs:`NodePort service
53-
</concepts/services-networking/service/#type-nodeport>` that exposes the |multi-cluster|:
54-
55-
.. code-block:: yaml
56-
57-
externalAccess:
58-
externalService:
59-
annotations:
60-
# cloud-specific annotations for the service
61-
spec:
62-
type: NodePort # default is LoadBalancer
63-
port: 27017
64-
# you can specify other spec overrides if necessary
65-
66-
.. tip::
67-
68-
To learn more, see
69-
:k8sdocs:`Annotations </concepts/overview/working-with-objects/annotations/>`
70-
and :k8sdocs:`ServiceSpec </reference/kubernetes-api/service-resources/service-v1/#ServiceSpec>`
71-
in the |k8s| documentation.
72-
23+
inherit:
24+
file: steps-create-external-services.yaml
25+
ref: create-external-services
26+
replacement:
27+
k8sResource: multi-Kubernetes-cluster deployment
28+
annotations: :ref:`spec.externalAccess.externalService.annotations <multi-spec-externalaccess-externalservice-annotations>`
29+
overrides: :ref:`spec.externalAccess.externalService.spec <multi-spec-externalaccess-externalservice-spec>`
7330
---
7431
title: "Configure an external service for cluster members."
7532
level: 4
@@ -132,30 +89,14 @@ content: |
13289
Add each external |dns| name to the certificate |san-dns|.
13390
13491
---
135-
title: "Verify the external services."
136-
level: 4
13792
stepnum: 5
138-
ref: k8s-verify-external-services
139-
content: |
140-
141-
In each cluster, run the following command to verify that the external services
142-
have been created.
143-
144-
.. code-block:: sh
145-
146-
$ kubectl get services
147-
148-
The command returns a list of services similar to the following output.
149-
For each database Pod in the cluster, the |k8s-op-short| creates an external service
150-
named ``<pod-name>-svc-external``. This service is configured according to the values
151-
and overrides you provide in the external service specification.
152-
153-
.. code-block:: sh
154-
:copyable: false
155-
156-
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
157-
my-replica-set-0-0-svc-external LoadBalancer 10.102.27.116 1.2.3.4 27017:27017/TCP 8m30s
158-
93+
ref: verify-external-services-multi-cluster
94+
inherit:
95+
file: steps-create-external-services.yaml
96+
ref: verify-external-services
97+
replacement:
98+
deployment: each cluster
99+
example: my-replica-set-0-0-svc-external
159100
---
160101
title: "Update your replica set resource |yaml| file."
161102
level: 4
@@ -164,7 +105,7 @@ ref: update-replset-resource-mc-split-horizon
164105
content: |
165106
166107
Set the hostnames and ports in :setting:`spec.connectivity.replicaSetHorizons`
167-
to the LoadBalancer values that you created in the previous step.
108+
to the external service values that you created in the previous step.
168109
169110
Confirm that you specified the correct external hostnames. External
170111
hostnames should match the |dns| names of |k8s| worker nodes.

‎source/release-notes.txt

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -72,7 +72,8 @@ MongoDBMultiCluster Resource
7272
:ref:`spec.clusterSpecList.externalAccess.externalService.annotations <multi-spec-clusterspeclist-annotations>`,
7373
:ref:`spec.clusterSpecList.externalAccess.externalService <multi-spec-clusterspeclist-externalservice>`,
7474
and :ref:`spec.clusterSpecList.externalAccess.externalDomain <multi-spec-clusterspeclist-externaldomain>`
75-
settings to configure external connectivity settings for |mongodb-multis|.
75+
settings to configure external connectivity settings for |mongodb-multis|. Use these settings to
76+
:ref:`connect to a Multi-Cluster Resource from outside Kubernetes <multi-cluster-connect-from-outside-k8s>`.
7677

7778
- Adds the :ref:`spec.memberOptions.memberConfig.votes <multi-spec-clusterspeclist-memberconfig-votes>`
7879
and :ref:`spec.memberOptions.memberConfig.priority <multi-spec-clusterspeclist-memberconfig-priority>`
@@ -98,8 +99,9 @@ MongoDB Resource
9899
- Adds the ``spec.externalAccess`` setting for configuring external
99100
connectivity for MongoDB resources.
100101
- Deprecates the :setting:`spec.exposedExternally` setting. This setting
101-
will be removed in the |k8s-op-short| 1.22.0 release. Use the
102-
``spec.externalAccess`` setting instead.
102+
will be removed in the |k8s-op-short| 1.22.0 release. To
103+
:ref:`connect to a MongoDB Resource from outside Kubernetes
104+
<connect-from-outside-k8s>`, use the ``spec.externalAccess`` setting instead.
103105

104106
Bug Fixes
105107
`````````

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,8 @@ from outside of the |k8s| cluster depends on the resource.
7272
To connect to your |k8s-op-short|-deployed MongoDB replica
7373
set resource from outside of the |k8s| cluster:
7474

75+
.. |external-domain| replace:: :setting:`spec.externalAccess.externalDomain`
76+
7577
.. include:: /includes/steps/enable-split-horizon.rst
7678

7779
.. tab:: OpenShift

0 commit comments

Comments
 (0)