> For the complete documentation index, see [llms.txt](https://docs.cloud.olakrutrim.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cloud.olakrutrim.com/basics/core-infrastructure/krutrim-kubernetes-system/creating-cluster.md).

# Creating Cluster

This guide walks you through creating a Kubernetes cluster using the Krutrim Kubernetes Service.

### Before You Begin

Ensure you have:

* [ ] A VPC created in your Krutrim Cloud account
* [ ] At least one subnet configured in your VPC
* [ ] Understanding of your [network configuration requirements](https://docs.cloud.olakrutrim.com/basics/core-infrastructure/krutrim-kubernetes-system/network-configuration)
* [ ] Decided on your cluster's purpose (development, staging, production)

### Cluster Configuration

When creating a cluster, you'll need to configure the following settings:

**Basic Settings:**

* Cluster Name: Choose a descriptive name for your cluster.
* Kubernetes Version:
  * Select the Kubernetes version for your cluster:
    * **Recommended**: Use the default version of Krutrim Kubernetes Service
    * **Specific Version**: Choose if you have application compatibility requirements

{% hint style="info" %}
**Note**: You can upgrade the Kubernetes version later, but you cannot downgrade.
{% endhint %}

**Network Configurations**

* VPC Configuration: 
  * Select the VPC you want your cluster to be in
  * This defines the network boundary for your cluster
* Subnet Configuration: 
  * Specify the subnet where your cluster resources will be deployed
  * Ensure the subnet has sufficient IP addresses
  * **Important**: This subnet is used for LoadBalancer IP allocation

**LoadBalancer IP Usage**:

```
Every time you create a LoadBalancer Service:
├─ One IP address is allocated from this subnet
├─ The IP is taken from your subnet's available pool
└─ Plan accordingly for your expected LoadBalancer count
```

### Kubernetes Network Configuration

**Pod CIDR**

* Default: `192.168.0.0/16`
* Understanding Pod CIDR:
  * This CIDR is the IP range for pods in your cluster
  * Each node receives a /24 subnet (256 IPs) from this CIDR range
  * Capacity: `/16` = 256 nodes max, `/18` = 64 nodes max, `/20` = 16 nodes max
* Pod CIDR cannot be changed after cluster creation. Plan for future growth!

Examples:

```yaml
# Small cluster (up to 16 nodes)
Pod CIDR: 192.168.0.0/20

# Medium cluster (up to 64 nodes)
Pod CIDR: 192.168.0.0/18

# Large cluster (up to 256 nodes)
Pod CIDR: 192.168.0.0/16
```

**Calculation:**

```
Pod CIDR: 192.168.0.0/16
├─ Total IPs: 65,536
├─ Per-node allocation: /24 (256 IPs)
├─ Maximum nodes: 256
└─ Maximum pods per node: ~250 (after system overhead)
```

{% hint style="warning" %}
**Reserved Range**: Cannot use `172.24.0.0/13` (reserved for system use)
{% endhint %}

**Service CIDR**

* Default: `10.100.0.0/16`
* Understanding Service CIDR:
  * This CIDR is the IP range for Kubernetes Services (ClusterIP, NodePort, LoadBalancer)
  * Each Service consumes one IP from this range
* Service CIDR must not overlap with Pod CIDR

Examples:

```yaml
# Standard configuration (65,536 service IPs)
Service CIDR: 10.100.0.0/16

# Smaller deployments (4,096 service IPs)
Service CIDR: 10.100.0.0/20
```

{% hint style="warning" %}
**Reserved Range**: Cannot use `172.24.0.0/13` (reserved for system use)
{% endhint %}

### Network Configuration Examples

**Development/Testing Cluster**:

```yaml
Cluster Name: dev-k8s-cluster
VPC: Select your dev VPC
Subnet: Select subnet with at least 100 available IPs
Pod CIDR: 192.168.0.0/20  # Supports up to 16 nodes
Service CIDR: 10.100.0.0/20  # Supports 4,096 services
```

**Production Cluster**:

```yaml
Cluster Name: prod-web-cluster
VPC: Select your production VPC
Subnet: Select subnet with at least 200 available IPs
Pod CIDR: 192.168.0.0/16  # Supports up to 256 nodes
Service CIDR: 10.100.0.0/16  # Supports 65,536 services
```

## Cluster Creation Process

After submitting your cluster configuration:

### Verification Checklist

Before creating the cluster, verify:

* [ ] Cluster name follows naming conventions
* [ ] Kubernetes version is appropriate
* [ ] VPC and subnet are correctly specified
* [ ] Pod CIDR matches your scale requirements
* [ ] Service CIDR doesn't overlap with Pod CIDR or Node Subnet
* [ ] Network capacity is sufficient

**Network Capacity Planning**:

```
Question: How many nodes do I plan to run?
Answer: ____ nodes

Required Pod CIDR:
- Up to 16 nodes → /20 or larger
- Up to 64 nodes → /18 or larger
- Up to 256 nodes → /16 or larger
```

### Cluster Creation Stages

{% stepper %}
{% step %}

### Creating

Initial resources are being provisioned.

* Timeline (part of total): Initial setup — 1-2 minutes
  {% endstep %}

{% step %}

### Provisioning

Control plane, network, and integrations are being configured.

* Timeline (part of total): Control plane provisioning — 2-3 minutes; Network configuration — 1-2 minutes
  {% endstep %}

{% step %}

### Provisioned

Cluster is ready. Wait until status shows `PROVISIONED` before creating node groups.
{% endstep %}
{% endstepper %}

**Overall Timeline**:

* Total time: Approximately 5-8 minutes

**What's Happening**:

{% stepper %}
{% step %}
Control plane is being created
{% endstep %}

{% step %}
Network resources are being configured
{% endstep %}

{% step %}
OpenStack integration is being set up
{% endstep %}

{% step %}
Core infrastructure components are being installed
{% endstep %}
{% endstepper %}

**Monitoring Status**:

* Cluster status transitions: `CREATING` → `PROVISIONING` → `PROVISIONED`
* Monitor the cluster status to track progress

⚠️ **Important**: Do not create node groups until the cluster status is `PROVISIONED`

## Next Steps After Cluster Creation

### Create Initial Node Groups

Once your cluster is provisioned, you need to create node groups to run your workloads.

**Critical First Step**: Create at least 1-2 nodes **without taints** to ensure system components can be scheduled.

**Why This Matters**:

```
Essential add-ons that need to be scheduled:
├─ CoreDNS (DNS resolution for the cluster)
└─ Cilium (CNI for pod networking)

If all nodes have taints:
├─ These add-ons cannot be scheduled
├─ Cluster remains in non-functional state
└─ Pods cannot start or communicate
```

**Recommended Approach**:

{% stepper %}
{% step %}

### Create Initial Node Group (without taints)

Example configuration:

```yaml
Name: general-nodes
Instance Type: 4vcpu-8gb or larger
Min Size: 1
Max Size: 3
Desired Size: 2
Taints: None
Labels:
  workload-type: general
```

{% endstep %}

{% step %}

### Create Additional Node Groups (with or without taints)

Example configuration:

```yaml
Name: workload-nodes
Instance Type: 4vcpu-8gb or larger
Min Size: 2
Max Size: 10
Desired Size: 3
Taints: Optional (based on workload requirements)
Labels:
  workload-type: application
```

{% endstep %}
{% endstepper %}

See [Managing Node Groups](https://docs.cloud.olakrutrim.com/basics/core-infrastructure/krutrim-kubernetes-system/managing-nodegroups) for detailed instructions.

### Install Add-ons

After creating node groups, install necessary add-ons for your cluster.

#### Essential Add-ons

**CoreDNS**:

* Provides DNS service for the cluster
* Required for service discovery
* Must be installed manually
* You can choose to install your own cluster DNS service also

### CNI (Container Network Interface) - REQUIRED

You must install a CNI for pod networking:

**Option 1: Cilium (Recommended)**:

* Optimized for Krutrim Cloud
* eBPF-based networking
* High performance and security
* **Important**: Do NOT install kube-proxy if using Cilium

**Option 2: Your Own CNI**:

* You can install kube-proxy
* Then install your preferred CNI solution
* Note: Our Cilium add-on may not work with kube-proxy

**CNI Installation Priority**:

```
1. Install Cilium (Krutrim optimized) - WITHOUT kube-proxy
   OR
2. Install kube-proxy first, then your own CNI solution
```

See [Installing Add-ons](broken://pages/1279ed917fcd47b1b408ede27aea9c58a949e7ed) for detailed instructions.

### Access Your Cluster

Once all components are installed, you can access your cluster using the kubeconfig file.

**Obtain Kubeconfig**:

* Retrieve the kubeconfig file for your cluster
* Save the file securely (this contains cluster access credentials)

**Verify Cluster Access**:

```bash
export KUBECONFIG=/path/to/downloaded-kubeconfig
kubectl cluster-info
```

**Check Node Status**:

```bash
kubectl get nodes
```

Expected output:

```
NAME                STATUS   ROLES    AGE   VERSION
node-1              Ready    <none>   5m    v1.31.0
node-2              Ready    <none>   5m    v1.31.0
node-3              Ready    <none>   3m    v1.31.0
```

**Verify System Pods**:

```bash
kubectl get pods -A
```

All pods should be in `Running` state:

```
NAMESPACE     NAME                        READY   STATUS    RESTARTS   AGE
kube-system   coredns-xxx                 1/1     Running   0          10m
kube-system   cilium-xxx                  1/1     Running   0          8m
kube-system   konnectivity-agent-xxx      1/1     Running   0          10m
```

## Common Issues During Creation

<details>

<summary>Issue: Cluster Stuck in CREATING</summary>

**Possible Causes**:

* VPC or subnet validation issues
* Network connectivity problems
* Resource quota limits

**Solution**:

1. Check if VPC and subnet are accessible
2. Verify your account has sufficient quota
3. Contact support if issue persists

</details>

<details>

<summary>Issue: Node Groups Not Creating</summary>

**Possible Causes**:

* Cluster not yet in PROVISIONED state
* Insufficient subnet IPs
* Invalid node configuration
* Resource issue within Krutrim Cloud

**Solution**:

1. Wait for cluster to reach PROVISIONED state
2. Verify subnet has available IPs
3. Check node group configuration
4. Contact support if issue persists

</details>

<details>

<summary>Issue: Pods Not Starting</summary>

**Possible Causes**:

* CNI not installed
* All nodes have taints
* No nodes without taints available

**Solution**:

1. Install Cilium or your CNI
2. Ensure at least 1-2 nodes without taints exist
3. Verify node status with `kubectl get nodes`

</details>

## Best Practices for Cluster Creation

### ✅ Do's

1. Plan Network Ranges:
   * Calculate required nodes before choosing Pod CIDR
   * Use default CIDRs unless you have specific requirements
   * Ensure no overlap between Pod and Service CIDRs
2. Create Untainted Nodes First:
   * Always create 1-2 nodes without taints
   * Use appropriate sizing (minimum 2vcpu-4gb)
   * Wait for nodes to be ready before deploying workloads
3. Install CNI Immediately:
   * Install Cilium or your CNI right after node creation
   * Verify all nodes reach Ready state
   * Check that all system pods are running
4. Use Descriptive Names:
   * Include environment in name (dev, staging, prod)
   * Include purpose (web, api, data)
   * Use consistent naming conventions
5. Plan for Growth:
   * Choose Pod CIDR with room for expansion
   * Ensure subnet has sufficient IPs for future LoadBalancers
   * Consider future node group additions

### ❌ Don'ts

1. Don't Use Small Pod CIDRs:
   * Avoid /24 or /22 for production
   * Don't underestimate growth
2. Don't Forget Untainted Nodes:
   * Never create only tainted nodes
   * Don't skip CoreDNS verification
3. Don't Mix CNI Strategies:
   * Don't install both Cilium and kube-proxy
   * Choose one networking approach
4. Don't Use Reserved Ranges:
   * Avoid 172.24.0.0/13 for Pod or Service CIDR
   * Check for conflicts with existing infrastructure

## Next Steps

After successfully creating your cluster:

1. [Configure Storage](https://docs.cloud.olakrutrim.com/basics/core-infrastructure/krutrim-kubernetes-system/storage-configuration) - Set up persistent storage for your applications
2. [Create Load Balancers](https://docs.cloud.olakrutrim.com/basics/core-infrastructure/krutrim-kubernetes-system/load-balancers) - Expose your services to the internet
3. [Learn Best Practices](broken://pages/43ad3c021a5a7766c22bac0cd782498f73bac782) - Optimize your cluster for production use

## Additional Resources

* [Troubleshooting Guide](broken://pages/46eccee5c14742b6ef6fa7e118ae1e6bb7703515) - Common issues and solutions
* [Network Configuration](https://docs.cloud.olakrutrim.com/basics/core-infrastructure/krutrim-kubernetes-system/network-configuration) - Detailed network planning
* [Managing Node Groups](https://docs.cloud.olakrutrim.com/basics/core-infrastructure/krutrim-kubernetes-system/managing-nodegroups) - Node group configuration
* [Installing Add-ons](https://docs.cloud.olakrutrim.com/basics/core-infrastructure/krutrim-kubernetes-system/installing-addons) - Essential cluster add-ons


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.cloud.olakrutrim.com/basics/core-infrastructure/krutrim-kubernetes-system/creating-cluster.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.