アップグレード

Jitera Self-Hostedを新しいHelmチャートバージョンに安全にアップグレードする

このページでは、既存のJitera Self-Hostedデプロイメントを新しいHelmチャートバージョンにアップグレードする手順を説明します。

---

​

アップグレード前のチェックリスト

1. データベースをバックアップする。 チャート変更前に、PostgreSQL（Automation、PGVector）および MongoDB / DocumentDB / Cosmos DB のバックアップを取得します。データベースマイグレーションは前方一方向です — チャートのpost-installフックが db:migrate と data:migrate を実行しますが、いずれもダウングレードパスはありません。具体的なバックアップ手順は構成によって異なります:

   • マネージドデータベース（RDS / Cloud SQL / Cosmos DB 等）: バックアップとリストア のクラウドプロバイダー別スナップショット手順を参照
   • クラスター内（in-cluster）データベース: PostgreSQL バックアップ および MongoDB バックアップ の pg_dump / mongodump 手順を参照
   メジャー版を跨ぐアップグレードでは、バックアップの取得は必須です。 バージョン間が離れている場合、多数のテーブル DROP やデータマイグレーションが含まれることがあります。helm rollback 単独ではスキーマがロールバックされないため、アプリケーションの一部機能（admin rake タスク、削除されたテーブルを参照する処理など）が PG::UndefinedTable で停止します。バックアップがなければ完全な復旧手段がありません。

   取得したバックアップ（スナップショット ID やダンプファイルパス）は リリース手順書 / リリースチケットに必ず記録 してください。ロールバック判断時に即座に参照できる状態にしておくことが、ダウンタイム短縮の前提条件になります。

2. 現在のHelmリリース状態を保存する。 ライブの values と revision 番号を記録します — どちらもロールバックが必要になった場合に役立ちます。

   helm -n jitera get values jitera > values-backup-$(date +%Y%m%d).yaml
   helm -n jitera history jitera
   

3. values.yaml の差分を確認する — 古いチャートと新しいチャートの間で、オーバーライドしているキーに注目します:

   diff <old-chart-dir>/charts/jitera/values.yaml         <new-chart-dir>/charts/jitera/values.yaml
   

   過去に変更されたことのある主なキー: externalPostgres.*、externalPgvector.*、externalMongodb.*、kong.proxy.annotations、boost.api_config.*、credentials.*。

4. 同時実行ワークロードを停止する。 クラスターにアクセスするCI/CDパイプラインを一時停止し、実行中のバックグラウンドジョブを完了させ、ユーザーに通知します — アップグレード範囲によってはロールアウトに 10〜30 分かかり、サービスが一時的に利用できない時間帯が発生します。

---

​

アップグレード手順

ハイレベルなフローはどのプラットフォームでも同じで、チャートの展開先と Helm コマンドの周辺要素のみが異なります。

1. 新しいチャートzipをJiteraから入手します（例: jitera-helm-<VERSION>.zip）。

2. 現在のチャートと並列に展開します（上書きしないでください — 前のチャートディレクトリはロールバック用に残しておきます）:

   cp /path/to/jitera-helm-<VERSION>.zip .
   unzip jitera-helm-<VERSION>.zip
   

3. Helm values を更新する（または Terraform 変数を更新する）— 新しいチャートパスを指すようにします:

   # Terraform
   helm_chart_path = "./jitera-helm-<VERSION>/charts/jitera"
   
   # Manual Helm — まずプレビュー（helm-diff プラグインが必要）
   helm -n jitera diff upgrade jitera ./jitera-helm-<VERSION>/charts/jitera      -f values.yaml
   
   # Manual Helm — 適用
   helm -n jitera upgrade jitera ./jitera-helm-<VERSION>/charts/jitera      -f values.yaml --timeout 15m
   

4. 計画して適用する（Terraform 管理の場合）— helm release をターゲット指定して、関係のないドリフトを避けます:

   terraform plan  -target=helm_release.jitera -out=upgrade.tfplan
   terraform apply upgrade.tfplan
   

5. ロールアウトを監視する。 チャートのpost-installフックが db:create、db:migrate、data:migrate を実行します。このフックが失敗すると、下流のPod（Automation、Ultron）が不完全なスキーマに対してクラッシュループします。マイグレーションジョブが Complete を表示するまで、その他のロールアウトを信頼しないでください。

   kubectl -n jitera get pods -w
   kubectl -n jitera logs -l app=jitera-automation-db --tail=200
   

6. CLI認証を確認する — Jitera CLI を使用している場合（チャートのpost-installフックは一部のプラットフォームで PEM の改行を削除することがあります — シークレットが正しく見えるか確認します）:

   kubectl -n jitera get secret jitera-ultron      -o jsonpath='{.data.CLI_ZIPPER_PRIVATE_KEY}' | base64 -d | head -1
   # 期待値: -----BEGIN PRIVATE KEY-----
   

7. アップグレードしたデプロイメントのスモークテスト。 Jitera Studio のアプリドメインにアクセスし（HTTP 200 が期待されます）、テストユーザーを招待し（メール配信が成功することを期待）、テストプロジェクトから jitera init を実行します（認証とアップロードが成功することを期待）。

---

​

ロールバック

アップグレードに失敗し、Helm の自動ロールバック（cleanup_on_fail）が完全に回復しない場合は、まずロールバック対象のリリースペアがどのシナリオに該当するかを判定 してから戦略を選択してください。helm rollback 単独で復旧できるケースと、必ず DB スナップショット復元を伴うケースが明確に分かれます。

​

ロールバックシナリオの判定

#	シナリオ	説明	スキーマ差分	helm rollback 単独で復旧?	推奨手順
1	パッチアップデート（差分なし）	同一マイナー内のパッチ間	なし（image tag のみ）	✅ 完全 OK	helm rollback のみ
2	マイナー / メジャーアップデート（前方互換あり）	マイナー / メジャー版を跨ぐアップデート	テーブル DROP 等あり、ただし旧コードからの参照が admin rake のみ	⚠️ ユーザ向け機能は OK、admin 系は NG	helm rollback のみ可（推奨はシナリオ 3 と同等の DB 復元）
3	マイナー / メジャーアップデート（整合性リスクあり）	マイナー / メジャー版を跨ぐアップデート / ロールバック期間中に書き込み発生	同上 + 旧コードで使用されるテーブルが消える / ロールバック中の書き込みあり	❌ 機能停止 / データ不整合	DB スナップショット復元が必須

判定手順:

1. 旧チャートと新チャートの charts/jitera/templates/ および values.yaml の diff を確認

2. Rails image 内の db/migrate/ および db/data/ のファイル一覧を新旧 image で比較し、新規ファイルの有無を確認

   docker run --rm <jitera_automation:OLD_TAG> ls /web/db/migrate/ > /tmp/old.txt
   docker run --rm <jitera_automation:NEW_TAG> ls /web/db/migrate/ > /tmp/new.txt
   diff /tmp/old.txt /tmp/new.txt
   

3. 以下の 両方 を満たせば シナリオ 1:

   • チャート構造（templates/ / values.yaml のキー）に変更がない（ステップ 1 が image tag のみの差分）、かつ
   • 新しい image に新規の db/migrate/* / db/data/* ファイルが存在しない（ステップ 2 が空）
   チャートに構造変更がなくても、Rails image に新規 migration が追加されているケースは存在します（パッチリリースで migration が混入するなど）。チャート差分だけでシナリオ 1 と判定すると、helm rollback 後に PG::UndefinedTable 等が発生する恐れがあるため、必ず image 内の migration も確認してください。

4. ステップ 3 の条件を満たさない場合、ステップ 2 で差分のある migration が destructive（Drop*Table / Drop*Column / NotNull / 型変更）を含むか確認

5. destructive を含む場合、削除対象テーブル / カラムが 旧コードのユーザ機能から参照されているか を grep で確認

6. ロールバック期間中に書き込みが発生する可能性、または完全なデータ整合性が要求される場合は シナリオ 3 に格上げ

判定困難な場合は デフォルトでシナリオ 3 として扱う ことを推奨します。シナリオ 2 として運用して問題が表面化するのは数日後（admin 操作時など）になりがちで、検出が遅れます。

​

シナリオ 1: パッチアップデートのロールバック

チャート構造の変更も新規 migration もないため、helm rollback 単独で完全に復旧できます。DB 復元やアプリスケールダウンは 不要 です。

Terraform 管理のロールバック:

# 1. tfvars の helm_chart_path を以前のバージョンに戻す
git checkout terraform.tfvars   # コミット済みの場合
# または手動で編集して戻す

# 2. Terraform にリリースをダウングレードさせる
terraform apply -target=helm_release.jitera

Helm 直接ロールバック（Terraform ダウングレードが破壊的な diff を生成する場合）:

helm -n jitera history jitera
helm -n jitera rollback jitera <prev-revision>
kubectl -n jitera rollout status deploy/jitera-automation-rails
terraform refresh   # 状態を再同期（該当する場合）

​

シナリオ 2: 前方互換ありのマイナー / メジャーロールバック

helm rollback を実行したあと、必ず以下の確認を実施してください:

# helm rollback 実行
helm -n jitera rollback jitera <prev-revision>
kubectl -n jitera rollout status deploy/jitera-automation-rails

# db:migrate:status で "NO FILE" 行を確認（cosmetic だが影響範囲の手がかり）
kubectl -n jitera exec deploy/jitera-automation-rails -- \
  bundle exec rails db:migrate:status | grep "NO FILE"

# 主要 UI フロー（サインイン、ダッシュボード、プロジェクト一覧）の動作確認

シナリオ 2 として運用する場合の前提条件:

• 削除対象テーブル / カラムを使う機能（モバイルアプリ機能、Web メール機能等）を実運用で使用していない
• ロールバック期間中に書き込み（新規プロジェクト作成等）が発生しない
• 多少のデータ不整合（admin 系の PG::UndefinedTable、schema_migrations が新バージョン値のまま等）を許容できる

これらが満たせない場合は、シナリオ 3（DB スナップショット復元付き）の手順を採用してください。

​

シナリオ 3: 整合性リスクありのロールバック（DB スナップショット復元必須）

以下の 3 つのリスクがあるため、helm rollback 単独では復旧できません:

• リスク A: 旧コードが触るテーブルが消えており、PG::UndefinedTable でユーザ機能が停止する
• リスク B: ロールバック期間中の書き込みが、再アップグレード時のデータマイグレーションの対象外になる（Rails の冪等動作により全行スキップされる）。期間中に作られた行は NULL のまま残り、整合性が崩れる
• リスク C: pg_restore -c（clean モード）では、新バージョン由来の ENUM 型や新規テーブルが残存し、再アップグレード時に PG::DuplicateObject で migration job が失敗する

​

復元対象のデータストア

以下のセクションでは Automation の PostgreSQL を例に手順を示します。アップグレード前のチェックリストで取得した すべてのデータストアのスナップショット を、同じタイミングで復元してください。データストア別の復元コマンドは バックアップとリストア を参照します:

データストア	復元手順
Automation PostgreSQL	PostgreSQL のリストア — 以下の手順と同じパターン
PGVector PostgreSQL	PostgreSQL のリストア — PGVector インスタンスに対して同じ手順を適用（埋め込みベクトルが旧バージョン整合の状態に戻る）
MongoDB / DocumentDB / Cosmos DB	MongoDB のリストア — mongorestore または各クラウドプロバイダーのスナップショット復元

Automation Postgres だけ復元してはいけません。 data:migrate は MongoDB のドキュメントや PGVector の埋め込みも書き換えることがあるため、片方のデータストアだけ巻き戻すと残るストアとの整合性が崩れます。事前にスナップショットを取得した すべてのデータストアを同じスナップショット世代に揃えて復元 してください。

pg_restore -c（clean モード）は使用しないでください。 pg_restore -c を使うと、新バージョンで追加された ENUM 型や新規テーブルがオーファンとして残存し、再アップグレード時に CREATE TYPE ... already exists エラーで migration job が失敗します。代わりに、以下の 新インスタンス復元 + エンドポイント切替 フローを使用してください。

​

推奨手順: 新インスタンスへのスナップショット復元 + エンドポイント切替

helm rollback はマニフェスト全体（Deployment の replicas を含む）を巻き戻すため、先にスケールダウンしておいた Pod が即座に復活します。同じインスタンス上で DROP DATABASE / pg_restore を実施しようとすると、復活した Pod が再接続して以下が発生します:

• DROP DATABASE が database "jitera" is being accessed by other users で失敗
• 一瞬接続が切れて DROP が成功したとしても、旧バージョン Pod が新スキーマに接続し PG::UndefinedTable を起こす
• Sidekiq のリトライキューやキャッシュに不整合データが残る

これらの競合を回避するため、スナップショットから新インスタンスを作成し、Helm value で接続先を切り替えてから helm rollback を実行します:

# === 前提: アップグレード前にスナップショット取得済み ===
# 「アップグレード前のチェックリスト」のステップ 1 を参照

# === ロールバック実行 ===

# 1. アプリ層スケールダウン（ユーザートラフィック停止 + DB 接続解放）
for d in jitera-automation-rails jitera-automation-rpc \
         jitera-automation-sidekiq jitera-automation-sidekiq-priority \
         jitera-hasura jitera-boost jitera-ultron jitera-ultron-public; do
  kubectl -n jitera scale deploy $d --replicas=0
done
kubectl -n jitera wait --for=delete --timeout=5m \
  -l 'app in (jitera-automation-rails,jitera-automation-rpc,jitera-automation-sidekiq,jitera-automation-sidekiq-priority,jitera-hasura,jitera-boost,jitera-ultron,jitera-ultron-public)' pod

# 2. スナップショットから新 RDS / PostgreSQL Flexible Server インスタンスを作成
#    AWS の例:
aws rds restore-db-instance-from-db-snapshot \
  --db-instance-identifier jitera-rollback-$(date +%Y%m%d-%H%M) \
  --db-snapshot-identifier <PRE_UPGRADE_SNAPSHOT_ID>
aws rds wait db-instance-available \
  --db-instance-identifier jitera-rollback-$(date +%Y%m%d-%H%M)
#    Azure / GCP のスナップショット復元コマンドは [バックアップとリストア] を参照

# 3. 復元したインスタンスのエンドポイントを Helm value に反映
#    例: values.yaml の externalPostgres.host を新エンドポイントに書き換える

# 4. Helm リソースをロールバック（新エンドポイントを反映した values で）
helm -n jitera rollback jitera <prev-revision> \
  -f values.yaml

# 5. ロールアウト完了を待機
for d in jitera-automation-rails jitera-automation-rpc \
         jitera-automation-sidekiq jitera-automation-sidekiq-priority \
         jitera-hasura jitera-boost jitera-ultron jitera-ultron-public; do
  kubectl -n jitera rollout status deploy/$d --timeout=5m
done

# 6. 検証
kubectl -n jitera exec deploy/jitera-automation-rails -- \
  bundle exec rails db:migrate:status | grep "NO FILE" | wc -l
# 期待値: 0

kubectl -n jitera exec deploy/jitera-automation-rails -- \
  bundle exec rails runner "puts Organization.count"
# 期待値: 数値が返る（PG::UndefinedTable が出ない）

<prev-revision> には「アップグレード前のチェックリスト」のステップ 2 で記録した revision 番号（helm history の出力）を指定します。

上記のスケールダウン対象は DB 接続を握る workload に限定しています。Frontend、SWEF、Playwright、Document Converter などユーザー向けの Pod は別途、メンテナンス画面の表示や maintenance mode への切替で遮断してください。

想定ダウンタイム:

段階	ダウンタイム
アプリスケールダウン	1 〜 5 分
スナップショット復元（新インスタンス作成）	5 〜 30 分（DB サイズ / クラウドプロバイダーに依存）
エンドポイント切替 + helm rollback	1 〜 3 分
ロールアウト完了待ち	2 〜 10 分

​

代替手順: 既存インスタンスを直接書き戻す（小規模環境向け）

新インスタンスを作成できない / コスト上の理由で既存インスタンスを再利用したい場合は、以下の手順を取ります。helm rollback で Pod が復活するレース を避けるため、ロールバック後に 再度スケールダウン してから DB を入れ替える点が要です。

# 1. アプリ層スケールダウン
for d in jitera-automation-rails jitera-automation-rpc \
         jitera-automation-sidekiq jitera-automation-sidekiq-priority \
         jitera-hasura jitera-boost jitera-ultron jitera-ultron-public; do
  kubectl -n jitera scale deploy $d --replicas=0
done
kubectl -n jitera wait --for=delete --timeout=5m \
  -l 'app in (jitera-automation-rails,jitera-automation-rpc,jitera-automation-sidekiq,jitera-automation-sidekiq-priority,jitera-hasura,jitera-boost,jitera-ultron,jitera-ultron-public)' pod

# 2. Helm リソースをロールバック
helm -n jitera rollback jitera <prev-revision>

# 3. ロールバックで replicas も巻き戻り Pod が復活するため、再度スケールダウン
for d in jitera-automation-rails jitera-automation-rpc \
         jitera-automation-sidekiq jitera-automation-sidekiq-priority \
         jitera-hasura jitera-boost jitera-ultron jitera-ultron-public; do
  kubectl -n jitera scale deploy $d --replicas=0
done
kubectl -n jitera wait --for=delete --timeout=5m \
  -l 'app in (jitera-automation-rails,jitera-automation-rpc,jitera-automation-sidekiq,jitera-automation-sidekiq-priority,jitera-hasura,jitera-boost,jitera-ultron,jitera-ultron-public)' pod

# 4. DB を初期化してスナップショットから復元
#    DROP / CREATE は対象 DB ではなく管理 DB (`postgres` など) に接続して実行する
psql -h <pg-host> -U <admin> -d postgres -c "DROP DATABASE jitera"
psql -h <pg-host> -U <admin> -d postgres -c "CREATE DATABASE jitera OWNER jitera"
pg_restore -h <pg-host> -U <admin> -d jitera --no-owner --no-acl /backup/jitera.dump

# 5. アプリ層スケールアップ
for d in jitera-automation-rails jitera-automation-rpc \
         jitera-automation-sidekiq jitera-automation-sidekiq-priority \
         jitera-hasura jitera-boost jitera-ultron jitera-ultron-public; do
  kubectl -n jitera scale deploy $d --replicas=1
done

---

​

関連ドキュメント

AWS EKS デプロイメント

完全なデプロイメントガイド（プラットフォーム別の前提条件と検証手順を含む）

Azure AKS デプロイメント

完全なデプロイメントガイド（プラットフォーム別の前提条件と検証手順を含む）

メンテナンス概要

バックアップ、リストア、定期メンテナンスタスク

トラブルシューティング

インシデント対応フローとよくある問題