# K3s Ansible 自动化安装

一键部署 K3s 集群，支持国内镜像加速、Tailscale 组网、SSH 安全加固。

## 目录结构

```
ansible/
├── ansible.cfg                 # Ansible 配置
├── inventory/
│   ├── hosts.yml               # 主机清单 ⭐ 需修改
│   └── group_vars/all.yml      # 全局变量
├── roles/
│   ├── ssh/                    # SSH 安全加固
│   │   ├── tasks/main.yml
│   │   ├── handlers/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                # 完整安装
```

## 快速开始

### 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"
```

### 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 first-master-name

# 方式四: 添加新节点
ansible-playbook playbooks/site.yml -l new-node-name
```

### 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 | - | 自定义标签 |
| `node_taints` | list | - | 节点污点 (格式: key=value:effect) |

## 环境变量

| 变量 | 必须 | 说明 |
|------|------|------|
| `TAILSCALE_AUTH_KEY` | ✅ | Tailscale Auth Key |
| `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. 自动添加本地公钥

## 集群安装流程

Playbook 按以下顺序执行:

1. **初始化节点安装**: 安装 `cluster_init: true` 的第一个 master 节点
2. **动态获取 Token**: 从初始化节点读取 `/var/lib/rancher/k3s/server/node-token`
3. **Token 注入**: 将 K3S_TOKEN 和 K3S_SERVER_URL 设置为所有节点的 fact
4. **其他 Master 节点**: 使用动态获取的 Token 加入集群
5. **Agent 节点**: 使用动态获取的 Token 加入集群

这样在一次性安装整个集群时，无需手动设置 `K3S_TOKEN` 环境变量。

## 常用命令

```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
```

## 升级已有集群

加载 `ansible/.env` 后运行：

```bash
source .env
ansible-playbook playbooks/site.yml --tags control-plane-relay,k3s,status
```

master 逐台升级，worker 保持并行（默认 20 forks）。已有 server 在安装前保存不压缩的 etcd 快照和恢复用 token；每台 server 等待本地 `/readyz`（包含 etcd 检查），所有节点等待目标版本和 Ready，失败则停止后续阶段。只有通过共享 master 执行的就绪检查限制为 5 并发，以避免 SSH 会话耗尽。快照位于 server 的 snapshots 目录，token 单独保存在 server 目录，权限 0600；恢复仍需另行演练。

选择性中继名单见 `inventory/group_vars/all.yml` 的 `tailscale_control_plane_relay_peers`，说明见 `README_MANUAL.md`。

在安装 Ansible 的 Python 环境运行就绪检查回归：`python -m unittest discover -s tests -v`。

### 2026-10-16 执行记录

16 个节点已升级至 `v1.35.9+k3s1`，3 个 server 逐台执行，13 个 worker 并行执行。升级前的不压缩快照以 `pre-upgrade-v1.35.9+k3s1-<node>-<timestamp>` 保存在 snapshots 目录，恢复用 token 为 server 目录下的 `pre-upgrade-v1.35.9+k3s1.token`。

homea 的 Velero 镜像拉取曾停滞：确认两个现有镜像源能下载、磁盘充足且没有进程代理后，通过 `ansible homea -m ansible.builtin.systemd -a 'name=k3s-agent state=restarted' -e ansible_port=2103` 释放旧下载请求，DaemonSet 随后完成更新。Velero 的 Helm 等待因此超时，通过相同时间戳的 `reconcile.fluxcd.io/requestedAt` 和 `reconcile.fluxcd.io/resetAt` 注解重新协调成功。

Grafana 的大镜像层再次在该节点的 1ms 链路停滞，分段下载验证 Daocloud 可用后，通过 homea 的 `registry_mirror_overrides` 调整 Docker 镜像优先级；其他 registry 继承全局配置。镜像配置单独变化时，role 会重启对应 K3s 服务并等待 Ready；版本升级时由安装流程加载新配置。调整后 Grafana 镜像约 27 秒拉取完成；Prometheus 栈因旧下载触发的部署超时也通过上述注解重新协调成功。

CloudNativePG/Barman 升级重建了两套单实例 PostgreSQL Pod，恢复后均为 2/2 Ready；PostgreSQL 数据镜像保持 17.4。各执行一次 `SELECT pg_switch_wal();` 验证新插件，两个实例的归档计数均增长，归档失败计数未增加。未进行数据恢复演练。