Tadej Borov
모듈 문서는 Ansible 시나리오 작성자의 시작점입니다.따라서 중요한 것은 상술한 문서와 모듈을 동기화시켜야 한다. 그렇지 않으면 분노의 오류 보고를 받을 수 있다.문제는 바로 여기에 있다.
문서 유지와 실현 사이의 동기화는 불가능한 것이 아니다.왜?각 Ansible 모듈에는 두 개의 매개변수 관련 정보의 복사본이 포함되어 있기 때문입니다.모듈 관리자는 먼저 모든 모듈의 매개 변수를 기록한 다음에 약간 변환된 설명을 매개 변수 검증기에 복사해야 한다.
현재 Ansible 모듈에서 중복 정보를 제거할 수 없습니다.따라서 우리는 다음 가장 좋은 일을 하기로 결정했다. 자동으로 부본을 검증기 부분으로 보내는 것이다.승리를 위해 게으르다;

용어에 대한 간략한 설명

본고의 매개 변수, 옵션과 매개 변수는 모두 같은 의미를 가지고 있다.Ansible 시나리오 작성자가 Ansible 모듈에 전달한 데이터를 나타냅니다.
그렇다면 왜 다른 단어로 같은 일을 묘사해야 합니까?Ansible 문서는 이름 매개 변수를 사용하기 때문에 Ansible 모듈의 문서 블록은 옵션을 사용합니다. 검증과 관련된 코드는 그것들을 매개 변수라고 부릅니다.왜냐하면

어디에 문제가 생겼는가

모든 Ansible 모듈은 different sections으로 구성되어 있지만 오늘 우리는 그 중 두 개의 모듈에만 흥미를 느낀다. [documentation Block] [doc]와 AnsibleModule 실례화.

문서 블록

문서 부분은 내부 연결된 YAML 문서로 모든 모듈 매개 변수에 대한 설명이 이 키에 포함되어 있습니다.예를 들어, 다음과 같은 간단한 모듈 옵션을 설명합니다.

DOCUMENTATION = """
module: some.awesome.thing
short_description: Manage resources
options:
  name:
    description:
      - Resource name.
    type: str
    required: true
  state:
    description:
      - Resource's desired state.
    type: str
    choices: [ present, absent ]
    default: present
"""

이전 매개변수 설명을 HTML로 표시하면 다음과 같은 테이블 행이 반환됩니다.

매개 변수 문서 캡처.
웹 브라우저보다 터미널을 선호하는 사람(hello brothers And sisters)은 ansible-doc 유틸리티를 사용하여 이 정보를 콘솔에 출력할 수 있다.
완벽한 세상에서 Ansible playbook의 작성자는 API 문서를 먼저 읽고 어떤 오류도 범하지 않고 임무를 작성합니다.그러나 불행하게도, 우리는 실수가 실제로 발생하는 세계에 살고 있으며, 대다수 사람들은 문제가 발생할 때만 문서를 읽는다.현실에 직면하게 하기 때문에 그들을 나무라기 어렵다. 우리 개발자가 작성한 대부분의 문서는 쓰레기이다.)

Ansible Module 인스턴스화

최소한 Ansible 시나리오의 오류를 잡으려고 하기 때문에, Ansible 모듈은 그들의 파라미터를 검증할 것입니다.위 문서의 예제 옵션에 대해 AnsibleModule을 다음과 같이 실례화합니다.

def main():
    argument_spec = dict(
        name=dict(
            type="str", required=True,
        ),
        state=dict(
            type="str", default="present", choices=["present", "absent"],
        ),
    )

    module = AnsibleModule(
        argument_spec=argument_spec,
    )

이렇게 해서 우리는 몇 가지 정보를 복제하여 DRY principle을 깨뜨리고 문서와 검증이 동기화되는 길을 걷게 되었다.

중복 문제 처리 - 실행 가능한 방법

그렇다면 Ansible은 현재 정보 중복 문제를 어떻게 처리하고 있습니까?요컨대 사실은 결코 그렇지 않다.Ansible은 두 정보 사본 사이의 오류를 감지하는 방법을 제공합니다.
validate-modules 건전성 테스트는 API 문서와 파라미터 규범 간의 차이를 보고하지만, 우리는 여전히 수동으로 그것들을 해결해야 한다.예를 들어, 매개변수 사양명세에서 상태 매개변수의 기본값을 absent으로 변경하면 Ansible의 상태 테스트에서 다음 오류가 보고됩니다.

$ ansible-test sanity --requirements --test validate-modules
ERROR: plugins/modules/thing.py:0:0: doc-default-does-not-match-spec:
    Argument 'state' in argument_spec defines default as ('absent') but
    documentation defines default as ('present')

기존 Ansible 모듈을 사용하는 경우 이러한 테스트 및 복구 방법은 매우 효과적입니다.이런 상황에서 매개 변수의 변경은 통상적으로 매우 작아서 오류 메시지 계수를 매우 낮게 한다.그러나 우리가 새로운 Ansible 모듈을 작성하고 있다면 일은 내리막길을 걷기 시작할 것이다.Ansible 모듈에 수많은 매개 변수가 포함되어 있는 상황에서 우리는 곧 수백 개의 오류가 발생할 것이다.

매개 변수 규범 생성기 도입

기존 Ansible 컬렉션에 새 모듈을 추가하는 경우가 많기 때문에 정보의 초기 동기화를 처리하는 데 상당한 개발 시간을 들였습니다.
이로써 우리는 ansible-argspec-gen 도구를 개발했고 이 도구는 모듈 문서에서 파라미터 규범을 직접 생성할 것이다.예, 개발자가 사물을 명명하는 것을 허용해서는 안 됩니다.)
다음은 ansible-argspec-gen 도구의 작동 방법입니다.

Ansible 모듈에서 먼저 문서 추출

그리고 추출한 문서

에서 매개 변수 규범을 생성합니다
마지막으로, 이것은 표시 사이에서 모듈의 원본 코드를 업데이트합니다.이것은 우리의 예시 모듈에서 어떻게 작동할지 봅시다.모듈의 소스 코드에 태그를 추가하면 다음과 같은 결과가 나타납니다.

def main():
    # AUTOMATIC MODULE ARGUMENTS
    argument_spec = dict(
        name=dict(
            type="str", required=True,
        ),
        state=dict(
            type="str", default="present", choices=["present", "absent"],
        ),
    )
    # AUTOMATIC MODULE ARGUMENTS

    module = AnsibleModule(
        argument_spec=argument_spec,
    )

예시에서 기본 태그 텍스트를 사용하지만, --marker 매개 변수를 통해 사용자 정의할 수 있습니다.현재 우리는 발전기를 운행할 준비가 되어 있다.

$ ansible-argspec-gen sample.py 

마지막 명령이 종료되면 모듈은 다음과 같습니다.

def main():
    # AUTOMATIC MODULE ARGUMENTS
    argument_spec = {
        "name": {"required": True, "type": "str"},
        "state": {
            "choices": ["present", "absent"],
            "default": "present",
            "type": "str",
        },
    }
    # AUTOMATIC MODULE ARGUMENTS

    module = AnsibleModule(
        argument_spec=argument_spec,
    )

마법하지만 더 많아요.이 도구에 --diff 스위치를 사용할 경우 콘솔 인쇄 모듈도 변경됩니다.

$ ansible-argspec-gen --diff sample.py 
--- sample.py.old
+++ sample.py.new
@@ -20,14 +20,14 @@

 def main():
     # AUTOMATIC MODULE ARGUMENTS
-    argument_spec = dict(
-        name=dict(
-            type="str", required=True,
-        ),
-        state=dict(
-            type="str", default="present", choices=["present", "absent"],
-        ),
-    )
+    argument_spec = {
+        "name": {"required": True, "type": "str"},
+        "state": {
+            "choices": ["present", "absent"],
+            "default": "present",
+            "type": "str",
+        },
+    }
     # AUTOMATIC MODULE ARGUMENTS

     module = AnsibleModule(

프로그램의 반환 코드는 실행 중 발생한 상황을 나타냅니다.

0은 모든 것이 변하지 않았다는 것을 의미한다.

1은 도구가 최소한 하나의 모듈을 업데이트했음을 나타낸다.

2은 실행 중 오류가 발생했음을 나타냅니다.

만약 우리가 상태 코드와 --dry-run 스위치를 결합하면 무엇을 얻을 수 있습니까?개발자가 이 도구를 실행하는 것을 잊지 않도록 우리의 지속적인 통합 파이프라인을 검사하십시오.천만에요.
이 도구는 문서에서 각종 제약을 추출하는 등 다른 기교도 실행할 수 있다.그러나 우리는 이 정보를 다른 게시물에 남길 것이다.동시에 GitHub gist에 있는 sample module을 가지고 놀 수 있습니다.

어디서 시작 해요?

현재 문제를 해결하는 정확한 방법은 코드에서 중복된 항목을 삭제하는 것이다.그러나 이것은 쉽게 실현되는 것이 아니다. 왜냐하면 모듈이 운행할 때 documentation fragments에서 온 정보를 얻을 수 없기 때문이다.
따라서 매개 변수 규범 생성기가 언뜻 보기에 얼마나 추하든지 간에 이것은 현재 정보에 대항하여 동기화하는 가장 좋은 무기이다.
이게 복잡하게 들려요?손과 reach out을 더럽히지 마세요.우리 팀의 도움으로 아주 짧은 시간 안에 고품질의 Ansible 통합을 실현하였다.우리는 이미 너를 위해 이 무거운 짐을 질 준비가 되어 있다.
건배!