Getting Started with MKS on Nutanix

This guide walks you through deploying and managing Kubernetes clusters on Nutanix infrastructure using Rafay's MKS (Managed Kubernetes Service) system templates.

What You'll Accomplish

By the end of this guide, you will have:

• ✅ Set up a project and shared the Nutanix system template
• ✅ Deployed a fully managed Kubernetes cluster on Nutanix
• ✅ Learned how to manage the cluster lifecycle

Why Use MKS System Templates?

System templates provide several key benefits:

• Faster Deployment: Pre-configured templates reduce setup time
• Consistency: Standardized configurations across environments
• Flexibility: Customizable while maintaining organizational standards
• Streamlined Workflows: Built-in approval processes and automation
• Team Collaboration: Enhanced efficiency in cluster management

Prerequisites

Before you begin, ensure you have:

Infrastructure Requirements

• Nutanix Infrastructure with VM provisioning permissions
• Nutanix Prism Element access with admin credentials
• Nutanix-compatible images for both Control Plane and Worker nodes

Rafay Platform Requirements

• Rafay Agent deployed in your Nutanix environment ( Setup Guide)
• Rafay API Key for authentication ( How to Generate)
• Organization Admin or Project Admin permissions

Outbound Network Access Requirements

To ensure successful provisioning of environments using the Nutanix template with OpenTofu, the following outbound network access must be allowed from the CD Agent:

• Nutanix Endpoints: Required to interact with Nutanix APIs for VM provisioning.
• OpenTofu Provider Registry: Required to download Terraform providers during provisioning.

The agent downloads provider plugins from the OpenTofu public registry. Typical provider sources include:

provider "registry.opentofu.org/hashicorp/external" {
  version = "2.3.5"
}

provider "registry.opentofu.org/hashicorp/local" {
  version = "2.5.3"
}

provider "registry.opentofu.org/nutanix/nutanix" {
  version     = "1.9.5"
  constraints = "~> 1.9.0"
}

Important

• If outbound access to these registries is blocked (e.g., by firewall restrictions), the CD Agent will not be able to pull required dependencies, resulting in provisioning failures
• The agent must be able to reach the Rafay Controller on port 443
• The agent machine must have general internet connectivity to resolve and download provider binaries

Information Needed

• Nutanix Endpoint IP and Port
• Nutanix Username and Password
• Nutanix Cluster Name
• Nutanix Subnet Name
• SSH Key Pair (for VM access)

What This Template Creates

The Nutanix system template automatically provisions:

Note: With this template, all nodes will have the same OS and configuration. We are working to enhance this further to allow configuring nodes with different resource configuration in the future.

Step-by-Step Guide

Step 1: Create Your Project

1. Navigate to Home → Your Projects
2. Click Create a New Project
3. Name it nutanix-project (or your preferred name)
4. Click Create

Step 2: Share the Nutanix Template

1. Go to Settings → Template Catalog
2. Find Rafay K8s Distro on Nutanix template
3. Click Get Started
4. Configure the template:
5. Template Name: Choose a unique name
6. Version: Enter 1.0 (or your preferred version)
7. Project: Select nutanix-project
8. Click Share

Step 3: Configure the Agent

1. You'll be redirected to your project
2. Select your Agent from the dropdown
3. Navigate back to General and save as Draft or Active Version

💡 Tip: Learn more about version management

Launching Your Cluster

Step 4: Start the Deployment

1. Navigate to Environments in your nutanix-project
2. Find your shared template and click Launch
3. Select your Agent (if not pre-configured)

Step 5: Configure Cluster Settings

General Configuration

Set up the core Kubernetes cluster parameters:

• Project Scope: Confirm project selection
• Cluster Name: Enter a unique name
• Kubernetes Version: Select your preferred version
• Blueprint: Choose cluster configuration blueprint
• Upgrade Strategy: Define update approach
• Control Plane Settings: Configure HA and dedicated settings

Network & Node Configuration

Configure networking and node specifications:

Network Settings:

• CNI Plugin: Select Container Network Interface
• Pod Subnet: Define pod IP range
• Service Subnet: Define service IP range
• Proxy Config: Optional proxy settings

Node Configuration:

• Control Plane VMs: Count and VM type
• Worker Node VMs: Count and VM type
• Image Names: Specify OS images
• Operating System: Choose OS type

📌 Single-Node Cluster: Set Worker VM Count to 0, Control Plane VM Count to 1, and disable both "Cluster Dedicated Control Plane" and "Cluster HA"

Nutanix Infrastructure Settings

Provide your Nutanix connection details:

• Endpoint: Nutanix Prism Element IP
• Port: Connection port
• Credentials: Username and password
• Cluster Name: Target Nutanix cluster
• Subnet Name: Network subnet for VMs

SSH Key Configuration (Choose One): - Option 1: Use packaged keys with Private/Public Key Paths - Option 2: Provide key content directly in "Other Configuration"

Security & Policy Settings (Optional)

Configure additional security features:

• Kata Deployment: Enable container runtime security
• OPA Gatekeeper: Enable policy enforcement
• Excluded Namespaces: Specify exemptions
• Policy Templates: Define constraint templates
• Policy Constraints: Apply specific constraints

Final Configuration

Complete the setup with authentication details:

• Controller Endpoint: Rafay controller URL
• API Key: Your Rafay authentication key
• SSH Keys: Private key content and authorized key

Step 6: Deploy and Monitor

1. Click Save & Deploy
2. Monitor the deployment progress
3. Wait for the cluster to reach "Ready" status

⏱️ Deployment Time: Typically takes 10-15 minutes depending on cluster size

Managing Your Cluster

Accessing Your Cluster

Once deployed, you can:

• Download kubeconfig from the cluster details
• Use kubectl to manage workloads
• Access through Rafay's console

Cluster Operations

Available management operations:

• Scale: Add/remove worker nodes
• Upgrade: Update Kubernetes versions
• Configure: Modify cluster settings
• Monitor: View cluster health and metrics

Cleanup

Deleting Your Cluster

⚠️ Warning: This action is irreversible and will delete all resources.

1. Navigate to your cluster environment
2. Click Destroy
3. Confirm by selecting Yes
4. Wait for complete resource cleanup

Troubleshooting

Common Issues

Getting Help

• Check deployment logs in the environment details
• Review Input Variables for configuration details
• Contact support if issues persist

Next Steps

Now that your cluster is running, consider:

1. Deploy Applications: Use Rafay's app management features
2. Set up Monitoring: Configure observability tools
3. Implement GitOps: Connect your repositories
4. Security Policies: Apply additional governance controls
5. Multi-Cluster: Replicate this setup for other environments

Summary

🎉 Congratulations! You have successfully:

• ✅ Created and shared a Nutanix system template
• ✅ Deployed a fully managed Kubernetes cluster on Nutanix
• ✅ Learned cluster lifecycle management basics

The MKS system templates provide a powerful way to standardize and automate Kubernetes deployments on Nutanix infrastructure while maintaining flexibility for your specific requirements.