This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Getting started

1: Deploying CAREN

1.1: Via clusterctl
1.2: Via Helm

2: Creating clusters from example ClusterClasses

2.1: AWS
2.2: Nutanix
2.3: Docker

3: Integrating with your ClusterClass

To deploy CAREN, follow the docs on how to deploy CAREN using either clusterctl or Helm.

1 - Deploying CAREN

CAREN is implemented as a CAPI runtime extension provider, which means it can be deployed alongside all other CAPI providers in the same way using clusterctl. However, as CAREN is not yet integrated into clusterctl, it is necessary to first configure clusterctl to know about CAREN before we can deploy it.

Alternatively, you can install CAREN via Helm. Installing via Helm will provide some default ClusterClasses and allow for further customization of the CAREN deployment.

1.1 - Via clusterctl

Add the following to your clusterctl.yaml file, which is normally found at ${XDG_CONFIG_HOME}/cluster-api/clusterctl.yaml (or ${HOME}/cluster-api/clusterctl.yaml). See clusterctl configuration file for more details. If the providers section already exists, add the entry and omit the providers key from this block below:

providers:
  - name: "caren"
    url: "https://github.com/nutanix-cloud-native/cluster-api-runtime-extensions-nutanix/releases/v0.23.1/runtime-extensions-components.yaml"
    type: "RuntimeExtensionProvider"

Now we can deploy CAREN and other necessary providers (update infrastructure providers for your needs), leaving all configuration values blank as we will specify these when creating clusters:

env CLUSTER_TOPOLOGY=true \
    EXP_RUNTIME_SDK=true  \
    EXP_CLUSTER_RESOURCE_SET=true  \
    NUTANIX_ENDPOINT= NUTANIX_PASSWORD= NUTANIX_USER=  \
    AWS_B64ENCODED_CREDENTIALS=  \
    clusterctl init \
      --infrastructure docker,nutanix:v1.4.0,aws \
      --addon helm \
      --runtime-extension caren:v0.23.1 \
      --wait-providers

1.2 - Via Helm

When installing CAREN via Helm, we need to deploy Cluster API core providers and any other required infrastructure providers to our management cluster via clusterctl:

env CLUSTER_TOPOLOGY=true \
    EXP_RUNTIME_SDK=true  \
    EXP_CLUSTER_RESOURCE_SET=true  \
    NUTANIX_ENDPOINT= NUTANIX_PASSWORD= NUTANIX_USER=  \
    AWS_B64ENCODED_CREDENTIALS=  \
    clusterctl init \
      --infrastructure docker,nutanix:v1.4.0,aws \
      --addon helm \
      --wait-providers

We can then deploy CAREN via Helm by adding the Helm repo and installing in the usual way via Helm: Add the CAREN Helm repo:

helm repo add caren https://nutanix-cloud-native.github.io/cluster-api-runtime-extensions-nutanix/helm
helm repo update caren
helm upgrade --install caren caren/cluster-api-runtime-extensions-nutanix \
  --version v0.23.1 \
  --namespace caren-system \
  --create-namespace \
  --wait \
  --wait-for-jobs

2 - Creating clusters from example ClusterClasses

CAREN currently supports clusters for the providers below (follow the links below to see instructions on how to use CAREN with these providers).

2.1 - AWS

Cluster API requires that ClusterClasses referenced by a Cluster reside in the same namespace as the Cluster. To create the necessary ClusterClass, run:

kubectl apply --server-side \
  -f https://github.com/nutanix-cloud-native/cluster-api-runtime-extensions-nutanix/releases/download/v0.23.1/aws-cluster-class.yaml

You can then create your cluster. First, let's list the required variables:

clusterctl generate cluster my-cluster \
  --from https://github.com/nutanix-cloud-native/cluster-api-runtime-extensions-nutanix/releases/download/v0.23.1/aws-cluster-cilium-helm-addon.yaml \
  --list-variables

Export the required variables and any optional variables that you may want to set:

export AMI_LOOKUP_BASEOS=<value> \
       AMI_LOOKUP_FORMAT=<value> \
       AMI_LOOKUP_ORG=<value>

And create your cluster:

clusterctl generate cluster my-cluster \
  --from https://github.com/nutanix-cloud-native/cluster-api-runtime-extensions-nutanix/releases/download/v0.23.1/aws-cluster-cilium-helm-addon.yaml \
  --kubernetes-version=v1.31.2 \
  --worker-machine-count=1 \
  | kubectl apply --server-side -f -

To customize your cluster configuration prior to creation, generate the cluster definition to a file and edit it before applying:

clusterctl generate cluster my-cluster \
  --from https://github.com/nutanix-cloud-native/cluster-api-runtime-extensions-nutanix/releases/download/v0.23.1/aws-cluster-cilium-helm-addon.yaml \
  --kubernetes-version=v1.31.2 >mycluster.yaml

# EDIT mycluster.yaml

kubectl apply --server-side -f mycluster.yaml

2.2 - Nutanix

Cluster API requires that ClusterClasses referenced by a Cluster reside in the same namespace as the Cluster. To create the necessary ClusterClass, run:

kubectl apply --server-side \
  -f https://github.com/nutanix-cloud-native/cluster-api-runtime-extensions-nutanix/releases/download/v0.23.1/nutanix-cluster-class.yaml

You can then create your cluster. First, let's list the required variables:

clusterctl generate cluster my-cluster \
  --from https://github.com/nutanix-cloud-native/cluster-api-runtime-extensions-nutanix/releases/download/v0.23.1/nutanix-cluster-cilium-helm-addon.yaml \
  --list-variables

Export the required variables and any optional variables that you may want to set:

export CONTROL_PLANE_ENDPOINT_IP=<value> \
       DOCKER_HUB_PASSWORD=<value> \
       DOCKER_HUB_USERNAME=<value> \
       NUTANIX_ENDPOINT=<value> \
       NUTANIX_INSECURE=<value> \
       NUTANIX_MACHINE_TEMPLATE_IMAGE_NAME=<value> \
       NUTANIX_PASSWORD=<value> \
       NUTANIX_PORT=<value> \
       NUTANIX_PRISM_ELEMENT_CLUSTER_NAME=<value> \
       NUTANIX_STORAGE_CONTAINER_NAME=<value> \
       NUTANIX_SUBNET_NAME=<value> \
       NUTANIX_USER=<value>

And create your cluster:

clusterctl generate cluster my-cluster \
  --from https://github.com/nutanix-cloud-native/cluster-api-runtime-extensions-nutanix/releases/download/v0.23.1/nutanix-cluster-cilium-helm-addon.yaml \
  --kubernetes-version=v1.31.2 \
  --worker-machine-count=1 \
  | kubectl apply --server-side -f -

To customize your cluster configuration prior to creation, generate the cluster definition to a file and edit it before applying:

clusterctl generate cluster my-cluster \
  --from https://github.com/nutanix-cloud-native/cluster-api-runtime-extensions-nutanix/releases/download/v0.23.1/nutanix-cluster-cilium-helm-addon.yaml \
  --kubernetes-version=v1.31.2 >mycluster.yaml

# EDIT mycluster.yaml

kubectl apply --server-side -f mycluster.yaml

2.3 - Docker

Cluster API requires that ClusterClasses referenced by a Cluster reside in the same namespace as the Cluster. To create the necessary ClusterClass, run:

kubectl apply --server-side \
  -f https://github.com/nutanix-cloud-native/cluster-api-runtime-extensions-nutanix/releases/download/v0.23.1/docker-cluster-class.yaml

You can then create your cluster. First, let's list the required variables:

clusterctl generate cluster my-cluster \
  --from https://github.com/nutanix-cloud-native/cluster-api-runtime-extensions-nutanix/releases/download/v0.23.1/docker-cluster-cilium-helm-addon.yaml \
  --list-variables

Export the required variables and any optional variables that you may want to set and then create your cluster:

clusterctl generate cluster my-cluster \
  --from https://github.com/nutanix-cloud-native/cluster-api-runtime-extensions-nutanix/releases/download/v0.23.1/docker-cluster-cilium-helm-addon.yaml \
  --kubernetes-version=v1.31.2 \
  --worker-machine-count=1 \
  | kubectl apply --server-side -f -

To customize your cluster configuration prior to creation, generate the cluster definition to a file and edit it before applying:

clusterctl generate cluster my-cluster \
  --from https://github.com/nutanix-cloud-native/cluster-api-runtime-extensions-nutanix/releases/download/v0.23.1/docker-cluster-cilium-helm-addon.yaml \
  --kubernetes-version=v1.31.2 >mycluster.yaml

# EDIT mycluster.yaml

kubectl apply --server-side -f mycluster.yaml

3 - Integrating with your ClusterClass

CAREN provides an extension config for the provided runtime hooks for the various supported providers that you can integrate with your own ClusterClass to add to your own customizations. In this way you can take advantage of what CAREN provides instead of having to write your own.

To integrate with your ClusterClasses, you will need to add the appropriate external patch references to your ClusterClass depending on your infrastructure provider under spec.patches. Once you have done this, you will be able to specify the variables clusterConfig and workerConfig¹ regardless of infrastructure provider, although remember that each variable will have provider-specific fields as part of the schema.

The required values are shown below per provider.

AWS

  patches:
  - external:
      discoverVariablesExtension: awsclusterconfigvars.cluster-api-runtime-extensions-nutanix
      generateExtension: awsclusterconfigpatch.cluster-api-runtime-extensions-nutanix
    name: cluster-config
  - external:
      discoverVariablesExtension: awsworkerconfigvars.cluster-api-runtime-extensions-nutanix
      generateExtension: awsworkerconfigpatch.cluster-api-runtime-extensions-nutanix
    name: worker-config

Nutanix

  patches:
  - external:
      discoverVariablesExtension: nutanixclusterconfigvars.cluster-api-runtime-extensions-nutanix
      generateExtension: nutanixclusterconfigpatch.cluster-api-runtime-extensions-nutanix
    name: cluster-config
  - external:
      discoverVariablesExtension: nutanixworkerconfigvars.cluster-api-runtime-extensions-nutanix
      generateExtension: nutanixworkerconfigpatch.cluster-api-runtime-extensions-nutanix
    name: worker-config

Docker (for development and testing only)

  patches:
  - external:
      discoverVariablesExtension: dockerclusterconfigvars.cluster-api-runtime-extensions-nutanix
      generateExtension: dockerclusterconfigpatch.cluster-api-runtime-extensions-nutanix
    name: cluster-config
  - external:
      discoverVariablesExtension: dockerworkerconfigvars.cluster-api-runtime-extensions-nutanix
      generateExtension: dockerworkerconfigpatch.cluster-api-runtime-extensions-nutanix
    name: worker-config

Generic (any infrastructure provider)

  patches:
  - external:
      discoverVariablesExtension: genericclusterconfigvars.cluster-api-runtime-extensions-nutanix
      generateExtension: genericclusterconfigpatch.cluster-api-runtime-extensions-nutanix
    name: cluster-config

Generic runtime hooks only include clusterConfig variable as there are no generic worker customizations currently available. ↩︎