qdrant-hybrid-cloud-setup

Qdrant Hybrid Cloud のセットアップ

Hybrid Cloud（独自のインフラ上にコントロールプレーンをマネージドで配置）を選択済みです。まだ検討中の場合は、qdrant-deployment-options スキルをご利用ください。セットアップに失敗する原因のほとんどは、ストレージ（CSI ドライバーが Qdrant に必要な機能を提供できない）か、接続性（エージェントが Qdrant Cloud に接続できない）のどちらかです。ほかのことに手を加える前に、原因を特定してください。

Kubernetes クラスターの準備（最初に実施）

次の場合に使用します：環境を作成する前、またはストレージが原因でインストール／クラスターのプロビジョニングに失敗した場合。

• Qdrant にはブロックストレージ用の CSI ドライバーが必要です。ネットワークストレージ（NFS）とオブジェクトストレージ（S3）はサポートされていません。これらに接続されたクラスターは、性能が低下するのではなく、動作に失敗します。前提条件
• StorageClass（allowVolumeExpansion: true を指定）と VolumeSnapshotClass は、インストール後ではなく、事前に作成してください。ボリューム拡張を有効にしないと、後からディスクを拡張できません。また、VolumeSnapshotClass と CSI スナップショットコントローラーがないと、バックアップを作成できません。
• 標準に準拠した Kubernetes であればどれでも動作します。また、マネージドプラットフォーム向けに、プラットフォーム固有のセットアップガイドが用意されています：Akamai（Linode/LKE）、AWS（EKS）、Civo、DigitalOcean（DOKS）、Gcore、GCP（GKE）、Azure（AKS）、Oracle（OKE）、OVHcloud、Red Hat OpenShift、Scaleway、STACKIT、Vultr。デプロイプラットフォーム
• ストレージのサポート状況はプラットフォームによって異なります。たとえば、Linode/LKE や Vultr などは CSI ボリュームスナップショットをまったくサポートしていないため、そこでバックアップは利用できません。利用を決める前に、プロバイダーのスナップショットに関するページを確認し、推奨されるインスタンスとディスクの種類（EKS の gp3、AKS の Premium SSD v2 など）を選択してください。
• 外部への接続を確認してください。エージェントは grpc.cloud.qdrant.io と api.cloud.qdrant.io に対して、ポート 443 で接続を開始します。ファイアウォールや送信プロキシによって接続が黙ってブロックされることがあります。「インストール中」のまま進まないエージェントは、通常これが原因です。
• 対象クラスターに対して cluster-admin 権限があり、kubectl と helm が設定されている必要があります。

環境の作成

次の場合に使用します：Cloud Console のインストールウィザードを実行する場合。

• Kubernetes の名前空間は固定です。後から変更できない唯一の選択肢です。それ以外（ノードセレクター、許容設定、レジストリ URL、プロキシ）は作成後も編集できるため、今は考えすぎる必要はありません。
• ウィザードは、シークレットを作成し、Helm でエージェントとオペレーターをインストールする、一度だけ使用するインストールコマンドを生成します。最初のインストール時にのみ必要です。以降の更新は Console から行います。セットアップガイド
• 高度なオペレーターの動作（ポッドのスケジューリング、セキュリティコンテキスト、イングレス、ネットワーキング、スナップショット管理）は、環境レベルのオペレーター設定で調整でき、インストール後も変更可能です。オペレーター設定
• エアギャップ環境、またはレジストリに制限がありますか？/qdrant/ イメージと /qdrant-charts/ チャートを独自のレジストリにミラーリングし、環境の詳細設定でコンテナ URL とチャート URL を設定してください。すべてのアーキテクチャ（または適切なアーキテクチャ）のイメージを同期してください。同期されていない場合、ARM／x86 ノードでイメージをプルできません。

環境でクラスターを作成する

使用する場面：環境が存在し、データベースをプロビジョニングするとき。

• ここでデータベースストレージクラスとボリュームスナップショットクラスを選択します。ボリュームスナップショットクラスを None に設定するとバックアップが無効になり、スナップショットボリュームに emptyDir を指定すると一時的なものになります（ポッドの再起動時に失われます）。これらは意図的に選択するものであり、デフォルトをよく考えずに受け入れてはいけません クラスターの作成。
• デフォルトでは、Qdrant Cloud は各ポッドの CPU／メモリの約20%を OS およびシステムコンポーネント用に予約します。小規模なノードでは予約を増やし、大規模なノードでは減らす必要がある場合があります。1ノードあたりデータベースポッド1つを目標にしてください。
• ノードセレクター／許容設定／トポロジー分散制約を使用して、データベースを専用ノードに配置し、ゾーン間で分散させます。

クラスターの公開とセキュリティ保護

使用する場面：Kubernetes クラスター外のアプリから Qdrant に接続する必要がある場合、または API キー／TLS について質問された場合。

• デフォルトは ClusterIP サービスで、内部からのみアクセスでき、API キーはありません。公開した時点（LoadBalancer、NodePort、Ingress のいずれか）で、必ず API キーを設定する必要があります。API キーは Kubernetes シークレットとして用意し、クラスター設定から参照します ネットワークとセキュリティ。
• 内部のノード間 gRPC はポート6335を使用し、API キーでも TLS でも保護されません。決してパブリックに到達可能にしてはいけません。Hybrid Cloud にはこれを制限する NetworkPolicy が付属しているため、制限を緩めないでください。
• TLS：Ingress／LB でオフロードするか、TLS シークレットを使って Qdrant で終端します。誤って両方を行わないでください。

ロギング

使用する場面：ログレベルを設定するとき、またはクラスターのログをスタックに接続するとき。（メトリクス／Prometheus／Grafana には、代わりに qdrant-monitoring スキルを使用してください。）

• ログレベルは2か所で設定します。データベースごとの設定はクラスター詳細ページで行いますが、Agent と Operator の設定はクラスターごとではなく、Hybrid Cloud Environment の設定で行います ネットワーク、ロギング、モニタリング。
• ログは Qdrant 固有のフォーマットを持たない通常のポッドログです。Kubernetes 対応のログコレクターを Qdrant 名前空間内のすべてのポッドに向けてください。Qdrant 固有の設定は不要です。

やってはいけないこと

• NFS、S3、またはブロックストレージ以外のストレージ上にプロビジョニングしないでください。サポート対象外であり、単に遅くなるのではなく、完全に失敗します。
• StorageClass／VolumeSnapshotClass を後から作成したり、allowVolumeExpansion を有効にしたりしてから、ディスクを拡張したりバックアップを取得したりできないことに気づくのは避けてください。これらは事前に存在している必要があります。
• Linode や Vultr でバックアップが「そのまま使える」と決めつけないでください。まず、お使いのプラットフォームで CSI スナップショットがサポートされていることを確認してください。
• API キーを設定せずに LoadBalancer／Ingress 経由でクラスターを公開したり、ポート6335をパブリックに到達可能なままにしたりしないでください。
• インストールコマンドを再生成（またはシークレットをローテーション）した後、再適用を忘れないでください。適用するまで、エージェントと Cloud の接続が気づかないうちに切断されます。
• クラスターを削除する前に Hybrid Cloud 環境を削除しないでください。まずクラスターを削除し、次に環境を削除してから、クリーンアップスクリプトを実行してください。そうしないと、クラスター内にリソースが残ってしまいます。