役割ロール仕様

Tadej Borov語AKによる語
我々の最後のハードコア技術的なポスト以来、それはしばらくありました.だから私たちは蒸し暑いことにしたcloud posts アンディケーションコア2.11の新機能の1つで、一瞬一瞬、汚くなってしまいます.
私たちは、どのようにして適切な役割をどのようにパラメタ化できるか、そして、それらを使用するとき、我々が予想することができるどんな問題の簡単な説明から始めます.次に、適切なロールについての議論仕様の高レベルの概要を説明し、可用性のある脚本とロール著者に対する利点を説明し、簡単な例を説明します.
そして、私たちと苦々しい終わりに固執するあなたのそれらのために、我々は議論仕様開発についての短い話さえ投げるでしょう.
健全な計画のような音?——

必要条件
あなたが沿って続くことを望むならば、あなたはansible-core Pythonパッケージ.システムを混乱させないようにするには、新しい仮想環境にアンコアをインストールする必要があります.

$ python3 -m venv venv
$ . venv/bin/activate
(venv) $ pip install --pre ansible-core

The last command installed a prerelease version of Ansible Core. That version contains a critical bug fix that we need and is not part of the latest stable release yet. Stick to the end if you are interested in gory details.

sensu - go - ansibleコレクションがインストールされている必要があります.

(venv) $ ansible-galaxy collection install "sensu.sensu_go:<1.11"

インストールが邪魔になっているので、我々は理解できない役割とその議論について話すことができます.

役割引数
厳密に言えば、不可解な役割には引数がありません.しかし、変数でパラメータ化することができます.一般的に、可用性のある本はこのように見えます.

---
- name: Install Sensu components
  hosts: all
  become: true

  tasks:
    - name: Install backend
      include_role:
        name: sensu.sensu_go.install
      vars:
        components: [ sensu-go-agents ]

もちろん、タスク自体に変数を設定する必要はありません.変数の値は多種多様なソースから来ることができます、しかし、我々はそれらを単純さのためにincludeタスクに近いと定義しました.
今日のもっともらしいロール変数を文書化する最も一般的な方法はREADME文書で記述することです.なぜ?不可解な銀河がそれを示す方法を知っているので.The Apache Cassandra Ansible role を含むgreat example .
不可解なコレクションの導入で、物事は少し複雑になった.可用性の高いコレクションには、複数の実行可能なロールを含めることができますので、すべての情報を単一のREADMEファイルに配置することは、ほとんど不愉快にならずに不可能です.のためにSensu Go Ansible Collection , 私たちは、この問題を解決するdocumentation site . 各扇子の役割は、専用のセクションがあります.
可用性の高いロール変数を記述すると、すべての必要な情報を再生可能な脚本家に与えます.しかし、まだ1つの主要な問題があります:私たちはプレイブック作者に依存しない入力とコピーペーストの間違いをする.そして、さらに悪いことをするために、そのようなTyposは通常、比較的遅れることを明らかにします.
例えば、このセクションの開始から我々の可用性のある脚本を走らせるならば、我々は以下のような出力を見ます:

PLAY [Install Sensu components] ******************************************

TASK [Gathering Facts] ***************************************************
ok: [default]

TASK [Install backend] ***************************************************

TASK [sensu.sensu_go.install : Prepare package repositories] *************
included: /home/tadej/.../tasks/repositories.yml for default

TASK [sensu.sensu_go.install : Prepare package repositories] *************
included: /home/tadej/.../tasks/dnf/prepare.yml for default

TASK [sensu.sensu_go.install : Include distro-specific vars (CentOS)] ****
ok: [default]

TASK [sensu.sensu_go.install : Add yum repository] ***********************
changed: [default]

TASK [sensu.sensu_go.install : Add yum source repository] ****************
changed: [default]

TASK [sensu.sensu_go.install : Install selected packages] ****************
included: /home/tadej/.../tasks/packages.yml for default

TASK [sensu.sensu_go.install : Install selected components (Linux)] ******
included: /home/tadej/.../tasks/dnf/install.yml for default

TASK [sensu.sensu_go.install : Install component] ************************
failed: [default] (item=sensu-go-agents) => {
  "ansible_loop_var": "item",
  "changed": false,
  "failures": ["No package sensu-go-agents available."],
  "item": "sensu-go-agents",
  "msg": "Failed to install some of the specified packages",
  "rc": 1,
  "results": []
}

PLAY RECAP ***************************************************************
default                    : ok=8    changed=2    unreachable=0    failed=1
                                        skipped=0    rescued=0    ignored=0   

見ることができるように、それらのうちの1つが失敗する前に、ansibleはかなりの数の仕事を実行しました.エラーメッセージは特に失敗したモジュールに依存しています.(分かりやすい脚本の中でエラーを見つけることができますか?
すべての必要な変数が設定され、許容値を含むことを確認する1つの方法は ansible.builtin.assert それぞれのタスクファイルの開始時のタスク.このように、実行可能なロール実行の開始時にエラーが発生します.
タスクファイルの先頭にAssertタスクを追加するには、1つの主な欠点があります.しかし、我々がその情報複製を取り除くことができるならば、我々は金色です.そして、これは正確に引数仕様が我々がすることができるものです.

引数仕様
引数の仕様は、その本質的には、マシンの実行可能な実行可能なドキュメントです.

それは源として役立つansible-doc 使用可能なロールの参照ドキュメントを作成できます.

ansible-playbook 使用可能なロールが実行される前に変数値を検証します.

我々が現在最新の安定版に我々のsensu試みansibleなコレクションを更新するならば.ansible-doc は以下の出力を生成します:

(venv) $ ansible-galaxy collection install "sensu.sensu_go:>=1.11"
(venv) $ ansible-doc --type role --list
sensu.sensu_go.agent   configure    Configure Sensu Go agent
sensu.sensu_go.agent   start        Start Sensu Go agent
sensu.sensu_go.agent   main         Install, configure, and start Sensu Go
sensu.sensu_go.backend configure    Configure Sensu Go backend
sensu.sensu_go.backend start        Start Sensu Go backend
sensu.sensu_go.backend main         Install, configure, and start Sensu Go
sensu.sensu_go.install repositories Enable Sensu Go repos
sensu.sensu_go.install packages     Install selected Sensu Go packages
sensu.sensu_go.install main         Enable Sensu Go repos and install

前に扇子囲碁コレクションを使用していた方はお役に立ちました.しかし、なぜそれぞれのsensu - go可能な役割のために3行がありますか?
全ての扇子の役割はモジュールです.それぞれに3つのエントリポイントがありますansible-doc 2列目のリスト.そして、あなたはエントリポイントのことを聞いたことがない場合:彼らは不可解な脚本家は、不可解な役割から個別にインポートできるタスクファイルです.
もっともよく知られている役割は、1つのエントリポイントだけですmain この実行可能なロールを含めると、デフォルトで実行可能です.しかし、賢明な脚本家はまた、設定することによって別のエントリポイントを選択することができます tasks_from parameter を返します.
我々は、ドキュメントを得ることができますmain エントリポイントは、以下のコマンドを実行して、サンプルを再生可能にします.

(venv) $ ansible-doc --type role --entry-point main sensu.sensu_go.install
> SENSU.SENSU_GO.INSTALL
  (/home/tadej/.ansible/collections/ansible_collections/sensu/sensu_go)

ENTRY POINT: main - Enable Sensu Go repos and install selected packages

        The main entry point just combines the repositories and
        packages entry points.

OPTIONS (= is mandatory):

- build
        Package build to install.
        Can be any valid build string such as `8290' or a special
        value latest.
        If the `version' variable is set to latest, this variable is
        ignored and the latest available build is installed.
        [Default: latest]
        type: str

- channel
        Repository channel that serves as a source of packages.
        Visit the packagecloud site to find all available channels.
        [Default: stable]
        type: str

- components
        List of components to install.
        (Choices: sensu-go-backend, sensu-go-agent, sensu-go-
        cli)[Default: ['sensu-go-backend', 'sensu-go-agent', 'sensu-
        go-cli']]
        elements: str
        type: list

- version
        Package version to install.
        Can be any valid version string such as `6.2.5' or special
        value `latest'.
        [Default: latest]
        type: str

の出力ansible-doc コマンドが多かれ少なかれ、我々のドキュメントで利用可能なドキュメントを複製しますdocumentation site .
我々が現在再実行するならばansible-playbook コマンドを実行します.

PLAY [Install Sensu components] ******************************************

TASK [Gathering Facts] ***************************************************
ok: [default]

TASK [Install backend] ***************************************************

TASK [sensu.sensu_go.install : Validating arguments against arg ] ********
fatal: [default]: FAILED! => {
  "argument_errors": [
    "value of components must be one or more of: sensu-go-backend,
     sensu-go-agent, sensu-go-cli. Got no match for: sensu-go-agents"
  ],
  ...
}

PLAY RECAP ***************************************************************
default                    : ok=1    changed=0    unreachable=0    failed=1
                                        skipped=0    rescued=0    ignored=0   

だってsensu.sensu_go.install 最新のsensu - go可用性コレクションのバージョンでは、タスクの実行を開始する前に、自動的に検証タスクを挿入しますmain エントリーポイント.そして、エラーメッセージは現在明確です:我々は、無効なコンポーネント名を入力しました.すごい!
そして、引数の仕様を使う方法を知っているので、簡単なものを書くときには頑張りましょう.

引数の指定
ここで述べる引数の仕様はmain エントリーポイントcomponents 引数.それで、ちょうど我々がポストを通して遊んでいたユースケースをカバーするのに十分です.そして、それ以上のADOなしで、ここで、それはその栄光のすべてです:

argument_specs:
  main:
short_description: Enable Sensu Go repos and install selected packages
description:
  - The main entry point just combines the repositories and packages
         entry points.
options:
  components:
    description:
      - List of components to install.
    type: list
    elements: str
    choices:
      - sensu-go-backend
      - sensu-go-agent
      - sensu-go-cli
    default:
      - sensu-go-backend
      - sensu-go-agent
      - sensu-go-cli

最初の6行はかなり自己説明的でなければなりません.彼らはいくつかの人間に読める情報をmain エントリーポイント.Ansibleは、この情報を生成されたドキュメントに追加します.
残りの部分は、ドキュメントが妥当性検査を満たしているところです.我々の場合はcomponents 変数は以下の規則に従わなければなりません:

文字列のリストでなければなりません(type: list and elements: str ).

扇子碁、扇子号、扇子碁の紐だけである.

デフォルトでは、変数はすべての有効なパッケージ名を保持します.

引数の指定をmeta/argument_specs.yml ファイルは、可用性を実行する前に変数を検証するために自動的に使用可能です.
引数仕様書の詳細についてはofficial documentation 詳細といくつかの追加サンプルが含まれます.またはgithubのロールディレクトリを参照repository SENSU GO ansibleコレクションについて.
そして、今日のポストの最高の部分のために:StoryTime!

CIが日を救う物語
最初の安定版リリースを見た直後に、SESSU - ANYコレクションのすべてのロールに引数仕様を追加しました.そして、物事は疑わしくスムーズに行きました:私たちのドキュメンテーションを議論仕様に変えるのに約1時間かかりました.
ANYコア2.11.0を使用して新しい機能をテストしたとき、すべてのチェックは緑色だった.それで、我々は少しものを磨いて、プル要求をつくりました.それからall hell broke loose .
我々はすべてのサポートされている賢明なバージョンに対する統合テストを実行します.そして、議論仕様の導入が許容可能な2.9と分別のあるベース2.10との後方の互換性を破ったことがわかりました.そして、それは公認のコレクションのためにありません.
コア開発者との簡単なチャットは、これは確かにbug 可用性コアで.幸いにも、私たちのために、不可解なコア開発者は素晴らしいです、そして、彼らは全くこれのために修正を準備しました.バグフィックスはまだ安定版リリースにはしていませんので、この投稿において可用性コアのプレリリース版を使用している理由です.

何を学びましたか
すべてが計画に従って行ったならば、あなたは現在、潜在的な役割パラメタリゼーションとどのように議論仕様があなたがあなたのオートメーションセットアップをより堅牢にするのを援助するかについて詳しく知っています.そして、あなたが前にエントリポイントを知っていなかった場合は、よく、今あなたがする;
また、あなたの分別のあるコレクションの品質がテストスイートの品質に大きく依存することも知りました.そして、最新の安定版のバージョンが出る前に、新しい機能をテストしようとするべきです.あなたは、不可解なコレクションをテストすることについてもっと知りたいならば、我々はIntro to testing Ansible Collections webinar .
また、もしあなたの役に立つコンテンツを作成またはアップグレードする必要がある場合は、無料でお気軽にcontact us . 我々は助けるために最善を尽くします.
乾杯!