Start Building for Free
CircleCI.comアカデミーブログコミュニティサポート

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

5 days ago2 min read
Server v4.x
サーバー管理者
このページの内容

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

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

前提条件

移行

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

  • KOTS 設定の YAML ファイルへのエクスポート

  • エクスポートされた YAML ファイルを、v4.x への移行に向け helm と一緒に使用するように変更

  • すべての Kubernetes リソースに helm の注釈を付与

  • Postgres DB の ドメイン の移行を実行

  • すべての KOTS 関連リソースを削除するクリーンアップステップの実行

  • 「次のステップ」を含む出力メッセージの表示

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 ファイルが生成されます。

  1. git clone https://github.com/CircleCI-Public/server-scripts を実行します。

  2. kots-exporter ディレクトリを cd server-scripts/kots-exporter に変更します。

  3. 移行スクリプト、./kots-exporter.sh を実行します。

  4. 以下の情報を入力するよう求められます。

    • CircleCI Server 3.x のリリース名、circleci-server

    • CircleCI Server 3.x の Kubernetes 名前空間

    • サーバー 4.x のライセンス文字列。CircleCI の担当者から提供されます。

  5. スクリプトが完成すると、実行する次のステップの詳細についての下記のようなメッセージが表示されます。

############ Upgrade Commands ################
Before upgrading to 4.0, follow below steps:

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.0
-------------------------------------------------------------------------
## 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

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 --contexts 5 oci://cciserver.azurecr.io/circleci-server --version 4.0.0

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

  • 黄色 に強調表示されている文字列: changedadded などの 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.0 --force

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

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

kubectl -n <namespace> get pods

8. DNS 設定を更新する

Server 4.x への移行は、DNS 設定に破壊的な変更を加えます。 Server 4.x では、これまで必要だった 4 つのロードバランサーと 5 つの DNS レコードが circleci-proxycircleci-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 でご利用いただけます。 ご協力いただき、ありがとうございます。

サポートが必要ですか

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

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