Developer workflow

June 30, 2026 ยท View on GitHub

Prerequisites

This project requires the following to be installed on the developer's workstation.

  1. devbox
  2. direnv

To install the required packages, please follow the directions provided for your system.

NOTE: The first time you cd into the directory, the required dependencies for the project will start to download and will take some time depending on your connection.

  1. Download source code:

    gh repo clone nutanix-cloud-native/cluster-api-provider-nutanix
cd cluster-api-provider-nutanix

  2. Build a container image with the source code:

    make docker-build

Create a local management cluster

  1. Create a KIND cluster:

     make kind-create

This will configure kubectl for the local cluster.

Build a CAPI Image for Nutanix

  1. Follow the instructions here to build a CAPI image for Nutanix. The image name printed at the end of the build will be needed to create a Kubernetes cluster.

Prepare local clusterctl

  1. Setup clusterctl with the configuration to ensure local clusterctl uses the development version of the provider:

    make prepare-local-clusterctl

Deploy cluster-api-provider-nutanix provider and CRDs on local management cluster

  1. Deploy the provider, along with CAPI core controllers and CRDs:

    make deploy

  2. Verify the provider Pod is READY:

    kubectl get pods -n capx-system

Create a regular test workload cluster (i.e. without clusterclass topology)

  1. Set the required environment variables:

    export EXP_CLUSTER_RESOURCE_SET=true
export EXP_CLUSTER_TOPOLOGY=true
export DOCKER_POD_IPV6_CIDRS="fc00::/112"
export WORKER_MACHINE_COUNT="2"

export CONTROL_PLANE_ENDPOINT_IP='10.0.0.1'
export NUTANIX_STORAGE_CONTAINER=storage-container
export NUTANIX_ADDITIONAL_CATEGORY_KEY="AppType"
export NUTANIX_ADDITIONAL_CATEGORY_VALUE="Kubernetes"
export NUTANIX_PROJECT_NAME="test-project"
export NUTANIX_PRISM_ELEMENT_CLUSTER_NAME='prism-element-name'
export NUTANIX_SUBNET_NAME="subnet-name"
export LOCAL_IMAGE_REGISTRY="your.registry.uri"

export NUTANIX_ENDPOINT='pc.nutanix.com'
export NUTANIX_USER='username'
export NUTANIX_PASSWORD='password'
# Optional: set API key instead of username/password.
# export NUTANIX_API_KEY='your-api-key'
export NUTANIX_INSECURE='false'
export NUTANIX_PORT='9440'


export KUBERNETES_VERSION="v1.33.0"
export NUTANIX_MACHINE_TEMPLATE_IMAGE_NAME="image-name-on-prism-central"

export NUTANIX_SSH_AUTHORIZED_KEY='your-ssh-key'

  2. Create a workload cluster:

    make test-cluster-create

    Optionally, to use a different cluster name:

    make test-cluster-create TEST_CLUSTER_NAME=<>

  3. (Optional) Get the workload cluster kubeconfig. This will write out the kubeconfig file in the local directory as <cluster-name>.workload.kubeconfig:

    make generate-cluster-kubeconfig

    When using a different cluster name set TEST_CLUSTER_NAME variable:

    make generate-cluster-kubeconfig TEST_CLUSTER_NAME=<>

  4. Install a CNI on the workload cluster:

    make test-cluster-install-cni

    When using a different cluster name set TEST_CLUSTER_NAME variable:

    make test-cluster-install-cni TEST_CLUSTER_NAME=<>

Create a test workload cluster with topology

  1. Create a workload cluster:

    make test-cc-cluster-create

    Optionally, to use a different cluster name:

    make test-cc-cluster-create TEST_TOPOLOGY_CLUSTER_NAME=<>

Upgrade test workload cluster's k8s version

  1. Upgrade workload cluster's k8s version

    make test-cc-cluster-upgrade TEST_TOPOLOGY_CLUSTER_NAME=<> UPGRADE_K8S_VERSION_TO=<vx.x.x>

Debugging failures

  1. Check the cluster resources:

    kubectl get cluster-api --namespace capx-test-ns

  2. Check the provider logs:

    kubectl logs -n capx-system -l cluster.x-k8s.io/provider=infrastructure-nutanix

  3. Check status of individual Nodes by using the address from the corresponding NutanixMachine:

    ssh capiuser@<address>

    • Check cloud-init bootstrap logs:

      tail /var/log/cloud-init-output.log

    • Check journalctl logs for Kubelet and Containerd

    • Check Containerd containers:

      crictl ps -a

Cleanup

  1. Delete the test workload cluster without topology:

    make test-cluster-delete

    When using a unique cluster name set TEST_CLUSTER_NAME variable:

    make test-cluster-delete TEST_CLUSTER_NAME=<>

  2. Delete the test workload cluster with topology:

    make test-cc-cluster-delete

    When using a unique cluster name set TEST_CLUSTER_NAME variable:

    make test-cluster-delete TEST_CLUSTER_NAME=<>

  3. Delete the management KIND cluster:

    make kind-delete

Running E2E tests

  1. Set the required environment variables

    export EXP_CLUSTER_RESOURCE_SET=true
export EXP_CLUSTER_TOPOLOGY=true
export DOCKER_POD_IPV6_CIDRS="fc00::/112"
export WORKER_MACHINE_COUNT="2"

export CONTROL_PLANE_ENDPOINT_IP='10.0.0.1'
export NUTANIX_STORAGE_CONTAINER=storage-container
export NUTANIX_ADDITIONAL_CATEGORY_KEY="AppType"
export NUTANIX_ADDITIONAL_CATEGORY_VALUE="Kubernetes"
export NUTANIX_PROJECT_NAME="test-project"
export NUTANIX_PRISM_ELEMENT_CLUSTER_NAME='prism-element-name'
export NUTANIX_SUBNET_NAME="subnet-name"
export LOCAL_IMAGE_REGISTRY="your.registry.uri"

export NUTANIX_ENDPOINT='pc.nutanix.com'
export NUTANIX_USER='username'
export NUTANIX_PASSWORD='password'
# Optional: set API key instead of username/password.
# export NUTANIX_API_KEY='your-api-key'
export NUTANIX_INSECURE='false'
export NUTANIX_PORT='9440'


export KUBERNETES_VERSION="v1.33.0"
export NUTANIX_MACHINE_TEMPLATE_IMAGE_NAME="image-name-on-prism-central"

export NUTANIX_SSH_AUTHORIZED_KEY='your-ssh-key'

    The remaining values for the e2e tests are set in test/e2e/config/nutanix.yaml

  2. Run the relevant e2e tests by specifying the label filters. For example, to run the non-clusterclass quickstart tests:

    LABEL_FILTERS="quickstart && !clusterclass" make test-e2e-cilium

    Note: E2E tests are run against a KIND management cluster created as part of the test run and deleted at the end of the test run.