Ansible角色：k3s（v3.x）

用于安装K3S（“轻量级Kubernetes”）的Ansible角色，可以作为独立服务器或集群使用。

寻求帮助！

你好！ :wave: @xanmanning 正在寻找新的维护者来维护这个Ansible角色。因为我没有那么多闲暇时间了，也不再定期在工作中使用Ansible。如果你有兴趣，请联系我。

发布说明

请参见发布记录和CHANGELOG.md。

要求

运行Ansible的主机需要以下Python依赖：

• python >= 3.6.0 - 请见下面的说明。
• ansible >= 2.9.16 或 ansible-base >= 2.10.4

你可以使用此库中的requirements.txt文件安装依赖： pip3 install -r requirements.txt。

该角色已在以下Linux发行版上进行了测试：

• Alpine Linux
• Amazon Linux 2
• Archlinux
• CentOS 8
• Debian 11
• Fedora 31
• Fedora 32
• Fedora 33
• openSUSE Leap 15
• RockyLinux 8
• Ubuntu 20.04 LTS

:warning: 本角色的v3版本仅支持 k3s >= v1.19，对于 k3s < v1.19，请考虑更新或使用本角色的v1.x版本。

在升级之前，请查看CHANGELOG以了解重大变化通知。

角色变量

自K3s v1.19.1+k3s1起，你现在可以使用配置文件来配置K3s，而不是使用环境变量或命令行参数。该角色的v2版本已转向使用配置文件方法，而不是用命令行参数填充systemd单元文件。可能有一些例外在全局/集群变量中定义，但你大多数配置k3s都是通过k3s_server和k3s_agent变量使用配置文件来完成的。

请参见下面的“_服务器（控制平面）配置_”和“_代理（工作节点）配置_”。

全局/集群变量

以下是针对所有播放主机设置的变量，以确保环境一致性。这些通常是集群级别的配置。

变量	描述	默认值
k3s_state	k3s的状态：已安装、已启动、已停止、已下载、已卸载、已验证。	installed
k3s_release_version	使用特定版本的k3s，例如 v0.2.0。指定false为稳定版本。	false
k3s_airgap	布尔值，启用脱机安装	false
k3s_config_file	k3s配置文件的位置。	/etc/rancher/k3s/config.yaml
k3s_build_cluster	当有多个播放主机可用时，试图构建集群。请阅读下面的说明。	true
k3s_registration_address	节点的固定注册地址。IP或FQDN。	NULL
k3s_github_url	设置从中安装k3s的GitHub URL。	https://github.com/k3s-io/k3s
k3s_api_url	K3S更新API的URL。	https://update.k3s.io
k3s_install_dir	k3s的安装目录。	/usr/local/bin
k3s_install_hard_links	使用硬链接而不是符号链接进行安装。	false
k3s_server_config_yaml_d_files	用于补充k3s_server配置的模板的扁平列表。	[]
k3s_agent_config_yaml_d_files	用于补充k3s_agent配置的模板的扁平列表。	[]
k3s_server_manifests_urls	部署在主要控制平面上的URL列表。请阅读下面的说明。	[]
k3s_server_manifests_templates	部署在主要控制平面上的模板的扁平列表。	[]
k3s_server_pod_manifests_urls	在控制平面上安装静态pod清单的URL列表。请阅读下面的说明。	[]
k3s_server_pod_manifests_templates	安装静态pod清单的模板的扁平列表。	[]
k3s_use_experimental	允许在k3s中使用实验性功能。	false
k3s_use_unsupported_config	允许在k3s中使用不受支持的配置。	false
k3s_etcd_datastore	启用嵌入式etcd数据存储（请阅读下面的说明）。	false
k3s_debug	启用k3s服务的调试日志。	false
k3s_registries	注册表配置文件内容。	{ mirrors: {}, configs:{} }

K3S服务配置

以下变量更改K3S的systemd服务单元文件的运行方式和时机。请谨慎使用，更多信息请参见systemd文档。

变量	描述	默认值
k3s_start_on_boot	在启动时启动k3s。	true
k3s_service_requires	k3s服务单元所需的systemd单元列表。	[]
k3s_service_wants	k3s服务的“想要的”systemd单元列表（比“需要”弱）。	[]*
k3s_service_before	在定义的systemd单元列表之前启动k3s。	[]
k3s_service_after	在定义的systemd单元列表之后启动k3s。	[]*
k3s_service_env_vars	在systemd单元文件中使用的环境变量字典。	{}
k3s_service_env_file	主机上包含环境文件的位置。	false**

* systemd单元模板始终为wants和after指定network-online.target。

** 文件必须已经存在于目标主机上，该角色不会创建或管理该文件。你可以在Ansible播放书中的前置任务中管理此文件。

组/主机变量

以下变量针对单个或一组播放主机设置。通常，你会在控制平面或工作节点的组级别设置这些。

变量	描述	默认值
k3s_control_node	指定主机（或主机组）是否为控制平面的一部分。	false（角色将自动委派一个节点）
k3s_server	服务器（控制平面）配置，见下面说明。	{}
k3s_agent	代理（工作节点）配置，见下面说明。	{}

服务器（控制平面）配置

控制平面通过k3s_server字典变量进行配置。有关配置选项，请参阅以下文档：

https://rancher.com/docs/k3s/latest/en/installation/install-options/server-config/

k3s_server字典变量将包含上述标志（去掉--前缀）。以下是一个示例：

k3s_server:
  datastore-endpoint: postgres://postgres:verybadpass@database:5432/postgres?sslmode=disable
  cluster-cidr: 172.20.0.0/16
  flannel-backend: 'none'  # 需要加引号
  disable:
    - traefik
    - coredns

另外，你可以创建一个.yaml文件，并像下面示例那样读取k3s_server变量：

k3s_server: "{{ lookup('file', 'path/to/k3s_server.yml') | from_yaml }}"

查看文档以获取示例配置。

代理（工作节点）配置

工作节点通过k3s_agent字典变量进行配置。有关配置选项，请参阅以下文档：

https://rancher.com/docs/k3s/latest/en/installation/install-options/agent-config

k3s_agent字典变量将包含上述标志（去掉--前缀）。以下是一个示例：

k3s_agent:
  with-node-id: true
  node-label:
    - "foo=bar"
    - "hello=world"

另外，你可以创建一个.yaml文件，并像下面示例那样读取k3s_agent变量：

k3s_agent: "{{ lookup('file', 'path/to/k3s_agent.yml') | from_yaml }}"

查看文档以获取示例配置。

Ansible控制器配置变量

以下变量用于更改角色在Ansible中的执行方式，特别是与权限提升相关。

变量	描述	默认值
k3s_skip_validation	跳过所有验证配置的任务。	false
k3s_skip_env_checks	跳过所有检查环境配置的任务。	false
k3s_skip_post_checks	跳过所有检查后执行状态的任务。	false
k3s_become	提升需要root权限的任务的用户权限。	false

关于Python的重要说明

从该角色的v3版本开始，目标系统和Ansible控制器上都需要Python 3。这是为了确保Ansible任务的一致行为，因为Python 2现在已不再支持。

如果目标系统上同时安装了Python 2和Python 3，默认情况下可能会选择Python 2。为了确保在具有两个版本的Python的目标上使用Python 3，请确保在清单中设置ansible_python_interpreter。以下是示例清单：

---

k3s_cluster:
  hosts:
    kube-0:
      ansible_user: ansible
      ansible_host: 10.10.9.2
      ansible_python_interpreter: /usr/bin/python3
    kube-1:
      ansible_user: ansible
      ansible_host: 10.10.9.3
      ansible_python_interpreter: /usr/bin/python3
    kube-2:
      ansible_user: ansible
      ansible_host: 10.10.9.4
      ansible_python_interpreter: /usr/bin/python3

关于 k3s_release_version 的重要说明

如果你不设置 k3s_release_version，将安装k3s稳定通道的最新版本。如果你正针对特定版本的k3s进行开发，必须在Ansible配置中设置此变量，例如：

k3s_release_version: v1.19.3+k3s1

也可以安装特定的K3s“通道”，以下是一些 k3s_release_version 的示例：

k3s_release_version: false             # 默认为'stable'通道
k3s_release_version: stable            # 最新的'stable'版本
k3s_release_version: testing           # 最新的'testing'版本
k3s_release_version: v1.19             # 最新的'v1.19'版本
k3s_release_version: v1.19.3+k3s3      # 特定版本

# 特定提交
# 注意 - 仅用于测试 - 必须是40个字符
k3s_release_version: 48ed47c4a3e420fa71c18b2ec97f13dc0659778b

关于 k3s_install_hard_links 的重要说明

如果你使用系统升级控制器，你需要使用硬链接而不是符号链接，因为控制器无法跟随符号链接。这个选项已经添加，但默认情况下未启用以避免破坏现有安装。

要启用硬链接的使用，请确保将 k3s_install_hard_links 设置为 true。

k3s_install_hard_links: true

你可以通过在 k3s_install_dir 中运行以下命令查看结果：

ls -larthi | grep -E 'k3s|ctr|ctl' | grep -vE ".sh$" | sort

符号链接示例：

[root@node1 bin]# ls -larthi | grep -E 'k3s|ctr|ctl' | grep -vE ".sh$" | sort
3277823 -rwxr-xr-x 1 root root  52M Jul 25 12:50 k3s-v1.18.4+k3s1
3279565 lrwxrwxrwx 1 root root   31 Jul 25 12:52 k3s -> /usr/local/bin/k3s-v1.18.6+k3s1
3279644 -rwxr-xr-x 1 root root  51M Jul 25 12:52 k3s-v1.18.6+k3s1
3280079 lrwxrwxrwx 1 root root   31 Jul 25 12:52 ctr -> /usr/local/bin/k3s-v1.18.6+k3s1
3280080 lrwxrwxrwx 1 root root   31 Jul 25 12:52 crictl -> /usr/local/bin/k3s-v1.18.6+k3s1
3280081 lrwxrwxrwx 1 root root   31 Jul 25 12:52 kubectl -> /usr/local/bin/k3s-v1.18.6+k3s1

硬链接示例：

[root@node1 bin]# ls -larthi | grep -E 'k3s|ctr|ctl' | grep -vE ".sh$" | sort
3277823 -rwxr-xr-x 1 root root  52M Jul 25 12:50 k3s-v1.18.4+k3s1
3279644 -rwxr-xr-x 5 root root  51M Jul 25 12:52 crictl
3279644 -rwxr-xr-x 5 root root  51M Jul 25 12:52 ctr
3279644 -rwxr-xr-x 5 root root  51M Jul 25 12:52 k3s
3279644 -rwxr-xr-x 5 root root  51M Jul 25 12:52 k3s-v1.18.6+k3s1
3279644 -rwxr-xr-x 5 root root  51M Jul 25 12:52 kubectl

关于 k3s_build_cluster 的重要说明

如果你将 k3s_build_cluster 设置为 false，该角色将把每个播放主机安装为独立节点。使用这个选项的一个场景可能是当你需要构建大量运行K3s的独立物联网设备时。以下是一个假设的情况，我们将部署25个树莓派设备，每个设备都是独立系统，而不是25个节点的集群。为此，我们会使用类似下面的播放书：

- hosts: k3s_nodes  # 例如，清单中定义的25个RPi。
  vars:
    k3s_build_cluster: false
  roles:
    - xanmanning.k3s

关于 k3s_control_node 和高可用性（HA）的重要说明

默认情况下，仅会将一个主机定义为控制节点。如果你没有将主机设置为控制节点，该角色将自动将第一个播放主机委派为控制节点。这不适合在生产工作负载中使用。

如果多个主机将 k3s_control_node 设置为 true，你还必须在 k3s_server 中设置 datastore-endpoint 作为连接字符串，指向MySQL或PostgreSQL数据库，或外部Etcd集群，否则播放将失败。

如果使用TLS，CA、证书和密钥需要已经在播放主机上可用。

请参见：使用外部数据库实现高可用性

尽管不支持，但也可以使用定义了datastore-endpoint的单个K3s控制节点进行运行。由于这不是典型的支持配置，你需要将 k3s_use_unsupported_config 设置为 true。

自K3s v1.19.1以来，可以使用嵌入式Etcd作为后端数据库，只需将 k3s_etcd_datastore 设置为 true。Etcd的最佳实践是定义至少3个成员以确保达成法定人数。此外，建议使用奇数个成员以确保在网络分区时具有多数。如果希望使用2个成员或偶数个成员，请将 k3s_use_unsupported_config 设置为 true。

关于 k3s_server_manifests_urls 和 k3s_server_pod_manifests_urls 的重要说明

要从URL部署服务器清单和服务器pod清单，你需要指定url，并可以选择性提供filename（如果未提供，则使用基本名称）。以下是如何部署Calico和kube-vip的Tigera操作员的示例：

---

k3s_server_manifests_urls:
  - url: https://docs.projectcalico.org/archive/v3.19/manifests/tigera-operator.yaml
    filename: tigera-operator.yaml

k3s_server_pod_manifests_urls:
  - url: https://raw.githubusercontent.com/kube-vip/kube-vip/main/example/deploy/0.1.4.yaml
    filename: kube-vip.yaml

关于 k3s_airgap 的重要说明

在脱机环境中部署k3s时，应在./files/中提供 k3s二进制文件。将不会从Github下载二进制文件，因此无法使用提供的sha256和校验和进行验证，也无法确认你正在运行的版本。在这种情况下，所有风险和责任均由用户承担。

依赖关系

没有其他角色的依赖关系。

示例播放书

示例播放书，单控制节点运行testing通道k3s：

- hosts: k3s_nodes
  vars:
    k3s_release_version: testing
  roles:
     - role: xanmanning.k3s

示例播放书，高可用性配置，使用PostgreSQL数据库运行最新稳定版本：

- hosts: k3s_nodes
  vars:
    k3s_registration_address: loadbalancer  # 通常是负载均衡器。
    k3s_server:
      datastore-endpoint: "postgres://postgres:verybadpass@database:5432/postgres?sslmode=disable"
  pre_tasks:
    - name: 将每个节点设置为控制节点
      ansible.builtin.set_fact:
        k3s_control_node: true
      when: inventory_hostname in ['node2', 'node3']
  roles:
    - role: xanmanning.k3s

许可证

BSD 3条款

贡献者

欢迎社区的贡献，但请在此之前阅读贡献指南，这将有助于使事情尽可能顺利。

同时，请查看精彩的贡献者列表。

作者信息

Xan Manning