Skip to content

Commit b29ceff

Browse files
joekrjoekr
authored
docs: update workload cluster with multi-region support (#52)
Add a section that documents how to use the new `cluster-template-alternative-region.yaml` template to show users how to launch clusters in multiple regions.
1 parent 5146ab8 commit b29ceff

File tree

3 files changed

+201
-2
lines changed

3 files changed

+201
-2
lines changed

‎docs/build.sh‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,12 @@ case ${os} in
5151
;;
5252
esac
5353

54+
# handle M1 mac
55+
# at this time mdbook doesn't support M1 so we will need to use the x86 architecture
56+
if [[ ${target} == "apple-darwin" ]] && [[ ${arch} == "arm64" ]]; then
57+
arch="x86_64"
58+
fi
59+
5460
# grab mdbook
5561
# we hardcode linux/amd64 since rust uses a different naming scheme and it's a pain to tran
5662
echo "downloading mdBook-v${MDBOOK_VERSION}-${arch}-${target}.${ext}"

‎docs/src/gs/create-workload-cluster.md‎

Lines changed: 54 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,10 +23,10 @@ when creating a workload cluster on OCI using one of our predefined templates:
2323
| `OCI_CONTROL_PLANE_PV_TRANSIT_ENCRYPTION` | true | Enables [in-flight Transport Layer Security (TLS) 1.2 encryption](https://docs.oracle.com/en-us/iaas/Content/File/Tasks/intransitencryption.htm) of data between control plane nodes and their associated block storage devices. |
2424
| `OCI_NODE_PV_TRANSIT_ENCRYPTION` | true | Enables [in-flight Transport Layer Security (TLS) 1.2 encryption](https://docs.oracle.com/en-us/iaas/Content/File/Tasks/intransitencryption.htm) of data between worker nodes and their associated block storage devices. |
2525

26-
*NOTE* Only specific [bare metal shapes](https://docs.oracle.com/en-us/iaas/releasenotes/changes/60d602f5-abb3-4639-aa19-292a5744a808/)
26+
> Note: Only specific [bare metal shapes](https://docs.oracle.com/en-us/iaas/releasenotes/changes/60d602f5-abb3-4639-aa19-292a5744a808/)
2727
support in-transit encryption. If an unsupported shape is specified, the deployment will fail completely.
2828

29-
*NOTE:* Using the predefined templates the machine's memory size is automatically allocated based on the chosen shape
29+
> Note: Using the predefined templates the machine's memory size is automatically allocated based on the chosen shape
3030
and OCPU count.
3131

3232
The following Cluster API parameters are also available:
@@ -98,6 +98,57 @@ clusterctl generate cluster <cluster-name>\
9898
--from cluster-template-oraclelinux.yaml | kubectl apply -f -
9999
```
100100

101+
## Create a workload cluster in an alternative region
102+
103+
CAPOCI provides a way to launch and manage your workload cluster in multiple
104+
regions. Choose the `cluster-template-alternative-region.yaml` template when
105+
creating your workload clusters from the [latest released artifacts][latest-release].
106+
Currently, the other templates do not support the ability to change the workload
107+
cluster region.
108+
109+
Each cluster can be further configured with the parameters
110+
defined in [Workload Cluster Parameters](#workload-cluster-parameters) and
111+
additionally with the parameter below.
112+
113+
| Parameter | Default Value | Description |
114+
|-----------------------|------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------|
115+
| `OCI_WORKLOAD_REGION` | Configured as [`OCI_REGION`][configure-authentication] | The [OCI region](https://docs.oracle.com/en-us/iaas/Content/General/Concepts/regions.htm) in which to launch the workload cluster. |
116+
117+
The following example configures the CAPOCI provider to authenticate in
118+
`us-phoenix-1` and launch a workload cluster in `us-sanjose-1`.
119+
120+
> Note: Ensure the specified image is available in your chosen region or the launch will fail.
121+
122+
To configure authentication for management cluster, follow the steps in
123+
[Configure authentication][configure-authentication].
124+
125+
Extend the preceding configuration with the following additional configuration
126+
parameter and initialize the CAPOCI provider.
127+
128+
```bash
129+
...
130+
export OCI_REGION=us-phoenix-1
131+
...
132+
133+
clusterctl init --infrastructure oci
134+
```
135+
136+
Create a new workload cluster in San Jose (`us-sanjose-1`) by explicitly setting the
137+
`OCI_WORKLOAD_REGION` environment variable when invoking `clusterctl`:
138+
139+
```bash
140+
OCI_WORKLOAD_REGION=us-sanjose-1 \
141+
OCI_COMPARTMENT_ID=<compartment-id> \
142+
OCI_IMAGE_ID=<in-region-custom-image-id> \
143+
OCI_SSH_KEY=<ssh-key> \
144+
CONTROL_PLANE_MACHINE_COUNT=1 \
145+
KUBERNETES_VERSION=v1.20.10 \
146+
NAMESPACE=default \
147+
NODE_MACHINE_COUNT=1 \
148+
clusterctl generate cluster <cluster-name>\
149+
--from cluster-template-alternative-region.yaml | kubectl apply -f -
150+
```
151+
101152
### Access workload cluster Kubeconfig
102153

103154
Execute the following command to list all the workload clusters present:
@@ -145,3 +196,4 @@ By default, the [OCI Cloud Controller Manager (CCM)][oci-ccm] is not installed i
145196
[oci-ccm]: https://github.com/oracle/oci-cloud-controller-manager
146197
[latest-release]: https://github.com/oracle/cluster-api-provider-oci/releases/tag/v0.1.0
147198
[install-oci-ccm]: ./install-oci-ccm.md
199+
[configure-authentication]: ./install-cluster-api.html#configure-authentication

‎templates/cluster-template-alternative-region.yaml‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
apiVersion: cluster.x-k8s.io/v1beta1
2+
kind: Cluster
3+
metadata:
4+
labels:
5+
cluster.x-k8s.io/cluster-name: "${CLUSTER_NAME}"
6+
name: "${CLUSTER_NAME}"
7+
namespace: "${NAMESPACE}"
8+
spec:
9+
clusterNetwork:
10+
pods:
11+
cidrBlocks:
12+
- ${POD_CIDR:="192.168.0.0/16"}
13+
serviceDomain: ${SERVICE_DOMAIN:="cluster.local"}
14+
services:
15+
cidrBlocks:
16+
- ${SERVICE_CIDR:="10.128.0.0/12"}
17+
infrastructureRef:
18+
apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
19+
kind: OCICluster
20+
name: "${CLUSTER_NAME}"
21+
namespace: "${NAMESPACE}"
22+
controlPlaneRef:
23+
apiVersion: controlplane.cluster.x-k8s.io/v1beta1
24+
kind: KubeadmControlPlane
25+
name: "${CLUSTER_NAME}-control-plane"
26+
namespace: "${NAMESPACE}"
27+
---
28+
apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
29+
kind: OCICluster
30+
metadata:
31+
labels:
32+
cluster.x-k8s.io/cluster-name: "${CLUSTER_NAME}"
33+
name: "${CLUSTER_NAME}"
34+
spec:
35+
compartmentId: "${OCI_COMPARTMENT_ID}"
36+
region: "${OCI_WORKLOAD_REGION}"
37+
---
38+
kind: KubeadmControlPlane
39+
apiVersion: controlplane.cluster.x-k8s.io/v1beta1
40+
metadata:
41+
name: "${CLUSTER_NAME}-control-plane"
42+
namespace: "${NAMESPACE}"
43+
spec:
44+
version: "${KUBERNETES_VERSION}"
45+
replicas: ${CONTROL_PLANE_MACHINE_COUNT}
46+
machineTemplate:
47+
infrastructureRef:
48+
kind: OCIMachineTemplate
49+
apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
50+
name: "${CLUSTER_NAME}-control-plane"
51+
namespace: "${NAMESPACE}"
52+
kubeadmConfigSpec:
53+
clusterConfiguration:
54+
kubernetesVersion: ${KUBERNETES_VERSION}
55+
apiServer:
56+
certSANs: [localhost, 127.0.0.1]
57+
dns: {}
58+
etcd: {}
59+
networking: {}
60+
scheduler: {}
61+
initConfiguration:
62+
nodeRegistration:
63+
criSocket: /var/run/containerd/containerd.sock
64+
kubeletExtraArgs:
65+
cloud-provider: external
66+
provider-id: oci://{{ ds["id"] }}
67+
joinConfiguration:
68+
discovery: {}
69+
nodeRegistration:
70+
criSocket: /var/run/containerd/containerd.sock
71+
kubeletExtraArgs:
72+
cloud-provider: external
73+
provider-id: oci://{{ ds["id"] }}
74+
---
75+
kind: OCIMachineTemplate
76+
apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
77+
metadata:
78+
name: "${CLUSTER_NAME}-control-plane"
79+
spec:
80+
template:
81+
spec:
82+
imageId: "${OCI_IMAGE_ID}"
83+
compartmentId: "${OCI_COMPARTMENT_ID}"
84+
shape: "${OCI_CONTROL_PLANE_MACHINE_TYPE=VM.Standard.E4.Flex}"
85+
shapeConfig:
86+
ocpus: "${OCI_CONTROL_PLANE_MACHINE_TYPE_OCPUS=1}"
87+
metadata:
88+
ssh_authorized_keys: "${OCI_SSH_KEY}"
89+
isPvEncryptionInTransitEnabled: ${OCI_CONTROL_PLANE_PV_TRANSIT_ENCRYPTION=true}
90+
---
91+
apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
92+
kind: OCIMachineTemplate
93+
metadata:
94+
name: "${CLUSTER_NAME}-md-0"
95+
spec:
96+
template:
97+
spec:
98+
imageId: "${OCI_IMAGE_ID}"
99+
compartmentId: "${OCI_COMPARTMENT_ID}"
100+
shape: "${OCI_NODE_MACHINE_TYPE=VM.Standard.E4.Flex}"
101+
shapeConfig:
102+
ocpus: "${OCI_NODE_MACHINE_TYPE_OCPUS=1}"
103+
metadata:
104+
ssh_authorized_keys: "${OCI_SSH_KEY}"
105+
isPvEncryptionInTransitEnabled: ${OCI_NODE_PV_TRANSIT_ENCRYPTION=true}
106+
---
107+
apiVersion: bootstrap.cluster.x-k8s.io/v1alpha4
108+
kind: KubeadmConfigTemplate
109+
metadata:
110+
name: "${CLUSTER_NAME}-md-0"
111+
spec:
112+
template:
113+
spec:
114+
joinConfiguration:
115+
nodeRegistration:
116+
kubeletExtraArgs:
117+
cloud-provider: external
118+
provider-id: oci://{{ ds["id"] }}
119+
---
120+
apiVersion: cluster.x-k8s.io/v1beta1
121+
kind: MachineDeployment
122+
metadata:
123+
name: "${CLUSTER_NAME}-md-0"
124+
spec:
125+
clusterName: "${CLUSTER_NAME}"
126+
replicas: ${NODE_MACHINE_COUNT}
127+
selector:
128+
matchLabels:
129+
template:
130+
spec:
131+
clusterName: "${CLUSTER_NAME}"
132+
version: "${KUBERNETES_VERSION}"
133+
bootstrap:
134+
configRef:
135+
name: "${CLUSTER_NAME}-md-0"
136+
apiVersion: bootstrap.cluster.x-k8s.io/v1beta1
137+
kind: KubeadmConfigTemplate
138+
infrastructureRef:
139+
name: "${CLUSTER_NAME}-md-0"
140+
apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
141+
kind: OCIMachineTemplate

0 commit comments

Comments
 (0)