Jenkinsインスタンスのバックアップと復元方法
JENKINS_HOMEをアーカイブし、シークレットを保存し、復元テストを行うことで、Jenkinsを安全にバックアップおよび復元します。
Jenkinsインスタンスのバックアップと復元方法
Jenkinsは、ビルド、デプロイ、認証情報、リリース履歴のコントロールプレーンとなることがよくあります。ディスク障害や不適切な移行中に$JENKINS_HOMEを失うと、Jenkinsパッケージ自体の再インストールは簡単でも、CI/CDパイプラインが停止する可能性があります。
このガイドでは、何をバックアップすべきか、ファイルシステムアーカイブを安全に作成する方法、そして認証情報やファイルの所有権を壊さずにJenkinsを復元する方法を説明します。
核となる理解: $JENKINS_HOMEディレクトリ
すべてのJenkinsインスタンスは、$JENKINS_HOMEと呼ばれる単一のルートディレクトリに依存しています。このディレクトリには、すべての設定ファイル、プラグイン、ログ、ジョブデータが含まれています。Jenkinsのバックアップとは、基本的にこのディレクトリの内容をバックアップすることを意味します。
インストール方法（例：Linuxパッケージ、Dockerコンテナ）によって、$JENKINS_HOMEの場所は通常異なります。
- Linux（パッケージインストール）:
/var/lib/jenkins - Docker: 多くの場合、ボリュームにマウントされます（例：
/var/jenkins_home） - スタンドアロンJAR: 環境変数で指定されていない限り、Jenkinsプロセスが起動されたディレクトリ。
重要なデータコンポーネントの特定
$JENKINS_HOMEディレクトリ全体をバックアップするのが最も簡単な方法ですが、ビルド履歴とワークスペースデータが含まれていると、アーカイブが非常に大きくなる可能性があります。迅速かつ効率的なディザスタリカバリバックアップのためには、以下のディレクトリとファイルが確実にキャプチャされるようにする必要があります。
| コンポーネント | $JENKINS_HOME内のパス |
目的 |
|---|---|---|
| グローバル設定 | config.xml |
Jenkinsルートインスタンスのプライマリ設定ファイル。 |
| ジョブ定義 | jobs/ |
設定されたすべてのジョブのサブディレクトリが含まれ、それぞれに独自のconfig.xmlがあります。 |
| ユーザーと認証情報 | users/ および credentials.xml |
ユーザーアカウント、セキュリティレルム設定、保存されたシークレット。 |
| セキュリティキー | secrets/ |
保存された認証情報などの機密データを復号化するために不可欠な暗号化キー。 |
| プラグインリスト | plugins/ |
インストールされているすべてのプラグインの.hpiファイルが含まれています。 |
| ノード定義 | nodes/ |
接続されているすべてのビルドエージェントの設定（定義されている場合）。 |
方法1: ファイルシステムバックアップ（推奨）
Jenkinsをバックアップする最も信頼性の高い方法は、サービスを一時的に停止している間に、必要なファイルの一貫性のある圧縮アーカイブを作成することです。
ステップ1: Jenkinsサービスの停止
バックアッププロセス中のデータの一貫性を確保し、部分的なファイル書き込みを防ぐために、Jenkinsプロセスを停止する必要があります。サービスを停止しないと、バックアップが不完全または破損するリスクがあります。
# systemdを使用するシステムの場合（最新のLinuxディストリビューションのほとんど）
sudo systemctl stop jenkins
# または、serviceコマンドを使用するシステムの場合
sudo service jenkins stop
ステップ2: バックアップアーカイブの作成
$JENKINS_HOMEの親ディレクトリに移動し、tarを使用して圧縮アーカイブを作成します。時間と容量を節約するために、大きなビルドアーティファクトを除外することを強くお勧めします。
$JENKINS_HOMEが/var/lib/jenkinsであると仮定します。
JENKINS_HOME="/var/lib/jenkins"
BACKUP_TARGET="/mnt/backups/jenkins"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
ARCHIVE_NAME="jenkins_backup_${TIMESTAMP}.tar.gz"
# ターゲットディレクトリが存在しない場合は作成
mkdir -p $BACKUP_TARGET
# ビルド履歴とワークスペースを除外してアーカイブを作成
sudo tar -czvf "${BACKUP_TARGET}/${ARCHIVE_NAME}" \
--exclude="${JENKINS_HOME}/workspace" \
--exclude="${JENKINS_HOME}/caches" \
--exclude="${JENKINS_HOME}/jobs/*/builds" \
"${JENKINS_HOME}"
ヒント: ビルド履歴を含める場合
ビルド履歴（
jobs/*/builds）を保持することが重要な場合は、対応する--excludeフラグを削除できます。ただし、アーカイブサイズが数百ギガバイトに達する可能性があることに注意してください。
ステップ3: 確認とオフサイト保存
アーカイブが作成されたら、信頼する前に読み取り可能かどうかをテストします。
tar -tzf "${BACKUP_TARGET}/${ARCHIVE_NAME}" >/dev/null
次に、ローカルディスクの障害でJenkinsとそのバックアップの両方が失われないように、S3バケットやネットワークバックアップシステムなどの外部ストレージ場所に転送します。
ステップ4: Jenkinsの再起動
sudo systemctl start jenkins
方法2: Jenkinsバックアッププラグインの利用（部分的な解決策）
ThinBackupやBackup Pluginなどのプラグインは存在しますが、多くの場合、設定ファイル（config.xml）のみをキャプチャし、大きなファイルや必要なセキュリティ要素すべてを堅牢に処理できない場合があります。これらは一般的にジョブ設定のみのバックアップに適しており、完全で安全なディザスタリカバリ戦略として信頼すべきではありません。
Jenkinsインスタンスの復元
復元には、バックアップデータをターゲットマシンの$JENKINS_HOMEディレクトリにコピーし、サービスを開始する前にファイルのアクセス許可が正しいことを確認する必要があります。
ステップ1: ターゲット環境の準備
ターゲットシステム（または修復されたシステム）にJenkinsがインストールされていることを確認しますが、サービスは停止したままにします。
sudo systemctl stop jenkins
ステップ2: 既存のJenkinsデータのクリア（推奨）
以前にJenkinsをホストしていたマシンに復元する場合は、既存の$JENKINS_HOMEの内容をクリアして、環境がクリーンであることを確認します。
# 'rm -rf'コマンドは注意して使用してください！
sudo rm -rf /var/lib/jenkins/*
ステップ3: バックアップアーカイブの展開
圧縮アーカイブ（jenkins_backup_latest.tar.gz）をターゲットマシンにコピーし、$JENKINS_HOMEディレクトリに展開します。-Cフラグは展開先のディレクトリを指定します。
# アーカイブが/tmpにあり、JENKINS_HOMEが/var/lib/jenkinsであると仮定
sudo tar -xzvf /tmp/jenkins_backup_latest.tar.gz -C /var/lib/
# 注: tarコマンドにアーカイブ内の親ディレクトリが含まれている場合は、パスを調整してください。
# 結果として、アーカイブの内容が/var/lib/jenkinsの内容を置き換える必要があります。
ステップ4: アクセス許可の確認と修正
これは復元後最も重要なステップです。ファイルの所有権が正しくない場合、Jenkinsは起動に失敗するか、安全に動作しません。Jenkinsサービスが実行されるユーザーとグループ（多くの場合jenkins:jenkins）に所有権を再帰的に設定する必要があります。
JENKINS_HOME="/var/lib/jenkins"
JENKINS_USER="jenkins"
JENKINS_GROUP="jenkins"
sudo chown -R $JENKINS_USER:$JENKINS_GROUP $JENKINS_HOME
sudo find "$JENKINS_HOME" -type d -exec chmod 755 {} \;
sudo find "$JENKINS_HOME" -type f -exec chmod 644 {} \;
sudo chmod -R go-rwx "$JENKINS_HOME/secrets" "$JENKINS_HOME/users" 2>/dev/null || true
ステップ5: Jenkinsの起動と確認
サービスを開始し、ログを監視して起動が成功したことを確認します。
sudo systemctl start jenkins
# 起動ログを監視
sudo tail -f /var/log/jenkins/jenkins.log
起動が成功したら、すべてのジョブ、ユーザー、インストール済みプラグインが存在し、正しく機能していることを確認します。
自動バックアップのベストプラクティス
手動バックアップから移行するには、システムツールと外部構成管理を使用して自動化を実装します。
1. Cronジョブの活用
cronまたは同様のスケジューラを使用して、バックアップスクリプト（方法1のステップ1と2）を毎日または毎晩実行するようにスケジュールします。cronジョブが、Jenkinsサービスを停止および開始し、$JENKINS_HOMEディレクトリに対して読み取り/書き込みを行うための適切な権限を持つユーザーとして実行されるようにします。
2. コードとしての設定（CasC）
Jenkins Configuration as Code（CasC）の採用を検討してください。CasCは、宣言型YAMLファイルを使用してJenkinsの設定、ジョブ、プラグインを定義します。これらのYAMLファイルを別のソース管理リポジトリ（Gitなど）に保存することで、設定が移植可能でバージョン管理されるようになり、コアバックアップ要件が大幅に簡素化されます。
まとめ
Jenkinsのバックアップは、復元をテストした後にのみ有用であると見なしてください。適切な復旧計画では、config.xml、jobs/、plugins/、users/、credentials.xml、secrets/を保存し、クリーンなインスタンスでジョブを実行できることを確認します。
警告: 認証情報の保護
インスタンスを復元するときは、
secrets/ディレクトリが存在し、正しいことを確認してください。Jenkinsが認証情報（APIキーやパスワードなど）の暗号化に使用されるキーを見つけられない場合、それらの認証情報は使用できなくなり、手動で再入力する必要があります。