うさラボ

お勉強と備忘録

作成したtemplateをntc-templatesにPRする

こちらは エーピーコミュニケーションズ Advent Calendar 2021 4日目の記事です qiita.com

はじめに

今年の個人的な目標はOSS参加でした。 結果的に数件ですがの活動ができました。
直近に実施したntc-templatesの追加について実施した内容をまとめてみました。

ことの発端

やったこと

新規テンプレートを作成して、ntc-templatesにプルリクエストを出します

github.com

前回の記事でテンプレートの作成を解説しています。 usage-automate.hatenablog.com

前回の記事で作成してshow ip nat translationsのテンプレートを改修してプルリクエストを出します。

OSSの参加自体あまり慣れてません、お作法的によろしくないことがあれば優しくおしらせください

手順

手順の流れはざっくりと以下になります。
1. Githubでの作業
2. ローカル(自端末)での作業
3. テンプレート作成
4. テスト作成
5. テスト
6. コミット&プッシュ
7. プルリクエスト作成
8. マージされる

1. Githubでの作業

ntc-templatesのリポジトリをフォークし作業をします。
まずは、右上のフォークボタンを押します。 f:id:usage_automate:20211203091503p:plain

フォーク後 f:id:usage_automate:20211203091605p:plain

ksaegusa/ntc-templatesになってますね これで準備完了で、ローカルで開発を始めます。

2. ローカル(自端末)での作業

フォークしたリポジトリをクローンしローカルでの作業を開始ます。

git clone https://github.com/ksaegusa/ntc-templates.git

ブランチの作成と移動

git branch add-cisco-show-ip-nat-translations
git checkout add-cisco-show-ip-nat-translations

ブランチ名は、ほかのコントリビュータの方を参考に命名しました。
※マージ済みのプルリクエストなどから雰囲気をつかむ。

3. テンプレート作成

show ip nat translationsのテンプレートを追加していきます。 さらにテンプレートとの紐付けが書かれているindexファイルの更新も合わせて実施します。

新規作成ファイル

  • ntc_templates/templates/cisco_ios_show_ip_nat_translations.textfsm
Value PROTOCOL (tcp|udp|icmp|---)
Value INSIDE_GLOBAL_IP (\d+\.\d+\.\d+\.\d+|---)
Value INSIDE_GLOBAL_PORT (\S+)
Value INSIDE_LOCAL_IP (\d+\.\d+\.\d+\.\d+|---)
Value INSIDE_LOCAL_PORT (\S+)
Value OUTSIDE_LOCAL_IP (\d+\.\d+\.\d+\.\d+|---)
Value OUTSIDE_LOCAL_PORT (\S+)
Value OUTSIDE_GLOBAL_IP (\d+\.\d+\.\d+\.\d+|---)
Value OUTSIDE_GLOBAL_PORT (\S+)

Start
  ^Pro\s+Inside\sglobal\s+Inside\slocal\s+Outside\slocal\s+Outside\sglobal
  ^${PROTOCOL}\s+${INSIDE_GLOBAL_IP}:${INSIDE_GLOBAL_PORT}\s+${INSIDE_LOCAL_IP}:${INSIDE_LOCAL_PORT}\s+${OUTSIDE_LOCAL_IP}:${OUTSIDE_GLOBAL_PORT}\s+${OUTSIDE_GLOBAL_IP}:${OUTSIDE_LOCAL_PORT} -> Record
  ^${PROTOCOL}\s+${INSIDE_GLOBAL_IP}\s+${INSIDE_LOCAL_IP}\s+${OUTSIDE_LOCAL_IP}\s+${OUTSIDE_GLOBAL_IP} -> Record

作成したテンプレートをtemplatesディレクトリ配下に格納します。 前回の記事で紹介したときよりパワーアップしています。

前回のテンプレートを使ったアウトプット
 - protocol: 'tcp'
   inside_global: '10.9.0.0:51776',
   inside_local: '10.1.0.2:51776',
   outside_global: '10.2.0.2:21',
   outside_local: '10.2.0.2:21',

今回のテンプレート
  - protocol: "tcp"
    inside_global_ip: "10.9.0.0"
    inside_global_port: "51776"
    inside_local_ip: "10.1.0.2"
    inside_local_port: "51776"
    outside_local_ip: "10.2.0.2"
    outside_local_port: "21"
    outside_global_ip: "10.2.0.2"
    outside_global_port: "21"

IPの情報とポートの情報がひとまとまりになってしまっていたのでこちらを分離できるようにしました。

修正ファイル

  • ntc_templates/templates/index
~snip~
cisco_ios_show_ipv6_interface_brief.textfsm, .*, cisco_ios, sh[[ow]] ipv[[6]] i[[nterface]] b[[rief]]
cisco_ios_show_ip_nat_translations.textfsm, .*, cisco_ios, sh[[ow]] ip nat translation[[s]]
cisco_ios_show_ip_eigrp_neighbors.textfsm, .*, cisco_ios, sh[[ow]] ip ei[[grp]] nei[[ghbors]]
~snip~

続いて、既存のファイルの更新をします。indexはコマンドとテンプレートを紐づけをするようファイルのようです。 READMEに更新の際の注意が書いてありました。

  • アルファベット順のOS
  • 長さ順にテンプレート名
  • 長さが同じ場合は、コマンド名のアルファベット順を使用してください
  • OS間のスペースを確保する

今回はcisco,iosのコマンド追加なのでcisco_ios_show_xxxが並んでいる部分に追記をします。その際テンプレート名の長い順に並べるようです。 cisco_ios_show_ipv6_interface_brief.textfsmとcisco_ios_show_ip_eigrp_neighbors.textfsmの間に追加したテンプレート情報を追加しました。

cisco_ios_show_ipv6_interface_brief.textfsm => 43文字
cisco_ios_show_ip_nat_translations.textfsm = > 42文字 ★この位置に差し込み
cisco_ios_show_ip_eigrp_neighbors.textfsm => 41文字

後半部分は、以下のルールになっているようです。

.*,ベンダ_OS, コマンド省略可能な個所

今回は省略可能な個所が開発時に理解できていなかったためsだけになってます。。
実際にはsh ip na tでもコマンドが通るため、下記のように書く方がよかったです。 f:id:usage_automate:20211204092607p:plain

cisco_ios_show_ip_nat_translations.textfsm, .*, cisco_ios, sh[[ow]] ip n[[at]] t[[ranslations]]

タイミングを見計らって直しちゃおうと思います。

これで、テンプレートの作成とindexの更新が完了です。

4. テスト作成

さて、今回は合わせてテストも書いてあげる必要があるようです。 testsディレクトリの配下にベンダ_OS命名で作成されたディレクトリがあります。さらにその配下にコマンド名でディレクトリを作成しその中に必要なファイルを用意します。 ほかのディレクトリを参考に、コマンド実行時に出力されたものを記載したファイル(.raw)とパース後の想定Yamlファイルを用意します。

新規作成

  • tests/cisco_ios/show_ip_nat_translations/show_ip_nat_translations.raw
Pro Inside global      Inside local       Outside local      Outside global
tcp 10.9.0.0:51776     10.1.0.2:51776     10.2.0.2:21        10.2.0.2:21
tcp 10.9.0.0:51778     10.1.0.2:51778     10.2.0.2:21        10.2.0.2:21
tcp 10.9.0.0:56384     10.1.0.2:56384     10.2.0.2:22        10.2.0.2:22
icmp 10.9.0.0:513     10.1.0.2:512     10.2.0.2:512        10.2.0.2:513
--- 10.9.0.0     10.1.0.2     ---        ---
  • tests/cisco_ios/show_ip_nat_translations/show_ip_nat_translations.yml
---
parsed_sample:
  - protocol: "tcp"
    inside_global_ip: "10.9.0.0"
    inside_global_port: "51776"
    inside_local_ip: "10.1.0.2"
    inside_local_port: "51776"
    outside_local_ip: "10.2.0.2"
    outside_local_port: "21"
    outside_global_ip: "10.2.0.2"
    outside_global_port: "21"
  - protocol: "tcp"
    inside_global_ip: "10.9.0.0"
    inside_global_port: "51778"
    inside_local_ip: "10.1.0.2"
    inside_local_port: "51778"
    outside_local_ip: "10.2.0.2"
    outside_local_port: "21"
    outside_global_ip: "10.2.0.2"
    outside_global_port: "21"
  - protocol: "tcp"
    inside_global_ip: "10.9.0.0"
    inside_global_port: "56384"
    inside_local_ip: "10.1.0.2"
    inside_local_port: "56384"
    outside_local_ip: "10.2.0.2"
    outside_local_port: "22"
    outside_global_ip: "10.2.0.2"
    outside_global_port: "22"
  - protocol: "icmp"
    inside_global_ip: "10.9.0.0"
    inside_global_port: "513"
    inside_local_ip: "10.1.0.2"
    inside_local_port: "512"
    outside_local_ip: "10.2.0.2"
    outside_local_port: "513"
    outside_global_ip: "10.2.0.2"
    outside_global_port: "512"
  - protocol: "---"
    inside_global_ip: "10.9.0.0"
    inside_global_port: ""
    inside_local_ip: "10.1.0.2"
    inside_local_port: ""
    outside_local_ip: "---"
    outside_local_port: ""
    outside_global_ip: "---"
    outside_global_port: ""

5. テスト

プッシュする前にローカルでテストを実施します。 実施しるためにtoxをインストールしておく必要があります。

pip install tox

テストの実行

tox

テストが開始され、いろいろとテストしてくれてますかっこいいですね(アホ)
f:id:usage_automate:20211203181225p:plain

すべてPASSになったことを確認します
f:id:usage_automate:20211203181426p:plain

これでテストは完了です、テスト実施に出来上がるキャッシュファイルや.toxはすべて削除しました。 (毎回手で削除する必要なさそうだけどよくわからず。)

この時、Lintも同時行ってくれます、テストが通るまで根気よく修正します。

6. コミット&プッシュ

git add .
git commit -m 'add show ip nat translations template'
git push origin add-cisco-show-ip-nat-translations

7. プルリクエスト作成

プッシュが完了したらGithubでプルリクエストを作成します、この時マージ先はntc-templates/masterになります。 github.com

プルリクエストを作成するとCIが走るようになっているようです。 この時、なぜ更新をかけていない箇所でCIのエラーが出てしまいました。
ローカルのテストでは引っかからなかったためプルリクエストのコメントでレビュアーに確認しました。

何やらmasterにバグがあったのか、再現性があったりなかったりで暫定的な対応をしてもらいいったん解決

バグの修正をしてもらい、コメントをしつつマージをされるのを待ちました。

8. マージされた

そして、マージされました。めでたしめでたし。

f:id:usage_automate:20211203184036p:plain

次回?のバージョンにも追加されるようです。

まとめ

フォークするところからマージまで一連の手順を書きました。
実際には何度もlintで引っかかったり、別のエラーがでたりでそこまでスムーズではなかったですが、流れがなんとなくでもつかんでもらえれば幸いです。

今年から始めたOSS活動ですが、少しづつ、ほんとに少しづつですができることが増えてきました。
来年は2桁マージを目指したいなと思います。