NTT Com で OSS を作って公開してみた - やったことリスト共有

この記事は、 NTT Communications Advent Calendar 2022 8日目の記事です。

サマリ

  • OSS 公開中の Go による SDN コントローラー Pola PCE の開発ノウハウを紹介
  • 開発・公開・運用に際してやったことと得られた Tips を紹介 (CI・ドキュメント・コンテナ・その他 Go 関連)

はじめに

イノベーションセンターの三島です。 普段の業務では Multi-AS Segment Routing(SRv6/SR-MPLS)や Telemetry などの技術検証、BGP 技術の検証と AS 運用などを行っています。

この記事では、SDN コントローラーを OSS として公開して得た知見を、Go による開発支援や GitHub を通じた公開・運用の Tips を交えつつご紹介します。

公開した OSS: Pola PCE

経路制御技術の Segment Routing(SR)において、発行した経路を管理するための SDN コントローラーである Pola PCE を開発・公開しています。
Pola PCE を SR 網に導入することで、大規模なネットワーク運用やアプリケーション単位での通信品質向上などを実現できます。 (プロダクトの詳細は後日また本ブログで解説予定ですので、ご期待ください。)

Pola PCE は Go で開発し、2022年6月に OSS としてリリースしました。
2022年12月8日時点では v1.1.2 が公開中で、Go のパッケージ、クロスコンパイルしたバイナリ、Docker イメージの3種を配布中です。

https://nttcom.github.io/pola/

開発の経緯と OSS 化に踏み切った理由

NTT Com では Multi-AS SR 技術を用いた社内ネットワークを運用しています。 その中で複雑な Traffic Engineering のユースケースとスケーラビリティを実現するため、継続的な機能追加やニーズに応じた拡張性を持ち、Multi-vendor 環境でも動作可能なコントローラーが必要となりました。

これらの要求を満たすため、Pola PCE を開発し自社ネットワークへ導入しました。
開発の当たってのより詳しいモチベーションは下記でご紹介しています。

ネットワークで活用するソフトウェアは、開発するだけでなく、その後の機能拡張や他製品との連携が重要となります。 継続的な開発を進める上で、下記の3点を期待し OSS としての公開に踏み切りました。

  • ユーザや対応製品の増加・PCE 界隈の盛り上げ
    • ネットワーク運用者に広く利用されることによる、プロトコル対応製品の増加や外部ツールの充実
  • 多彩な環境での動作を通じた新規ニーズの開拓や知見の蓄積
    • 新規ユースケースの獲得や機能要望の期待
  • コミュニティ運用による機能追加や知見の獲得
    • 外部の Contributor の視点を取り入れることによる新規知見の獲得や機能向上

以降の章では、これらを達成することを目指した OSS 開発・公開・運用の Tips をご紹介します。

OSS 開発・公開・運用の Tips

前章の要件を満たすため、下記のポリシーで OSS 公開手法を検討しました。

  • 広く利用者を増やすための工夫
    • Example の充実やドキュメント整備、SEO 対策
  • 多彩な環境への適用
    • クロスコンパイル・Docker 等での配布
  • 運用・メンテナンスの効率化
    • CI の 活用や標準的なプロジェクト構成への準拠、関連ライセンス表示等の自動化

それぞれのポリシーを満たすために実施した Tips を、(1) GitHub での公開・運用知見、(2) Go の開発支援、(3) その他 OSS 開発・運用の工夫の3つに分けて解説します。

GitHub での公開・運用知見

リポジトリ運営

  • Community Standards の整備
    • GitHub の公式機能として、リポジトリを潤滑に運用するためのチェックリストが公開されている
    • 特に Description は検索時に表示されるページ名や後述の Docker イメージのラベルにもなるため重要
  • GitHub Actions
    • あらかじめ作成したワークフローを自動実行し、CI を実現する機能
      • フォーマットに関するレビューやリリースなどの定型作業の負荷を低減
      • Pola PCE のワークフロー では、Git で Tag を付与した際にクロスコンパイルされたバイナリと Docker image をリリースする仕組みを作成

ドキュメント公開& SEO 対策

  • GitHub Pages
    • プロジェクト全体に関する情報公開と SEO 対策を目的とした Web ページ
    • SEO 対策の視点でも、GitHub のリポジトリページは Google 等のクローラーに認識されるのが遅い傾向にあるため、リリース直後の検索用にも作っておくと良い
      • Pola PCE の場合、GitHub Pages は公開後半日程、GitHub のリポジトリページは公開後約2週間後に Google 検索結果へ表示された
    • 環境構築方法を gh-pages/README.md に記載済。誰でも PR ベースで編集可能
      • 下記の Hugo と Docsy を利用し、ページ作成を効率化
  • Hugo
    • Markdown で記載したファイルから動的に Web ページを生成するツール
    • Template を活用しつつ、Markdown ベースで手軽にブログが作成できるのは便利!
  • Docsy
    • 技術文書を書くためのテンプレート。gRPC・Selenium・etcd など様々なソフトウェアが使用中
    • OSS プロダクトらしい公式ページを高速に開発可能。1 時間ほどで必要な機能・見た目のページを作ることができて助かった

GitHub Container Registry(ghcr)による Docker イメージのリリース

  • GitHub 上で Docker イメージを提供する機能
  • Docker Hub と異なり、公式機能で GitHub Actions との API 連携が可能
    • 公式ワークフローを利用するだけで、リポジトリ情報・バージョンやライセンス情報などがラベルとして埋め込まれた Docker イメージを生成可能(
  • Docker イメージのも含め、全てを Github で完結して公開できるのは良い点
    • 一方、Docker Hub と違いレジストリ名(ghcr.io)が必要になるため、イメージ名が長くなるデメリットも存在

その他

  • README.md の整備
    • トップページの README.md には、CI 状態や関連ページなどを Badge として付与
    • 各階層にも README.md を配置し、ツールの使い方等を解説
      • コマンドの使い方や仕様などの記載は特に重要
  • main ブランチの保護
    • latest リリース破壊の防止
    • Setting → Branches → Branch protection rules

Go の開発支援

プロジェクトの構造を Standard Go Project Layout に準拠

  • Standard Go Project Layout
    • 可読性・保守性の高い Go プロジェクトのベストプラクティス
    • 各ファイルの役割が明確になると共に、Go の開発者が理解しやすいプロジェクト構造になった

linging/formatting

  • golangci-lint

    • CI から呼び出し、Go 関連の linting/formatting を行ってくれる機能
      • Push の度に GitHub Actions で実行
      • 次の Go Report Card と合わせ、gocyclo のパラメータを調整することを推奨
  • Go Report Card

    • lintng/formatting や 英語の綴りなどを確認し、Web 上で表示するサービス
      • 設定不要でコードの確認ができるので便利
      • Go の文法的な lint/format の他、英語のスペル確認なども実行してくれる
    • 結果は Badge として README.md に表示可能
  • editorconfig
    • コードの統一性を持たせるための linter/formatter
      • 開発者の環境を問わず、生成されるコードを統一する意図。 CI 実施前のチェックに利用
      • Vim/Emacs/VSCode など様々なエディターに導入可能
      • Go の場合その他の linter が充実しているため恩恵は薄いが、Markdown/YAML 他様々な形式に対応
    • いずれは開発環境の整え方のような手順を作る、あるいはネットワーク環境を含めた開発用コンテナを公開すると良さそう

その他

  • gocredits

    • Go で使用したライブラリのライセンスをまとめて表示してくれるツール
      • OSS として公開する上で重要なライセンス管理をサポート
    • 今のところリリースごとにローカルでコマンドを実行して利用中
      • Tag を付与した際、あるいは go ファイルが更新された際に自動実行するなど、CI に組み込むのが良さそう
  • pkg.dev.go

    • Go 公式のドキュメント機能
    • go install するだけでコードを自動解析してドキュメントを作ってくれるのは便利

その他 OSS 開発・運用の工夫

Getting StartedExample の整備

  • ツールの利用方法と試しやすい手順を公開することでユーザを増やす狙い
  • Example は誰もが手軽に試すことができ、なるべく同じ環境で再現できると Good
    • 手軽さと再現性の両立にはコンテナ環境がおすすめ
  • Pola PCE は Tinet の設定ファイルを公開
    • Docker さえ準備すれば、誰でも気軽に設定済みの SR ネットワーク(D-Plane/C-Plane)を利用可能に!
    • 実際に手元で動かした結果をもとにした問い合わせや感想もいただくことができた

公式アイコンの作成

  • トポロジー図・システム図等でソフトウェアを示すことができ、発表資料の顔にもなるので重要
    • 遠目に Pola や PCE の P となるようにデザイン
  • 公式ページや OSS の各所で利用するためのテーマカラーを決めておくと便利
    • Pola PCE では#81C0FC#03498D の2色をテーマカラーとして設定、アイコンや GitHub Pages のテーマに利用
  • ステッカーを作成、JANOG 50 等のイベントで配布
    • 興味を持っていただけた方が検索可能なように、名前入りのロゴを作成
  • 自身で図やスライドを作成する際も便利であり、またこれをきっかけにお声がけいただいたりもしたため、やってよかった取り組みの1つ

まとめ

本記事では、Pola PCE の開発経験を通じて得た知見を、Go 製 OSS の開発支援と・GitHub における公開の Tips としてご紹介しました。

各 Tips に記載した通り、各 CI やベストプラクティスに従うことでリポジトリ公開・運用やドキュメントの整備等を効率的に進めることができたと感じています。

より Pola PCE に寄せた感想としては、OSS としての公開を通じて、 研究での利用をしていただくなど、事前に期待した通りの一部 PCE 界隈の盛り上げやユースケースの創出に貢献できたかなと感じています。 また、今回はネットワークに関するソフトウェアであるため、 公開した Example ネットワーク環境を手元で動かした結果をもとに感想や問い合わせをいただくなど、裾野を広げることができたのもよかったポイントです。

OSS 公開を検討中の方や、開発に興味のある方はぜひそれぞれの Tips を参考にしてみてください。 また、その他こんな方法もあるよという知見をお持ちの方は、ぜひはてなブックマークやTwitterでコメントをお願いします!

宣伝

Pola PCE への Contribution 募集

Pola PCE の Contributor を募集中です!

  • SR 網を運用中で、SDN 制御による運用効率化や新たなサービスを提供してみたい方
  • RFC/Internet-Draft 準拠のソフトウェアを開発してみたい方

お気軽に PR/Issue の作成をお願いします!

12/19 (月) に SR 視点で Pola PCE の内部構造と使い方を紹介する記事を公開予定ですので、ぜひそちらもご覧ください!

また、PCE の活用事例も含め、SR の検証例を連載記事としてご紹介しています。こちらも合わせてご覧ください。

冬季インターンシップ開催のお知らせ

2022年度インターンシップの参加者を募集中です!

期間は 2023年02月06日〜17日 のうち、土日祝を除く実働10日間です。

締め切りは 12月14日(水)13:00 までとなっていますので、興味のある方はお早めにご応募ください!

私たちのチーム(SR を用いたキャリアネットワークの開発)では、SR-MPLS/SRv6 の技術検証や Pola PCE を含めた SR 周辺技術の OSS 実装等のテーマを用意しています。 また、参加者の希望するテーマをご提案いただくこともできます。

昨年は2名の方に参加いただき、FRRouting への BGP-LS の実装と、キャリアルーターを用いた SRv6 VPN の技術検証を実施していただきました。 体験記を寄稿してもらっていますので、こちらもぜひ参考にしてください。

© NTT Communications Corporation 2014