NetBox v4.1で追加されたブランチ機能の紹介

(2023/12/13修正)必要バージョンは正しくは`v4.1`でしたので修正。

# はじめに

本エントリは[エーピーコミュニケーションズ Advent Calendar 2024](https://qiita.com/advent-calendar/2024/ap-com)の13日目のエントリです。 

NetBoxはちょっと前にv4.1がリリースされました。
その際にブランチ機能(`netbox-branching`)が出たのですが、これを使うことでNetBoxを大規模チームで使う上際のデータ管理がしやすくなりました。

本記事ではそのブランチ機能のインストール方法と使い方を紹介します。

ちなみに、v4ではまだ変な表現はあるものの日本語化にも対応しています。
UIも洗礼され使いやすくなっているので興味があれば公式で[デモ環境](https://demo.netbox.dev/)も用意されているので触ってみることをお勧めします。

# ブランチ機能

ブランチ機能は`NetBox Labs`が開発したNetBoxプラグインです。
NetBox Labsは、NetBoxの主要開発メンバーが所属しており、NetBoxのEnterprise版を出している会社なので実質的に公式プラグインといえます。

機能は簡単に説明すると、NetBoxのデータをGitのようにブランチ分けできるようにするものです。

仕組みとしては、Mainブランチが実際のNetBoxデータで、開発ブランチをPostgreSQLのスキーマで表現して変更差分を管理しているようです。

この機能を使うことで、NetBoxへの設定変更を一度開発ブランチにまとめたうえで、一気にマージして設定反映をすることができます。
また、Mainブランチと開発ブランチで差分が発生した際も変更同期(Gitでいう`git pull main`)ができ、Revertすることも可能です。

イメージとしては[公式ドキュメント](https://github.com/netboxlabs/netbox-branching/blob/develop/docs/index.md)から抜粋した以下の図が分かりやすいです。

### マージ

```mermaid
sequenceDiagram
    actor User B
    participant Main
    participant Branch
    actor User A
    Main->>Branch: Provision new branch
    User A->>Branch: Make changes
    User B->>Main: Make unrelated changes
    Main->>Branch: Synchronize changes
    User A->>Branch: Make more changes
    Branch->>Main: Merge branch
```

### Revert

```mermaid
sequenceDiagram
    participant Main
    participant Branch
    actor User A
    Main->>Branch: Provision new branch
    User A->>Branch: Make changes
    Branch->>Main: Merge branch
    Note left of Main: Error detected!
    Main->>Branch: Revert changes
    User A->>Branch: Correct error
    Branch->>Main: Merge branch
```

# ブランチ機能のインストール

ブランチ機能は、何点か注意点がありますが他のNetBoxプラグインと同様の方法でインストールできます。

詳細は、[公式ドキュメント](https://github.com/netboxlabs/netbox-branching/blob/develop/docs/index.md#getting-started)に記載されていますが要約すると以下の通りです。
**手順の`1.`と`4.`は一般的なプラグインインストールでは行わない追加手順なので忘れないように注意が必要です。**

1. PostgreSQLでNetBox用ユーザにスキーマを作成する権限付与
1. Python仮想環境に入り、プラグインをpipでインストール
1. `configuration.py`の`PLUGIN`にインストールしたプラグインを指定
1. 動的スキーマ解決できるようにするため、`local_settings.py`を追加
1. データベースマイグレートを実行
1. NetBoxを再起動

NetBox再起動後、右上に`Main`というボタンが表示されるとインストール成功です。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/335255/0c3c5566-eae4-3a91-586c-3357625ed48f.png)

# 機能紹介

NetBoxプラグインをインストールすることで使える機能を紹介します。

## ブランチ作成

`Create a Branch`を押下することで新規に開発ブランチを作成できます。
開発ブランチは複数作成でき、ブランチ名は作成後に変更することも可能です。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/335255/e272ab28-bc62-66bc-107b-ffc830839c2f.png)

ブランチ用ページが作成され、この中で設定変更(`作成`, `更新`, `削除`)が管理できます。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/335255/247a6dca-f613-dbdd-92ff-445dbf05a119.png)

例えば、開発ブランチに入ってVLANを作成すると、変更点が記録されます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/335255/89746ce7-93e4-9c02-4a59-11a087f441bf.png)

また、すでにMainブランチに存在するオブジェクトを操作した場合、以下画像のように開発ブランチで編集されていることが表記されます。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/335255/beac565a-42e4-7762-aa4d-82aea3abce2b.png)

## マージ

開発ブランチの変更結果は、`Merge`ボタンよりMainブランチに反映します。
コンフリクトのチェックとドライラン機能もあるので、マージ後にデータがおかしくなる心配もなさそうです。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/335255/89b0a098-5baa-6fe2-a865-fc1d1c878f97.png)

変更後は、開発ブランチのステータスが`Merged`となりブランチが右上の選択肢から削除されます。

## Main同期

開発ブランチを作成後にMain側を更新をした場合、差分が出てきます。
その場合は、開発ブランチ側で`同期`をすることでMain側の変更を開発ブランチに反映することができます。

同期時に変更点がある場合は、履歴に情報が追記されます。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/335255/2f5e2569-e41d-e6a0-8e29-ede6eb22b35c.png)

## Revert

開発ブランチをマージ後にデータ不備があった場合、Revertすることでデータをもとに戻して開発ブランチを再度編集可能にすることができます。

ただし、マージ後にMain側で変更した差分もすべてRevertされてしまうので注意が必要です。

## Archive

ブランチをDBから完全に削除し、再度Revert、Activateできなくします。
変更ログは残されるので、マージから一定期間経過したらArchiveにするような運用でよいかと思います。

# 注意点

- マージは、開発ブランチの作業ログを上から順にDB反映する仕様のため、作業途中に誤ってslug名を同一にするなどDB制約に引っかかるような作業をした場合、マージエラーが発生してマージできなくなる
- NetBox自体のアップデートやプラグイン導入をする際は、ブランチは閉じたほうが良さそう

# さいごに

まだ、運用上の課題点はありそうですが、十分商用でも利用できるレベルでNetBoxを利用する場合は必ず入れてもよい機能だと思いました。

NetBoxのブランチと自動化の仕組みを組み合わせてデータ登録は自動でブランチを分けて投入し、承認完了後にマージをするなど運用方法は無限大だと思うので今後も活用していきたいですね。