feat(ansible): add K3s installation playbooks and configuration templates

2026-02-09 14:03:42 +08:00
@@ -0,0 +1,166 @@
+# K3s Ansible 自动化安装
+
+一键部署 K3s 集群，支持国内镜像加速、Tailscale 组网、SSH 安全加固。
+
+## 目录结构
+
+```
+ansible/
+├── ansible.cfg                 # Ansible 配置
+├── inventory/hosts.yml         # 主机清单 ⭐ 需修改
+├── group_vars/all.yml          # 全局变量
+├── .env.example                # 环境变量模板
+├── roles/
+│   ├── ssh/                    # SSH 安全加固
+│   │   ├── tasks/main.yml
+│   │   └── templates/sshd_config.j2
+│   ├── common/                 # 基础配置 (hostname, sysctl, tailscale)
+│   │   ├── tasks/main.yml
+│   │   └── handlers/main.yml
+│   └── k3s/                    # K3s 安装
+│       ├── tasks/main.yml
+│       └── templates/
+│           ├── k3s-server.yaml.j2   # Server 配置 (统一 init/join)
+│           ├── k3s-agent.yaml.j2    # Agent 配置
+│           └── registries.yaml.j2   # 镜像加速
+└── playbooks/
+    ├── site.yml                # 完整安装
+    ├── init.yml                # 首次安装 (含 SSH 加固)
+    └── add-node.yml            # 添加节点
+```
+
+## 快速开始
+
+### 1. 配置主机清单
+
+编辑 `inventory/hosts.yml`:
+
+```yaml
+masters:
+  hosts:
+    master1:
+      ansible_host: 10.0.0.1
+      node_hostname: master1
+      cluster_init: true        # 首个节点设为 true
+      node_region: cn-sh        # 区域标签
+      use_mirror: true          # 使用镜像加速
+      enable_lb: true           # 启用 LB
+      netfilter_mode: ""        # 阿里云/华为云设为 nodivert
+```
+
+### 2. 设置环境变量
+
+```bash
+# 必须
+export TAILSCALE_AUTH_KEY="tskey-auth-xxx"
+
+# 首次安装 (SSH 加固)
+export SSH_PASSWORD="your-root-password"
+
+# 添加节点时 (从首节点安装输出获取)
+export K3S_TOKEN="K10xxx::server:xxx"
+export K3S_SERVER_URL="https://10.0.0.1:6443"
+```
+
+### 3. 执行安装
+
+```bash
+cd k3s/ansible
+
+# 方式一: 首次安装 (含 SSH 加固，端口改为 2103，启用密钥认证)
+ansible-playbook playbooks/site.yml --tags ssh,common,k3s,status
+
+# 方式二: 常规安装 (已配置 SSH 密钥)
+ansible-playbook playbooks/site.yml
+
+# 方式三: 仅安装首个 master
+ansible-playbook playbooks/site.yml -l master1
+
+# 方式四: 添加新节点
+ansible-playbook playbooks/add-node.yml -l agent1
+```
+
+### 4. 获取 kubeconfig
+
+```bash
+# 安装完成后自动保存到 ansible/kubeconfig.yaml
+sed -i '' 's/127.0.0.1/k3s.yourdomain.com/g' kubeconfig.yaml
+export KUBECONFIG=$(pwd)/kubeconfig.yaml
+kubectl get nodes
+```
+
+## 节点变量
+
+| 变量 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `ansible_host` | string | - | 节点 IP |
+| `node_hostname` | string | - | 主机名 |
+| `cluster_init` | bool | false | 首个 master 设为 true |
+| `node_region` | string | - | 区域标签 (cn-sh/hk/us-west) |
+| `use_mirror` | bool | false | 使用镜像加速 |
+| `enable_lb` | bool | - | 启用 K3s LB |
+| `netfilter_mode` | string | "" | Tailscale netfilter: off/nodivert/on |
+| `node_labels` | dict | - | 自定义标签 |
+| `kubelet_reserved` | string | - | 资源预留: cpu=500m,memory=512Mi |
+
+## 环境变量
+
+| 变量 | 必须 | 说明 |
+|------|------|------|
+| `TAILSCALE_AUTH_KEY` | ✅ | Tailscale Auth Key |
+| `K3S_TOKEN` | 加入节点时 | 集群 Token |
+| `K3S_SERVER_URL` | 加入节点时 | API Server 地址 |
+| `SSH_PASSWORD` | 首次安装 | SSH 密码 |
+| `SSH_PUBKEY` | - | SSH 公钥 (默认 ~/.ssh/id_rsa.pub) |
+
+## 镜像加速
+
+当 `use_mirror: true` 时自动启用:
+
+- K3s 安装脚本: `rancher-mirror.rancher.cn`
+- 常规容器镜像加速
+
+## SSH 安全加固
+
+首次安装时 (`--tags ssh`) 自动执行:
+
+1. 端口改为 2103
+2. 禁用密码登录
+3. 启用密钥认证
+4. 自动添加本地公钥
+
+## 常用命令
+
+```bash
+# 测试连接
+ansible all -m ping
+
+# 仅运行特定阶段
+ansible-playbook playbooks/site.yml --tags common
+ansible-playbook playbooks/site.yml --tags k3s
+
+# 指定节点
+ansible-playbook playbooks/site.yml -l master1,agent1
+
+# 调试模式
+ansible-playbook playbooks/site.yml -vvv
+
+# 检查语法
+ansible-playbook playbooks/site.yml --syntax-check
+```
+
+## 故障排查
+
+```bash
+# K3s 状态
+systemctl status k3s
+journalctl -u k3s -f
+
+# Tailscale 状态
+tailscale status
+
+# 获取 Token
+cat /var/lib/rancher/k3s/server/node-token
+```
+
+