puppet/kubetool

Kubernetes

概述

本模块用于安装和配置https://kubernetes.io/%EF%BC%8C%E8%BF%99%E6%98%AF%E4%B8%80%E4%B8%AA%E5%BC%80%E6%BA%90%E7%B3%BB%E7%BB%9F%EF%BC%8C%E7%94%A8%E4%BA%8E%E8%87%AA%E5%8A%A8%E5%8C%96%E9%83%A8%E7%BD%B2%E3%80%81%E6%89%A9%E5%B1%95%E5%92%8C%E7%AE%A1%E7%90%86%E5%AE%B9%E5%99%A8%E5%8C%96%E5%BA%94%E7%94%A8%E3%80%82%E6%9E%84%E6%88%90%E5%BA%94%E7%94%A8%E7%9A%84%E5%AE%B9%E5%99%A8%E8%A2%AB%E5%88%86%E7%BB%84%E4%B8%BA%E9%80%BB%E8%BE%91%E5%8D%95%E5%85%83%EF%BC%8C%E4%BB%A5%E4%BE%BF%E9%AB%98%E6%95%88%E7%AE%A1%E7%90%86%E5%92%8C%E5%8F%91%E7%8E%B0%E3%80%82

为了以安全且可扩展的方式引导Kubernetes集群，本模块使用https://kubernetes.io/docs/setup/independent/create-cluster-kubeadm/%E5%B7%A5%E5%85%B7%E5%8C%85%E3%80%82

核心功能和特性

• 使用kubeadm工具包引导Kubernetes集群
• 支持配置控制器节点（包含控制平面和etcd）和工作节点（运行应用）
• 提供Kubetool配置工具，自动生成Hiera安全参数、发现令牌哈希和其他集群配置
• 支持Docker和cri_containerd容器运行时
• 支持weave和flannel等CNI网络提供商
• 兼容Puppet Development Kit (PDK)，支持单元测试和模块验证

使用场景和适用范围

• 自动化部署Kubernetes集群
• 管理多节点Kubernetes集群（控制器节点和工作节点）
• 企业级容器化应用的部署和扩展
• 需要安全配置和可扩展架构的Kubernetes环境

使用方法和配置说明

安装准备

1. 安装此模块（参考Puppet模块安装文档）
2. 生成配置
3. 将OS和主机名yaml文件添加到Hiera
4. 配置节点

模块包含https://github.com/puppetlabs/puppetlabs-kubernetes/blob/master/tooling/kube_tool.rb%E9%85%8D%E7%BD%AE%E5%B7%A5%E5%85%B7%EF%BC%8C%E5%8F%AF%E8%87%AA%E5%8A%A8%E7%94%9F%E6%88%90Hiera%E5%AE%89%E5%85%A8%E5%8F%82%E6%95%B0%E3%80%81%E5%8F%91%E7%8E%B0%E4%BB%A4%E7%89%8C%E5%93%88%E5%B8%8C%E5%92%8C%E5%85%B6%E4%BB%96%E9%9B%86%E7%BE%A4%E9%85%8D%E7%BD%AE%E3%80%82%E4%B8%BA%E7%AE%80%E5%8C%96%E5%AE%89%E8%A3%85%E5%92%8C%E4%BD%BF%E7%94%A8%EF%BC%8C%E8%AF%A5%E5%B7%A5%E5%85%B7%E4%BB%A5Docker%E9%95%9C%E5%83%8F%E5%BD%A2%E5%BC%8F%E6%8F%90%E4%BE%9B%E3%80%82

生成模块配置

如果工作站未安装Docker，请从https://docs.docker.com/install/%E5%AE%89%E8%A3%85%E3%80%82

Kubetool Docker镜像将每个参数作为环境变量接收。

注意：使用的Kubetool版本必须与Puppet Forge上的模块版本匹配。例如，若使用模块版本1.0.0，则使用puppet/kubetool:1.0.0。

要在工作目录中输出对应操作系统的yaml文件（针对每个控制器节点），运行以下任一docker run命令：

bash
docker run --rm -v $(pwd):/mnt --env-file env docker.xuanyuan.run/puppet/kubetool:{$module_version}

上述命令包含一个env文件，位于此仓库的根目录中。

bash
docker run --rm -v $(pwd):/mnt -e OS=debian -e VERSION=1.10.2 -e CONTAINER_RUNTIME=docker -e CNI_PROVIDER=weave -e ETCD_INITIAL_CLUSTER=kube-master:172.17.10.101,kube-replica-master-01:172.17.10.210,kube-replica-master-02:172.17.10.220 -e ETCD_IP="%{::ipaddress_eth1}" -e KUBE_API_ADVERTISE_ADDRESS="%{::ipaddress_eth1}" -e INSTALL_DASHBOARD=true docker.xuanyuan.run/puppet/kubetool:{$module-version}

参数说明：

• OS：Kubernetes运行的操作系统
• VERSION：要部署的Kubernetes版本
• CONTAINER_RUNTIME：Kubernetes使用的容器运行时，可设为docker（官方支持）或cri_containerd（高级用户使用，需了解Kubernetes HA集群知识）
• CNI_PROVIDER：要安装的CNI网络，可设为weave或flannel
• ETCD_INITIAL_CLUSTER：服务器主机名和IP，格式为hostname:ip。生产环境中，etcd节点数应为3、5或7个
• ETCD_IP：每个etcd成员监听的IP，建议使用集群接口的fact值
• KUBE_API_ADVERTISE_ADDRESS：每个控制器上etcd/apiserver实例使用的IP，建议使用集群接口的fact值
• INSTALL_DASHBOARD：布尔值，指定是否安装dashboard

Kubetool创建：

• 对应OS参数的yaml文件（如Debian系统为Debian.yaml，RedHat系统为RedHat.yaml），包含引导初始etcd集群的证书信息，需放在hieradata目录的节点级别
• Kubernetes所需的发现令牌哈希和编码值，可通过再次运行kubetool命令重新生成（包括证书和令牌）

添加{$OS}.yaml和{$hostname}.yaml文件到Hiera

将{$OS}.yaml文件添加到Hiera数据所在的控制仓库（通常是data目录）。通过利用位置fact（如pp_datacenter 可信fact），每个集群可分配自己的配置。

配置节点

将{$OS}.yaml和{$hostname}.yaml文件添加到Puppet服务器上的Hiera目录后，将节点配置为控制器或工作节点。

控制器节点包含控制平面和etcd，生产集群应配置3、5或7个控制器；工作节点运行应用，可根据Kubernetes承载能力添加任意数量。

注意：节点不能同时作为控制器和工作节点，只能二选一。

配置为控制器节点

在manifest中添加以下代码：

puppet
class {'kubernetes':
  controller => true,
}

配置为工作节点

在manifest中添加以下代码：

puppet
class {'kubernetes':
  worker => true,
}

验证和单元测试模块

本模块兼容Puppet Development Kit (PDK)，提供工具帮助运行模块单元测试并验证模块元数据、语法和样式。

注意：要使用pdk validate和pdk test unit命令对模块运行静态验证和单元测试，必须安装Puppet 5或更高版本。以下示例指定Puppet 5.3.6。

验证metadata.json文件

bash
pdk validate metadata --puppet-version='5.3.6'

验证Puppet代码和语法

bash
pdk validate puppet --puppet-version='5.3.6'

注意：pdk validate ruby命令会忽略.rubocop.yml文件中指定的排除目录。因此，要验证Ruby代码样式和语法，必须指定代码所在目录。

例如，验证lib目录中的Ruby代码：

bash
pdk validate ruby lib --puppet-version='5.3.6'

单元测试模块

bash
pdk test unit --puppet-version='5.3.6'

参考

类

公共类

• kubernetes

私有类

• kubernetes::cluster_roles
• kubernetes::config
• kubernetes::kube_addons
• kubernetes::packages
• kubernetes::repos
• kubernetes::service

定义类型

• kubernetes::kubeadm_init
• kubernetes::kubeadm_join

参数

kubernetes类可用以下参数：

apiserver_cert_extra_sans

API服务器证书的主题备用名称字符串数组，默认[]。

apiserver_extra_arguments

传递给API服务器的额外参数字符串数组，默认[]。

cloud_provider

/etc/kubernetes/cloud-config中配置的云提供商名称，默认undef。注意：此文件不由本模块管理，引导Kubernetes控制器前必须存在。

cloud_config

cloud_provider使用的云配置文件位置（v1.12及以上版本使用），默认undef。注意：此文件不由本模块管理，引导Kubernetes控制器前必须存在。

cni_network_provider

CNI提供商yaml文件的URL，由kube_tool设置，默认undef。

cni_rbac_binding

CNI提供商RBAC规则的下载URL（仅Calico使用），默认undef。

cni_pod_cidr

指定覆盖（内部）网络范围，由kube_tool根据CNI_PROVIDER设置，默认undef。

container_runtime

Kubernetes集群使用的运行时，有效值为cri_containerd或docker，默认docker。

controller

指定节点是否为Kubernetes控制器，有效值true/false，默认false。

containerd_version

要安装的containerd运行时版本，默认1.1.0。

containerd_archive

containerd归档文件名称，默认containerd-${containerd_version}.linux-amd64.tar.gz。

containerd_source

containerd归档文件的下载URL，默认https://github.com/containerd/containerd/releases/download/v${containerd_version}/${containerd_archive}。

controller_address

工作节点加入的控制器IP地址和端口（如172.17.10.101:6443），默认undef。

create_repos

指定是否安装上游Kubernetes和Docker仓库，有效值true/false，默认true。

disable_swap

指定是否关闭swap设置（kubeadm要求），有效值true/false，默认true。

manage_kernel_modules

指定是否管理Kubernetes所需的内核模块，有效值true/false，默认true。

manage_sysctl_settings

指定是否管理Kubernetes所需的sysctl设置，有效值true/false，默认true。

discovery_token_hash

加入集群时用于验证根CA公钥的字符串，由kubetool创建，默认undef。

docker_apt_location

Docker包的APT仓库URL，默认https://apt.dockerproject.org/repo。

docker_apt_release

Docker包APT仓库的发行名称，默认'ubuntu-${::lsbdistcodename}'。

docker_apt_repos

从Docker APT URL安装的仓库，默认main。

docker_version

要安装的Docker运行时版本，默认：

• RedHat：17.03.0.ce-1.el7.centos
• Ubuntu：17.03.0~ce-0~ubuntu-xenial

docker_package_name

从上游仓库下载的Docker包名称，默认docker-engine。

docker_key_id

Docker APT仓库的GPG密钥ID，默认'58118E89F3A912897C070ADBF76221572C52609D'。

docker_key_source

Docker APT仓库GPG密钥的URL，默认https://apt.dockerproject.org/gpg。

docker_yum_baseurl

Docker包的YUM仓库URL，默认https://packages.cloud.google.com/yum/repos/kubernetes-el7-x86_64。

docker_yum_gpgkey

Docker YUM仓库GPG密钥的URL，默认https://yum.dockerproject.org/gpg。

etcd_version

etcd版本，默认3.1.12。

etcd_archive

etcd归档文件名称，默认etcd-v${etcd_version}-linux-amd64.tar.gz。

etcd_source

etcd归档文件的下载URL，默认https://github.com/coreos/etcd/releases/download/v${etcd_version}/${etcd_archive}。

etcd_ip

etcd用于通信的IP地址，Hiera示例：kubernetes::etcd_ip:"%{::ipaddress_enp0s8}"，默认undef。

etcd_initial_cluster

告知etcd集群中的节点数量，Hiera示例：kubernetes::etcd_initial_cluster: kube-master:172.17.10.101,kube-replica-master-01:172.17.10.210,kube-replica-master-02:172.17.10.220，默认undef。

etcd_peers

etcd列出连接集群的对等节点，Hiera示例：kubernetes::etcd_peers:

• 172.17.10.101
• 172.17.10.102
• 172.17.10.103，默认undef。

etcd_ca_key

etcd集群的CA证书密钥数据（字符串形式，非文件），默认undef。

etcd_ca_crt

etcd集群的CA证书数据（字符串形式，非文件），默认undef。

etcdclient_key

etcd集群的客户端证书密钥数据（字符串形式，非文件），默认undef。

etcdclient_crt

etcd集群的客户端证书数据（字符串形式，非文件），默认undef。

etcdserver_key

etcd集群的服务器证书密钥数据（字符串形式，非文件），默认undef。

etcdserver_crt

etcd集群的服务器证书数据（字符串形式，非文件），默认undef。

etcdpeer_crt

etcd集群的对等节点证书数据（字符串形式，非文件），默认undef。

etcdpeer_key

etcd集群的对等节点证书密钥数据（字符串形式，非文件），默认undef。

image_repository

拉取控制平面镜像的容器 registry，默认k8s.gcr.io。

install_dashboard

指定是否安装Kubernetes dashboard，有效值true/false，默认false。

kubernetes_ca_crt

集群CA证书（字符串形式，非文件），默认undef。

kubernetes_ca_key

集群CA密钥（字符串形式，非文件），默认undef。

kube_api_advertise_address

API服务器公开的IP地址，Hiera示例：kubernetes::kube_api_advertise_address:"%{::ipaddress_enp0s8}"，默认undef。

kubernetes_version

要安装的Kubernetes容器版本，默认1.10.2。

kubernetes_package_version

要安装的Kubernetes OS包（如kubectl和kubelet）版本，默认1.10.2。

kubeadm_extra_config

包含额外配置数据的哈希，将通过to_yaml序列化并附加到kubeadm使用的config.yaml文件，默认{}。

kubelet_extra_config

包含额外配置数据的哈希，将通过to_yaml序列化并附加到集群的Kubelet配置文件（需DynamicKubeletConfig），默认{}。

kubelet_extra_arguments

附加到Kubelet的nodeRegistration配置中kubeletExtraArgs的字符串数组，适用于主节点和工作节点，用于配置关键Kubelet设置（如pod-infra-container-image），默认[]。

kubernetes_apt_location

Kubernetes包的APT仓库URL，默认https://apt.kubernetes.io。

kubernetes_apt_release

Kubernetes包APT仓库的发行名称，默认'kubernetes-${::lsbdistcodename}'。

kubernetes_apt_repos

使用Kubernetes APT URL安装的仓库，默认main。

kubernetes_key_id

Kubernetes APT仓库的GPG密钥ID，默认'54A647F9048D5688D7DA2ABE6A030B21BA07F4FB'。

kubernetes_key_source

APT仓库GPG密钥的URL，默认https://packages.cloud.google.com/apt/doc/apt-key.gpg。

kubernetes_yum_baseurl

Kubernetes包的YUM仓库URL，默认https://packages.cloud.google.com/yum/repos/kubernetes-el7-x86_64。

kubernetes_yum_gpgkey

Kubernetes YUM仓库GPG密钥的URL，默认https://packages.cloud.google.com/yum/doc/rpm-package-key.gpg。

manage_docker

指定是否通过此模块安装Docker仓库和包，有效值true/false，默认true。

manage_etcd

指定是否通过此模块安装外部Etcd，有效值true/false，默认true。

node_label

节点标签的覆盖值，默认hostname。

runc_source

runc的下载URL，默认`https