5.4. 基于 Ansible 的 Operator

流程

1. 创建一个项目。

   1. 创建您的项目目录：

      $ mkdir memcached-operator

   2. 切换到项目所在的目录：

      $ cd memcached-operator

   3. 使用 ansible 插件运行 operator-sdk init 命令以初始化项目：

      $ operator-sdk init \
          --plugins=ansible \
          --domain=example.com

2. 创建 API。

   创建简单的 Memcached API：

   $ operator-sdk create api \
       --group cache \
       --version v1 \
       --kind Memcached \
       --generate-role 1

   1

   为 API 生成 Ansible 角色。

3. 构建并推送 Operator 镜像。

   使用默认的 Makefile 目标来构建和推送 Operator。使用镜像的 pull spec 设置 IMG，该 spec 使用您可推送到的 registry：

   $ make docker-build docker-push IMG=<registry>/<user>/<image_name>:<tag>

4. 运行 Operator。

   1. 安装 CRD：

      $ make install

   2. 将项目部署到集群中。将 IMG 设置为您推送的镜像：

      $ make deploy IMG=<registry>/<user>/<image_name>:<tag>

5. 创建示例自定义资源（CR）。

   1. 创建一个示例 CR：

      $ oc apply -f config/samples/cache_v1_memcached.yaml \
          -n memcached-operator-system

   2. 查看 CR 协调 Operator：

      $ oc logs deployment.apps/memcached-operator-controller-manager \
          -c manager \
          -n memcached-operator-system

      输出示例

      ...
      I0205 17:48:45.881666       7 leaderelection.go:253] successfully acquired lease memcached-operator-system/memcached-operator
      {"level":"info","ts":1612547325.8819902,"logger":"controller-runtime.manager.controller.memcached-controller","msg":"Starting EventSource","source":"kind source: cache.example.com/v1, Kind=Memcached"}
      {"level":"info","ts":1612547325.98242,"logger":"controller-runtime.manager.controller.memcached-controller","msg":"Starting Controller"}
      {"level":"info","ts":1612547325.9824686,"logger":"controller-runtime.manager.controller.memcached-controller","msg":"Starting workers","worker count":4}
      {"level":"info","ts":1612547348.8311093,"logger":"runner","msg":"Ansible-runner exited successfully","job":"4037200794235010051","name":"memcached-sample","namespace":"memcached-operator-system"}

6. 删除 CR

   运行以下命令来删除 CR：

   $ oc delete -f config/samples/cache_v1_memcached.yaml -n memcached-operator-system

7. 清理。

   运行以下命令清理在此流程中创建的资源：

   $ make undeploy

流程

1. 为项目创建一个目录：

   $ mkdir -p $HOME/projects/memcached-operator

2. 进入该目录：

   $ cd $HOME/projects/memcached-operator

3. 使用 ansible 插件运行 operator-sdk init 命令以初始化项目：

   $ operator-sdk init \
       --plugins=ansible \
       --domain=example.com

流程

1. 用下列结构更新 roles/memcached/tasks/main.yml 文件：

   ---
   - name: start memcached
     k8s:
       definition:
         kind: Deployment
         apiVersion: apps/v1
         metadata:
           name: '{{ ansible_operator_meta.name }}-memcached'
           namespace: '{{ ansible_operator_meta.namespace }}'
         spec:
           replicas: "{{size}}"
           selector:
             matchLabels:
               app: memcached
           template:
             metadata:
               labels:
                 app: memcached
             spec:
               containers:
               - name: memcached
                 command:
                 - memcached
                 - -m=64
                 - -o
                 - modern
                 - -v
                 image: "docker.io/memcached:1.4.36-alpine"
                 ports:
                   - containerPort: 11211

   这个 memcached 角色可确保存在 memcached 部署并设置部署大小。

2. 通过编辑 roles/memcached/defaults/main.yml 文件，为您的 Ansible 角色中使用的变量设置默认值：

   ---
   # defaults file for Memcached
   size: 1

3. 使用以下结构更新 config/samples/cache_v1_memcached.yaml 文件中的 Memcached 示例资源：

   apiVersion: cache.example.com/v1
   kind: Memcached
   metadata:
     labels:
       app.kubernetes.io/name: memcached
       app.kubernetes.io/instance: memcached-sample
       app.kubernetes.io/part-of: memcached-operator
       app.kubernetes.io/managed-by: kustomize
       app.kubernetes.io/created-by: memcached-operator
     name: memcached-sample
   spec:
     size: 3

   自定义资源（CR）spec 中的键值对作为额外变量传递给 Ansible。

流程

1. 通过使用以下内容更新 roles/memcached/tasks/main.yml 文件，将环境变量添加到部署中：

   ...
   env:
      - name: HTTP_PROXY
        value: '{{ lookup("env", "HTTP_PROXY") | default("", True) }}'
      - name: http_proxy
        value: '{{ lookup("env", "HTTP_PROXY") | default("", True) }}'
   ...

2. 通过在 config/manager/manager.yaml 文件中添加以下内容来设置 Operator 部署上的环境变量：

   containers:
    - args:
      - --leader-elect
      - --leader-election-id=ansible-proxy-demo
      image: controller:latest
      name: manager
      env:
        - name: "HTTP_PROXY"
          value: "http_proxy_test"

流程

1. 切换到安装 Operator 的命名空间。例如，如果使用 make deploy 命令部署 Operator：

   $ oc project memcached-operator-system

2. 编辑 config/samples/cache_v1_memcached.yaml 上的 Memcached CR 清单示例，使其包含以下规格：

   apiVersion: cache.example.com/v1
   kind: Memcached
   metadata:
     name: memcached-sample
   ...
   spec:
   ...
     size: 3

3. 创建 CR:

   $ oc apply -f config/samples/cache_v1_memcached.yaml

4. 确保 Memcached Operator 为示例 CR 创建部署，其大小正确：

   $ oc get deployments

   输出示例

   NAME                                    READY   UP-TO-DATE   AVAILABLE   AGE
   memcached-operator-controller-manager   1/1     1            1           8m
   memcached-sample                        3/3     3            3           1m

5. 检查 pod 和 CR 状态，以确认其状态是否使用 Memcached pod 名称更新。

   1. 检查 pod:

      $ oc get pods

      输出示例

      NAME                                  READY     STATUS    RESTARTS   AGE
      memcached-sample-6fd7c98d8-7dqdr      1/1       Running   0          1m
      memcached-sample-6fd7c98d8-g5k7v      1/1       Running   0          1m
      memcached-sample-6fd7c98d8-m7vn7      1/1       Running   0          1m

   2. 检查 CR 状态：

      $ oc get memcached/memcached-sample -o yaml

      输出示例

      apiVersion: cache.example.com/v1
      kind: Memcached
      metadata:
      ...
        name: memcached-sample
      ...
      spec:
        size: 3
      status:
        nodes:
        - memcached-sample-6fd7c98d8-7dqdr
        - memcached-sample-6fd7c98d8-g5k7v
        - memcached-sample-6fd7c98d8-m7vn7

6. 更新部署大小。

   1. 更新 config/samples/cache_v1_memcached.yaml 文件，将 Memcached CR 中的 spec.size 字段从 3 改为 5：

      $ oc patch memcached memcached-sample \
          -p '{"spec":{"size": 5}}' \
          --type=merge

   2. 确认 Operator 已更改部署大小：

      $ oc get deployments

      输出示例

      NAME                                    READY   UP-TO-DATE   AVAILABLE   AGE
      memcached-operator-controller-manager   1/1     1            1           10m
      memcached-sample                        5/5     5            5           3m

7. 运行以下命令来删除 CR：

   $ oc delete -f config/samples/cache_v1_memcached.yaml

8. 清理本教程中创建的资源。

   • 如果使用 make deploy 命令来测试 Operator，请运行以下命令：

     $ make undeploy

   • 如果使用 operator-sdk run bundle 命令来测试 Operator，请运行以下命令：

     $ operator-sdk cleanup <project_name>

流程

1. 对 config/default/manager_auth_proxy_patch.yaml 文件进行以下更改：

   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: controller-manager
     namespace: system
   spec:
     template:
       spec:
         containers:
         - name: kube-rbac-proxy
           image: registry.redhat.io/openshift4/ose-kube-rbac-proxy:v4.12 1
           args:
           - "--secure-listen-address=0.0.0.0:8443"
           - "--upstream=http://127.0.0.1:8080/"
           - "--logtostderr=true"
           - "--v=0"
   ...

   1

   将标签版本从 v4.11 更新至 v4.12。

2. 对 Makefile 进行以下更改：

   1. 要启用多架构构建支持，请将 docker-buildx 目标添加到项目的 Makefile 中：

      Makefile示例

      # PLATFORMS defines the target platforms for  the manager image be build to provide support to multiple
      # architectures. (i.e. make docker-buildx IMG=myregistry/mypoperator:0.0.1). To use this option you need to:
      # - able to use docker buildx . More info: https://docs.docker.com/build/buildx/
      # - have enable BuildKit, More info: https://docs.docker.com/develop/develop-images/build_enhancements/
      # - be able to push the image for your registry (i.e. if you do not inform a valid value via IMG=<myregistry/image:<tag>> than the export will fail)
      # To properly provided solutions that supports more than one platform you should use this option.
      PLATFORMS ?= linux/arm64,linux/amd64,linux/s390x,linux/ppc64le
      .PHONY: docker-buildx
      docker-buildx: test ## Build and push docker image for the manager for cross-platform support
      	# copy existing Dockerfile and insert --platform=${BUILDPLATFORM} into Dockerfile.cross, and preserve the original Dockerfile
      	sed -e '1 s/\(^FROM\)/FROM --platform=\$$\{BUILDPLATFORM\}/; t' -e ' 1,// s//FROM --platform=\$$\{BUILDPLATFORM\}/' Dockerfile > Dockerfile.cross
      	- docker buildx create --name project-v3-builder
      	docker buildx use project-v3-builder
      	- docker buildx build --push --platform=$(PLATFORMS) --tag ${IMG} -f Dockerfile.cross
      	- docker buildx rm project-v3-builder
      	rm Dockerfile.cross

   2. 要在 Operator 项目中启用对 64 位 ARM 架构的支持，请对 Makefile 进行以下更改：

      旧 Makefile

      OS := $(shell uname -s | tr '[:upper:]' '[:lower:]')
      ARCH := $(shell uname -m | sed 's/x86_64/amd64/')

      新的 Makefile

      OS := $(shell uname -s | tr '[:upper:]' '[:lower:]')
      ARCH := $(shell uname -m | sed 's/x86_64/amd64/' |  sed 's/aarch64/arm64/')

   3. 将 Kustomize 版本更新至 v4.5.5，如下例所示：

      旧 Makefile

      .PHONY: kustomize
      KUSTOMIZE = $(shell pwd)/bin/kustomize
      kustomize: ## Download kustomize locally if necessary.
      ifeq (,$(wildcard $(KUSTOMIZE)))
      ifeq (,$(shell which kustomize 2>/dev/null))
      	@{ \
      	set -e ;\
      	mkdir -p $(dir $(KUSTOMIZE)) ;\
      	curl -sSLo - https://github.com/kubernetes-sigs/kustomize/releases/download/kustomize/v3.8.7/kustomize_v3.8.7_$(OS)_$(ARCH).tar.gz | \
      	tar xzf - -C bin/ ;\
      	}
      else

      新的 Makefile

      .PHONY: kustomize
      KUSTOMIZE = $(shell pwd)/bin/kustomize
      kustomize: ## Download kustomize locally if necessary.
      ifeq (,$(wildcard $(KUSTOMIZE)))
      ifeq (,$(shell which kustomize 2>/dev/null))
      	@{ \
      	set -e ;\
      	mkdir -p $(dir $(KUSTOMIZE)) ;\
      	curl -sSLo - https://github.com/kubernetes-sigs/kustomize/releases/download/kustomize/v4.5.5/kustomize_v4.5.5_$(OS)_$(ARCH).tar.gz | \ 1
      	tar xzf - -C bin/ ;\
      	}
      else

      1

      将版本 v3.8.7 更新至 v4.5.5。

      重要

      Kustomize 版本 4.0.0 删除了 go-getter 插件，并引入了破坏与早期版本不向后兼容的更改。依赖于较旧版本的 Kustomize 的 Operator 项目可能无法与较新的版本一起使用。

   4. 要将更改应用到 Makefile 并重建 Operator，请输入以下命令：

      $ make

3. 更新 Operator Dockerfile 中的镜像标签，如下例所示：

   Dockerfile 示例

   FROM registry.redhat.io/openshift4/ose-ansible-operator:v4.12 1

   1

   将 version 标签更新至 v4.12。

4. 更新 config/default/kustomizations.yaml 文件，如下例所示：

   kustomizations.yaml 文件示例

   # Adds namespace to all resources.
   namespace: memcached-operator-system
   # Value of this field is prepended to the
   # names of all resources, e.g. a deployment named
   # "wordpress" becomes "alices-wordpress".
   # Note that it should also match with the prefix (text before '-') of the namespace
   # field above.
   namePrefix: memcached-operator-
   
   # Labels to add to all resources and selectors.
   #labels: 1
   #- includeSelectors: true 2
   #  pairs:
   #    someName: someValue
   
   resources: 3
   - ../crd
   - ../rbac
   - ../manager

   1

   将 commonLabels 字段替换为 labels 字段。

   2

   添加 includeSelectors: true。

   3

   将 bases 字段替换为 resources 字段。

5. 使用以下更改更新您的 molecule/default/kustomize.yml 文件：

   molecule/default/kustomize.yml 文件示例

   ---
   - name: Build kustomize testing overlay
     # load_restrictor must be set to none so we can load patch files from the default overlay
     command: '{{ kustomize }} build --load-restrictor LoadRestrictionsNone' 1
     args:
       chdir: '{{ config_dir }}/testing'
     register: resources
     changed_when: false

   1

   将 --load_restrictor none . 替换为 --load-restrictor LoadRestrictionNone。

流程

1. 安装 Ansible 2.9+：

   $ sudo dnf install ansible

2. 安装 OpenShift python 客户端 软件包：

   $ pip3 install openshift

3. 使用以下方法之一安装 Kubernetes Collection：

   • 您可以直接从 Ansible Galaxy 安装集合：

     $ ansible-galaxy collection install community.kubernetes

   • 如果您已初始化了 Operator，则可能在项目顶层都有一个 requirements.yml 文件。此文件指定必须安装的 Ansible 依赖项，才能让 Operator 正常工作。默认情况下，此文件会安装 community.kubernetes 集合以及 operator_sdk.util 集合，它为特定 Operator 的 fuctions 提供模块和插件。

     安装来自 requirements.yml 文件的依赖模块：

     $ ansible-galaxy collection install -r requirements.yml

流程

1. 在基于 Ansible 的 Operator 项目目录中，使用您想要的 Ansible 逻辑来修改 roles/<kind> /tasks/main.yml 文件。在创建 API 时，当使用 --generate-role 标志时，会创建 roles/<kind> / 目录。<kind> 可替换与您为 API 指定的类型匹配。

   以下示例根据名为 state 的变量值创建并删除配置映射：

   ---
   - name: set ConfigMap example-config to {{ state }}
     community.kubernetes.k8s:
       api_version: v1
       kind: ConfigMap
       name: example-config
       namespace: <operator_namespace> 1
       state: "{{ state }}"
     ignore_errors: true 2

   1

   指定要创建配置映射的命名空间。

   2

   设置 ignore_errors: true 可确保删除不存在的配置映射不会失败。

2. 修改 roles/<kind> /defaults/main.yml 文件，将默认 state 设置为 present：

   ---
   state: present

3. 通过在项目目录的顶层创建一个 playbook.yml 文件来创建一个 Ansible playbook，其中包含您的 <kind> 角色：

   ---
   - hosts: localhost
     roles:
       - <kind>

4. 运行 playbook：

   $ ansible-playbook playbook.yml

   输出示例

   [WARNING]: provided hosts list is empty, only localhost is available. Note that the implicit localhost does not match 'all'
   
   PLAY [localhost] ********************************************************************************
   
   TASK [Gathering Facts] ********************************************************************************
   ok: [localhost]
   
   TASK [memcached : set ConfigMap example-config to present] ********************************************************************************
   changed: [localhost]
   
   PLAY RECAP ********************************************************************************
   localhost                  : ok=2    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

5. 验证配置映射是否已创建：

   $ oc get configmaps

   输出示例

   NAME               DATA   AGE
   example-config     0      2m1s

6. 重新运行 playbook，设置 state 为 absent：

   $ ansible-playbook playbook.yml --extra-vars state=absent

   输出示例

   [WARNING]: provided hosts list is empty, only localhost is available. Note that the implicit localhost does not match 'all'
   
   PLAY [localhost] ********************************************************************************
   
   TASK [Gathering Facts] ********************************************************************************
   ok: [localhost]
   
   TASK [memcached : set ConfigMap example-config to absent] ********************************************************************************
   changed: [localhost]
   
   PLAY RECAP ********************************************************************************
   localhost                  : ok=2    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

7. 验证配置映射是否已删除：

   $ oc get configmaps

流程

1. 为自定义资源（CR）安装自定义资源定义（CRD）和正确的基于角色的访问控制（RBAC）定义：

   $ make install

   输出示例

   /usr/bin/kustomize build config/crd | kubectl apply -f -
   customresourcedefinition.apiextensions.k8s.io/memcacheds.cache.example.com created

2. 运行 make run 命令：

   $ make run

   输出示例

   /home/user/memcached-operator/bin/ansible-operator run
   {"level":"info","ts":1612739145.2871568,"logger":"cmd","msg":"Version","Go Version":"go1.15.5","GOOS":"linux","GOARCH":"amd64","ansible-operator":"v1.10.1","commit":"1abf57985b43bf6a59dcd18147b3c574fa57d3f6"}
   ...
   {"level":"info","ts":1612739148.347306,"logger":"controller-runtime.metrics","msg":"metrics server is starting to listen","addr":":8080"}
   {"level":"info","ts":1612739148.3488882,"logger":"watches","msg":"Environment variable not set; using default value","envVar":"ANSIBLE_VERBOSITY_MEMCACHED_CACHE_EXAMPLE_COM","default":2}
   {"level":"info","ts":1612739148.3490262,"logger":"cmd","msg":"Environment variable not set; using default value","Namespace":"","envVar":"ANSIBLE_DEBUG_LOGS","ANSIBLE_DEBUG_LOGS":false}
   {"level":"info","ts":1612739148.3490646,"logger":"ansible-controller","msg":"Watching resource","Options.Group":"cache.example.com","Options.Version":"v1","Options.Kind":"Memcached"}
   {"level":"info","ts":1612739148.350217,"logger":"proxy","msg":"Starting to serve","Address":"127.0.0.1:8888"}
   {"level":"info","ts":1612739148.3506632,"logger":"controller-runtime.manager","msg":"starting metrics server","path":"/metrics"}
   {"level":"info","ts":1612739148.350784,"logger":"controller-runtime.manager.controller.memcached-controller","msg":"Starting EventSource","source":"kind source: cache.example.com/v1, Kind=Memcached"}
   {"level":"info","ts":1612739148.5511978,"logger":"controller-runtime.manager.controller.memcached-controller","msg":"Starting Controller"}
   {"level":"info","ts":1612739148.5512562,"logger":"controller-runtime.manager.controller.memcached-controller","msg":"Starting workers","worker count":8}

   现在，Operator 会监控 CR 的事件，创建 CR 将触发您的 Ansible 角色运行。

   注意

   考虑 config/samples/<gvk>.yaml CR 清单示例：

   apiVersion: <group>.example.com/v1alpha1
   kind: <kind>
   metadata:
     name: "<kind>-sample"

   因为未设置 spec 字段，所以调用 Ansible 时无额外变量。其他部分将涵盖从 CR 传递给 Ansible 的额外变量。为 Operator 设置适当的默认值是很重要的。

3. 创建 CR 实例，并将默认变量 state 设置为 present：

   $ oc apply -f config/samples/<gvk>.yaml

4. 检查 example-config 配置映射是否已创建：

   $ oc get configmaps

   输出示例

   NAME                    STATUS    AGE
   example-config          Active    3s

5. 修改 config/samples/<gvk>.yaml 文件，将 state 字段设置为 absent。例如：

   apiVersion: cache.example.com/v1
   kind: Memcached
   metadata:
     name: memcached-sample
   spec:
     state: absent

6. 应用更改：

   $ oc apply -f config/samples/<gvk>.yaml

7. 确认配置映射已被删除：

   $ oc get configmap

流程

1. 运行以下 make 命令来构建和推送 Operator 镜像。在以下步骤中修改 IMG 参数来引用您可访问的库。您可以获取在存储库站点（如 Quay.io）存储容器的帐户。

   1. 构建镜像：

      $ make docker-build IMG=<registry>/<user>/<image_name>:<tag>

      注意

      由 SDK 为 Operator 生成的 Dockerfile 需要为 go build 明确引用 GOARCH=amd64。这可以在非 AMD64 构架中使用 GOARCH=$TARGETARCH。Docker 自动将环境变量设置为 -platform 指定的值。对于 Buildah，需要使用 -build-arg 来实现这一目的。如需更多信息，请参阅多个架构。

   2. 将镜像推送到存储库：

      $ make docker-push IMG=<registry>/<user>/<image_name>:<tag>

      注意

      镜像的名称和标签，如 IMG=<registry> /<user> /<image_name>:<tag>，在两个命令中都可在您的 Makefile 中设置。修改 IMG ?= controller:latest 值来设置您的默认镜像名称。

2. 运行以下命令来部署 Operator：

   $ make deploy IMG=<registry>/<user>/<image_name>:<tag>

   默认情况下，这个命令会创建一个带有 Operator 项目名称的命名空间，格式为 <project_name>-system，用于部署。此命令还从 config/rbac 安装 RBAC 清单。

3. 运行以下命令验证 Operator 是否正在运行：

   $ oc get deployment -n <project_name>-system

   输出示例

   NAME                                    READY   UP-TO-DATE   AVAILABLE   AGE
   <project_name>-controller-manager       1/1     1            1           8m

流程

1. 更新 watches.yaml 文件，把一个 manageStatus 项设置为 false：

   - version: v1
     group: api.example.com
     kind: <kind>
     role: <role>
     manageStatus: false

2. 使用 operator_sdk.util.k8s_status Ansible 模块来更新子资源。例如，使用键 test 和值 data 更新，operator_sdk.util 可以按以下方式使用：

   - operator_sdk.util.k8s_status:
       api_version: app.example.com/v1
       kind: <kind>
       name: "{{ ansible_operator_meta.name }}"
       namespace: "{{ ansible_operator_meta.namespace }}"
       status:
         test: data

3. 您可以为角色在 meta/main.yml 文件中声明集合，用于构建基于 Ansible 的 Operator：

   collections:
     - operator_sdk.util

4. 在角色 meta 中声明集合后，您可以直接调用 k8s_status 模块：

   k8s_status:
     ...
     status:
       key1: value1