Helmでの移行

Kubernetes + Helm で運用しているドメインをv1からv2へ移行する手順です。

移行は3つのチャートを段階的に切り替えていく形で進めます。

1. concrnt(v1)… 現在運用中のチャート
2. concrnt2-migration … v1とv2の両スタックを併設する移行用チャート
3. concrnt2(v2)… v1を撤去した純v2チャート

concrnt2-migration チャートは、既存のv1データベース(db)を再利用しつつv2用のデータベース(v2db)を新たに立ち上げ、両者を同時に稼働させます。この状態で移行コマンドを実行してv1のデータをv2へコピーし、最後に純v2チャートへ切り替えます。

Danger

作業を始める前に、必ずv1データベースのバックアップを取得してください。

チャートは以下のHelmリポジトリで公開されています。

helm repo add concrnt https://concrnt.github.io/helmcharts
helm repo update

Note

リポジトリを追加する代わりに、helmchartsリポジトリをgit cloneしてcharts/配下のチャートをローカルパス指定で使うこともできます。

Step 1. 移行用チャート(concrnt2-migration)へ切り替える

現在v1の concrnt チャートで使っている values.yaml に、v2側の設定(concrnt2: ブロック)を追記します。

Caution

concrnt2.fqdn と concrnt2.privatekey には、v1と同じ値(concrnt.fqdn / concrnt.privatekey)を指定してください。ドメインの同一性を引き継ぐために必須です。

# 既存のv1設定(そのまま)
concrnt:
  fqdn: example.tld
  privatekey: <v1と同じ秘密鍵>
  dimension: concrnt-mainnet
  # ...

# v2側の設定(追記)
concrnt2:
  fqdn: example.tld          # v1と同じfqdn
  privatekey: <v1と同じ秘密鍵>  # v1と同じ秘密鍵
  layer: concrnt-mainnet
  registration: invite

同じリリース名で concrnt2-migration チャートへアップグレードします。

helm upgrade <リリース名> concrnt/concrnt2-migration -n <namespace> -f values.yaml

これにより、既存のv1データベースのPVC(postgres-varlib)はそのまま維持され、v2スタック(concrnt2 / world-app / v2db / v2-redis / v2-memcached)が追加で起動します。公開エンドポイントはv2の concrnt2 に切り替わり、/api/v1 や /ap などのレガシーパスは内部で ccgateway(v1)へプロキシされます。v1のActivityPubブリッジ(activitypub.enabled: true)を運用している場合も、この時点では /ap や .well-known 系のパスは引き続きv1ブリッジが処理します(ActivityPubの移行はStep 4で行います)。

Podがすべて起動したことを確認してください。

kubectl get pods -n <namespace>

Step 2. 移行ジョブを実行する

データ移行は conctl migrate v1-to-v2 コマンドで行います。以下は移行ジョブのサンプル(migration.yaml)です。concrnt2-migration チャートを展開したものと同じnamespaceに適用してください。

apiVersion: batch/v1
kind: CronJob
metadata:
  name: v1-v2-migration
  namespace: denken
spec:
  suspend: true
  schedule: "0 * * * *"
  concurrencyPolicy: Forbid

  successfulJobsHistoryLimit: 1
  failedJobsHistoryLimit: 3

  jobTemplate:
    spec:
      backoffLimit: 0
      ttlSecondsAfterFinished: 86400
      template:
        spec:
          restartPolicy: Never
          containers:
            - name: migration
              image: ghcr.io/concrnt/concrnt:v1.10.0-beta4
              command:
                - conctl
                - migrate
                - v1-to-v2
                - --from-csid
                - ccs15zt7a8kxv2k9pguy4m6wfucwj2makte8fzfl7v
                - --from-dsn
                - postgres://postgres:postgres@db:5432/concrnt
                - --from-fqdn
                - denken.concrnt.net
                - --dest-dsn
                - postgres://postgres:postgres@v2db:5432/concrnt
                - --dest-fqdn
                - denken.concrnt.net
                - --ignore-ccids
                - con1zzvye2yc84a7vx7eyznaseghhnmsvtss4aavjr
              volumeMounts:
                - mountPath: /etc/concrnt/config
                  name: concrnt2-config
          volumes:
            - name: concrnt2-config
              projected:
                defaultMode: 420
                sources:
                  - configMap:
                      name: concrnt2-config
                  - secret:
                      name: concrnt2-secret

各項目の意味と、自分の環境に合わせて書き換える箇所は以下のとおりです。

項目	説明
metadata.namespace	concrnt2-migration を展開したnamespaceに合わせます。
spec.suspend: true	誤って定期実行されないよう、CronJobは停止状態にしておきます(手動でJobを起動します)。
image	conctl migrate サブコマンドを含むイメージです。
--from-csid	移行元(v1)ドメインのCSIDを指定します。
--from-dsn	v1データベースへの接続文字列。移行チャートでは db サービスです。
--from-fqdn	移行元ドメインのfqdn。
--dest-dsn	v2データベースへの接続文字列。移行チャートでは v2db サービスです。
--dest-fqdn	移行先ドメインのfqdn。--from-fqdn と同じ値を指定します。
--ignore-ccids	移行対象から除外するアカウントのCCID(例: v1用のAPIサーバーエージェント)。不要なら削除します。

Note

volumes で concrnt2-config と concrnt2-secret をマウントしているのは、移行コマンドがv2の設定(config.yaml)を参照するためです。これらは concrnt2-migration チャートが生成したものをそのまま利用します(concrnt2-secret は concrnt2.useSecret: true の場合のみ存在します)。

適用したら、CronJobから手動でJobを起動して移行を実行します。

kubectl apply -f migration.yaml -n <namespace>
kubectl create job --from=cronjob/v1-v2-migration v1-v2-migration-run-1 -n <namespace>

進捗はログで確認します。

kubectl logs -f job/v1-v2-migration-run-1 -n <namespace>

Caution

データ量によっては移行に時間がかかります。ジョブが正常に完了(Completed)することを確認してから次のステップへ進んでください。エラーが出た場合は原因を解消し、v2データベースを初期化してからやり直してください。

Step 3. 移行結果を確認する

Webクライアント https://concrnt.world から自分のドメインにアクセスし、既存のアカウントでログインできること、過去のタイムラインやメッセージが表示されることを確認します。

Step 4. ActivityPubブリッジを移行する(オプション)

Note

v1のActivityPubブリッジ(ccworld-ap-bridge)を運用していない場合、このステップは不要です。Step 5へ進んでください。

v2では新しいActivityPubブリッジ(concrnt/activitypub、イメージ ghcr.io/concrnt/activitypub)を使用します。移行は「並行デプロイ → データ移行 → 経路切り替え」の順で行います。データ移行が終わるまでは /ap や .well-known 系のパスはv1ブリッジが処理し続けるため、外部からの連合は途切れません。

4-1. ブリッジ用サービスアカウントを用意する

v2ブリッジはconcrnt上のサービスアカウントとして動作します。v1ブリッジで使っていたアカウント(activitypub.privatekey に設定していた鍵)をそのまま引き継ぐことを推奨します。

このアカウントはv1上の通常のアカウントなので、Step 2の移行で(--ignore-ccids で除外していなければ)既にv2へ移行されています。その場合は新たに作成する必要はなく、その秘密鍵を4-2でそのまま使ってください。

もしv2に存在しない場合(移行時に除外した場合など)は、--privatekey で鍵を指定して登録できます。

kubectl exec -n <namespace> deploy/concrnt2 -- conctl operation create-account --privatekey <v1ブリッジの秘密鍵>

新しいアカウントを作る場合は --privatekey を付けずに実行し、出力される ccid と privatekey を控えてください(いずれの場合もアカウントはv2コアにローカル登録されます)。

4-2. v2ブリッジを並行デプロイする

values.yaml に activitypub2: ブロックを追記して helm upgrade します。

activitypub2:
  enabled: true
  active: false   # まだ経路はv1に向けたままにする
  privatekey: <4-1で用意したアカウントの秘密鍵>

CCIDの設定は不要です(秘密鍵から自動で導出されます)。

helm upgrade <リリース名> concrnt/concrnt2-migration -n <namespace> -f values.yaml

Caution

active はまだ false のままにしてください。データ移行が完了する前に経路をv2へ切り替えると、外部サーバーからの /ap へのアクセスに空の応答が返ってしまいます(切り替えは4-5で行います)。

Note

databaseUrl / redisUrl はデフォルトで v2db / v2-redis(v2コアと共有)を指します。DB構成を変更している場合はURL形式(postgres://...)で上書きしてください。

起動を確認します。初回起動時にv2ブリッジ用のテーブルが自動作成されます(これは4-4の移行コマンドの前提です)。

kubectl logs -n <namespace> deploy/activitypub

4-3. v2ブリッジを一時停止する

Caution

データ移行中にv2ブリッジが動いていると、移行中のフォローに対してFollowアクティビティをリモートサーバーへ再送してしまいます。必ず停止してから移行してください。

kubectl scale deployment activitypub --replicas=0 -n <namespace>

4-4. データを移行する

concrnt2 Podの中で conctl migrate ap-v1-to-v2 を実行します(認証トークンはPodにマウント済みのv2設定から自動生成されます)。まずは --dry-run で内容を確認します。

kubectl exec -n <namespace> deploy/concrnt2 -- conctl migrate ap-v1-to-v2 \
  --from-dsn "host=db user=postgres password=postgres dbname=concrnt port=5432 sslmode=disable" \
  --dest-dsn "postgres://postgres:postgres@v2db:5432/concrnt" \
  --dest-fqdn <あなたのfqdn> \
  --ap-ccid <4-1で用意したアカウントのCCID> \
  --dry-run

項目	説明
--from-dsn	v1データベースへの接続文字列。v1ブリッジはv1コアとデータベースを共有しているため、移行チャートでは db サービスです。
--dest-dsn	v2ブリッジのデータベースへの接続文字列。移行チャートでは v2db(v2コアと共有)です。
--dest-fqdn	移行先(v2)ドメインのfqdn。
--ap-ccid	4-1で用意したブリッジ用サービスアカウントのCCID。v1のアカウントを引き継いだ場合は、v1でブリッジ用ボットとして使っていたアカウントのCCIDです。

問題なければ --dry-run を外して再実行します。v1の ap_entities(アカウントと鍵)とフォロー・フォロワー情報がv2へ移行されます。

Caution

以下は移行されません。

• 各ユーザーのlisten対象タイムライン設定はリセットされます(ユーザーによる再設定が必要です)
• 既存投稿とActivityPubオブジェクトの対応関係(ap_object_references)は引き継がれません
• also_known_as の設定は引き継がれません
• 鍵はPEMからJWKへ変換されます。変換に失敗したアカウントには新しい鍵が発行され、署名の連続性が失われます(リモートサーバーからの見え方に影響する場合があります)

4-5. ブリッジを再開し、経路を切り替える

v2ブリッジを再開します。ブリッジは起動時に移行済みのフォロー情報を読み込みます。

kubectl scale deployment activitypub --replicas=1 -n <namespace>

Note

helm upgrade はreplicas数を復元しないため、このコマンドは省略できません。

ログにエラーがないことを確認したら、values.yaml で activitypub2.active: true に変更して helm upgrade します。これで /ap と .well-known/webfinger などの経路がv1ブリッジからv2ブリッジへ切り替わります(concrnt2 Podは設定チェックサムの変更により自動で再起動されます)。

動作を確認します。

curl "https://<fqdn>/.well-known/webfinger?resource=acct:<ユーザー名>@<fqdn>"
curl "https://<fqdn>/ap/test"

問題なければv1ブリッジは不要です。values.yaml の activitypub.enabled を false にして helm upgrade してかまいません。

Step 5. 純v2チャート(concrnt2)へ切り替える

移行が問題なく完了したら、v1スタックを撤去して純v2構成へ移行します。同じリリース名で concrnt2 チャートへアップグレードしてください。

helm upgrade <リリース名> concrnt/concrnt2 -n <namespace> -f values.yaml

v2db / v2-redis / v2-memcached のPVCは維持されたまま、v1関連のコンポーネント(ccgateway / ccapi / ccwebui など)が削除されます。以降はv2単独での運用となります。

Note

concrnt2 チャートには /api/v1 などのレガシーパスをv1へプロキシする設定はありません。このステップに進む前に、移行が完全に済んでいることを必ず確認してください。

Note

concrnt2 チャートにもv2 ActivityPubブリッジのモジュールが含まれています。activitypub2: ブロックはそのまま引き継がれ、enabled: true であればブリッジのデプロイと /ap の経路設定が維持されます(active キーはこのチャートでは使われません)。v1用の activitypub: ブロックは削除してかまいません。

不要になったv1のデータベースPVC(postgres-varlib)は、バックアップを保全したうえで削除してかまいません。