五分钟快速学习Ansible Operator
Operator Framework[1]是由CoreOS开发，后被RedHat收购的一个开源工具包，它可以有效的、自动化的和可扩展的方式管理 Kubernetes原生应用程序。该框架下包含Operator SDK，可协助开发人员利用自己的专业知识来引导和构建Operator，而无需了解 Kubernetes API复杂性。今天我们就学习它，用于创建一个基于Ansible的Operator应用（之前小白在《Loki Operator简明教程》中也简单聊到过），它可以利用现有 Ansible playbook和模块来部署和管理Kubernetes资源作为统一应用程序的生命周期，而无需编写任何Go代码。
安装
- Homebrew安装 (MacOS)
如果你使用的是Homebrew，你可以用以下命令安装SDK CLI工具。
$ brew install operator-sdk
- 二进制安装
$ export ARCH=$(case $(uname -m) in x86_64) echo -n amd64 ;; aarch64) echo -n arm64 ;; *) echo -n $(uname -m) ;; esac)
$ export OS=$(uname | awk '{print tolower($0)}')
$ export OPERATOR_SDK_DL_URL=https://github.com/operator-framework/operator-sdk/releases/download/v1.10.0
#下载operator-sdk
$ curl -LO ${OPERATOR_SDK_DL_URL}/operator-sdk_${OS}_${ARCH}
$ chmod +x operator-sdk_${OS}_${ARCH} && sudo mv operator-sdk_${OS}_${ARCH} /usr/local/bin/operator-sdk
- 编译安装
$ git clone https://github.com/operator-framework/operator-sdk
$ cd operator-sdk
$ git checkout master
$ make install
初始化
1. 初始化项目
使用operator-sdk命令来快速初始化这个项目的空间。
$ mkdir loki-operator
$ cd loki-operator
$ operator-sdk init --plugins=ansible --domain cloudxiaobai.com
这条命令生成的文件中有一个Kubebuilder的PROJECT描述文件。从里面我们可以得知，该工程是一个基于Ansible实现的项目
$ cat PROJECT
domain: loki.cloudxiaobai.com
layout:
- ansible.sdk.operatorframework.io/v1
plugins:
manifests.sdk.operatorframework.io/v2: {}
scorecard.sdk.operatorframework.io/v2: {}
projectName: cloudxiaobai
version: "3"
2. 创建API
$ operator-sdk create api \
--group=plugins --version=v1 --kind=Loki \
--generate-playbook \
--generate-role
上面这条命令可以快速帮助我们生成这个项目的脚手架。其中包含如下内容：
- 生成了Loki这个CRD的定义，和一个Loki CR的样例；
- 生成了Controller，用于管理CR的的服务在Kubernetes集群上的状态
- 生成了Ansible Playbook的目录结构
- 生成了一个 watches.yaml文件，它用来将CR资源与Ansible Playbook关联起来。
Ansible Playbook
在完成项目的初始化后，我们在项目下就得到了以下主要的目录。
├── Dockerfile
├── config
│ ├── samples
│ │ └── plugins_v1_loki.yaml //Loki的CR样例
├── playbooks //playbook的入口
│ └── loki.yml
├── roles //playbook文件
│ └── loki
│ ├── README.md
│ ├── defaults
│ │ └── main.yml
│ ├── files
│ ├── handlers
│ │ └── main.yml
│ ├── meta
│ │ └── main.yml
│ ├── tasks
│ │ └── main.yml
│ ├── templates
│ └── vars
│ └── main.yml
熟悉Ansible的朋友看到这个就比较眼熟了，接下来我们就开始写入一个Loki服务简单playbook文件来演示它的基本逻辑。
1. 修改 roles/loki/tasks/main.yaml
- name: Loki Operator | Loki | StatefulSet
community.kubernetes.k8s:
definition: "{{ lookup('template', 'statefulset.yaml') | from_yaml }}"
可以看到ansible是通过community.kubernetes[2]的k8s模块来跟kubernetes交互的。上面这条task的意思是让ansible去templates目录下去寻找statefulset.yaml文件，然后将它渲染成yaml文件后提交给kubernetes。
2. 创建 roles/loki/template/statefulset.yaml
statefulset.yaml是真正需要部署的ansible模版文件，我们需要创建的内容如下：
#jinja2:lstrip_blocks: True
apiVersion: apps/v1
kind: StatefulSet
metadata:
name: '{{ansible_operator_meta.name}}'
namespace: '{{ansible_operator_meta.namespace}}'
labels:
app.kubernetes.io/name: '{{ ansible_operator_meta.name }}-loki-system'
spec:
replicas: {{ replicas }}
serviceName: '{{ansible_operator_meta.name}}-headless'
selector:
matchLabels:
app.kubernetes.io/name: '{{ ansible_operator_meta.name }}-loki-system'
template:
metadata:
labels:
app.kubernetes.io/name: '{{ ansible_operator_meta.name }}-loki-system'
spec:
containers:
- name: loki-system
image: grafana/loki:2.2.1
imagePullPolicy: IfNotPresent
ports:
- containerPort: 3100
name: http-3100
protocol: TCP
上面的Ansible应用模版中有几点信息值得强调：
#jinja2:lstrip_blocks: True保留yaml文件中的空格、缩进等语句{{ansible_operator_meta.name}}定义了CR里面控制的Loki资源名称{{ansible_operator_meta.namespace}}定义了CR作用的命名空间{{ replicas }}自定义的CR变量
可以看到我们声明了一个名replicas的自定义变量，我们需要通过它来控制服务的副本数。Ansible中的变量取值由用户创建的CR来控制。
Ansible的roles文件中task实际上定义了CR的状态，在Kubernetes在创建资源时，由于允许输入任意字段，所以我们不需要在CRD中实际定义CR字段类型的声明。虽然在Operator SDK中它不能被自动生成，不过还是建议在实际使用时最好添加上CRD的字段说明，以便Kubernetes用户在使用CR时可以看到它对应的描述信息。
3. 创建CR
默认情况下Operator SDK会创建一个默认的CR样例文件，它位于config/samples/目录下。在本文中，我们的CR文件名称为plugins_v1_loki.yaml
apiVersion: plugins.cloudxiaobai.com/v1
kind: Loki
metadata:
name: loki
spec:
replicas: 1
构建与部署
当完成应用的playbook编写后，我们就可以使用make命令进行镜像的构建和上传。我们可以提前编辑Makefile来自定义镜像的名称,
IMAGE_TAG_BASE ?= cloudxiaobai.com/cloudxiaobai
IMG ?= $(IMAGE_TAG_BASE):$(VERSION)
这样，当我们每次build镜像时，产生固定的镜像名称。
1. 构建Operator镜像
$ make docker-build docker-push VERSION="0.1"
构建和上传operator镜像。
2. 部署Operator服务
$ make deploy
# kustomize build config/default | kubectl apply -f -
可以看到在部署时调用了kustomize将config/default目录下的文件进行构建后提交到kubernetes。这里面需要注意的是，默认情况下，kustomize会创建一个名为<project-name>-system的新命名空间用于部署Operator。
当部署完成后，我们就可以用kubectl进行验证服务状态。
$ kubectl get deployment -n cloudxiaobai--system
NAME READY UP-TO-DATE AVAILABLE AGE
loki-controller-manager 1/1 1 1 8m
3. 提交CR
将上文的CR声明文件提交到kubernetes
$ cat config/samples/plugins_v1_loki.yaml
apiVersion: plugins.cloudxiaobai.com/v1
kind: Loki
metadata:
name: loki
spec:
replicas: 1
$ kubectl apply -f config/samples/plugins_v1_loki.yaml
之后我们就可以通过以下命令进行验证服务是否达到预期
$ kubectl get deployment
NAME READY UP-TO-DATE AVAILABLE AGE
cloudxiaobai-31e1d3526-a1klm 1/1 1 1 1m
如果我们要调整Loki的副本数，我们只需有修改CR中的replicas变量即可，也可以通过patch的方式修改。
$ kubectl patch loki cloudxiaobai -p '{"spec":{"size": 2 }}' --type=merge
4. 删除资源
直接执行下列命令就能分别删除CR和Operator关联的所有资源
$ kubectl delete -f config/samples/plugins_v1_loki.yaml
$ make undeploy
小技巧
1. Ansible变量转化
自定义CR中的spec字段中所有变量的名称均被操作符转换为snake_case（下横线）命名格式。例如，我们在spec中写入了一个变量serviceAccount，那么在ansible中会被转成service_account。小白建议可以在watches.yaml中将snakeCaseParameters设置为false来禁用这种大小写转换。
2. 使用默认值
为了能将ansible template适配大部分场景，小白建议在模版中使用默认值，避免在CR中没有定义变量而造成的playbook执行报错。例如，我们在CR中定义了Loki的镜像信息如下。
spec:
image:
repository: grafana/loki
tag: 2.1.1
那我们在template就可以如下编写：
containers:
- name: loki-system
image: '{{service.cluster.loki.image | default('grafana/loki')}}:{{version | default('latest')}}'
这里，如果我们没在CR中定义image的变量，当playbook执行到这里时，就会采用grafana/loki:latest镜像。
3. 巧用items
由于community.kubernetes.k8s模块不允许提交一个allinone的yaml文件，所以当在实际编写playbook时，如果想在一个task时里面完成所有yaml提交时，我们可以使用如下语句：
- name: Loki Operator | Loki | Deploy
community.kubernetes.k8s:
definition: "{{ lookup('template', item) | from_yaml }}"
with_items:
- statefulset.yaml
- service.yaml
4. 控制模块启用或关闭
如果我们的CR中希望能够控制某些服务的启用或关闭时，通常情况下会直接使用enabled: true来做明确的定义，例如下面这个CR
spec:
redis:
enabled: true
那么，我们在写playbook时，可以通过在state中判断CR中的该变量来决定是否执行，如下：
- name: Loki Operator | Reids Cache | PVC
community.kubernetes.k8s:
state: '{{"present" if redis is defined and redis.enabled else "absent"}}'
definition: "{{ lookup('template', 'redis/pvc.yaml') | from_yaml }}
5. Owner References
Owner References是Kubernetes中的垃圾删除机制，它能够在删除CR后进行后续清理。默认情况下，ownerReferences由代理在ansible执行时注入。在当CR和被管理的资源在同一个命名空间下时，ownerReferences会在资源中如下显示：
metadata:
ownerReferences:
- apiVersion: loki.cloudxiaobai.com/v1
kind: loki
name: loki
uid:fda3b711-1f25-4d14-bf84-cf70f48e7ff4
CR和被管理的资源不在一个命名空间下时，ownerReferences便是通过如下的annotation字段来定义的：
operator-sdk/primary-resource: {metadata.namespace}/{metadata.name}
operator-sdk/primary-resource-type: {kind}.{group}
当然，如果你要禁用ownerReferences的话，如下修改dockerfile即可：
ENTRYPOINT ["/usr/local/bin/entrypoint", "--inject-owner-ref=false"]
6. 任务并发
默认情况下，ansible调用的runtime.NumCPU()来设置最大并发协调值，可以看到它取决于你主机的CPU核心数。增加并发协调的数量和允许并发处理事件，可以提高ansible执行任务时的协调性能。我们可以在operator的启动参数来手动设置
- name: manager
args:
- "--max-concurrent-reconciles"
- "3"
总结
本文通过一个小例子介绍了如何通过Operator SDK快速构建、管理Loki应用。并通过6个小技巧让读者在使用过程中尽量避坑。目前小白在实际工作中，将Ansible Operator主要应用在kubernetes平台初始化时各种插件、三方服务的安装管理，如prometheus、loki、grafna等等，希望它也能在其它方面帮助到大家。
参考资料
[1]
Operator Framework: https://sdk.operatorframework.io/docs/overview/
[2]
community.kubernetes: https://docs.ansible.com/ansible/2.10/collections/community/kubernetes/k8s_module.html
