AWS EKS インストール

このガイドでは、AWS ネイティブサービスを使用して Amazon EKS に Jitera Self-Hosted をデプロイする手順を説明します。

このガイドの例では、以下のサンプル値を使用しています。実際の値に置き換えてください：

Helmリリース名 / ネームスペース：jitera（つまりhelm install jitera ./charts/jitera --namespace jitera）— Kubernetesリソース名はこれがプレフィックスとして付与されます（例：jitera-automation-rails、jitera-ultron）
S3バケット名：jitera-storage-default、jitera-storage-public、jitera-storage-export、jitera-storage-ultron
S3バケットリージョン：ap-northeast-1（必須 — ステップ 2 の Warning を参照）
AWSリージョン（EKS、RDS等）：ap-northeast-1
ドメイン：jitera.yourdomain.com
シークレット名：jitera-registry（イメージプルシークレット）、jitera-tls（TLS証明書）

前提条件チェックリスト

まずデプロイ要件のチェックリストを完了してから、以下のAWS固有の項目を確認してください：

適切な権限を持つ AWS アカウント
AWS CLI が設定済み（aws configure）
eksctl がインストール済み（推奨）または Terraform

AWS インフラストラクチャのセットアップ

このセクションのAWS CLIコマンドは例として提供されています。お客様の環境では異なる設定が必要な場合があります。詳細な手順については、AWSの公式ドキュメントを参照してください。本番環境で外部マネージドサービス（RDS、DocumentDB、ElastiCache、Amazon MQ）を使用する場合：これらのサービスの作成をEKSクラスター作成（ステップ 1）と並行して開始してください。マネージドデータベースは通常10〜20分で利用可能になり、ステップ 4のHelmインストール実行前に準備が完了している必要があります。設定の詳細は外部AWSサービスセクションを参照してください。

ステップ 1: EKS クラスターの作成

クラスター仕様を満たすEKSクラスターを作成します。以下はeksctlを使用した例です：

この例では3x m6i.xlargeノード（合計12 vCPU、48 GB）をプロビジョニングしており、評価環境の最小値を満たしています。本番環境のデプロイメントでは、m6i.2xlargeインスタンスを使用するか、ノード数を増やして本番環境の最小値（16コア、64 GB）を満たしてください。サイジングガイドでティア推奨事項を参照してください。

# cluster.yaml
apiVersion: eksctl.io/v1alpha5
kind: ClusterConfig

metadata:
  name: jitera-cluster
  region: ap-northeast-1
  version: "1.35"

managedNodeGroups:
  - name: jitera-nodes
    instanceType: m6i.xlarge
    desiredCapacity: 3
    minSize: 3
    maxSize: 6
    volumeSize: 200
    volumeType: gp3
    iam:
      withAddonPolicies:
        ebs: true
        efs: true

iam:
  withOIDC: true

addons:
  - name: vpc-cni
  - name: coredns
  - name: kube-proxy
  - name: aws-ebs-csi-driver

eksctl create cluster -f cluster.yaml

aws-ebs-csi-driver アドオンは永続ボリュームのプロビジョニングに必要です。これがないと、データベースPodがPVCバインドエラーで起動に失敗します。

Amazon Linux 2023（EKS 1.30+のデフォルト）を使用するEKSでは、volumeSizeをノードあたり最低200 GBに設定してください。Jiteraコンテナイメージは合計約30〜50 GBの圧縮レイヤーがあり、containerdのoverlayfsストレージは展開時にこれを増大させます。100 GBのボリュームでは初回のイメージプル時にディスク容量が不足し、no space left on deviceエラーが発生します。このエラーが発生した場合は、ボリュームサイズを増やしてノードを入れ替えてください。

この例ではeksctlのデフォルトVPCを使用しており、プライベートサブネットからのアウトバウンド通信用NATゲートウェイが自動的にプロビジョニングされます。カスタムVPCを使用する場合は、NATゲートウェイを明示的に設定する必要があります — NATゲートウェイがない場合、ワーカーノードがAWSサービス（ECR、S3、STSなど）に到達できず、クラスターのブートストラップ時にイメージプルやアドオンのインストールが失敗します。詳細は Amazon EKSのVPC要件を参照してください。

クラスター作成の詳細な手順については Amazon EKSドキュメントを参照してください。

ステップ 2: S3 バケットの作成

ストレージ設定に記載されたアクセスレベルで4つのS3バケットを作成し、デフォルトバケットとパブリックバケットにCORSを設定します。

すべてのS3バケットは ap-northeast-1（東京）に作成する必要があります。アプリケーションはダイレクトアップロード用の署名付きURLを ap-northeast-1 リージョンでハードコードして生成します。他のリージョンのバケットを使用すると、jitera init（CLIプロジェクトインポート）が 301 Moved Permanently リダイレクトで失敗します。S3のクロスリージョンアクセスは正常に動作するため、EKSクラスターやその他のAWSサービスは別のリージョンに配置できます。

パブリックバケットにはパブリック読み取りアクセスを有効にする必要があります（S3バケットポリシーまたはACL）。その他のバケットはプライベートのままにしてください。
CORSのAllowedOriginsには、メインドメインとチャットドメインの両方を含める必要があります（例：https://app.example.com と https://chat.example.com）。オリジンが不足していると、アプリケーションでファイルアップロードが失敗します。
デフォルトバケットとパブリックバケットに必要なCORSルールについては、オブジェクトストレージ — CORS設定を参照してください。

バケット作成については Amazon S3ドキュメント、CORS設定を参照してください。

Helm設定

以下は例です — リージョン、バケット名、認証情報を実際の値に置き換えてください：

storage:
  provider: S3
  secret:
    aws:
      AWS_ACCESS_KEY_ID: "<YOUR_ACCESS_KEY>"
      AWS_SECRET_ACCESS_KEY: "<YOUR_SECRET_KEY>"
      AWS_REGION: "ap-northeast-1"                       # ap-northeast-1 必須（上記の Warning を参照）
      AWS_BUCKET: "jitera-storage-default"              # デフォルトバケット名
      AWS_PUBLIC_BUCKET: "jitera-storage-public"        # パブリックバケット名
      AWS_EXPORT_PROJECT_BUCKET: "jitera-storage-export" # エクスポートバケット名
      AWS_ULTRON_BUCKET: "jitera-storage-ultron"        # AIサービスバケット名

ステップ 3: S3 アクセス用 IAM ユーザーの作成

4つのJiteraバケットに対する以下のS3権限を持つIAMユーザーを作成してください。以下は例です — バケット名はステップ2で作成したものに置き換えてください：

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:PutObject",
        "s3:DeleteObject",
        "s3:ListBucket",
        "s3:GetBucketLocation"
      ],
      "Resource": [
        "arn:aws:s3:::jitera-storage-default",
        "arn:aws:s3:::jitera-storage-default/*",
        "arn:aws:s3:::jitera-storage-public",
        "arn:aws:s3:::jitera-storage-public/*",
        "arn:aws:s3:::jitera-storage-export",
        "arn:aws:s3:::jitera-storage-export/*",
        "arn:aws:s3:::jitera-storage-ultron",
        "arn:aws:s3:::jitera-storage-ultron/*"
      ]
    }
  ]
}

このIAMユーザーのアクセスキーを生成してください — Helmチャートには静的な認証情報（AWS_ACCESS_KEY_IDとAWS_SECRET_ACCESS_KEY）が必要です。ポリシー作成とアクセスキー管理については AWS IAMドキュメントを参照してください。

ステップ 4: TLS 証明書の取得

証明書は両方のホスト名（メインドメインとチャットドメイン）をカバーする必要があります。

自己署名証明書はサポートされていません。

オプション 1: AWS Certificate Manager（ACM）

ACMはAWSロードバランサーで使用するマネージド証明書を提供します。ACMの場合、Subject Alternative Name（SAN）またはワイルドカード証明書を使用してください。詳細な手順については AWS Certificate Managerドキュメントを参照してください。

例：CLI で ACM 証明書をリクエスト

aws acm request-certificate \
  --domain-name jitera.yourdomain.com \
  --subject-alternative-names "chat.yourdomain.com" \
  --validation-method DNS \
  --region ap-northeast-1

指示に従ってDNS検証を完了します。証明書ARNはHelm valuesのingress.annotationsで使用します（ステップ4: Valuesファイルの作成を参照）。

オプション 2: cert-manager と Let’s Encrypt

ACMを使用しない自動証明書管理の場合。インストール手順については cert-managerドキュメントを参照してください。

ステップ 5: メール（SES）の設定

メール配信用にAmazon SESをセットアップします。詳細な最新の手順については Amazon SESドキュメントを参照してください。

新しいSESアカウントはサンドボックスモードで開始され、検証済みメールアドレスへの送信のみが許可されます。サンドボックスモードでは、組織オーナーの招待メールが 554 Message rejected: Email address is not verified で暗黙的に失敗します — このエラーはRailsログにのみ表示され、UIには表示されません。テスト/パイロット環境の場合: 招待を送信する前に、各受信者アドレスを検証してください：

aws ses verify-email-identity \
  --profile <your-aws-profile> \
  --region ap-northeast-1 \
  --email-address recipient@example.com

本番環境の場合: サンドボックス制限を解除するために本番環境アクセスをリクエストしてください。承認には通常最大24時間かかります：

aws sesv2 put-account-details \
  --profile <your-aws-profile> \
  --region ap-northeast-1 \
  --production-access-enabled

詳細はAmazon SESサンドボックスのドキュメントを参照してください。

例：ドメインの検証とSMTP認証情報の作成

# ドメインIDの検証
aws ses verify-domain-identity \
  --domain yourdomain.com \
  --region ap-northeast-1

# 検証用DNSレコードの取得
aws ses get-identity-verification-attributes \
  --identities yourdomain.com \
  --region ap-northeast-1

DNS設定にTXTレコードを追加します。

# SMTP用IAMユーザーの作成
aws iam create-user --user-name jitera-ses-smtp

# SES送信ポリシーのアタッチ
aws iam attach-user-policy \
  --user-name jitera-ses-smtp \
  --policy-arn arn:aws:iam::aws:policy/AmazonSESFullAccess

# アクセスキーの作成
aws iam create-access-key --user-name jitera-ses-smtp

SMTPパスワードはIAMシークレットアクセスキーとは異なります。SES固有の署名アルゴリズムを使用して変換する必要があります。公式のSES SMTP認証情報変換手順に従ってください。Pythonのリファレンス実装が含まれています。

Helm設定

以下は例です — SMTPエンドポイント、認証情報、送信元アドレスを実際の値に置き換えてください：

mailer:
  smtp_settings:
    address: email-smtp.ap-northeast-1.amazonaws.com  # 使用するリージョンのSESエンドポイント
    user_name: "<SES_SMTP_USERNAME>"
    password: "<SES_SMTP_PASSWORD>"
  default_from_email: "noreply@yourdomain.com"

Jitera のインストール

ステップ 1: cert-manager のインストール（オプション）

TLSにACMを使用しない場合は、cert-managerをインストールします。インストール手順については cert-managerドキュメントを参照してください。

ステップ 2: Namespace とレジストリシークレットの作成

kubectl create namespace jitera

kubectl create secret docker-registry jitera-registry \
  --namespace jitera \
  --docker-server=registry.jitera.com \
  --docker-username="your-username" \
  --docker-password="your-password"

シークレット名（jitera-registry）はHelm valuesファイルのimagePullSecretsエントリと一致する必要があります。不一致の場合、すべてのPodでイメージプルが失敗します。

ステップ 3: Values ファイルの作成

AWSデプロイメント用のvaluesファイルを作成します。すべてのプレースホルダー値（<...>）を実際の設定に置き換えてください。ここに記載されていないパラメータはデフォルト値が使用されます — 完全なリストはHelm Valuesリファレンスを参照してください。

ロードバランサーとインバウンドIP制限。 Jiteraは、Kongイングレスコントローラー経由で**Classic Load Balancer（CLB）**をデフォルトでプロビジョニングします。ALBはサポートされていません — Kong IngressコントローラーがALBモードのイングレスを提供していないためです。NLBはJitera側の制限によりサポートされていません。Layer-4のIP許可リストには、インフラ層（コンソール / CLI / IaC）で事前にSecurity Groupを作成し、service.beta.kubernetes.io/aws-load-balancer-security-groups アノテーションでKongサービスにアタッチしてください。これによりSGのライフサイクルはHelmチャートから切り離され、helm uninstall でSGが削除されることはありません。

kong.proxy.loadBalancerSourceRanges は使用しないでください — 機能はしますが、インフラ層のルールをアプリケーション層のHelm値に結合してしまいます。
service.beta.kubernetes.io/aws-load-balancer-source-ranges アノテーションは使用しないでください — in-tree CLBでは静かに無視されます。
事前に作成したSGには、NAT Gateway EIP(s) を含める必要があります。公開アプリドメインへ戻るPodの通信（ヘアピン）がドロップされないようにするためです。インバウンドアクセスを参照してください。

AWS WAF。 CLBもNLBも、AWS WAFとのネイティブ統合はサポートしていません。WAFが必要な場合は、CloudFront + AWS WAF をCLBの前段に配置してください（エッジキャッシュやDDoS対策の利点もあります）。またはCloudflareのようなサードパーティのCDN/WAFを使用してください。

信頼済みプロキシ。 本番環境では、kong.env.trusted_ips（チャートのデフォルトは 0.0.0.0/0,::/0）とJiteraアプリケーション層の信頼済みプロキシをLBのCIDRに絞り込んでください。信頼済みプロキシを参照してください。

EKSのネットワーク。 JiteraはAmazon VPC CNIアドオン（EKSのデフォルトで、上記のクラスター設定の addons: に既に含まれています）で動作検証されています。PodのIPはVPCサブネットから払い出されるため、aws-load-balancer-security-groups アノテーションでアタッチしたインバウンドSecurity Groupは、Service（CLB）のフロントエンド層に適用されます — Pod層のネットワークとは独立しています。

# values-aws.yaml
# ============================================================
# コア設定 — 以下のパラメータはすべてオーバーライドが必要です
# ============================================================

# --- レジストリ認証情報（Jiteraから提供） ---
registryCredentials:
  server: "<REGISTRY_URL>"
  username: "<REGISTRY_USERNAME>"
  password: "<REGISTRY_PASSWORD>"
  email: "<REGISTRY_EMAIL>"

# --- ドメイン ---
ingress:
  domainName: "app.yourdomain.com"
  chatDomainName: "chat.yourdomain.com"

# --- TLS — CLB での ACM 証明書 + 事前作成 Security Group ---
kong:
  proxy:
    annotations:
      service.beta.kubernetes.io/aws-load-balancer-backend-protocol: "http"
      service.beta.kubernetes.io/aws-load-balancer-ssl-ports: "kong-proxy-tls"
      service.beta.kubernetes.io/aws-load-balancer-ssl-cert: "<ACM_CERTIFICATE_ARN>"
      # 事前作成した Security Group（インバウンド許可リストルールを含む）。
      # インフラストラクチャレイヤーで作成し（コンソール / CLI / IaC）、
      # Pod ヘアピン用に NAT ゲートウェイ EIP を含めてください。上記の Warning を参照。
      service.beta.kubernetes.io/aws-load-balancer-security-groups: "<SECURITY_GROUP_ID>"
    tls:
      overrideServiceTargetPort: 8000

# --- JWT ---
jwt:
  secret: "<GENERATE_WITH_pwgen_64_1>"

# --- 内部シークレット（それぞれユニークな値を生成） ---
automation:
  env:
    PUBLIC_OPEN_AI_INTERNAL_SECRET: "<GENERATE_RANDOM_SECRET>"
ultron:
  secret:
    PUBLIC_OPEN_AI_INTERNAL_SECRET: "<SAME_VALUE_AS_ABOVE>"
credentials:
  hasura:
    HASURA_GRAPHQL_ADMIN_SECRET: "<GENERATE_RANDOM_SECRET>"
  boost:
    JITERA_BOOST_API_KEY_MAIN: "<GENERATE_WITH_pwgen_32_1>"
    JITERA_BOOST_AUTO_API_KEY: "<SAME_AS_HASURA_ADMIN_SECRET>"
    JITERA_BOOST_OPENAI_KEY_LITELLM: "<GENERATE_WITH_pwgen_32_1>"
    JITERA_BOOST_ROLLBAR_ACCESS_TOKEN: ""  # Rollbarトークンを設定するか空のまま
  html_conversion:
    BEARER_TOKEN: "<GENERATE_WITH_pwgen_32_1>"

# --- データベース認証情報（クラスター内） ---
postgresql:
  postgresql:
    username: "<DB_USERNAME>"
    password: "<DB_PASSWORD>"
    database: "<DB_NAME>"
    postgresPassword: "<POSTGRES_SUPERUSER_PASSWORD>"
pgvector:
  postgresql:
    username: "<PGVECTOR_USERNAME>"
    password: "<PGVECTOR_PASSWORD>"
    database: "<PGVECTOR_DB_NAME>"
mongodb:
  auth:
    databases: ["<MONGO_DB_NAME>"]
    usernames: ["<MONGO_USERNAME>"]
    passwords: ["<MONGO_PASSWORD>"]
rabbitmq:
  auth:
    password: "<RABBITMQ_PASSWORD>"
    erlangCookie: "<GENERATE_RANDOM_STRING>"

# --- ストレージ — AWS S3 ---
storage:
  provider: S3
  secret:
    aws:
      AWS_ACCESS_KEY_ID: "<AWS_ACCESS_KEY_ID>"
      AWS_SECRET_ACCESS_KEY: "<AWS_SECRET_ACCESS_KEY>"
      AWS_REGION: "ap-northeast-1"  # ap-northeast-1 必須 — S3バケットの Warning を参照
      AWS_BUCKET: "jitera-storage-default"
      AWS_PUBLIC_BUCKET: "jitera-storage-public"
      AWS_EXPORT_PROJECT_BUCKET: "jitera-storage-export"
      AWS_ULTRON_BUCKET: "jitera-storage-ultron"
document_converter:
  env:
    USE_AZURE: "false"
ultron:
  env:
    STORAGE_DISK: "s3"

# --- メール — AWS SES ---
mailer:
  smtp_settings:
    address: "email-smtp.ap-northeast-1.amazonaws.com"
    user_name: "<SES_SMTP_USERNAME>"
    password: "<SES_SMTP_PASSWORD>"
  default_from_email: "noreply@yourdomain.com"

# --- 会社情報 ---
company:
  name: "<YOUR_COMPANY_NAME>"
  brand_name: "<YOUR_BRAND_NAME>"
  domain: "@yourdomain.com"
  language: "en"

# --- AI / LLMプライマリプロバイダー（1つ選択、下のタブを参照） ---
# このコードブロックの下にあるAIプロバイダータブを参照してください。

# ============================================================
# オプション設定
# ============================================================
# 以下はデフォルト値で動作します。必要な場合のみオーバーライドしてください。
# 参照: /ja/self-hosted-v26.02.16/reference/helm-values
#
# インテグレーション:     credentials.github.*, credentials.gitlab.*, credentials.figma.*
# サインアップ制御:       automation.env.SECURED_SIGN_UP, frontend.env.REACT_APP_SECURED_SIGN_UP
# StorageClass:          postgresql.persistence.storageClassName, mongodb.persistence.storageClass 等
# 外部データベース:       externalPostgres.*, externalRedis.*, externalMongodb.*, externalRabbitmq.*
# モニタリング:           monitoring.*
# エラーモニタリング:     credentials.rollbar.*
# モニタリングドメイン:   ingress.grafana.domain, ingress.prometheus.domain

環境がDocker Hubへのアクセスを制限している場合、すべてのイメージの取得先をJitera ACRレジストリに変更できます。設定方法はコンテナレジストリを参照してください。

AI / LLMプライマリプロバイダー

1つのプライマリプロバイダーを選択し、対応する設定をvaluesファイルに追加してください。AI_MODE設定はUltronのプライマリLLMルーティングを決定します。追加プロバイダー（AWS Bedrock/Claude、Anthropic Direct API、Google Gemini、vLLM）は併用可能です — 詳細はAI設定を参照してください。

Azure OpenAI
OpenAI

openai:
  AI_MODE: azure
  secretKeys:
    azure:
      AZURE_OPENAI_KEYS: '["<AZURE_OPENAI_KEY>"]'
      AZURE_OPENAI_INSTANCE_NAMES: '["<AZURE_OPENAI_INSTANCE_NAME>"]'
      AZURE_OPENAI_VERSION: "2024-10-21"
      AZURE_OPENAI_DEVELOPMENT_NAME: "gpt-4.1"
      AZURE_OPENAI_EMBEDDING_DEVELOPMENT_NAME: "text-embedding-ada-002"
      AZURE_OPENAI_VISION_DEVELOPMENT_NAME: "gpt-4o"
      AZURE_OPENAI_GPT_4O_DEVELOPMENT_NAME: "gpt-4o"
      AZURE_OPENAI_GPT_4O_MINI_DEVELOPMENT_NAME: "gpt-4o-mini"
    openai:
      OPENAI_MAIN_MODEL_NAME: "gpt-4.1"
credentials:
  boost:
    # デプロイ済みモデル — 完全な設定文字列を指定
    JITERA_BOOST_API_CONFIG_AZURE_INSTANCE_1_41: "behavior=azure,url=https://<INSTANCE>.openai.azure.com/openai/deployments/gpt-4.1,headers={\"api-key\": \"<KEY>\"},query_params={\"api-version\": \"2024-10-21\"}"
    JITERA_BOOST_API_CONFIG_AZURE_INSTANCE_1_41_MINI: "behavior=azure,url=https://<INSTANCE>.openai.azure.com/openai/deployments/gpt-4.1-mini,headers={\"api-key\": \"<KEY>\"},query_params={\"api-version\": \"2024-10-21\"}"
    JITERA_BOOST_API_CONFIG_AZURE_INSTANCE_1_41_NANO: "behavior=azure,url=https://<INSTANCE>.openai.azure.com/openai/deployments/gpt-4.1-nano,headers={\"api-key\": \"<KEY>\"},query_params={\"api-version\": \"2024-10-21\"}"
    JITERA_BOOST_API_CONFIG_AZURE_INSTANCE_1_4O: "behavior=azure,url=https://<INSTANCE>.openai.azure.com/openai/deployments/gpt-4o,headers={\"api-key\": \"<KEY>\"},query_params={\"api-version\": \"2024-10-21\"}"
    JITERA_BOOST_API_CONFIG_AZURE_INSTANCE_1_4O_MINI: "behavior=azure,url=https://<INSTANCE>.openai.azure.com/openai/deployments/gpt-4o-mini,headers={\"api-key\": \"<KEY>\"},query_params={\"api-version\": \"2024-10-21\"}"
    JITERA_BOOST_API_CONFIG_AZURE_INSTANCE_1_ADA: "behavior=azure,url=https://<INSTANCE>.openai.azure.com/openai/deployments/text-embedding-ada-002,headers={\"api-key\": \"<KEY>\"},query_params={\"api-version\": \"2024-10-21\"}"
    # 未デプロイモデル — 起動時クラッシュ防止のため空文字列でオーバーライド必須
    JITERA_BOOST_API_CONFIG_AZURE_INSTANCE_1_O1: ""
    JITERA_BOOST_API_CONFIG_AZURE_INSTANCE_1_O3: ""
    JITERA_BOOST_API_CONFIG_AZURE_INSTANCE_1_O3_MINI: ""
    JITERA_BOOST_API_CONFIG_AZURE_INSTANCE_1_O4_MINI: ""

カスタムサブドメイン要件、すべてのBoost設定キー、モデルデプロイメント、SuperAdmin登録を含む完全なセットアップについては、AI設定 — Azure OpenAIを参照してください。

openai:
  AI_MODE: open_ai
  secretKeys:
    openai:
      OPENAI_API_KEY: "<OPENAI_API_KEY>"
      OPENAI_API_KEYS: '["<OPENAI_API_KEY>"]'
      OPENAI_VISION_KEY: "<OPENAI_API_KEY>"
      OPENAI_EMBEDDING_KEY: "<OPENAI_API_KEY>"
      OPENAI_MAIN_MODEL_NAME: "gpt-4o"

Boost設定とモデル登録については、AI設定 — OpenAIを参照してください。

設定可能なパラメータの完全なリファレンスについては Helm Valuesリファレンスを参照してください。

ステップ 3.5: デフォルトStorageClassの作成

Helmチャートのモニタリングスタックとクラスター内データベースは、クラスターのデフォルトStorageClassに依存するPersistentVolumeClaimを使用します。EKSでは、gp3 StorageClassを作成しデフォルトに設定してください：

# storageclass-gp3.yaml
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: gp3
  annotations:
    storageclass.kubernetes.io/is-default-class: "true"
provisioner: ebs.csi.aws.com
parameters:
  type: gp3
reclaimPolicy: Delete
volumeBindingMode: WaitForFirstConsumer

kubectl apply -f storageclass-gp3.yaml
kubectl get storageclass   # gp3に「(default)」が表示されることを確認

デフォルトStorageClassはデータベースを外部化する場合でも必要です — モニタリングスタック（Grafana、Prometheus、Loki、Tempo）は引き続き永続ボリュームを必要とします。デフォルトStorageClassがない場合、Podはunbound immediate PersistentVolumeClaimsでPending状態のままになります。

ステップ 4: Jitera のインストール

# Jitera Helmチャートzipを展開
unzip jitera-helm-chart.zip

# Jiteraをインストール
helm install jitera ./charts/jitera \
  --namespace jitera \
  --values values-aws.yaml \
  --wait \
  --timeout 15m

初回インストールでは --timeout 15m フラグが重要です。データベースの初期化とマイグレーションに数分かかることがあります。インストールがタイムアウトした場合は、再試行前に kubectl get pods -n jitera でPodステータスを確認してください。

外部 AWS サービス（オプション）

本番環境の高可用性デプロイメントでは、データベースをマネージドサービスに外部化することを検討してください。セットアップ手順については Amazon RDSドキュメントを参照してください。

Amazon RDS（PostgreSQL）の使用

PostgreSQL 14.xを実行するRDSインスタンスを作成してください。検証済みバージョンについては外部サービスを参照してください。 Jiteraには以下のPostgreSQL拡張機能が必要です：btree_gist、citext、cube、pg_stat_statements、pg_trgm、pgcrypto、uuid-ossp、vector。これらはデプロイ時に自動的にインストールされます。詳細はAmazon RDS PostgreSQL拡張機能を参照してください。

# values-aws.yaml への追加
postgresql:
  enabled: false

externalPostgres:
  enabled: true
  host: jitera-db.cluster-xxxxx.ap-northeast-1.rds.amazonaws.com
  port: "5432"
  dbName: jitera
  username: jitera
  password: "your-rds-password"

Amazon RDS（PGVector）の使用

PostgreSQL 16.xを実行する別のRDSインスタンスを作成してください。検証済みバージョンについては外部サービスを参照してください。 Jiteraにはプライマリデータベースと同じPostgreSQL拡張機能が必要です：btree_gist、citext、cube、pg_stat_statements、pg_trgm、pgcrypto、uuid-ossp、vector。これらはデプロイ時に自動的にインストールされます。詳細はAmazon RDSでのpgvectorを参照してください。

# values-aws.yaml への追加
pgvector:
  enabled: false

externalPgvector:
  enabled: true
  host: jitera-pgvector.cluster-xxxxx.ap-northeast-1.rds.amazonaws.com
  port: "5432"
  database: jitera_pgvector
  username: jitera
  password: "your-rds-pgvector-password"
  sslMode: disable

TLS制限については外部サービス — PGVectorを参照してください。

Amazon DocumentDB（MongoDB）の使用

DocumentDBのマスターパスワードは8〜100文字で、/、"、@を含めることができません。これらの文字はURI予約文字であり、MongoDBの接続文字列も破壊します。生成コマンド例: openssl rand -base64 24 | tr -d '/+="@'

接続URI要件については外部サービス — MongoDBを参照してください。

# values-aws.yaml への追加
mongodb:
  enabled: false

externalMongodb:
  enabled: true
  mongodb_uri: "mongodb://jitera:password@jitera-docdb.cluster-xxxxx.ap-northeast-1.docdb.amazonaws.com:27017/jitera?replicaSet=rs0&readPreference=secondaryPreferred&retryWrites=false"

TLS制限と接続URI要件については外部サービス — MongoDBを参照してください。

Amazon ElastiCache（Redis）の使用

# values-aws.yaml への追加
redis:
  enabled: false

externalRedis:
  enabled: true
  host: jitera-redis.xxxxx.cache.amazonaws.com
  port: 6379
  username: ""       # 必須 — ElastiCacheの場合は空のまま（ACLユーザー名なし）
  password: ""
  useTls: true

Amazon MQ（RabbitMQ）の使用

# values-aws.yaml への追加
rabbitmq:
  enabled: false

externalRabbitmq:
  enabled: true
  host: "b-xxxxx.mq.ap-northeast-1.amazonaws.com"
  port: "5671"
  username: "jitera"
  password: "your-rabbitmq-password"
  useTls: true

インストール後の確認

ステップ 1: Pod ステータスの確認

# すべての Pod が Running であること
kubectl get pods -n jitera

# 期待される出力:
# NAME                           READY   STATUS    RESTARTS   AGE
# jitera-api-xxxxx               1/1     Running   0          5m
# jitera-web-xxxxx               1/1     Running   0          5m
# jitera-worker-xxxxx            1/1     Running   0          5m
# jitera-postgresql-0            1/1     Running   0          5m
# jitera-mongodb-0               1/1     Running   0          5m
# jitera-redis-master-0          1/1     Running   0          5m

ステップ 2: ロードバランサーの確認

# Kong プロキシのロードバランサーホスト名を取得
kubectl get svc -n jitera -l app.kubernetes.io/name=kong -o jsonpath='{.items[0].status.loadBalancer.ingress[0].hostname}'

ステップ 3: DNS の設定

両方のホスト名（メインドメインとチャットドメイン）をKongロードバランサーのホスト名に向けるCNAMEレコードを作成します。ホスト名の詳細についてはデプロイ要件を参照してください。

app.example.com     CNAME  xxxxx.ap-northeast-1.elb.amazonaws.com
chat.example.com    CNAME  xxxxx.ap-northeast-1.elb.amazonaws.com

例：Route 53 の設定

# Kong ロードバランサーのホスト名を取得
LB_HOSTNAME=$(kubectl get svc -n jitera -l app.kubernetes.io/name=kong -o jsonpath='{.items[0].status.loadBalancer.ingress[0].hostname}')

# CNAME レコードを作成
aws route53 change-resource-record-sets \
  --hosted-zone-id <YOUR_HOSTED_ZONE_ID> \
  --change-batch '{
    "Changes": [
      {
        "Action": "UPSERT",
        "ResourceRecordSet": {
          "Name": "app.example.com",
          "Type": "CNAME",
          "TTL": 300,
          "ResourceRecords": [{"Value": "'$LB_HOSTNAME'"}]
        }
      },
      {
        "Action": "UPSERT",
        "ResourceRecordSet": {
          "Name": "chat.example.com",
          "Type": "CNAME",
          "TTL": 300,
          "ResourceRecords": [{"Value": "'$LB_HOSTNAME'"}]
        }
      }
    ]
  }'

詳細な手順については Amazon Route 53ドキュメントを参照してください。

トラブルシューティング

Pod が起動しない

# Pod イベントを確認
kubectl describe pod <pod-name> -n jitera

# ログを確認
kubectl logs <pod-name> -n jitera

# よくある問題:
# - イメージプルエラー: レジストリ認証情報を確認
# - リソース問題: ノードのキャパシティを確認
# - PVC 問題: EBS CSI ドライバーがインストールされているか確認

ロードバランサーがプロビジョニングされない

# Kong プロキシサービスのステータスを確認
kubectl get svc -n jitera -l app.kubernetes.io/name=kong

# Kong Pod のログを確認
kubectl logs -n jitera -l app.kubernetes.io/name=kong

# よくある問題:
# - サブネットタグの問題
# - セキュリティグループの制限

データベース接続の問題

# PostgreSQL 接続をテスト
kubectl run -it --rm psql --image=postgres:15 --restart=Never -- \
  psql -h jitera-postgresql -U jitera -d jitera

# MongoDB 接続を確認
kubectl run -it --rm mongo --image=mongo:6 --restart=Never -- \
  mongosh "mongodb://jitera-mongodb:27017/jitera"

S3 アクセスの問題

# 設定されているストレージプロバイダーを確認
kubectl get configmap jitera-ultron -n jitera -o jsonpath='{.data.STORAGE_DISK}'

# Ultron シークレットの S3 認証情報を確認
kubectl get secret jitera-ultron -n jitera \
  -o jsonpath='{.data.S3_KEY}' | base64 -d

# Automation シークレット（secrets.yml）のストレージ設定を確認
kubectl get secret jitera-automation -n jitera \
  -o jsonpath='{.data.secrets\.yml}' | base64 -d | grep -A 5 'storage_service\|aws:'

# Ultron シークレットの S3 設定を確認
kubectl get secret jitera-ultron -n jitera -o json | \
  jq '.data | to_entries[] | select(.key | test("S3_")) | {(.key): (.value | @base64d)}'

# Pod から S3 への接続テスト
kubectl exec -it deploy/jitera-automation-rails -n jitera -- \
  curl -s -o /dev/null -w "%{http_code}" https://s3.amazonaws.com

# IAM ポリシーを確認
aws iam get-policy-version \
  --policy-arn arn:aws:iam::${AWS_ACCOUNT_ID}:policy/JiteraS3Access \
  --version-id v1

S3 CORS エラー

ブラウザコンソールで CORS エラーが表示される場合:

CORS 設定にデフォルトバケットとパブリックバケットのドメインが含まれていることを確認してください
許可されたメソッドに必要なすべての HTTP メソッドが含まれていることを確認してください
S3 エンドポイントがブラウザからアクセス可能であることを確認してください

aws s3api get-bucket-cors --bucket jitera-storage-default
aws s3api get-bucket-cors --bucket jitera-storage-public

メールのテスト

# Rails コンソールにアクセス
kubectl exec -it deploy/jitera-automation-rails -n jitera -- rails console

# テストメールの送信
ActionMailer::Base.mail(
  from: 'noreply@yourdomain.com',
  to: 'test@example.com',
  subject: 'Test Email',
  body: 'This is a test email from Jitera.'
).deliver_now

# SES への SMTP 接続テスト
kubectl exec -it deploy/jitera-automation-rails -n jitera -- \
  nc -zv email-smtp.ap-northeast-1.amazonaws.com 587

# 環境変数の確認
kubectl exec -it deploy/jitera-automation-rails -n jitera -- \
  env | grep -i smtp

# メールエラーの automation ログ確認
kubectl logs deploy/jitera-automation-rails -n jitera | grep -i mail

メール接続拒否

# SES SMTP エンドポイントへの到達性を確認
kubectl exec -it deploy/jitera-automation-rails -n jitera -- \
  telnet email-smtp.ap-northeast-1.amazonaws.com 587

# セキュリティグループで送信ポート 587 が許可されていることを確認

メール認証失敗

認証情報が正しいことを確認します
AWS シークレットアクセスキーを SES SMTP パスワードに変換したことを確認してください — これらは同じ値ではありません。変換手順については AWS SES ドキュメントを参照してください。
SMTP ユーザー名の形式が正しいことを確認します

# シークレット値の確認
kubectl get secret jitera-mailer -n jitera -o yaml

メールが配信されない

迷惑メール/ジャンクフォルダを確認します
ドメインの SPF/DKIM レコードを確認します
SES でドメイン/メールアドレスが検証済みであることを確認します（SES は送信者の検証が必要です）
SES 送信ダッシュボードでバウンスと苦情を確認します

デプロイメントの削除

Jiteraをクラスターから完全に削除します。

この操作は元に戻せません。クラスター内のすべてのデータ（データベース、キャッシュ、メッセージキュー）が永久に削除されます。実行前にすべてのデータをバックアップしてください。

# Helmリリースをアンインストール
helm uninstall jitera -n jitera

# 名前空間を削除（残りのリソースをすべて削除）
kubectl delete namespace jitera

外部リソース（S3バケット、RDSインスタンス、DocumentDBクラスター、ElastiCache、ACM証明書、Route 53レコード）はhelm uninstallでは削除されません。AWSコンソール、CLI、またはTerraformを使用して別途削除する必要があります。

要件

必須およびオプションのデプロイ要件

アーキテクチャ

アーキテクチャの理解

バックアップとリストア

アップグレード前のデータベースバックアップ手順

トラブルシューティング

よくある問題と解決策

リリースノート

Documentation Index

​前提条件チェックリスト

​AWS インフラストラクチャのセットアップ

​ステップ 1: EKS クラスターの作成

​ステップ 2: S3 バケットの作成

​Helm設定

​ステップ 3: S3 アクセス用 IAM ユーザーの作成

​ステップ 4: TLS 証明書の取得

​オプション 1: AWS Certificate Manager（ACM）

​オプション 2: cert-manager と Let’s Encrypt

​ステップ 5: メール（SES）の設定

​Helm設定

​Jitera のインストール

​ステップ 1: cert-manager のインストール（オプション）

​ステップ 2: Namespace とレジストリシークレットの作成

​ステップ 3: Values ファイルの作成

​AI / LLMプライマリプロバイダー

​ステップ 3.5: デフォルトStorageClassの作成

​ステップ 4: Jitera のインストール

​外部 AWS サービス（オプション）

​Amazon RDS（PostgreSQL）の使用

​Amazon RDS（PGVector）の使用

​Amazon DocumentDB（MongoDB）の使用

​Amazon ElastiCache（Redis）の使用

​Amazon MQ（RabbitMQ）の使用

​インストール後の確認

​ステップ 1: Pod ステータスの確認

​ステップ 2: ロードバランサーの確認

​ステップ 3: DNS の設定

​トラブルシューティング

​Pod が起動しない

​ロードバランサーがプロビジョニングされない

​データベース接続の問題

​S3 アクセスの問題

​S3 CORS エラー

​メールのテスト

​メール接続拒否

​メール認証失敗

​メールが配信されない

​デプロイメントの削除

​関連ドキュメント

要件

アーキテクチャ

バックアップとリストア

トラブルシューティング

前提条件チェックリスト

AWS インフラストラクチャのセットアップ

ステップ 1: EKS クラスターの作成

ステップ 2: S3 バケットの作成

Helm設定

ステップ 3: S3 アクセス用 IAM ユーザーの作成

ステップ 4: TLS 証明書の取得

オプション 1: AWS Certificate Manager（ACM）

オプション 2: cert-manager と Let’s Encrypt

ステップ 5: メール（SES）の設定

Helm設定

Jitera のインストール

ステップ 1: cert-manager のインストール（オプション）

ステップ 2: Namespace とレジストリシークレットの作成

ステップ 3: Values ファイルの作成

AI / LLMプライマリプロバイダー

ステップ 3.5: デフォルトStorageClassの作成

ステップ 4: Jitera のインストール

外部 AWS サービス（オプション）

Amazon RDS（PostgreSQL）の使用

Amazon RDS（PGVector）の使用

Amazon DocumentDB（MongoDB）の使用

Amazon ElastiCache（Redis）の使用

Amazon MQ（RabbitMQ）の使用

インストール後の確認

ステップ 1: Pod ステータスの確認

ステップ 2: ロードバランサーの確認

ステップ 3: DNS の設定

トラブルシューティング

Pod が起動しない

ロードバランサーがプロビジョニングされない

データベース接続の問題

S3 アクセスの問題

S3 CORS エラー

メールのテスト

メール接続拒否

メール認証失敗

メールが配信されない

デプロイメントの削除

関連ドキュメント