# 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](https://docs.rafay.co/integrations/repositories/agents/))
- **Rafay API Key** for authentication ( [How to Generate](https://docs.rafay.co/security/rbac/users/#manage-keys))
- 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](https://registry.opentofu.org/). 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:

| Component | Description |
| --- | --- |
| **Nutanix VMs** | Configured as Kubernetes nodes with your specifications |
| **MKS Cluster** | Fully managed Kubernetes running Rafay distribution |
| **Networking** | CNI (Calico), CSI, and cluster add-ons from Blueprint |
| **Access** | Kubeconfig file for secure cluster access |

> **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](https://docs.rafay.co/env_manager/templates/environment_templates/#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

| Issue | Solution |
| --- | --- |
| Agent not connecting | Verify network connectivity and credentials |
| VM provisioning fails | Check Nutanix resource availability and permissions |
| Cluster deployment stuck | Review logs in the deployment section |
| SSH access denied | Verify SSH key configuration and format |

### Getting Help

- Check deployment logs in the environment details
- Review [Input Variables](https://docs.rafay.co/template_catalog/nutanix/overview/) 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.