セルフマネージド Kubernetes

このガイドでは、お客様がプロビジョニングして運用する Kubernetes クラスターに Vantage 3.0 self-hosted をデプロイします。ここでは、Vantage がクラスターに対して必要とするインターフェイスを定義し、Linkerd、Traefik、External Secrets と HashiCorp Vault をその例として使用します。同じ要件を満たす同等のコンポーネントを使用できます。このガイドでは、稼働中の Kubernetes クラスターが用意されていることを前提としています。Kubernetes、サービスメッシュ、ingress コントローラー、シークレット管理システム、データベース、ストレージ、レジストリのインストールは行いません。

vantage-operator と vantage-selfhosted のチャートは、同じバージョンを使用する必要があります。このページの例では、両方のチャートにバージョン 0.70.13 を使用しています。

参照アーキテクチャ

懸念事項	Vantage の要件	実装例
Kubernetes	DNS、ネットワーク、永続ボリュームが正常に機能する、サポート対象の Kubernetes バージョン。	お客様が運用する Kubernetes。
デプロイのオーケストレーション	ApplicationSet Progressive Syncs が有効化された ArgoCD。	ArgoCD 3.4.3。
サービスメッシュ	Vantage 名前空間内でのワークロード間 mTLS。	Linkerd。
Ingress	Vantage のパスとリライトの要件を満たし、元のリクエストスキームを保持する HTTPS ingress。	cert-manager を使用する Traefik。
シークレット	Vantage 名前空間内のネイティブ Kubernetes `Secret` リソース。	HashiCorp Vault からシークレットを生成する External Secrets Operator。
データベース	SQL Server または PostgreSQL。各 Vantage サービスごとに個別の論理データベースを使用。	PostgreSQL。
キャッシュ	Redis。	Redis 7.4。
メール	既定では SendGrid、または SMTP Server。	SendGrid。
ストレージ	可用性と耐久性の要件に適した、既存の Kubernetes `StorageClass`。	お客様が提供する永続ストレージクラス。
レジストリ	Vantage アーティファクト用に提供されるソースレジストリと、お客様が運用する宛先レジストリ。	OCI 準拠の任意のプライベートレジストリ。
オートスケーリングとメトリクス	KEDA サポートが有効な場合は、Prometheus を追加した KEDA。	KEDA 2.17.3 および Prometheus Operator。

サポート対象および検証済みのコンポーネントのバージョンについては、Compatibility を参照してください。インフラストラクチャの完全な一覧とサイジングの基準については、Prerequisites を参照してください。

始める前に

次の値とリソースをあらかじめ用意してください。

変数	説明
`$operator_namespace`	Vantage operator の名前空間。
`$install_namespace`	Vantage ワークロードの名前空間。
`$operator_version`	`vantage-operator` チャートのバージョン。このガイドでは `0.70.13` を使用します。
`$selfhosted_version`	`vantage-selfhosted` チャートのバージョン。このガイドでは `0.70.13` を使用します。
`$charts_uri`	ABBYY が提供する Vantage operator チャートの OCI URI。
`$chart_uri`	ABBYY が提供する `vantage-selfhosted` チャートの OCI URI。
`$release_name`	Vantage の Helm リリース名。
`$your_vantage_hostname`	Vantage の DNS ホスト名。
`$your_mailfrom`	送信メールの送信元アドレス。
`$your_platformadmin_email`	初期プラットフォーム管理者のメールアドレス。
`$your_oci_host`	お客様が運用する宛先 OCI レジストリ。
`$abbyy_oci_source_host`, `$abbyy_oci_source_repository`	Vantage アーティファクト用に提供されるソースレジストリとリポジトリ。

また、次のものも必要です。

$your_vantage_hostname の DNS レコード (ingress のエントリポイントに名前解決されるもの) 。
そのホスト名に対する有効な TLS 証明書。
レジストリで認証が必要な場合は、Kubernetes の registry pull シークレット。
Secret aliases に記載されているすべてのアプリケーションシークレット。
データベースエイリアスごとに一意の論理データベース名。各サービスのマイグレーターは初回実行時にデータベースを作成します。
TechCore worker 用のラベルが付いたノード。

クラスターの準備

ArgoCD を設定する

ArgoCD をインストールし、ApplicationSet Progressive Syncs を有効にします。また、移行先のレジストリから Vantage component のチャートを取得できる OCI リポジトリ接続も ArgoCD に必要です。 ArgoCD private repository documentation に従って、移行先のレジストリを OCI Helm リポジトリとして登録します。レジストリの認証情報は、ArgoCD の Application マニフェストに直接記述するのではなく、既存のシークレット管理システムで管理してください。

サービスメッシュを構成する

Vantage では、ワークロード間で mTLS が必要です。サポートされているサービスメッシュをインストールして運用し、Vantage をインストールする前に $install_namespace のメッシュインジェクションを有効にします。たとえば、Linkerd の場合:

kubectl create namespace $install_namespace --dry-run=client -o yaml | kubectl apply -f -
kubectl label namespace $install_namespace linkerd.io/inject=enabled --overwrite

続行する前に、名前空間で新たに作成したテスト用podに mesh のサイドカーが挿入されていることを確認してください。別の mesh を使用している場合は、その名前空間または workload への挿入手順に従ってください。

TechCore workerノードの構成

TechCore workerのワークロードは、k8s.abbyy.com/techcore=true ラベルが付いたノードを選択します。TechCore プール内の各ノードにラベルと taint を設定してください。

kubectl label node <node-name> k8s.abbyy.com/techcore=true
kubectl taint node <node-name> k8s.abbyy.com/techcore=true:NoSchedule

条件に一致するノードが 1 つもない場合、TechCore の pod は Pending のままになります。学習ワーカーの分離については Kubernetes ノード要件を、プールごとの容量についてはサイジングを参照してください。

永続ストレージを Configure

Vantage をインストールする前に、StorageClass を作成または選択します。ストレージ実装は、本番環境で必要な可用性、耐久性、容量、拡張性、バックアップ、復旧の要件を満たしている必要があります。これを Vantage の values で参照します。

vantage:
  storage:
    custom:
      storageClass: <storage-class-name>
      size: 300Gi

StorageClass の名前は Kubernetes ディストリビューションに依存しません。開発クラスターのローカルストレージクラスを、損失やフェールオーバーの特性を評価せずに本番環境へそのままコピーしないでください。 Vantage は、指定したクラス上に独自の PersistentVolumeClaims をプロビジョニングします。どの StorageClass にも、次の 2 つの要件が適用されます。

プロビジョニングされたボリュームは、非 root ユーザーが書き込み可能でなければなりません。 Vantage のサービスは non-root で実行されます。ボリュームの mount ディレクトリーが root 所有で、コンテナーユーザーに書き込み権限がない場合 (たとえば、モードが 0755 の場合) 、blobstorage サービスは起動時のファイルシステムチェックに失敗し、ホストの初期化は中断され、ストレージに依存するすべてのサービスが Degraded になります。
PVC の storageClassName は変更できません。 既存のインストールを別の StorageClass に移行するには、新しいクラス上で operator の PVC を削除して再作成します。

ノードローカルクラスでは、各 PVC は単一ノードの disk にバインドされます。ノード間で共有されるストレージについては、検証済みの例として csi-driver-nfs を介した NFS があり、これにより nfs StorageClass が提供されます。ドライバーのノードプラグインには NFS の mount ユーティリティが含まれているため、クラスターノードに追加の NFS パッケージは不要です。

vantage:
  storage:
    custom:
      storageClass: nfs
      size: 300Gi

csi-driver-nfs を使用する場合:

このドライバーを使用するには、既存の構成済み NFSv3 または NFSv4 サーバーが必要です。Vantage にはドライバーもサーバーも含まれておらず、どちらも自分でインストールして運用する必要があります。
StorageClass で mountPermissions: "0777" を設定します。プロビジョナーは各ボリュームのサブディレクトリーを root 所有で作成するため、0755 のディレクトリーには Vantage サービスユーザーは書き込めません。
NFS サーバーはすべてのノードから到達可能であり、共有を rw,sync,all_squash,insecure,no_subtree_check,anonuid=65532,anongid=65532 でエクスポートしている必要があります。anonuid/anongid を伴う all_squash マッピングにより、CSI ドライバーを含むすべてのクライアントが uid/gid 65532 として扱われ、Vantage pod のセキュリティコンテキストと一致します。insecure は、コンテナー化された NFS クライアントが使用する非特権ポートからの接続を許可します。これがないと、サーバーはそれらの接続を黙って拒否し、ストレージへの書き込みは目に見えるエラーなしで失敗します。
エクスポートルートディレクトリーの所有者は 65532:65532、モードは 0755 である必要があります。実行中のサーバーで /etc/exports または所有権を変更した後は、exportfs -ra で再エクスポートします。

データベースを準備する

Vantage は SQL Server と PostgreSQL をサポートしています。provider は必ず以下のとおり正確に設定してください。値では大文字と小文字が区別されます：

vantage:
  databaseProvider: PostgreSQL

有効な値は SqlServer と PostgreSQL です。Postgresql や PostgreSql のような値は、アプリケーションのデータプロバイダー名と一致しないため、ランタイムで失敗する可能性があります。すべての Vantage サービスは、それぞれ別個の論理データベースを使用する必要があります。各サービスは独自にマイグレーションを実行するため、複数のサービスを 1 つのデータベースに向けると、マイグレーションの状態が競合します。データベース名と接続文字列を計画するには、Database aliases 配下のデータベース一覧を利用してください。データベースを手動で作成する必要はありません。各サービスのマイグレーターが初回実行時にデータベースを作成します。

Reporting を利用できるのは SQL Server の場合のみです。PostgreSQL を使用する場合は、vantage.reportingEnabled を false のままにしてください。

PostgreSQL の接続文字列は、先頭・末尾・途中に改行文字を含まない 1 行である必要があります。

Kubernetes Secrets を準備する

Kubernetes secrets プロバイダーは、$install_namespace 内の Kubernetes ネイティブの Secret リソースを読み取ります。Vantage は Vault やその他の外部シークレットストアに直接接続しません。External Secrets Operator、CSI ドライバー、またはその他の同期ツールを使用する場合は、Vantage をインストールする前に、必要な Kubernetes Secrets が作成されるように設定してください。 Kubernetes provider を選択します。

vantage:
  secrets:
    kubernetes: {}

デフォルトでは、Vantage はドキュメントに記載されているシークレット名を使用します。objects を使用して、エイリアスを別のシークレットにマッピングします:

vantage:
  secrets:
    kubernetes:
      objects:
        authSigningTlsCrt:
          secretName: vantage-auth-signing
        authSigningTlsKey:
          secretName: vantage-auth-signing
        authDeactivatedTlsCrt:
          secretName: vantage-auth-deactivated
        authDeactivatedTlsKey:
          secretName: vantage-auth-deactivated
        subscriptionDatabaseConnectionString:
          secretName: vantage-db-subscriptions

2 つの認証キーペアは、アプリケーショントークンの署名に使用されます。これらは、ingress controller で公開 HTTPS を終端する証明書とは別のものです。必要なキーと形式については、Certificate aliasesを参照してください。複数のサービスで汎用のDatabase__ConnectionStringキーを使用する場合は、サービスごとに個別のSecretを作成し、各データベースエイリアスをvantage.secrets.kubernetes.objectsを通じてマッピングします。シークレット管理システムでは、共通の接続文字列テンプレートからこれらのSecretを生成できますが、生成される各接続文字列では、それぞれ異なるデータベース名を指定する必要があります。

operator は、事前チェック時にシークレット構成を検証します。対応するvantage-operatorチャートとvantage-selfhostedチャートでは、Vantage リリースの名前空間でのみバインドされる ClusterRole を通じて、operator に Secrets への読み取りアクセスを付与します。operator の名前空間やコントローラーの ServiceAccount をカスタマイズする場合は、Vantage チャート内の対応するoperator値を、そのインストールに合わせてください。カスタムのresourceNames制限には、Kubernetes provider が参照するすべてのSecretを含める必要があります。

レジストリアクセスを設定する

レジストリアクセスには、3 つの独立した利用主体があります。

Consumer	Required access
Vantage operator	オペレーターイメージをプルします。必要に応じて `manager.imagePullSecrets` を設定します。
OCI 移行ジョブ	ジョブイメージをプルし、ソースレジストリから読み取り、宛先レジストリに書き込みます。
Vantage workloads and ArgoCD	宛先レジストリからワークロードイメージとコンポーネントのチャートをプルします。

各利用主体が実行される名前空間に、レジストリのシークレットを作成します。values ファイルには、平文のレジストリパスワードを記載しないでください。 OCI 移行では、ソースおよび宛先の認証情報シークレットを参照します。

vantage:
  ociMigration:
    enabled: true
    serviceAccountName: <vantage-service-account>
    imagePullSecrets:
      - name: <operator-image-pull-secret>
    sources:
      - host: <source-registry>
        repository: <source-repository>
        credentialsRef:
          name: <source-registry-credentials>
    destination:
      host: <destination-registry>
      credentialsRef:
        name: <destination-registry-credentials>

送信先レジストリのプル用シークレットを、Vantageワークロードでデフォルトとして使用される、vantage.serviceAccountName で指定された ServiceAccount の imagePullSecrets に追加します。

コンポーネントの pod が別の ServiceAccount で実行されている場合は、その ServiceAccount にもレジストリのプルアクセスが必要です。名前空間の default ServiceAccount を変更する前に、pod の spec.serviceAccountName を確認してください。

自動スケーリングとメトリクスを設定する

KEDA のサポートは任意ですが、推奨されています。KEDA 2.17.3 を使用してください。KEDA 2.18 以降では、現在の Vantage workload チャートで使用されている scaler field が削除されたため、必要な HPA を作成できません。一部の Vantage ScaledObject リソースは、この固定アドレスの Prometheus をクエリします。

http://prometheus-operated.observability.svc.cluster.local:9090

KEDA を有効にする前に:

KEDA 2.17.3 をインストールします。
observability 名前空間に Prometheus Operator と Prometheus インスタンスをインストールします。
それを管理する Service の名前が prometheus-operated で、ポート 9090 を公開していることを確認します。
Vantage の ServiceMonitor を検出できるように Prometheus を設定します。

Vantage リソースで KEDA を有効にし、別個のトップレベル observability スタンザでチャートの ServiceMonitor を有効にします:

vantage:
  keda:
    enabled: true

observability:
  prometheus:
    namespace: observability
    serviceMonitor:
      create: true

observability は最上位のキーです。vantage の下にネストしないでください。トリガー戦略、検証、キャパシティプランニングについては、KEDA を使用したオートスケーリングを参照してください。メッシュ固有のスクレイピング設定については、Prometheus による監視を参照してください。

ingress と TLS を設定する

チャートに組み込まれている ingress は Istio 用です。Traefik または他の ingress コントローラーを使用する場合は、これを無効にしてください:

ingress:
  enabled: false

ingress の構成では、次の要件を満たす必要があります。

信頼できる証明書を使用して、vantage.dnsRecord の HTTPS を終端すること。
Vantage UI、API、認証、ヘルプ、SCIM、URL-shortener、ワークスペース、Verification、Try Any Skill の各パスを、それぞれ対応する Service にルーティングすること。
Vantage で使用される /api/vN/ から /publicapi/vN/ への書き換え、および /api/、SCIM、ハートビートの書き換えを適用すること。
UI のキャッチオールルートよりも前に、より具体的なルートを優先してマッチさせること。
元の host とスキームを転送すること。これには、TLS が ingress controller で終端される場合の X-Forwarded-Proto: https も含まれます。

Traefik では、これらの要件を IngressRoute と順序付けされた Middleware リソースで実装します。ルートマニフェストは、バージョン管理される Vantage の構成として扱ってください。別の環境の値をそのままコピーするのではなく、ご利用のリリースに合わせて、hostname、名前空間、証明書用シークレット、生成される Service 名をパラメーター化してください。

ルーティング仕様

$install_namespace 内で生成された Kubernetes Service 名を確認し、以下の順序でこれらのルートを実装します。正規表現ルートと完全一致ルートは、プレフィックスルートおよびキャッチオールルートより優先する必要があります。

Public path	Vantage component	Rewrite or behavior
`^/api/v[0-9]+(/\|$)`	API ゲートウェイ	`/api/vN/...` を `/publicapi/vN/...` に書き換えます。
`^/verification/(markup\|manualreview)/<id>/notifications`	Verification	書き換えなし。
`^/workspace/(v1/files\|skilloperations/notifications\|projects/<id>/notifications\|skills/<id>/notifications\|catalogoperations/notifications)`	Workspace	書き換えなし。
Exact `/try-any-skill`	Try Any Skill	`/try-any-skill/` に恒久的にリダイレクトします。
`/try-any-skill/`	Try Any Skill	書き換えなし。
`/ad/` and `/ss/`	AD フロントエンド	書き換えなし。生成されたワークロードが公開する Service ポートを使用します。
`/auth2`	Auth identity	書き換えなし。
`/surl`	URL shortener	書き換えなし。
`/api` and `/api/`	API ゲートウェイ	`/api` プレフィックスを削除します。
`/`	Vantage フロントエンド	キャッチオールルートです。最後に評価します。

チャートに組み込まれている Istio ingress は、クライアントに不要な内部ステータス情報を公開する /api/status と /api/status/config もブロックします。これらのパスをブロックすることが推奨されますが、Vantage の動作に必須ではありません。使用している ingress コントローラーが直接拒否レスポンスを返せない場合は、一般的な /api ルールの前に、これらのパスを専用の拒否バックエンドにルーティングできます。

HTTPS スキームの転送

TLS が ingress コントローラーで終端され、バックエンド接続が HTTP の場合、Vantage の認証サービスは X-Forwarded-Proto を認識する必要があります。これを行わないと、OIDC の Discovery Document で http:// エンドポイントが通知され、ブラウザーでのサインインが失敗します。vantage.reverseProxy を true に設定して、この構成を有効にしてください。

vantage:
  reverseProxy: true

オペレーターをインストールする

クラスターにオペレーターのインスタンスを1つインストールします。

helm upgrade --install vantage-operator $charts_uri/vantage-operator \
  --version 0.70.13 \
  --namespace $operator_namespace \
  --create-namespace \
  --wait

operator レジストリでプルシークレットが必要な場合は、--wait の前にこのオプションをコマンドに追加します:

  --set "manager.imagePullSecrets[0].name=<operator-image-pull-secret>"

Vantage をインストールする

上で準備した設定をまとめた values ファイルを作成します。この簡略化した例では、セルフマネージド環境に固有の値のみを示しています。実際の環境に合わせて、完全なシークレットのマッピングとレジストリの認証情報を追加してください。

operator:
  namespace: <operator-namespace>

ingress:
  enabled: false

vantage:
  dnsRecord: <vantage-hostname>
  mailFrom: <sender-email>
  platformAdminEmail: <platform-admin-email>
  serviceAccountName: <vantage-service-account>
  databaseProvider: PostgreSQL
  reportingEnabled: false
  updatePolicy:
    manual: {}

  secrets:
    # シークレット名がデフォルトと異なる場合は、objects のマッピングを追加してください。
    kubernetes: {}

  storage:
    custom:
      storageClass: <storage-class-name>
      size: 300Gi

  keda:
    enabled: true

  ociMigration:
    enabled: true
    serviceAccountName: <vantage-service-account>
    imagePullSecrets:
      - name: <operator-image-pull-secret>
    sources:
      - host: <source-registry>
        repository: <source-repository>
        credentialsRef:
          name: <source-registry-credentials>
    destination:
      host: <destination-registry>
      credentialsRef:
        name: <destination-registry-credentials>

observability:
  prometheus:
    namespace: observability
    serviceMonitor:
      create: true

vantage-selfhosted チャートをインストールします。

helm upgrade --install $release_name $chart_uri/vantage-selfhosted \
  --version 0.70.13 \
  --namespace $install_namespace \
  --create-namespace \
  --values values-self-managed.yaml \
  --wait

オペレーターがワークロードの Service を作成したら、Ingress コントローラーの設定を適用し、TLS 証明書の準備ができていることを確認してください。

インストールを監視する

カスタムリソースが Ready になるまで待ちます:

kubectl -n $install_namespace wait \
  --for=condition=Ready vantages.vantage.abbyy.com/$release_name \
  --timeout=30m

次に、生成された ArgoCD アプリケーションとワークロードを確認します。Ready だけで判断しないでください。

argocd app list -l vantage.abbyy.com/managed-by=vantage-operator
kubectl -n $install_namespace get pods
kubectl -n $install_namespace get scaledobjects,hpa

OCI 移行が有効な場合は、個別に監視してください：

kubectl -n $install_namespace wait --for=create job/$release_name-oci-migration --timeout=2m
kubectl -n $install_namespace wait --for=condition=Complete job/$release_name-oci-migration --timeout=20m

Skill のインストールは別のジョブで実行され、Vantage が Ready を示した後も継続することがあります。

kubectl -n $install_namespace wait --for=create job/$install_namespace-skill-installer-job
kubectl -n $install_namespace wait --for=condition=Complete job/$install_namespace-skill-installer-job

最後に、次の点を確認してください。

生成されたすべての ArgoCD application が Synced かつ Healthy であること。
Vantage の pod が実行中で、mesh がインジェクトされていること。
Prometheus で Vantage の /metrics-text ターゲットが UP と表示されていること。
KEDA の ScaledObject リソースが Ready で、HPA のメトリクス値が <unknown> ではないこと。
OIDC の Discovery Document とブラウザーのリダイレクトで https:// URL が使用されていること。
https://$your_vantage_hostname で Vantage にアクセスできること。

次のステップ

シークレット

Kubernetes Secret のエイリアス、認証キーペア、データベース接続文字列。

監視

サービスメッシュ経由で Vantage をスクレイプするように Prometheus を設定します。

トラブルシューティング

operator、データベース、レジストリ、Ingress、オートスケーリングの障害を診断します。

アップグレード

operator と Vantage のチャートをまとめてアップグレードします。

​参照アーキテクチャ

​始める前に

​クラスターの準備

​ArgoCD を設定する

​サービスメッシュを構成する

​TechCore workerノードの構成

​永続ストレージを Configure

​データベースを準備する

​Kubernetes Secrets を準備する

​レジストリアクセスを設定する

​自動スケーリングとメトリクスを設定する

​ingress と TLS を設定する

​ルーティング仕様

​HTTPS スキームの転送

​オペレーターをインストールする

​Vantage をインストールする

​インストールを監視する

​次のステップ

シークレット

監視

トラブルシューティング

アップグレード

参照アーキテクチャ

始める前に

クラスターの準備

ArgoCD を設定する

サービスメッシュを構成する

TechCore workerノードの構成

永続ストレージを Configure

データベースを準備する

Kubernetes Secrets を準備する

レジストリアクセスを設定する

自動スケーリングとメトリクスを設定する

ingress と TLS を設定する

ルーティング仕様

HTTPS スキームの転送

オペレーターをインストールする

Vantage をインストールする

インストールを監視する

次のステップ