てくなべ (tekunabe)

ansible / network automation / 学習メモ

3級 テクニカルライティング試験[TW]を受けてきました

はじめに

以前から文章に対する苦手意識がありました。

分かりやすく誤解されにくい文章を書くには?レビューで指摘したあの件、合っていたのかな?などなど・・。

何かのタイミングで体系的にテクニカルライティングを学んで見たいと思っていて、気になっていた「3級 テクニカルライティング試験[TW]」を本日受験してきました。

jtca.org

この記事では、やってきたことや、当日の感想などをまとめます。

(結果発表はまだです)

試験を知る

まずは、試験の説明ページをよく見て、試験の範囲や形式を確認しました。

例題でレベル感を確認して、いけなくもないかな・・・と思って受験することにしました。

想定する受験対象者として「製品の設計に関わるエンジニア」もあるので、親和性は高いと思います。

他にも、受験された方の記事を拝見しました。大変参考になりました。

勉強方法

書籍

現状は「日本語スタイルガイド(第3版)」がバイブル(試験対策としてはこの本の主張が正解)とのことなので、これを読み込みました。

jtca.org

練習問題もあるので何回かやりました。回答に解説が書いてあると助かるのですが、載っていません・・。

こちらの書籍、試験対策としてだけでなく、とても役立つ内容でした。「よくやってしまうやつだ」「そう言われてみればそうだな」「なるほど、よく迷うけどそういう使い分けすればいいのか」といった発見がたくさんありました。

例:

  • 動詞に「こと」、「方法」などを付けに安易に名詞化しない(P104)

    • ✗ マウスを使用するという方法もあります。
    • ◯ マウスも使用できます。
  • 複数の修飾語がある場合は、長い修飾語・修飾部から順に記載する(P75)

    • ✗ コンパクトな多くの編集機能を搭載した複合機
    • ◯ 多くの編集機能を搭載したコンパクトな複合機
  • 「に」と「へ」を区別して使う(P78)
    • 「〜に」は、動作目標や到達点
    • 「〜へ」は、方向

P289 には、各分野のウェイトがA〜Dで示されているので、どこに注力すると良さそうかが分かります。優先して身につけたい分野と同じだったので良かったです。

ちなみに第4版は制作中のようです。

ウェビナー

一般財団法人テクニカルコミュニケーター協会が主催している、試験対策ウェビナーも参加しました。

日本語スタイルガイドをベースにしたポイントのおさらいや、練習問題の提供などがありました。

受験日当日

試験の形式は、選択問題が50分、休憩を挟んで記述問題が50分です。

総じて「時間がない」という印象でした。途中で何度か、これはだめかも知れないと思いました。

選択問題は以下の順番で解いていきました。

  1. すぐ解ける問題
  2. 少し考えれば解ける問題
  3. ほぼ当てずっぽうになりそうな問題

記述問題は、問題を解く前にペース配分(この問題を何時何分に始めれば順調か)を書いてから始めました。

こちらもやはり、特に時間がかかる問題は一旦とばしました。

結果としてはかなりギリギリでした。解答欄はすべて埋めましたが、もう15分くらい確認に時間が欲しかったです。

ひとことでいうと舐めていました。レベル感だけで判断してはいけませんね。慣れていないと問題をペースよくさばけていけません。。

(完全に余談ですが、お昼に入ったラーメン屋さんでASIAN KUNG-FU GENERATION の「リライト」が流れたのが面白かったです。リライト作業が求められるので)

感想

当日は思いの外あせって、疲れてしまいました。

ですが、勉強の段階で得られたものは大きかったです。

迷っていた書き方の判断ができるようになったり、なんとなく書き分けていた根拠が得られたり、自分の癖がわかったり。

合否はまだわかりませんが、良いきっかけになりました。

JANOG53 Meeting アーカイブ視聴レポート

はじめに

2024/01/17-19 に福岡県福岡市の博多国際展示場&カンファレンスセンターで JANOG53 Meeting が開催されました。

現地は私のチームの他の人に行ってもらいました。また、ストリーミングもなしということでしたので、アーカイブが公開(ありがとうざいます!)されてから視聴しました。

現地参加者は3000人を超えて、大盛りあがりだったようですね。すごい!

本記事では、アンケート締め切り前に視聴したいくつかのプログラムや、全体的な所感についてまとめます。

なお、各プログラムの詳細ページから資料や、アーカイブ動画が見れます(一部アーカイブなし)。アーカイブ動画は 2024/02/29 13:00 まで の公開です。

www.janog.gr.jp

Day1

海外で日本のやり方が通用しないの、なぁぜなぁぜ? 〜東南アジアでのインターネットインフラを構築の実例から、グローバルでのオペレータ交流を考える〜

www.janog.gr.jp

www.youtube.com

立松さんパート

BBIX のフィリピン展開にあたって、実際の経験からくるリアルなお話がたくさん聞けました。大きく分けると、文化の違いと物理的な事情からるくるように感じました。

いわゆる「日本品質」という考えに縛られずに、国によって求められる QCD のバランスをしっかり考える必要があるようでした。

物理的な事情でいうと、フィリピンでは、車両ナンバーの末尾によって走行できる日が規制されているそうです。交通という物理インフラの固有の事情は様々な場面に影響しそうですね。基本的に渋滞対策だそうです。他にも、現地での作業で機材が予定通りに届かないというトラブルなどでも苦労されたそうです。

これらの違いは一見、海外が変わってるようにも見えますが、逆に海外からると日本が変わっているという見方もあるように思います。立松さんパートにあった、なぜそうなってるのかを考えて、よく理解することが大切だという点が印象的でした。

私の場合、つい言語の壁がまっさきに思い浮かびましたが、それだけではないのですね。

また、SNS投稿禁止のパートなので内容の言及は避けますが、発表冒頭のアイスブレイクパートが大変興味深かったです。

冨樫さんパート

ジャカルタの JKT-IX の成長過程のお話でした。こちらのパートは、対人、コミュニケーション、周りの経験談がメインでした。

印象的だったのが、めぐりめぐって分かるJANOGの良さの話でした。

なんとなくの言葉の定義でコミュニケーションを取って問題になることがあるため、その話をIDNOGで問題定義しようと思っても、スポンサー枠もあってか、枠が空いてないという事情で発表できなかったそうです。一方で、JANOGは、自由公募で審査通過のみオペレーターが発表でき、この制度は素晴らしいというお話でした。こういうのも地域によって違うものですね。

お二方のパートを通じて新鮮なお話が聞け、品質や価値の捉え方について考えるきっかけになりました。

Day3

BIGLOBE AS2518をまるごと仮想環境へ”コピー”してみた

www.janog.gr.jp

www.youtube.com

自動化の文脈でも、検証環境がなかったり環境差分がったりというのは課題になりがちなので、以前から興味があるトピックでした。また、習熟が難しい構成ほど、習熟するための環境を用意することも難しい、というジレンマがあるようにも思います。タイトルに有るように、確かに ”コピー” ができたらよいなと思いました。

思うところまでは簡単にできますが、実際にやってみた、というところが今回のプログラムの貴重なところでした。一定の効果が見られた一方で、他ベンダー対応、インターフェース名の差分などの課題も出てきたようです。

どこまで頑張るか、どこまで例外を認めるかという話も難しいですね・・

NETCON Wrap-up

www.janog.gr.jp

www.youtube.com

定番化してきている、ネットワークエンジニアのためのコンテスト NETCON。ふりかえりと表彰式的なプログラムです。

参加者の 45.3% が 8時間以上 NETCON に取り組んだというアンケート結果があって驚きました。ものすごい熱意です・・。

優勝された方!

NETCONは環境に結構なお金(100万円くらい)がお金がかかっているという話もあって、資金的な課題があるようです。スポンサーなどの形式で資金的な援助があるとよいのでしょうか。

JANOG update

www.janog.gr.jp

www.youtube.com

本会議参加登録者数 3,028名。オンラインなしでもこの人数、いやぁすごいですね・・。

また、JANOG 45 から会長を努められていた吉野さんが会長を辞め、運営員会からも引退されるそうです。JANOG 45 というと 2020年1月開催。コロナ禍に突入する時期から今までということで、とても大変な時期だったと思います。お疲れ様でした。

最後のごあいさつのところで、ご自身のリーダーシップのスタイルを語られているところが印象的でした。自分は前に出るタイプではないが、そういうのでも良いというのが不思議で、すごく幸せな環境、と。

新しい会長は宮坂さん。よろしくおねがします!

他のアーカイブ視聴予定

本記事では、アンケートの締め切り(2024/02/04 23:59 まで)までに、アーカイブ視聴したプログラムのみ取り上げました。

他にも興味深いプログラムがあるため、アーカイブが公開されているうち(2024/02/29 13:00まで)に視聴しようと思います。主に以下のプログラムを中心に視聴予定です。

以下、アーカイブはありませんが、資料は拝見したいと思います。

プログラム以外

今回の JANOG 自体で感じたことなどです。

Slack のプログラムごとのチャンネル

これまでは会場の部屋ごとにチャンネルが用意されていました。

今回は、#janog53-インフラ運用ツール開発組織を1から組織した話 のようにプログラムごとにチャンネルが用意されていました。

私のようにアーカイブで見る場合、Slackを見返しやすくて便利に感じました。

インターネット体験会

すごい良い企画だなーとおもいました。物理の作業を体験できるのも貴重な機会だと思います。

www.janog.gr.jp

オンラインの扱いの変化

前回はストリーミングはあっても音声による質疑はできない仕組みでした(Slackは可)。今回はストリーミング自体がありませんでした。

申込時画面にもオンライン参加の選択肢はありませんでした。そのため、広島の JANOG 41での参加以降、初めて申し込みをしないで当日を迎えました。

ここ数年はコロナ禍の影響で、例外的にオンラインで参加しやすい体制を作っていただいていたという認識です。実際に少し前は、オンラインで質問やコメントをさせていただきました。

あまり詳細な経緯は追えていませんが、状況に合わせて変化していくものだと思っています。ハイブリッドも大変のようですからね。運営の方の判断を尊重したいと思います。

おわりに

今回は参加できず、アーカイブ視聴のみとなりましたが、現地が盛り上がっていたようで嬉しく感じました。登壇者、スタッフ、スポンサーのみなさまありがとうございました!

次回 JANOG54 Meeting は 2024年7月に奈良県奈良市で開催予定とのことです。その次が京都なので近畿が続きますね。

参考

show int さんの関連動画

www.youtube.com

www.youtube.com

togetter

私と JANOG のこれまで

[Ansible] 「つまずき Ansible 【Part38】ネットワークモジュールを VS Code でデバッグしたい」ふりかえり

はじめに

2024/02/04 に、「つまずき Ansible【Part38】ネットワークモジュールを VS Codeデバッグしたい」という配信をしました。

tekunabe.connpass.com

cisco.ios コレクションのモジュールのような、ネットワーク機器に接続して操作するとき、Playbook で指定したオプションがどのように処理されるのか、を知りたいときがあって、VS Code でステップ実行とかできたらいいなーと思っていました。

あくまでも Playbook を起点にデバッグしたかったです。

いろいろ試行錯誤した結果できるようになり、ブログよりもデモ中心にお見せしたほうが伝わりやすいと思い、久々に配信をしました。


動画

youtu.be

前提条件

今回の方法が通用するのは、わかっている範囲でいくつか条件があります。

  • ネットワークモジュールであること
    • つまり、コントロールノードでモジュールのコードが動作する
  • Direct Execution (import_modules) が有効であること
    • ansible.netcommon コレクション 3.0.0 からデフォルトで有効
    • つまり、コントロールノードで「圧縮→コピー→解凍」というフェーズを介さずにモジュールのコードが動作する

また、私の環境ではまだ macOS でしかできていません。Remote SSH で接続した先の Linux ではうまくブレークポイントを有効にできませんでした(類似事象 issue)。

([2024/02/27 追記] issue がクローズされ、参考ドキュメトがアップされていました)

仕込み

デバッガの定義ファイルである .vscode/launch.json には以下の定義をしてあります。

今回は、ansible もコレクションも ${workspaceFolder}/.venv にインストールしています。

programで、そのなかの ansible-playbook を指定しているのが一番のポイントです。

{
  // IntelliSense を使用して利用可能な属性を学べます。
  // 既存の属性の説明をホバーして表示します。
  // 詳細情報は次を確認してください: https://go.microsoft.com/fwlink/?linkid=830387
  "version": "0.2.0",
  "configurations": [
    {
      "name": "ansible-playbook: 現在のファイル",
      "type": "debugpy",
      "request": "launch",
      "console": "integratedTerminal",
      "program": "${workspaceFolder}/.venv/bin/ansible-playbook",   // ポイント
      "args": [
        "${file}",   // 開いているファイル
        "-i",
        "${workspaceFolder}/inventory.yml",    // イベントリファイル
        "-vvvvv"   // お好み
      ],
      "env": {
        // "PYTHONPATH": "${workspaceFolder}/.venv/lib/python3.11/site-packages/", // 試行錯誤の残骸
        // "ANSIBLE_COLLECTIONS_PATHS": "hogehoge",  // 必要に応じて
        "ANSIBLE_PERSISTENT_CONNECT_TIMEOUT": "0" // 必要に応じて(デバッグ中に接続断しないように)
      },
      "justMyCode": false, // モジュールのコードにブレークポイントを張るため
      // "subProcess": false, // 試行錯誤の残骸
    }
  ]
}

cisco.ios.ios_command モジュールのデバッグ

以下のような、show コマンドを実行する Playbook をデバッグします。

---
- name: Test play
  hosts: ios
  gather_facts: false

  tasks:
    - name: Test ios
      cisco.ios.ios_command:
        commands:
          - show interfaces

動かしたいファイルを開いている状態で、統合ターミナルではなく 「実行とデバッグ」経由で、launch.json で定義した ansible-playbook: 現在のファイル" を選択します。

デバッガの起動

すると、あらかじめ設定したブレークポイントのところで止まってくれます。

モジュール内部のブレークポイントで止まっている

少し進めると、Playbook で指定した show コマンドが入っていることがわかります。

show interfaces

変数の値は参照だけでなく変更もできます。この状態で show ip route にコマンドを書き換えて処理を実行すると、show ip route が実行されます。

show ip route に変更

cisco.ios.ios_interfaces モジュールのデバッグ

続いて、インターフェースの基本設定をする cisco.ios.ios_interfaces モジュールのデバッグを試します。

---
- name: Test play
  hosts: ios
  gather_facts: false

  tasks:
    - name: Configure interface
      cisco.ios.ios_interfaces:
        config:
          - name: GigabitEthernet0/0
            description: sakana

今回は、モジュール本体から呼ばれている別のファイルのところにブレークポイントを設定しました。wantd という変数に、Playbook で指定した、こうなってほしいという設定値が入っているのがわかります。

ステップ実行中

一方 haved の中には、機器から取得したインターフェースの今の設定が入っているのがわかります。

haved の中身

今度はちょっと変わった例として、以下のような変なインターフェースの名前を Playbookで指定してデバッグします。

          - name: Giggegegegeggegerrjii0/0

処理を追っていくと、normalize_interface で、インターフェースの名前のノーマライズをしていることがわかります。ここでは、小文字に変換したうえで gi から始まれば、GigabitEthernet として扱う、ということがわかります。

github.com

ノーマライズ判定

おわりに

コードを読む力があれば、デバッグしなくても処理が理解できると思うのですが、私はこのようにステップ実行して見れると非常にありがたいです。

配信方法を急遽 YouTube Live から Zoom に切り替えたため、参加者の皆様にはお手数おかけしました・・。 それでもご視聴いただいた皆さん、ありがとうございました!

参考

VS Code の基本やデバッグについては、最近発売された「改訂新版 Visual Studio Code実践ガイド」がおすすめです。いろいろと新しい機能についても説明されています。

[Ansible] ansible-lint で hosts ディレクティブに変数が含まれると発生するエラーの対処案2つ

はじめに

hosts: "{{ targets }}" のように、hosts に変数を利用していると、ansible-lint のチェックで変数未定義のエラーになってしまいます。

$ ansible-lint debug.yml 
WARNING  Listing 1 violation(s) that are fatal
syntax-check[specific]: The field 'hosts' has an invalid value, which includes an undefined variable. The error was: 'targets' is undefined. 'targets' is undefined
assert.yml:2:3


                  Rule Violation Summary                   
 count tag                    profile rule associated tags 
     1 syntax-check[specific] min     core, unskippable    

Failed: 1 failure(s), 0 warning(s) on 1 files.

これにひっかかると、他のチェックがされなくなるのでどうにかしたいところです。

かといって、このチェックは .config/ansible-lint.yml の設定の skip_list に指定してスキップすることはできません。

私が分かっている範囲では、これを回避するには2つの方法があります。

  • 検証環境
    • ansible-lint 6.22.2

対処案1: default フィルターを利用

ルール syntax-check の説明ページにもありますが、変数未定義時の代わりの値を指定する default フィルターを利用する方法です。これ自体はもともと Ansible でも利用できる機能です。

---
- name: Test play
  hosts: "{{ targets | default([]) }}"
  gather_facts: false
  connection: local

  tasks:
    - name: Debug
      ansible.builtin.debug:
        msg: Hello

こんな風にしておけば、変数未定義のエラーは起こらなくなります。

対処案2: ansible-lint としての extra_vars で定義しておく

対処案1では Playbook を修正する必要がありますが、修正したくない場合こちらの案が候補になります。

ansible-lint の設定ファイル内の extra_vars で変数を定義しておけばエラーは起こらなくなります。

  • .config/ansible.yml:
---
extra_vars:
  targets: []

Playbook は以下の通り。default フィルターは利用しません。

---
- name: Test play
  hosts: "{{ targets }}"
  gather_facts: false
  connection: local

  tasks:
    - name: Debug
      ansible.builtin.debug:
        msg: Hello

おわりに

設定ファイルが思いのほか気が利いてるので、一度目を通すと新しい発見があるかもしれません。

ansible.readthedocs.io

参考

関連 issue

github.com

[Ansible] 公式ドキュメントのあのページ、どこにいった?を探す

はじめに

コレクションというモジュール類の管理単位がだいぶ浸透してきてると思いますが、それに伴ってか、ドキュメント上にも変化が見られます。

もともとAnsible本体側にあったページがコレクション側に移動してたりします。

コレクション側に移動しているページ

一部ですが、コレクション側に移動しているクラウド・仮想化系ページの例をご紹介します。

分野 以前のページ 現在のページ(コレクション側)
AWS 以前のページ 現在のページ(コレクション側)
VMware 以前のページ 現在のページ(コレクション側)
VMware REST 以前のページ 現在のページ(コレクション側)

おわりに

あれどこいったかな?というときは、どのコレクションか見当がつくのであれば Collection Index から追ってみると見つかるかもしれません。

たとえば、community.general コレクショには、現状 2つのガイドがあります。結構詳しいです。各モジュールやプラグインのページで情報が足りないときに便利です。

docs.ansible.com

[TTP] スペース含めて値を取得する

はじめに

ネットワーク機器の show コマンドのパーサーとして TextFSM や TTP (Template Text Parser) を使い分けています。

個人的には TTP が直感的に使える一方で、ちょっとしたことでつまずくことがあります。

例えば今回紹介する、スペースを含めて値を取得する場合です。

何も考えずにやると・・

例えば以下のコンフィグがある場合、

interface GigabitEthernet0/0
 description kingyo ugui oikawa
 negotiation auto

なんとなくで、以下のテンプレートにすると

<group name="interfaces">
interface {{ interface }}
 description {{ description }}
</group>

以下の結果になります。description が拾えてません。マッチしていないためです。

[
    {
        "interfaces": {
            "interface": "GigabitEthernet0/0"
        }
    }
]

description kingyo のような値であれば単純なテンプレートで取得できるのですが。

| re(".+") を添える

re を使って、スペースでもマッチする正規表現を指定します。

<group name="interfaces">
interface {{ interface }}
 description {{ description | re(".+") }}
</group>

これで、スペース含めて取得できます。

[
    {
        "interfaces": {
            "description": "kingyo ugui oikawa",
            "interface": "GigabitEthernet0/0"
        }
    }
]

公式ドキュメントの例 の例を参考にしました。

(おまけ) ignore(".+") だと

<group name="interfaces">
interface {{ interface }}
 description {{ description }} {{ ignore(".+") }}
</group>

だと、以下のように、スペースで区切られた値の最初のところだけしか取得できません。

[
    {
        "interfaces": {
            "description": "kingyo",
            "interface": "GigabitEthernet0/0"
        }
    }
]

参考

zaki-hmkc.hatenablog.com

[Ansible] 組織内でのみ使うコレクションの名前空間「local」が公式ドキュメントに明示された

そもそもコレクションとは

Ansible は現在、モジュール類の管理はコレクションという単位でまとめられています。

このコレクションは「名前空間(namespace).コレクション名」という形式で識別されます。例えば、ansible.utislcisco.ios などです。

コレクションは Ansible Galaxy でインターネット上に公開されてるので、名前空間は一意であるあることが求められます。

組織内だけで利用するコレクション

ただ、Ansible Galaxy では公開せず、組織の中だけで使うコレクションもあるかと思います。

この場合、組織内で独自に名前空間を付けたとしても、その名前空間が第三者によって Ansible Galaxy に登録されるとトラブルの元です。

それを防ぐには、自らが Ansible Galaxy でその名前空間を予約しておくことが対策になります。

気軽に使える名前空間「local」

とはいえ「そこまでするほどでもないけど、とにかく組織内だけでコレクションの体裁を保つための名前空間があればいいなぁ」というときに有効なのが「local」です。

今まで、中身が空の名前空間としてあることはありましたが、最近ドキュメント上に用途が明示されました。

docs.ansible.com

The local namespace does not contain any collection on Ansible Galaxy, and the intention is that this will never change. You can use the local namespace for collections that are locally on your machine or locally in your git repositories, without having to fear collisions with actually existing collections on Ansible Galaxy.

Galaxy に公開せず、一意性を気にせずに組織内でコレクションの名前空間を使いたいときに便利です。

経緯

私が気になっていたことで、Forum で質問したら local の持ち主さんに回答いただき、ドキュメントに記載していただた、という流れです。

とても助かりました。

forum.ansible.com