zaki work log

作業ログやら生活ログやらなんやら

[NetBox] Docker Compose版NetBoxを1.0.2へアップグレード

Docker ComposeでデプロイしたNetBoxをバージョンアップする。
基本的には「動作中NetBoxを停止 -> Composeファイルを(リポジトリごと)更新 -> 新バージョンNetBoxを起動」で良いが、更新内容によっては追加手順があるのでここ最近のバージョンから最新安定版へのアップグレード時のチェック箇所について簡単にまとめた。

見るべきポイントは基本的にGitHubリポジトリのReleasesページ。

github.com

詳細が必要な場合はNetBox本体のドキュメントも参照する。

netbox.readthedocs.io

本記事はversin 0.27.0 から現バージョンの1.0.2へのアップグレード例。
それ以前空のアップグレードについてはわかる範囲で調査・検証した。

現バージョンの確認

確認するバージョンはNetBox本体とnetbox-dockerのバージョンの両方を確認。
Docker版NetBoxは、NetBox本体のバージョンと、Docker Composeとしてのバージョンの2系統あるためちょっとややこしいので注意。

NetBox本体は、webアクセスした際のページヘッダに表示される。

f:id:zaki-hmkc:20210223155117p:plain

6e5c27b39de8 (v2.10.3)

netbox-dockerのバージョンは、cloneしたリポジトリ直下のVERSIONファイルを確認する。

[zaki@manager netbox-docker]$ cat VERSION 
0.27.0

アップグレード内容の確認

GitHubのReleaseの内容を確認する。

github.com

ここで upgrad compati earlier あたりの単語検索しておく。

NetBox本体の互換性

Release Noteの各バージョンの「Compatibility」を確認。

例えばNetBox本体がv2.9.xからのアップグレードの場合は、「Version 0.26.2はNetBox v2.9.xと互換あり」の状態から、その次の「Version 0.27.0はNetBox 2.10.xと互換あり」になっているため、このバージョンをまたぐアップグレードの場合(netbox-dockerのバージョン0.26.2以前からのアップグレードの場合)は、内容をよく確認しておく。

このバージョンの場合はinitializersを使用している場合に追加手順が必要。
DBのマイグレーションとあるので、DBコンテナのみ起動してDjangomanage.pyを実行すればよさそう。(詳細未確認)

github.com

github.com

PostgreSQLのバージョン

比較的目立たない気がするけど重要な件で、netbox-dockerのVersion 0.26.0以降では使用するDBが、PostgreSQL 11からPostgreSQL 12に変更されている。

このアップグレードはどちらかの対応が必要。
(11のデータのままだと12のPostgreSQLは利用できない)

PostgreSQL 11のまま使用する場合は、docker-compose.override.ymlで設定を上書きし、postgres:11-alpineを使用するようにすれば動作する。
DBのバックアップ&リストアによる更新は後述。

アップグレード

まず現バージョンのNetBoxを停止。 (git pullするとdocker-compose.ymlが更新されてしまうので先に停止する。先にgit pullしてしまった場合は、git checkout <tagname>で戻してからdocker-compose downする)

$ docker-compose down
Stopping netbox-docker_nginx_1         ... done
Stopping netbox-docker_netbox_1        ... done
Stopping netbox-docker_netbox-worker_1 ... done
Stopping netbox-docker_postgres_1      ... done
Stopping netbox-docker_redis_1         ... done
Stopping netbox-docker_redis-cache_1   ... done
Removing netbox-docker_nginx_1         ... done
Removing netbox-docker_netbox_1        ... done
Removing netbox-docker_netbox-worker_1 ... done
Removing netbox-docker_postgres_1      ... done
Removing netbox-docker_redis_1         ... done
Removing netbox-docker_redis-cache_1   ... done
Removing network netbox-docker_default

停止したことを確認。
DBをバックアップする場合はこのタイミングでDBのコンテナのみ起動してpg_dumpする。

$ docker-compose ps
Name   Command   State   Ports
------------------------------

リポジトリを更新。

$ cat VERSION 
0.27.0
$ git pull
remote: Enumerating objects: 263, done.
remote: Counting objects: 100% (263/263), done.
remote: Compressing objects: 100% (96/96), done.
remote: Total 433 (delta 175), reused 228 (delta 162), pack-reused 170
Receiving objects: 100% (433/433), 85.81 KiB | 285.00 KiB/s, done.
Resolving deltas: 100% (260/260), completed with 50 local objects.
From https://github.com/netbox-community/netbox-docker
   aa4d630..c80fb19  release    -> origin/release
   4e8588a..009eb1f  develop    -> origin/develop
 * [new tag]         1.0.2      -> 1.0.2
 * [new tag]         1.0.0      -> 1.0.0
 * [new tag]         1.0.1      -> 1.0.1
Updating aa4d630..c80fb19
Fast-forward
 .ecrc                                                 | 23 +++++++++++++++++++++++
 .editorconfig                                         | 11 +++++++++++

 :
 :
$ cat VERSION 
1.0.2

ここでnetbox-docker version 1.0.0未満からのアップグレードの場合はNginxコンテナを使わなくなっているため、docker-compose.override.ymlに上書き設定を記述している場合は更新する。(ここが元のままだと次のdocker-compose pullが失敗する)

  version: '3.4'
  services:
-   nginx:
+   netbox:
      ports:
      - '8080:8080'

latestの中身が更新されているのでイメージをpullする。

$ docker-compose pull
Pulling postgres      ... waiting
Pulling redis-cache   ... waiting
Pulling redis         ... waiting
Pulling netbox-worker ... downloading (86.6%)
Pulling netbox        ... downloading (86.6%)

DBのバージョンを更新した場合はこのタイミングでリストアする。
準備できたらデプロイする。

$ docker-compose up -d
Creating network "netbox-docker_default" with the default driver
Creating netbox-docker_postgres_1    ... done
Creating netbox-docker_redis_1       ... done
Creating netbox-docker_redis-cache_1 ... done
Creating netbox-docker_netbox-worker_1 ... done
Creating netbox-docker_netbox_1        ... done

f:id:zaki-hmkc:20210223161309p:plain

アップグレードできた。

バックアップ・リストアによるPostgreSQL 12へのデータ移行

PostgreSQL 12へ移行する場合は、ver11のDBデータをバックアップし、ver12でリストアすると良い。

Troubleshooting / Database Operations

NetBoxを一度停止。

$ docker-compose stop
Stopping netbox-docker_nginx_1         ... done
Stopping netbox-docker_netbox_1        ... done
Stopping netbox-docker_netbox-worker_1 ... done
Stopping netbox-docker_redis-cache_1   ... done
Stopping netbox-docker_postgres_1      ... done
Stopping netbox-docker_redis_1         ... done

pg_dumpを使ったデータのバックアップのためDBのみ起動。

$ docker-compose up -d postgres
Starting netbox-docker_postgres_1 ... done
$ docker-compose ps
            Name                           Command               State     Ports  
----------------------------------------------------------------------------------
netbox-docker_netbox-worker_1   python3 /opt/netbox/netbox ...   Exit 0           
netbox-docker_netbox_1          /opt/netbox/docker-entrypo ...   Exit 0           
netbox-docker_nginx_1           nginx -c /etc/netbox-nginx ...   Exit 0           
netbox-docker_postgres_1        docker-entrypoint.sh postgres    Up       5432/tcp
netbox-docker_redis-cache_1     docker-entrypoint.sh sh -c ...   Exit 0           
netbox-docker_redis_1           docker-entrypoint.sh sh -c ...   Exit 0   

DBにアクセスできることを確認。

$ source env/postgres.env 
$ docker-compose exec postgres sh -c 'psql -U $POSTGRES_USER $POSTGRES_DB'
psql (11.11)
Type "help" for help.

netbox=# 

PostgreSQLのデータバックアップ。

$ docker-compose exec -T postgres sh -c 'pg_dump -cU $POSTGRES_USER $POSTGRES_DB' | gzip > db_dump.sql.gz
ls -l db_dump.sql.gz
-rw-rw-r--. 1 zaki zaki 48388  2月 23 15:19 db_dump.sql.gz

データのバックアップが終わったらPostgreSQLを停止、アップグレードしたPostgreSQL 12でPostgreSQL 11のデータを読み込むとエラーになるため、ボリュームも削除する。

$ docker-compose down
Stopping netbox-docker_postgres_1 ... done
Removing netbox-docker_nginx_1         ... done
Removing netbox-docker_netbox_1        ... done
Removing netbox-docker_netbox-worker_1 ... done
Removing netbox-docker_redis-cache_1   ... done
Removing netbox-docker_postgres_1      ... done
Removing netbox-docker_redis_1         ... done
Removing network netbox-docker_default
$ docker volume ls | grep netbox | grep postgres
local     netbox-docker_netbox-postgres-data
$ docker volume rm netbox-docker_netbox-postgres-data
netbox-docker_netbox-postgres-data

この状態でgit pull, docker-compose pullリポジトリ・イメージを更新し、まずはDBをリストアするためにPostgreSQLのみデプロイしてデータをリストアする。 (docker-compose.override.ymlnetboxの上書き設定がある場合はnetboxに修正する)

$ docker-compose up -d postgres
Creating network "netbox-docker_default" with the default driver
Creating volume "netbox-docker_netbox-postgres-data" with local driver
Creating netbox-docker_postgres_1 ... done
$ gunzip -c db_dump.sql.gz | docker-compose exec -T postgres sh -c 'psql -U $POSTGRES_USER $POSTGRES_DB' 
SET
SET
SET
SET
SET
 set_config 
------------
 
(1 row)

:
:

残りのコンテナも起動する。

$ docker-compose up -d 
netbox-docker_postgres_1 is up-to-date
Creating netbox-docker_redis-cache_1 ... done
Creating netbox-docker_redis_1       ... done
Creating netbox-docker_netbox-worker_1 ... done
Creating netbox-docker_netbox_1        ... done
$ docker-compose ps
            Name                           Command               State                       Ports                     
-----------------------------------------------------------------------------------------------------------------------
netbox-docker_netbox-worker_1   /opt/netbox/venv/bin/pytho ...   Up                                                    
netbox-docker_netbox_1          /opt/netbox/docker-entrypo ...   Up      0.0.0.0:8099->8080/tcp,0.0.0.0:49177->8080/tcp
netbox-docker_postgres_1        docker-entrypoint.sh postgres    Up      5432/tcp                                      
netbox-docker_redis-cache_1     docker-entrypoint.sh sh -c ...   Up      6379/tcp                                      
netbox-docker_redis_1           docker-entrypoint.sh sh -c ...   Up      6379/tcp   

これでPostgreSQL 12にデータを引き継げるはず。

注意点としてはドキュメントの以下記述。

  • If your database is not too big, a full backup (with PostgreSQL 11, i.e. before the upgrade) and restore (with a clean PostgreSQL 12, i.e. after the upgrade) is probably the easiest to achieve
  • Please test the procedure on a test system first!

データがデカすぎると…リソースを喰いすぎるのかな?
あとテストをよく実施するように、ということ。

※ 上記も適当なデータ入れた状態で試したレベルなので、実際にやる場合はよく検証してください。

検証のため古いバージョンでデプロイする

リポジトリバージョンをターゲットに合わせてcheckoutする。

$ git checkout 0.26.2

また、これだけだとコンテナイメージはlatestを持ってきてしまうため、環境変数VERSIONv2.9など必要に応じて設定すれば指定バージョンでデプロイできる。

services:
  netbox: &netbox
    image: netboxcommunity/netbox:${VERSION-latest}