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:
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:
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:
- Getting started with GPU on Nutanix Karbon
- Karbon and Metrics API: A simple approach with metrics-server
- Karbon and Metrics API: A practical guide
- Original article: Automating Karbon Deployments via API
Thanks for reading and have a great day. 🙂