CircleCI Server v3 から v4.x への移行

このページの内容

CircleCI Server v3.x から v4.x への移行は インプレース 移行です。 helm-value ファイルを生成し、そのファイルを helm コマンドで使用して CircleCI Server v3.x から v4.x へのアップグレードを行います。

移行プロセスは、まずステージング環境で試してから、本番環境で行うことをお勧めします。ステージング環境を挟むことで、移行プロセスに対する理解を深められ、また移行完了にかかる時間を確認できます。

前提条件

現在インストールされている CircleCI Server が v3.x である。
バックアップと復元ガイドの手順に従って v3.x のインスタンスのバックアップが作成してある。
- 外部データストアを使用している場合は、それらを個別にバックアップする必要があります。
- 内部データストアを使用している場合は、上記リンクに記載されているバックアッププロセスでバックアップが作成されています。
移行スクリプトは、インストールされている以下のツールを使ってマシンから実行する必要があります。
- CircleCI Server 3.x のインスタンス用に設定された kubectl
- yq
- helm
- helm-diff

移行

CircleCI Server をv3.x から v4.x にインプレースアップグレードするには、以下のタスクを行う移行スクリプトを実行します。

KOTS 設定の YAML ファイルへのエクスポート
エクスポートされた YAML ファイルを、v4.x への移行に向け helm と一緒に使用するように変更
すべての Kubernetes リソースに helm の注釈を付与
Postgres DB の ドメイン の移行を実行
すべての KOTS 関連リソースを削除するクリーンアップステップの実行
「次のステップ」を含む出力メッセージの表示

CircleCI server v4.x では、ワークフローデータの保存方法が変更されました。以前は、Postgres にワークフローデータを保存していましたが、このデータをストレージバケットに移動しました (GCS/S3/MinIO)。移行後、ワークフローデータが使用できない期間が発生します。これは既存のワークフローデータがストレージバケットに転送されているためです。所要時間は既存のワークフローデータの量によって異なりますが、移行を行う workflow-conductor ポッドをスケールして、このプロセスを高速化することができます。クラスタで許可される範囲でスケールできます。ポッドのスケール方法については後述します。

kots-exporter スクリプトでは必要に応じて以下の機能を実行できます。

注釈ステップのみを再実行 (-f annotate)
kots-annotation cleanup ジョブの実行 (-f kots_cleanup)
出力メッセージの表示 (-f message)
PostgreSQL データーベースの移行の再実行 (-f flyway)

1. CircleCI イメージのレジストリ用 Docker シークレットを作成する

この移行スクリプトには、移行機能を実行するために CircleCI イメージレジストリへのアクセス権が必要です。このイメージのレジストリは、CircleCI Server v4.x のインストール環境でも使用されます。 CircleCI Server がインストールされている同じ名前空間に docker-registry シークレットを作成します。イメージレジストリの認証情報が CircleCI の担当者から提供されます。

ターミナルで < > で示されているすべての値を置き換えて、以下を実行します。

kubectl -n <namespace> create secret docker-registry regcred \
  --docker-server=https://cciserver.azurecr.io \
  --docker-username=<image-registry-username> \
  --docker-password=<image-registry-token> \
  --docker-email=<notification-email-id>

2. リポジトリをクローンし、 kots-exporter スクリプトを実行する

下記では、KOTS exporter スクリプトを含むリポジトリをクローンする方法を説明します。このスクリプトにより、CircleCI Server 4.x の helm-value ファイルが生成されます。

git clone https://github.com/CircleCI-Public/server-scripts を実行します。
kots-exporter ディレクトリを cd server-scripts/kots-exporter に変更します。
移行スクリプト、./kots-exporter.sh を実行します。
以下の情報を入力するよう求められます。
- CircleCI Server 3.x のリリース名、circleci-server
- CircleCI Server 3.x の Kubernetes 名前空間
- Server 4.x のライセンス文字列。CircleCI の担当者から提供されます。
スクリプトが完成すると、実行する次のステップの詳細についての下記のようなメッセージが表示されます。

############ Upgrade Commands ################
Before upgrading to 4.x, follow the steps below:

Your helm values file with your installation config is here:
- <path>/kots-exporter/output/helm-values.yaml

## Helm login to cciserver.azurecr.io
helm registry login cciserver.azurecr.io --username <image-registry-username>

## Helm Diff (optional)
The Helm Diff tool is used to verify that the changes between your current install and the upgrade are expected.

# diff command
helm diff upgrade <release-name> -n <namespace> -f <path>/kots-exporter/output/helm-values.yaml --show-secrets --context 5 oci://cciserver.azurecr.io/circleci-server --version 4.0.1
-------------------------------------------------------------------------
## Helm Upgrade CircleCI Server
helm upgrade <release-name> -n <namespace> -f <path>/kots-exporter/output/helm-values.yaml oci://cciserver.azurecr.io/circleci-server --version <version-to-upgrade-to> --force

NOTE: After server 3.x to 4.x migration, You must rerun the Nomad terraform with modified value of 'server_endpoint' variable
It should be - <domain-name>:4647

CircleCI Server v4.0 にアップグレードする際に、Postgres インスタンスが外部化されて いない場合、Postgres チャートもアップグレードされます。

3. 移行ツールのジョブのステータスを確認する

移行ツールのジョブがあるかどうかを確認します。

kubectl -n <namespace> get job/circle-migrator

ジョブがない場合、 log ディレクトリの Pod のログ (circle-migrator.log) を確認します。ログは以下のようになります。

Successfully baselined schema with version: 1
Current version of schema "public": 1
DEBUG: Parsing V0002__drop_domain_migrations.sql ...
DEBUG: Found statement at line 1: DROP TABLE IF EXISTS public.domain_migrations
DEBUG: Starting migration of schema "public" to version "0002 - drop domain migrations" ...
Migrating schema "public" to version "0002 - drop domain migrations"
DEBUG: Executing SQL: DROP TABLE IF EXISTS public.domain_migrations
DEBUG: 0 rows affected
DEBUG: Successfully completed migration of schema "public" to version "0002 - drop domain migrations"
DEBUG: Schema History table "public"."schema_version" successfully updated to reflect changes
Successfully applied 1 migration to schema "public", now at version v0002 (execution time 00:00.101s)
DEBUG: Memory usage: 12 of 15M

4. helm-value ファイルを検証する

移行スクリプトが完了したら、既存の CircleCI Server 3.x の設定ファイルに helm-values.yaml が生成されます。このファイルにはお客様が以前 KOTS で入力した設定データが格納されています。今後はこのファイルを標準の Helm プラクティスとして使用し、CircleCI Server の更新および設定を行います。

5. helm-diff 出力を生成する

次に、helm-diff コマンドを作成し、出力をレビューします。

helm registry login cciserver.azurecr.io -u <image-registry-username>

helm diff upgrade <release-name> -n <namespace> -f <path>/kots-exporter/output/helm-values.yaml --show-secrets --context 5 oci://cciserver.azurecr.io/circleci-server --version 4.0.1

helm-diff コマンドにより生成された出力を以下を参考にレビューします。

黄色 で強調表示されている文字列: changed、added などの Kubernetes リソースのステータス
赤色 で強調表示されている文字列: image などの削除された文字列
緑色 で強調表示されている文字列: imagePullSecret などの追加された文字列

以下は helm-diff の出力で見られる変更点の例です。

すべての Kubernetes リソースに imagePullSecrets が追加
コンテナイメージの更新
API トークンや署名キーなどのシークレット環境変数が Kubernetes シークレットを参照するように変更
RabbitMQ と MongoDB の URI の環境変数の変更
VM、OUTPUT、NOMAD サービスの URI の環境変数が <domain_name>:<service_port> を参照するように変更
VM、OUTPUT、NOMAD サービスリソースから注釈の削除
GitHub のチェックサムが注釈として追加
distributor-* のデプロイのシークレットや注釈の削除
アップストリームチャートの postgresql の更新
アップストリームチャートの再作成 (削除と作成)
- Prometheus (circleci-server-kube-state-metrics、node-exporter、prometheus-server)
- MongoDB
- RabbitMQ
- Redis (redis-master、redis-slave)

6. CircleCI Server 3.x をアップグレードする

helm-value ファイルの検証が完了したら、以下のコマンドを実行し、CircleCI Server を v4.x にアップグレードします。

Helm レジストリは Azure プライベートレジストリに保存されています。そのレジストリにアクセスするためのユーザー名とトークンが提供されます。

helm upgrade circleci-server -n <namespace> -f <path>/kots-exporter/output/helm-values.yaml oci://cciserver.azurecr.io/circleci-server --version 4.0.1 --force

7. アップグレードステータスを確認する

以下のコマンドを実行し、すべてのポッドが起動し実行されていることをことを確認します。

kubectl -n <namespace> get pods

8. DNS 設定を更新する

Server 4.x への移行は、DNS 設定に破壊的な変更を加えます。 Server 4.x では、これまで必要だった 4 つのロードバランサーと 5 つの DNS レコードが circleci-proxy や circleci-proxy-acm という名前の 1 つの load-balancer/external-ip サービスに置き換えられます。このロードバランサーは <your-domain> とアプリの <your-domain> の 2 つの DNS レコードを介してルーティングする必要があります。 vm-service、output-processer 、Nomad のそれぞれ異なるドメインは不要になりました。外部 IP/ ロードバランサーを取得して、DNS レコードを適宜アップデートしてください。

kubectl -n <namespace> get svc circleci-proxy

# AWS Provider: XXXXX.elb.XXXXX.amazonaws.com
# GCP Provider: XXX.XXX.XXX.XXX

以下の Kubernetes サービスオブジェクトは、名前が変更されています。

circleci-server-traefik (LoadBalancer) → kong (ClusterIP)
nomad-server-external (LoadBalancer) → nomad-server (ClusterIP)
output-processor (LoadBalancer) → output-processor (ClusterIP)
vm-service (LoadBalancer) → vm-service (ClusterIP)

以下の Kubernetes サービスオブジェクトが追加されています。

circleci-proxy or circleci-proxy-acm (LoadBalancer)

9. Nomad Terraform を実行する

Nomad Terraform を実行し、Nomad クライアントを再作成し、server_endpoint を <domain>:4647 に設定します。こちらに記載されている手順に従ってください。 Nomad Sever-Client の通信用に生成された証明書とキー (base64 エンコード) を使用して、helm 値のファイルを更新します。

10. CircleCI Server v4.x への移行を検証する

新しいコミットをプッシュして、新しい CircleCI Server 4.x 環境で realitycheck を再実行します。

11. 最新情報をチームで共有する

realitycheck の実行が正常に完了したら、このアップグレードについてチームに連絡します。

次のステップ

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

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

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

サポートが必要ですか

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

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

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