CircleCI Server v3.x への移行方法

Server v3.x

サーバー管理者

このページの内容

前提条件

CircleCI Server 2.19.x から 3.x に移行する際は、2.19 インスタンスのデータ (Mongo、Postgres、Vault) をバックアップしてから、待機中の CircleCI Server 3.x インスタンスにそのデータを復元する必要があります。問題が発生した場合は、2.19 インスタンスにフォールバックできます。移行する場合、先に CircleCI Server 3.x システムのインストールを完了している必要があります。

移行には、データストアのサイズにより数分～数時間かかります。移行プロセスは、まずステージング環境で試してから、本番環境で行うことをお勧めします。ステージング環境を挟むことで、移行プロセスに対する理解を深められるだけでなく、移行完了にかかる時間を確認することもできます。

前提条件

現在の CircleCI Server が 2.19 である。
2.19 インスタンスのバックアップが完了している。外部データストアを使用している場合は、それらを個別にバックアップする必要があります。
CircleCI Server 3.x を新たにインストール済みである。
コンテキストを使用した realitycheck の実行が正常に完了している。
移行スクリプトを実行するマシンに以下を準備する。
- CircleCI Server 3.x インスタンスに合わせて構成した kubectl
- CircleCI Server 2.19 Services box への ssh アクセス

外部データストアのみの場合

すべての外部データストアのバックアップが完了している。
Postgres をバージョン 12 に更新している。

内部データストアのみの場合

2.19 インスタンスのバックアップが完了している。
新しい CirclCI Server 3.x インスタンスでコンテキストを使用した realitycheck の実行が正常に完了している。

移行

CircleCI Server v3.x に移行すると、v2.19 アプリケーションはシャットダウンされます。 v2.19 アプリケーションは自動では再起動されませんが、KOTS 管理コンソールを使用して手動で再起動することはできます。

移行プロセスを開始するとダウンタイムが発生します。メンテナンス期間を計画しておくことをお勧めします。

CircleCI Server 2.19 と CircleCI Server 3.x を同時に実行すると、2.19 のビルドデータに問題が発生するおそれがあります。 CircleCI Server 3.x を実行している間、CircleCI Server 2.19 は再起動しないでください。

ステップ 1 - リポジトリのクローンと移行スクリプトの実行

以下の手順に従って、CircleCI Server v2.19.x から CircleCI Server v3.x への移行スクリプトが含まれるリポジトリをクローンします。

この移行スクリプトで行われる処理は、以下のとおりです。

v2.19.x アプリケーションを停止させる。
事前チェックを実行し、2.19.x の名前空間とデータストアを確認する。
v2.19.x アプリケーションの PostgreSQL データベースおよび Mongo データベースの tarball を作成する。
Vault の既存のアプリケーションデータと CircleCI の暗号化/署名キーをアーカイブする。
2.19.x の tarball を v3.x 環境にエクスポートする。エクスポートされたデータストアは、circleci_export という名前のディレクトリに保存されます。このディレクトリは、移行スクリプトを実行したディレクトリを基準に作成されます。これはデバッグに役立ちます。
事前チェックを実行し、3.x インスタンスの名前空間とデータストアを確認する。
v3.x アプリケーションのデプロイを 0 にスケーリングする。
前の手順でエクスポートした tarball から新しい v3.x インスタンスにデータをインポートする。
v3.x アプリケーションのデプロイを 1 にスケーリングする。

サービスを外部化している場合は、bash migrate.sh -v -p -m を実行してください。 -v -p -m の各フラグを指定すると、Vault、Postgres、Mongo の移行がそれぞれスキップされます。この 3 つをすべてスキップすると、v2.19.x Services マシンの /data/circle/circleci-encryption-keys からキーがコピーされます。これらのファイルを cat して、3.x の構成ページにファイルの内容をアップロードできます。

ターミナルで以下を実行します。

Run git clone https://github.com/CircleCI-Public/server-scripts.
cd server-scripts/migrate を実行して、migrate ディレクトリに移動します。
./migrate.sh を実行して、移行スクリプトを実行します。
以下の情報を入力するよう求められます。
- CircleCI Server 2.19 のユーザー名
- CircleCI Server 2.19 のホスト名
- CircleCI Server 2.19.x の SSH キーファイルのパス
- CircleCI Server 3.x の Kubernetes 名前空間
スクリプトの実行が完了したら、KOTS 管理者コンソールで 2.19 インスタンスの署名キーと暗号化キーを新しい 3.0 インスタンスに追加する必要があります。このキーは circleci_export/circle-data にあります。
2.19 インスタンスで使用していたのと同じストレージバケットを参照するように 3.x インスタンスを更新するか、データを新しいバケットにコピーする必要があります。後者の方法では、2.19 インスタンスが引き続き正常に動作します。そのため、この移行をテストの一貫として行う場合には後者のアプローチをお勧めします。

3.x 環境で使用するホスト名が 2.19 とは異なる場合、GitHub Webhookは 2.19 環境で使用していたホスト名を引き続き参照します。ホスト名は、[Stop Building (ビルドの停止)]、[Set Up Project (プロジェクトのセットアップ)] の順にクリックすることにより簡単に更新できます。これを行った後も、プロジェクトに関連するコンテキストと環境変数は引き続き保持されます。

ステップ 2 - CircleCI Server 3.0 への移行の検証

新しいコミットをプッシュして、新しい CircleCI Server 3.x 環境でコンテキストを使用して realitycheck を再実行します。

ステップ 3 - チームへの最新情報の共有

realitycheck の実行が正常に完了したら、新しい CircleCI UI と URL (変更した場合) をチームに連絡します。

よくあるご質問

過去のジョブとビルドの履歴がありません。どこに移動されたのですか？

既存のジョブとビルドの履歴はすべて、[Legacy Jobs (レガシージョブ)] ビューに移動されます。ジョブの全履歴は、以下のいずれかの方法で表示できます。
- [Projects (プロジェクト)] → [PROJECT_NAME] の順に選択し、プロジェクトのビルド履歴下部にある [legacy jobs view (レガシージョブビュー)] リンクを選択する。
- Using the following URL pattern: https://<APP_DOMAIN>/pipelines/github/<ORG>/<PROJECT>/jobs
- For a specific job, append a job number to the URL: https://<APP_DOMAIN>/pipelines/github/<ORG>/<PROJECT>/jobs/<JOB_NUMBER>

移行後にプロジェクトで [Start Building (ビルドの開始)] を選択しても何も起こりません。なぜですか？

デフォルトでは、新しく追加されたプロジェクト (1 回もフォローされていないプロジェクト) は、初めてフォローされた後に自動的にビルドがトリガーされます。プロジェクトが 2.0 または 3.0 でフォローされたことがある場合、そのプロジェクトは新しいプロジェクトや最初のビルドとは見なされず、フォロー後にビルドはトリガーされません。ビルドをトリガーするには、新しいコミットやブランチのプッシュなど、GitHub Web フックをトリガーするアクティビティを実行してください。

"Error from server (NotFound):" というエラーが表示されました。

移行スクリプトでは、Postgres および MongoDB の命名規則が特定のパターンに従っているものと想定しています。このエラーが表示される場合、インストール環境が標準と異なっているか、DB が移行されていないなどの問題があります。このエラーが表示された場合は、サポートバンドルと、移行スクリプトの出力を添えてサポートにお問い合わせ下さい。

トラブルシューティング

Server v2.x からv3 に移行する場合、パイプラインを導入する前にプロジェクトの設定を行います。 Server v3.x では、パイプラインが自動的に有効化されるため、プロジェクトの設定 (` .circleci/_config.yml`) を` version: 2.1` に変更するだけで、上記で述べたすべての機能にアクセスすることができます。

次に読む

ドキュメントの改善にご協力ください

このガイドは、CircleCI の他のドキュメントと同様にオープンソースであり、 GitHub でご利用いただけます。ご協力いただき、ありがとうございます。

このページの編集をご提案ください (最初に「コントリビューションガイド」をご覧ください)。
ドキュメントの問題点を報告する、またはフィードバックやコメントを送信するには、GitHub で issue を作成してください。
CircleCI は、ユーザーの皆様の弊社プラットフォームにおけるエクスペリエンスを向上させる方法を常に模索しています。フィードバックをお寄せいただける場合は、リサーチコミュニティにご参加ください。

サポートが必要ですか

CircleCI のサポートエンジニアによる、サービスに関する問題、請求およびアカウントについての質問への対応、設定の構築に関する問題解決のサポートを行っています。サポートチケットを送信して、CircleCI のサポートエンジニアにお問い合わせください。日本語でお問い合わせいただけます。

または、サポートサイトから、サポート記事やコミュニティフォーラム、トレーニングリソースをご覧いただけます。

CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.