在裸金属上安装 k3s - 分步操作指南及使用 Terraform

在家庭实验室集群上安装轻量级 k3s Kubernetes

目录

以下是逐步操作指南，介绍如何在裸金属服务器（1个主节点 + 2个工作节点）上**安装一个3节点K3s集群**。

本指南假设你从每个服务器上的最小 Linux安装 （例如，Ubuntu 22.04或Debian）开始，并希望自行托管控制平面和工作负载。

kubernetes裸金属集群

K3s 是 轻量级的Kubernetes发行版, 非常适合这个小型家庭实验室。

⚙️ 集群拓扑

节点名称 角色 主机名/IP
master-1 服务器（控制平面） 192.168.1.100
worker-1 代理（工作节点） 192.168.1.101
worker-2 代理（工作节点） 192.168.1.102

✅ 先决条件

🧱 硬件（最低要求）：

  • CPU: 2个核心
  • RAM: 每个节点2GB+
  • 磁盘: 每个节点20GB+

🛠 操作系统要求：

  • Linux（Ubuntu 22.04、Debian 12等）
  • 已安装curl、ssh和sudo
  • 具有root或sudo访问权限

🧼 清洁网络：

  • 确保所有节点可以通过IP或主机名解析并相互ping通。

  • 禁用交换：

    sudo swapoff -a
sudo sed -i '/ swap / s/^/#/' /etc/fstab

🚀 安装步骤

📍步骤1：在控制平面（master-1）上安装K3s

curl -sfL https://get.k3s.io | sh -

安装完成后：

sudo cat /var/lib/rancher/k3s/server/node-token
  • 这将为你提供工作节点所需的加入令牌。

确认集群正在运行：

sudo kubectl get nodes

k3s 包含一个安装为 k3s kubectl 或链接为 kubectl 的 kubectl。

📍步骤2：在工作节点（worker-1和worker-2）上安装K3s代理

在每个工作节点上重复以下操作：

将 <MASTER_IP> 和 <NODE_TOKEN> 替换为步骤1中的值。

curl -sfL https://get.k3s.io | K3S_URL=https://192.168.1.100:6443 K3S_TOKEN=<NODE_TOKEN> sh -

示例：

K3S_URL=https://192.168.1.100:6443 \
K3S_TOKEN=K10abcde123456789::server:abcde123456789 \
sh -c "$(curl -sfL https://get.k3s.io)"

📍步骤3：从master-1验证集群

kubectl get nodes

你应该看到：

NAME        STATUS   ROLES    AGE   VERSION
master-1    Ready    control  5m    v1.29.2+k3s1
worker-1    Ready    <none>   2m    v1.29.2+k3s1
worker-2    Ready    <none>   2m    v1.29.2+k3s1

🔐（可选）启用高可用性（HA）

对于类似生产环境的高可用性（家庭实验室中可选）：

  • 使用外部数据库（例如MySQL/PostgreSQL/etcd）。
  • 使用--server标志和共享数据库运行多个服务器节点。
  • 请参阅：K3s HA文档

🧪 测试部署

kubectl create deployment nginx --image=nginx
kubectl expose deployment nginx --port=80 --type=LoadBalancer
kubectl get svc

通过 curl http://<worker-ip>:<port> 或设置MetalLB以获取外部LoadBalancer IP来检查访问。

🧰 有用的提示

  • Kubeconfig: /etc/rancher/k3s/k3s.yaml

    • 复制到本地机器并使用 export KUBECONFIG=... 远程管理。

  • Systemd服务：

    • sudo systemctl status k3s
    • sudo systemctl status k3s-agent（在工作节点上）

💡 附加功能（可选）

  • K9s：用于管理Kubernetes的终端UI：brew install k9s 或 sudo snap install k9s

  • Dashboard：通过清单启用：

    kubectl apply -f https://raw.githubusercontent.com/kubernetes/dashboard/v2.7.0/aio/deploy/recommended.yaml

  • MetalLB：为裸金属添加负载均衡支持：

    kubectl apply -f https://raw.githubusercontent.com/metallb/metallb/v0.13.10/config/manifests/metallb-native.yaml

📦 清理

要删除k3s：

# 在主节点上：
/usr/local/bin/k3s-uninstall.sh

# 在工作节点上：
/usr/local/bin/k3s-agent-uninstall.sh

使用Terraform安装3节点裸金属K3s集群

这是一个**Terraform模板**，它可以帮助你部署一个3节点裸金属K3s集群，假设你正在通过SSH和Ansible管理**已部署的Linux服务器（例如，在你的局域网/家庭实验室中）。Terraform将调用Ansible playbook**来安装K3s。

🧱 假设条件

  • 你已经拥有：

    • 3台具有固定IP的服务器，可通过SSH访问。
    • SSH访问（基于密钥）。
    • 本地已安装Terraform和Ansible。

  • 目标操作系统：Ubuntu/Debian（可自定义）。

  • 你正在使用 Terraform local-exec 或 Ansible provisioner插件（我们将使用 local-exec 以提高可移植性）。

📁 目录结构

k3s-cluster/
├── main.tf
├── inventory.ini
├── ansible/
│   └── install_k3s.yml
└── variables.tf

📄 variables.tf

variable "master_ip" {
  default = "192.168.1.100"
}

variable "worker_ips" {
  default = ["192.168.1.101", "192.168.1.102"]
}

variable "ssh_user" {
  default = "your_user"
}

variable "ssh_private_key" {
  default = "~/.ssh/id_rsa"
}

📄 main.tf

provider "null" {}

resource "null_resource" "install_k3s" {
  provisioner "local-exec" {
    command = "ANSIBLE_HOST_KEY_CHECKING=False ansible-playbook -i inventory.ini ansible/install_k3s.yml --private-key ${var.ssh_private_key} -u ${var.ssh_user}"
  }

  triggers = {
    always_run = "${timestamp()}"
  }
}

📄 inventory.ini

[masters]
192.168.1.100

[workers]
192.168.1.101
192.168.1.102

[all:vars]
ansible_python_interpreter=/usr/bin/python3

📄 ansible/install_k3s.yml

---
- hosts: masters
  become: yes
  tasks:
    - name: 安装k3s主节点
      shell: |
        curl -sfL https://get.k3s.io | sh -        
    - name: 获取node-token
      shell: cat /var/lib/rancher/k3s/server/node-token
      register: node_token
      delegate_to: localhost

- hosts: workers
  become: yes
  tasks:
    - name: 将工作节点加入集群
      shell: |
        curl -sfL https://get.k3s.io | K3S_URL=https://{{ hostvars['192.168.1.100']['ansible_host'] }}:6443 K3S_TOKEN={{ hostvars['192.168.1.100']['node_token']['stdout'] }} sh -

注意：你可能需要根据Ansible版本调整IP或令牌变量访问。你也可以在主节点上生成令牌并保存到文件中，然后再运行工作节点安装。

🚀 如何运行

从 k3s-cluster/ 目录中：

terraform init
terraform apply

🧰 增强功能（可选）

  • 使用动态库存生成（例如，来自DHCP/dnsmasq）。
  • 通过Ansible添加MetalLB部署。
  • 添加主机名和HA功能。
  • 使用 Ansible角色 如 xanmanning.k3s 以获得更大的灵活性。

有用的链接