Cluster API Templates

Describes Kubernetes Cluster API template files in Oracle CNE.

A default OCI cluster can be created using the oci provider with no extra arguments. For example:

ocne cluster start --provider oci

The default cluster settings create a useful cluster, but, it's likely that extra configuration is required. To customize a deployment, generate a cluster template to use as a basis for the cluster.

The ocne cluster template command is used to create a cluster template, and uses the default configuration and any cluster configuration you set to generate the template. It also fetches things such as compute image OCIDs from the configured compartment automatically. You can create a cluster template and save it to a file, for example:

ocne cluster template > mytemplate.yaml

The resulting YAML file contains the Cluster Resources for the Kubernetes Cluster API to create a cluster, using all the configuration you have on the local system.

For example, you could create a cluster configuration file (named myconfig.yaml in this example) that includes customization to the deployment, and might include:

provider: oci
name: mycluster
controlPlaneNodes: 3
workerNodes: 3
clusterDefinition: /home/username/mytemplate.yaml
providers:
  oci:
    compartment: ocid1.compartment.oc1..uniqueID

In this example, the clusterDefinition file is the location of a Kubernetes Cluster API template, which is generated based on the configuration in this cluster configuration file. You use the template when you create the cluster. You can update the cluster template to use this new configuration by running the ocne cluster template command again and providing the configuration file. For example:

ocne cluster template --config myconfig.yaml > $HOME/mytemplate.yaml

Edit the template file to configure any Kubernetes Cluster API options that aren't provided in a cluster configuration file. When you're satisfied with the template, create the cluster using the cluster configuration file. As this cluster configuration file includes a link to the cluster template in the clusterDefinition, the template is used to create the cluster. For example:

ocne cluster start --config myconfig.yaml

Cluster API Template Files

Describes Kubernetes Cluster API template file contents.

A Kubernetes Cluster API template file can be generated that contains all the information required to create a Kubernetes cluster using the Kubernetes Cluster API. The ocne cluster template command is used to create this file. Save and edit this template to create clusters using the Kubernetes Cluster API.

Optionally, edit the Custom Resources in the template to suit the cluster you want to create. The options available are described in the upstream Kubernetes Cluster API Provider for Oracle Cloud Infrastructure documentation.

The template file contains Custom Resources for each component of a cluster, and includes:

apiVersion: cluster.x-k8s.io/v1beta1
kind: Cluster
metadata:
  labels:
    cluster.x-k8s.io/cluster-name: "ocne"
  name: "ocne"
  namespace: "ocne"
spec:
...
---
apiVersion: infrastructure.cluster.x-k8s.io/v1beta2
kind: OCICluster
metadata:
  labels:
    cluster.x-k8s.io/cluster-name: "ocne"
  name: "ocne"
  namespace: "ocne"
spec:
...
---
kind: KubeadmControlPlane
apiVersion: controlplane.cluster.x-k8s.io/v1beta1
metadata:
  name: "ocne-control-plane"
  namespace: "ocne"
spec:
...
---
kind: OCIMachineTemplate
apiVersion: infrastructure.cluster.x-k8s.io/v1beta2
metadata:
  name: "ocne-control-plane"
  namespace: "ocne"
spec:
...
---
apiVersion: infrastructure.cluster.x-k8s.io/v1beta2
kind: OCIMachineTemplate
metadata:
  name: "ocne-md-0"
  namespace: "ocne"
spec:
...
---
apiVersion: bootstrap.cluster.x-k8s.io/v1beta1
kind: KubeadmConfigTemplate
metadata:
  name: "ocne-md-0"
  namespace: "ocne"
spec:
...

Creating a Cluster API Template

Create a Kubernetes Cluster API template using the ocne cluster template command.

A Kubernetes Cluster API template can be used when deploying clusters using the Kubernetes Cluster API.

You can generate a Cluster API template using the defaults set on the local system, or using a cluster configuration file.

Create a cluster template.
Use the ocne cluster template command to generate a YAML file that contains a template to create a cluster using the Kubernetes Cluster API. The syntax is:
```
ocne cluster template 
[{-c|--config} path] 
[{-P|--provider} provider]
```
For more information on the syntax options, see Oracle Cloud Native Environment: CLI.

For example:
```
ocne cluster template --config myconfig.yaml > mytemplate.yaml
```
(Optional) Edit the template.

Edit the file to suit the requirements of the cluster you want to create. The options available are described in the upstream Kubernetes Cluster API Provider for Oracle Cloud Infrastructure documentation.

Using an Existing VCN

Edit a Cluster API template to use an existing OCI Virtual Cloud Network (VCN).

To use an existing VCN when deploying a Kubernetes cluster to OCI, generate and edit a Cluster API template to include the VCN information. You need to provide OCIDs for:

VCN. The VCN to use for the cluster nodes.
Network Security Group. This is the network security group that contains the ingress rules to the VCN.
Subnet. This is the subnet of the VCN.

The values provided for the VCN and subnet are also used by the OCI Cloud Controller Manager during deployment to configure the control plane load balancer.

Create a Cluster API template.

Set up the configuration files to create the cluster, including all relevant OCIDs and generate a Cluster API template. For information on creating a Cluster API template, see Creating a Cluster API Template.
Set the OCIDs as environment variables.
Replace OCID in each line with the OCID for the network object.
```
export VCN=OCID
export SECGROUP=OCID
export SUBNET=OCID
```

Create a YAML file with the VCN information.

Generate a file to include the VCN information, using the environment variables.

envsubst > vcn_config.yaml << EOF
  networkSpec:
    skipNetworkManagement: true
    vcn:
      id: $VCN 
      networkSecurityGroup:
        skip: true
        list:
        - name: control-plane-endpoint
          role: control-plane-endpoint
          id: $SECGROUP
        - name: control-plane
          role: control-plane
          id: $SECGROUP
        - name: worker
          role: worker
          id: $SECGROUP
        - name: service-lb
          role: service-lb
          id: $SECGROUP
      internetGateway:
        skip: true
      natGateway:
        skip: true
      serviceGateway:
        skip: true
      routeTable:
        skip: true
      subnets:
      - name: control-plane-endpoint
        role: control-plane-endpoint
        id: $SUBNET
        type: private
      - name: control-plane
        role: control-plane
        id: $SUBNET
        type: private
      - name: worker
        role: worker
        id: $SUBNET
        type: private
      - name: service-lb
        role: service-lb
        id: $SUBNET
        type: private
EOF

Edit the Cluster API template.
Open the file that includes the VCN information (vcn_config.yaml in this example), copy the content, and paste it into the Cluster API template. The information must be included in the OCICluster Custom Resource, in the spec section. For example:
```
apiVersion: infrastructure.cluster.x-k8s.io/v1beta2
kind: OCICluster
metadata:
  labels:
    cluster.x-k8s.io/cluster-name: "mycluster"
  name: "mycluster"
  namespace: "ocne"
spec:
  compartmentId: "ocid1.compartment.oc1..."
  # Paste the VCN information here.
  networkSpec:
    skipNetworkManagement: true
    vcn: ...
```
Create the cluster with the Cluster API template.
Ensure you include the location of the Cluster API template in the cluster configuration file when you create the cluster. The configuration file must include the location of the template using the clusterDefinition option. For example:
```
clusterDefinition: /home/username/mytemplate.yaml
```