Skip to content

Commit

Permalink
docs: update workload cluster with multi-region support (#52)
Browse files Browse the repository at this point in the history
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.
  • Loading branch information
joekr committed Apr 7, 2022
1 parent 5146ab8 commit b29ceff
Show file tree
Hide file tree
Showing 3 changed files with 201 additions and 2 deletions.
6 changes: 6 additions & 0 deletions docs/build.sh
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,12 @@ case ${os} in
;;
esac

# handle M1 mac
# at this time mdbook doesn't support M1 so we will need to use the x86 architecture
if [[ ${target} == "apple-darwin" ]] && [[ ${arch} == "arm64" ]]; then
arch="x86_64"
fi

# grab mdbook
# we hardcode linux/amd64 since rust uses a different naming scheme and it's a pain to tran
echo "downloading mdBook-v${MDBOOK_VERSION}-${arch}-${target}.${ext}"
Expand Down
56 changes: 54 additions & 2 deletions docs/src/gs/create-workload-cluster.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,10 +23,10 @@ when creating a workload cluster on OCI using one of our predefined templates:
| `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. |
| `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. |

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

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

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

## Create a workload cluster in an alternative region

CAPOCI provides a way to launch and manage your workload cluster in multiple
regions. Choose the `cluster-template-alternative-region.yaml` template when
creating your workload clusters from the [latest released artifacts][latest-release].
Currently, the other templates do not support the ability to change the workload
cluster region.

Each cluster can be further configured with the parameters
defined in [Workload Cluster Parameters](#workload-cluster-parameters) and
additionally with the parameter below.

| Parameter | Default Value | Description |
|-----------------------|------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------|
| `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. |

The following example configures the CAPOCI provider to authenticate in
`us-phoenix-1` and launch a workload cluster in `us-sanjose-1`.

> Note: Ensure the specified image is available in your chosen region or the launch will fail.
To configure authentication for management cluster, follow the steps in
[Configure authentication][configure-authentication].

Extend the preceding configuration with the following additional configuration
parameter and initialize the CAPOCI provider.

```bash
...
export OCI_REGION=us-phoenix-1
...

clusterctl init --infrastructure oci
```

Create a new workload cluster in San Jose (`us-sanjose-1`) by explicitly setting the
`OCI_WORKLOAD_REGION` environment variable when invoking `clusterctl`:

```bash
OCI_WORKLOAD_REGION=us-sanjose-1 \
OCI_COMPARTMENT_ID=<compartment-id> \
OCI_IMAGE_ID=<in-region-custom-image-id> \
OCI_SSH_KEY=<ssh-key> \
CONTROL_PLANE_MACHINE_COUNT=1 \
KUBERNETES_VERSION=v1.20.10 \
NAMESPACE=default \
NODE_MACHINE_COUNT=1 \
clusterctl generate cluster <cluster-name>\
--from cluster-template-alternative-region.yaml | kubectl apply -f -
```

### Access workload cluster Kubeconfig

Execute the following command to list all the workload clusters present:
Expand Down Expand Up @@ -145,3 +196,4 @@ By default, the [OCI Cloud Controller Manager (CCM)][oci-ccm] is not installed i
[oci-ccm]: https://github.com/oracle/oci-cloud-controller-manager
[latest-release]: https://github.com/oracle/cluster-api-provider-oci/releases/tag/v0.1.0
[install-oci-ccm]: ./install-oci-ccm.md
[configure-authentication]: ./install-cluster-api.html#configure-authentication
141 changes: 141 additions & 0 deletions templates/cluster-template-alternative-region.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,141 @@
apiVersion: cluster.x-k8s.io/v1beta1
kind: Cluster
metadata:
labels:
cluster.x-k8s.io/cluster-name: "${CLUSTER_NAME}"
name: "${CLUSTER_NAME}"
namespace: "${NAMESPACE}"
spec:
clusterNetwork:
pods:
cidrBlocks:
- ${POD_CIDR:="192.168.0.0/16"}
serviceDomain: ${SERVICE_DOMAIN:="cluster.local"}
services:
cidrBlocks:
- ${SERVICE_CIDR:="10.128.0.0/12"}
infrastructureRef:
apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
kind: OCICluster
name: "${CLUSTER_NAME}"
namespace: "${NAMESPACE}"
controlPlaneRef:
apiVersion: controlplane.cluster.x-k8s.io/v1beta1
kind: KubeadmControlPlane
name: "${CLUSTER_NAME}-control-plane"
namespace: "${NAMESPACE}"
---
apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
kind: OCICluster
metadata:
labels:
cluster.x-k8s.io/cluster-name: "${CLUSTER_NAME}"
name: "${CLUSTER_NAME}"
spec:
compartmentId: "${OCI_COMPARTMENT_ID}"
region: "${OCI_WORKLOAD_REGION}"
---
kind: KubeadmControlPlane
apiVersion: controlplane.cluster.x-k8s.io/v1beta1
metadata:
name: "${CLUSTER_NAME}-control-plane"
namespace: "${NAMESPACE}"
spec:
version: "${KUBERNETES_VERSION}"
replicas: ${CONTROL_PLANE_MACHINE_COUNT}
machineTemplate:
infrastructureRef:
kind: OCIMachineTemplate
apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
name: "${CLUSTER_NAME}-control-plane"
namespace: "${NAMESPACE}"
kubeadmConfigSpec:
clusterConfiguration:
kubernetesVersion: ${KUBERNETES_VERSION}
apiServer:
certSANs: [localhost, 127.0.0.1]
dns: {}
etcd: {}
networking: {}
scheduler: {}
initConfiguration:
nodeRegistration:
criSocket: /var/run/containerd/containerd.sock
kubeletExtraArgs:
cloud-provider: external
provider-id: oci://{{ ds["id"] }}
joinConfiguration:
discovery: {}
nodeRegistration:
criSocket: /var/run/containerd/containerd.sock
kubeletExtraArgs:
cloud-provider: external
provider-id: oci://{{ ds["id"] }}
---
kind: OCIMachineTemplate
apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
metadata:
name: "${CLUSTER_NAME}-control-plane"
spec:
template:
spec:
imageId: "${OCI_IMAGE_ID}"
compartmentId: "${OCI_COMPARTMENT_ID}"
shape: "${OCI_CONTROL_PLANE_MACHINE_TYPE=VM.Standard.E4.Flex}"
shapeConfig:
ocpus: "${OCI_CONTROL_PLANE_MACHINE_TYPE_OCPUS=1}"
metadata:
ssh_authorized_keys: "${OCI_SSH_KEY}"
isPvEncryptionInTransitEnabled: ${OCI_CONTROL_PLANE_PV_TRANSIT_ENCRYPTION=true}
---
apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
kind: OCIMachineTemplate
metadata:
name: "${CLUSTER_NAME}-md-0"
spec:
template:
spec:
imageId: "${OCI_IMAGE_ID}"
compartmentId: "${OCI_COMPARTMENT_ID}"
shape: "${OCI_NODE_MACHINE_TYPE=VM.Standard.E4.Flex}"
shapeConfig:
ocpus: "${OCI_NODE_MACHINE_TYPE_OCPUS=1}"
metadata:
ssh_authorized_keys: "${OCI_SSH_KEY}"
isPvEncryptionInTransitEnabled: ${OCI_NODE_PV_TRANSIT_ENCRYPTION=true}
---
apiVersion: bootstrap.cluster.x-k8s.io/v1alpha4
kind: KubeadmConfigTemplate
metadata:
name: "${CLUSTER_NAME}-md-0"
spec:
template:
spec:
joinConfiguration:
nodeRegistration:
kubeletExtraArgs:
cloud-provider: external
provider-id: oci://{{ ds["id"] }}
---
apiVersion: cluster.x-k8s.io/v1beta1
kind: MachineDeployment
metadata:
name: "${CLUSTER_NAME}-md-0"
spec:
clusterName: "${CLUSTER_NAME}"
replicas: ${NODE_MACHINE_COUNT}
selector:
matchLabels:
template:
spec:
clusterName: "${CLUSTER_NAME}"
version: "${KUBERNETES_VERSION}"
bootstrap:
configRef:
name: "${CLUSTER_NAME}-md-0"
apiVersion: bootstrap.cluster.x-k8s.io/v1beta1
kind: KubeadmConfigTemplate
infrastructureRef:
name: "${CLUSTER_NAME}-md-0"
apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
kind: OCIMachineTemplate

0 comments on commit b29ceff

Please sign in to comment.