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를 빌드하고 내보냅니다. 내보낼 수 있는 레지스트리를 사용하는 이미지의 가져오기 사양에 IMG를 설정합니다.

   $ 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 -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(사용자 정의 리소스) 사양의 키-값 쌍은 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
      • 암호화
      • oauthlib

      Operator가 이러한 제거된 Python 모듈 중 하나에 의존하는 경우 pip install 명령을 사용하여 필요한 모듈을 설치하도록 Dockerfile을 업데이트합니다.

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

   버전을 {osdk_ver-n1} 에서 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 컬렉션을 설치합니다.

   • Ansible Galaxy에서 컬렉션을 직접 설치할 수 있습니다.

     $ ansible-galaxy collection install community.kubernetes

   • Operator를 이미 초기화한 경우 프로젝트의 최상위 수준에 requirements.yml 파일이 있을 수 있습니다. 이 파일은 Operator 작동을 위해 설치해야 하는 Ansible 종속 항목을 지정합니다. 기본적으로 이 파일은 community.kubernetes 컬렉션과 Operator별 기능에 대한 모듈 및 플러그인을 제공하는 operator_sdk.util 컬렉션을 설치합니다.

     requirements.yml 파일에서 종속 모듈을 설치하려면 다음을 수행합니다.

     $ ansible-galaxy collection install -r requirements.yml

프로세스

1. Ansible 기반 Operator 프로젝트 디렉터리에서 원하는 Ansible 논리로 roles/<kind>/tasks/main.yml 파일을 수정합니다. roles/<kind>/ 디렉터리는 API를 생성하는 동안 --generate-role 플래그를 사용할 때 생성됩니다. 교체 가능한 <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 플레이북을 생성하고 <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. 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. 기본 변수 state를 present로 설정하여 CR 인스턴스를 생성합니다.

   $ 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>

      참고

      Operator용 SDK에서 생성한 Dockerfile은 Go 빌드에 대해 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>

   기본적으로 이 명령은 <project_name>-system 형식으로 된 Operator 프로젝트 이름을 사용하여 네임스페이스를 생성하고 배포에 사용됩니다. 이 명령은 또한 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. manageStatus 필드를 false로 설정하여 watches.yaml 파일을 업데이트합니다.

   - 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. 역할 메타에 컬렉션을 선언한 후에는 k8s_status 모듈을 직접 호출할 수 있습니다.

   k8s_status:
     ...
     status:
       key1: value1