Kubernetes & Karbon APIs: 2022 Update

Nutanix.dev - Kubernetes and Karbon APIs 2022 Update

In July 2020 we published an article titled Automating Karbon Deployments via API. Since the publication of that article there has been a small change in the required syntax when using our Karbon APIs. This brief article will discuss the main change that users of the Karbon APIs should be made aware of.

Note that all other aspects of the Nutanix Karbon APIs e.g. endpoints, authentication, required HTTP methods etc, remain unchanged.

Demo Environment

At this article’s date of publication, Nutanix Karbon’s current version is 2.4. The full demo environment used during testing is as follows:

  • AOS 6.0.2.4
  • Prism Central version pc.2022.1
  • Karbon 2.4
  • Kubernetes version 1.21.8-0, indicated by the {{k8s_version}} variable
  • Nutanix Karbon OS image ntnx-1.2, indicated by the {{karbon_image_version}} variable

Previous API Usage Example

At the time of publication, the initial article was designed for use with Nutanix Karbon 2.2.

If you followed along with the previous article and used the JSON payloads published there, there’s a single change that will need to be made before the payloads can be used with Karbon 2.4. This change relates to the naming of various entities within the new Karbon Kubernetes cluster. Specifically, the Karbon 2.2 APIs allowed entity names containing underscores. For example, the JSON snippet below shows the previous definition for a sample etcd node pool configuration:

    "etcd_config": {
        "node_pools": [
            {
                "name": "etcd_pool",
                "node_os_version": "{{karbon_image_version}}",
                "num_instances": 1,
                "ahv_config": {
                    "cpu": 4,
                    "disk_mib": 40960,
                    "memory_mib": 8192,
                    "network_uuid": "{{subnet_uuid}}",
                    "prism_element_cluster_uuid": "{{cluster_uuid}}"
                }
            }
        ]
    },

Note the etcd pool name “etcd_pool“. This name is invalid in Karbon 2.4 and will return the following error response when submitted using the Karbon APIs.

{
    "code": 605,
    "message": "name in body should match '^[a-z0-9]([-a-z0-9]*[a-z0-9])?$'"
}

As an additional test, https://regexr.com verifies the name “etcd_pool” does not match the required pattern:

No match when using the name “etcd_pool”

Nutanix Karbon 2.4 API Adjustments

To make adjustments for compatibility with Karbon 2.4, the “name” property must be changed to “etcd-pool” or any name not containing underscores. The complete updated etcd node pool configuration is as follows:

    "etcd_config": {
        "node_pools": [
            {
                "name": "etcd-pool",
                "node_os_version": "{{karbon_image_version}}",
                "num_instances": 1,
                "ahv_config": {
                    "cpu": 4,
                    "disk_mib": 40960,
                    "memory_mib": 8192,
                    "network_uuid": "{{subnet_uuid}}",
                    "prism_element_cluster_uuid": "{{cluster_uuid}}"
                }
            }
        ]
    },

Note the etcd pool name change from “etcd_pool” to “etcd-pool“.

Again using https://regexr.com, we can see the name “etcd_pool” matches the required pattern:

Match when using the name “etcd-pool”

Complete Kubernetes Cluster creation payloads

The examples payloads below are for demonstration purposes only and should be examined in detail before being used in a live environment.

Development Cluster

{
    "cni_config": {
        "node_cidr_mask_size": 24,
        "service_ipv4_cidr": "{{karbon_pod_ipv4_cidr}}",
        "pod_ipv4_cidr": "{{karbon_service_ipv4_cidr}}",
        "flannel_config": {}
    },
    "etcd_config": {
        "node_pools": [
            {
                "name": "etcd-pool",
                "node_os_version": "{{karbon_image_version}}",
                "num_instances": 1,
                "ahv_config": {
                    "cpu": 4,
                    "disk_mib": 40960,
                    "memory_mib": 8192,
                    "network_uuid": "{{subnet_uuid}}",
                    "prism_element_cluster_uuid": "{{cluster_uuid}}"
                }
            }
        ]
    },
    "masters_config": {
        "single_master_config": {},
        "node_pools": [
            {
                "name": "master-pool",
                "node_os_version": "{{karbon_image_version}}",
                "num_instances": 1,
                "ahv_config": {
                    "cpu": 2,
                    "disk_mib": 122880,
                    "memory_mib": 4096,
                    "network_uuid": "{{subnet_uuid}}",
                    "prism_element_cluster_uuid": "{{cluster_uuid}}"
                }
            }
        ]
    },
    "metadata": {
        "api_version": "v1.0.0"
    },
    "name": "{{karbon_dev_cluster_name}}",
    "storage_class_config": {
        "default_storage_class": true,
        "name": "default-storageclass",
        "volumes_config": {
            "username": "{{username}}",
            "password": "{{password}}",
            "storage_container": "{{container_name}}",
            "prism_element_cluster_uuid": "{{cluster_uuid}}",
            "file_system": "ext4",
            "flash_mode": false
        }
    },
    "version": "{{k8s_version}}",
    "workers_config": {
        "node_pools": [
            {
                "name": "worker-pool",
                "node_os_version": "{{karbon_image_version}}",
                "num_instances": 1,
                "ahv_config": {
                    "cpu": 8,
                    "disk_mib": 122880,
                    "memory_mib": 8192,
                    "network_uuid": "{{subnet_uuid}}",
                    "prism_element_cluster_uuid": "{{cluster_uuid}}"
                }
            }
        ]
    }
}

Multi Master Cluster

{
    "cni_config": {
        "flannel_config": {},
        "pod_ipv4_cidr": "{{karbon_pod_ipv4_cidr}}",
        "service_ipv4_cidr": "{{karbon_service_ipv4_cidr}}"
    },
    "etcd_config": {
        "node_pools": [
            {
                "name": "etcd-node-pool",
                "node_os_version": "{{karbon_image_version}}",
                "num_instances": 1,
                "ahv_config": {
                    "cpu": 2,
                    "disk_mib": 40960,
                    "memory_mib": 8192,
                    "network_name": "{{subnet_name}}",
                    "network_uuid": "{{subnet_uuid}}",
                    "prism_element_cluster_uuid": "{{cluster_uuid}}"
                }
            }
        ]
    },
    "masters_config": {
        "node_pools": [
            {
                "name": "master-node-pool",
                "node_os_version": "{{karbon_image_version}}",
                "num_instances": 2,
                "ahv_config": {
                    "cpu": 2,
                    "disk_mib": 122880,
                    "memory_mib": 8192,
                    "network_name": "{{subnet_name}}",
                    "network_uuid": "{{subnet_uuid}}",
                    "prism_element_cluster_uuid": "{{cluster_uuid}}"
                }
            }
        ],
        "active_passive_config": {
            "external_ipv4_address": "{{karbon_external_ipv4_address}}"
        }
    },
    "metadata": {
        "api_version": "v1.0.0"
    },
    "name": "{{karbon_multi_cluster_name}}",
    "storage_class_config": {
        "name": "default-storageclass",
        "default_storage_class" : true,
        "reclaim_policy": "Retain",
        "volumes_config": {
            "file_system": "ext4",
            "flash_mode": false,
            "password": "{{password}}",
            "username": "{{username}}",
            "storage_container": "{{container_name}}",
            "prism_element_cluster_uuid": "{{cluster_uuid}}"
        }
    },
    "version": "{{k8s_version}}",
    "workers_config" : {
        "node_pools": [
            {
                "name": "worker-node-pool",
                "node_os_version": "{{karbon_image_version}}",
                "num_instances": 3,
                "ahv_config": {
                    "cpu": 2,
                    "disk_mib": 122880,
                    "memory_mib": 8192,
                    "network_name": "{{subnet_name}}",
                    "network_uuid": "{{subnet_uuid}}",
                    "prism_element_cluster_uuid": "{{cluster_uuid}}"
                }
            }
        ]
    }
}

Wrapping Up

Hopefully this quick update will help you to use the Nutanix Karbon 2.4 APIs to deploy your Kubernetes clusters in a more automated fashion. Related content:

Thanks for reading and have a great day. 🙂