Kubernetes & Karbon APIs: 2022 Update

Nutanix.dev - Kubernetes and Karbon APIs 2022 Update

Table of Contents

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. 🙂

© 2024 Nutanix, Inc. All rights reserved. Nutanix, the Nutanix logo and all Nutanix product, feature and service names mentioned herein are registered trademarks or trademarks of Nutanix, Inc. in the United States and other countries. Other brand names mentioned herein are for identification purposes only and may be the trademarks of their respective holder(s). This post may contain links to external websites that are not part of Nutanix.com. Nutanix does not control these sites and disclaims all responsibility for the content or accuracy of any external site. Our decision to link to an external site should not be considered an endorsement of any content on such a site. Certain information contained in this post may relate to or be based on studies, publications, surveys and other data obtained from third-party sources and our own internal estimates and research. While we believe these third-party studies, publications, surveys and other data are reliable as of the date of this post, they have not independently verified, and we make no representation as to the adequacy, fairness, accuracy, or completeness of any information obtained from third-party sources.