> For the complete documentation index, see [llms.txt](https://asus-isg-aidc.gitbook.io/guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://asus-isg-aidc.gitbook.io/guide/latest/portal/overview/service-catalog/k8s.md).

# Native K8s Cluster

| Developer | Last modified |
| --------- | ------------- |
| AIDC Team | 2026/08/21    |

## Service Introduction

**Native K8s Cluster** is a native Kubernetes cluster deployment solution that provides container orchestration, auto-scaling, and service discovery capabilities.

![](https://pub-f334ff01208c4e6195b80133ac6e6030.r2.dev/portal/marketplace/service-catalog-k8s.png)

### Quick Summary

| Item                          | Details                                            |
| ----------------------------- | -------------------------------------------------- |
| ⏱️ **Estimated Time**         | 15-45 minutes (depends on node count)              |
| 💻 **Supported Platforms**    | See the **Supported Platforms Matrix**             |
| 🔧 **Minimum Nodes Required** | 2 nodes (Control Plane × 1, Worker × 1)            |
| 📦 **Included Components**    | kubeadm, kubelet, kubectl, containerd, CNI plugins |

***

## Prerequisites

Before starting the deployment, ensure the following requirements are met:

### Hardware Requirements

| Role              | Minimum Spec                 | Recommended Spec                  |
| ----------------- | ---------------------------- | --------------------------------- |
| **Control Plane** | 2 vCPU / 4GB RAM / 50GB Disk | 4 vCPU / 8GB RAM / 100GB Disk     |
| **Worker Node**   | 2 vCPU / 4GB RAM / 50GB Disk | 4+ vCPU / 16GB+ RAM / 100GB+ Disk |

### Network Requirements

* ✅ All nodes must be in the **same network segment** or have routing enabled
* ✅ Pod network CIDR must not overlap with node network

### Other Requirements

* ✅ Nodes have been provisioned and are in **Ready** state
* ✅ Swap disabled on all nodes
* ✅ Time synchronization (NTP/Chrony) enabled

***

## Deployment Dialog Introduction

Native K8s Cluster deployment is divided into **3 steps**:

```mermaid
flowchart LR
    Step1["Step 1: Control Plane Configuration"]
    Step2["Step 2: Network Configuration"]
    Review["Step 3: Review and Deploy"]

    Step1 --> Step2
    Step2 --> Review
```

[Step 1: Control Plane](#step-1-control-plane-configuration) | [Step 2: Network Configuration](#step-2-worker-node-and-network-configuration) | [Step 3: Review and Deploy](#step-3-review-and-deploy)

***

### Step 1: Control Plane Configuration

![](https://pub-f334ff01208c4e6195b80133ac6e6030.r2.dev/portal/marketplace/service-catalog-k8s-step1.png)

| Parameter Name        | Type   | Description                   |   Required  | Validation Rules                        | Example      |
| --------------------- | ------ | ----------------------------- | :---------: | --------------------------------------- | ------------ |
| **K8s Control Group** | select | Group for Control Plane nodes | 🔴 Required | **Cannot be same as K8s Data Group**    | `k8s-master` |
| **K8s Data Group**    | select | Group for Worker nodes        | 🔴 Required | **Cannot be same as K8s Control Group** | `k8s-worker` |

{% hint style="warning" %}
**⚠️ Critical Constraint**

Control Plane and Worker nodes **must be in different Groups** to ensure proper cluster architecture and high availability.
{% endhint %}

***

### Step 2: Worker Node and Network Configuration

![](https://pub-f334ff01208c4e6195b80133ac6e6030.r2.dev/portal/marketplace/service-catalog-k8s-step2.png)

| Parameter Name | Type   | Description                   |   Required  | Validation Rules                           | Example       |
| -------------- | ------ | ----------------------------- | :---------: | ------------------------------------------ | ------------- |
| **Gateway IP** | string | Cluster gateway IP address    | 🔴 Required | **Valid IPv4 format**                      | `192.168.1.1` |
| **Interface**  | string | Network interface device name | 🔴 Required | **Alphanumeric only; must exist on nodes** | `eth0`        |

{% hint style="info" %}
**💡 How to find Interface name**

Run `ip link show` or `ip addr` on the target node to list available interfaces.
{% endhint %}

***

## Post-Deployment Status

After successful deployment, you can view in **Status Monitor**:

* Task status progress
* Execution status of each node
* Error logs (if any)

### Deployment Verification

After the deployment status shows **Completed**, perform the following checks:

**1. Obtain kubeconfig**

```bash
# On Control Plane node
cat /etc/kubernetes/admin.conf
```

**2. Check Node Status**

```bash
kubectl get nodes
```

✅ **Expected Result:** All nodes should show `Ready` status

```
NAME           STATUS   ROLES           AGE   VERSION
k8s-master-1   Ready    control-plane   10m   v1.29.0
k8s-worker-1   Ready    <none>          8m    v1.29.0
k8s-worker-2   Ready    <none>          8m    v1.29.0
```

**3. Check System Pods**

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

✅ **Expected Result:** All pods in `kube-system` namespace should be `Running`

***

## Frequently Asked Questions

### Q: How do I find the correct Interface name?

A: Run `ip link show` or `ip addr` on the target node to list all network interfaces.

### Q: How long does deployment take?

A: Depends on the number of nodes, typically 15-45 minutes.

### Q: How to add more worker nodes after deployment?

A: Generate a new join token on Control Plane using `kubeadm token create --print-join-command` and run the output on new nodes.

### Q: What if a node shows NotReady status?

A: Check kubelet logs with `journalctl -xeu kubelet` and verify network plugin is running.

***

## Related References

* [Service Catalog](/guide/latest/portal/overview/service-catalog.md)
* [Status Monitor User Guide](/guide/latest/portal/overview/status-monitor.md#k8s-status-card)
* [Kubernetes Official Documentation](https://kubernetes.io/docs/)