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. 对 Operator 的 Dockerfile 进行以下更改：

   1. 将 ansible-operator-2.11-preview 基础镜像替换为 ansible-operator 基础镜像，并将版本更新至 1.31.0，如下例所示：

      Dockerfile 示例

      FROM quay.io/operator-framework/ansible-operator:v1.31.0

   2. Ansible Operator 版本 1.30.0 中的 Ansible 2.15.0 的更新删除了以下预安装的 Python 模块：

      • ipaddress
      • openshift
      • jmespath
      • cryptography
      • oauthlib

      如果您的 Operator 依赖于其中一个删除的 Python 模块，请更新 Dockerfile 以使用 pip install 命令安装所需的模块。

2. 编辑 Operator 项目的 makefile，将 Operator SDK 版本更新至 1.31.0，如下例所示：

   makefile 示例

   # Set the Operator SDK version to use. By default, what is installed on the system is used.
   # This is useful for CI or a project to utilize a specific version of the operator-sdk toolkit.
   OPERATOR_SDK_VERSION ?= v1.31.0 1

   1

   将版本从 1.28.0 更改为 1.31.0。

3. 更新 requirements.yaml 和 requirements.go 文件，以删除 community.kubernetes 集合，并将 operator_sdk.util 集合更新至版本 0.5.0，如下例所示：

   requirements.yaml 文件示例

     collections:
   -  - name: community.kubernetes 1
   -    version: "2.0.1"
      - name: operator_sdk.util
   -    version: "0.4.0"
   +    version: "0.5.0" 2
      - name: kubernetes.core
        version: "2.4.0"
      - name: cloud.common

   1

   删除 community.kubernetes 集合

   2

   将 operator_sdk.util 集合更新至 0.5.0 版本。

4. 从 molecule/kind/molecule.yml 和 molecule/default/molecule.yml 文件中删除 lint 字段的所有实例，如下例所示：

     ---
     dependency:
       name: galaxy
     driver:
       name: delegated
   -   lint: |
   -     set -e
   -     yamllint -d "{extends: relaxed, rules: {line-length: {max: 120}}}" .
     platforms:
       - name: cluster
         groups:
   	- k8s
     provisioner:
       name: ansible
   -     lint: |
   -       set -e
         ansible-lint
       inventory:
         group_vars:
   	all:
   	  namespace: ${TEST_OPERATOR_NAMESPACE:-osdk-test}
         host_vars:
   	localhost:
   	  ansible_python_interpreter: '{{ ansible_playbook_python }}'
   	  config_dir: ${MOLECULE_PROJECT_DIRECTORY}/config
   	  samples_dir: ${MOLECULE_PROJECT_DIRECTORY}/config/samples
   	  operator_image: ${OPERATOR_IMAGE:-""}
   	  operator_pull_policy: ${OPERATOR_PULL_POLICY:-"Always"}
   	  kustomize: ${KUSTOMIZE_PATH:-kustomize}
       env:
         K8S_AUTH_KUBECONFIG: ${KUBECONFIG:-"~/.kube/config"}
     verifier:
       name: ansible
   -     lint: |
   -       set -e
   -      ansible-lint

流程

1. 安装 Ansible 2.15+：

   $ sudo dnf install ansible

2. 安装 Python Kubernetes 客户端软件包 ：

   $ pip install kubernetes

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

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

     $ ansible-galaxy collection install community.kubernetes

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

     安装来自 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