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:

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. 设置环境变量

# 必须
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. 执行安装

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

# 安装完成后自动保存到 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) 自动执行:

端口改为 2103
禁用密码登录
启用密钥认证
自动添加本地公钥

常用命令

# 测试连接
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

故障排查

# K3s 状态
systemctl status k3s
journalctl -u k3s -f

# Tailscale 状态
tailscale status

# 获取 Token
cat /var/lib/rancher/k3s/server/node-token