Azure AKS へのシングルクラスターインストール (Helm)

1. PostgreSQL データベースをセットアップする

CodeCanvas では、CodeCanvas アプリケーションデータ用に PostgreSQL データベースが必要です。

1. Azure Database for PostgreSQL サーバー（バージョン 12.2 – 15.12 がサポートされています）をデプロイします。CodeCanvas アプリケーションクラスターからサーバーにアクセスできることを確認してください。

2. CodeCanvas アプリケーション専用のデータベースを作成します。

3. インストールを続行する前に、データベースサーバーが起動して実行されていることを確認してください。

2. オブジェクトストレージを構成する

ユーザーデータとアプリケーションデータを保存するための Azure BLOB ストレージコンテナーを作成します。詳細な手順については、Azure Blob ストレージのドキュメントを参照してください。アクセスには、ワークロード ID または静的認証情報を使用してください。

3. CodeCanvas アプリケーションクラスターを準備する

CodeCanvas アプリケーションクラスターは、CodeCanvas アプリケーションと関連サービスをホストします。CodeCanvas アーキテクチャの詳細

1. Azure AKS クラスター

   次の要件を満たす CodeCanvas アプリケーション用の Azure AKS クラスターをセットアップします。

   要件	説明
   Helm	バージョン 3.8.0 以降
   Kubernetes	バージョン 1.29 以降
   CodeCanvas アプリケーションノード	CodeCanvas アプリケーションとメインコンポーネントを実行するノード。 Linux OS (x86_64) を搭載したノードが 4 つ以上。推奨最小リソース: CPU コア 4 個、メモリ 8GB
   開発環境ノード	開発環境用のワーカー pods を実行するノード。 開発環境を実行するのに十分なノード（それぞれ Linux OS（Ubuntu、x86_64）搭載）が必要です。推奨最小リソース: CPU コア 4 個、メモリ 8GB。以下の推奨事項をご確認ください。

   ノードに関する主な推奨事項

   • 一般的なノード要件

     Linux OS (Ubuntu、x86_64)、推奨最小リソース: 4 つの vCPU と 8 GB のメモリ。

   • 自動スケーリングを構成する

     自動スケーリングを使用して、負荷に応じてノード数を調整します。通常の使用状況をカバーするのに十分な最小ノード数から開始し、ピーク時には自動スケーリングによってノードを追加できます。自動スケーリングに関する推奨事項を参照してください。

   • リソースを見積もる

     通常およびピーク時の同時使用率（同時環境の平均数と最大数）を見積もります。例: ピーク時のアクティビティで 20 人の開発者がそれぞれ 2 ～ 3 の開発環境を使用する場合、ピーク時の需要は 60 のアクティブ環境になります。

     合計リソース要件を計算します。例: 一般的な開発環境が 4 つの vCPU と 16 GB のメモリである場合、60 の開発環境では 240 の vCPU と 960 GB のメモリが必要になります。

     重要: Kubernetes は、kubelet、kube-proxy などのシステムタスクのために各ノードのリソースの一部を必要とします。システムタスク用に、ノードごとに約 0.2 vCPU と 1 ～ 2GB のメモリを予約する必要があります。正確な値はインストールによって異なります。実際のノードリソース使用量を確認するには、kubectl describe node <node-name> を実行してください。

   • ノード割り当て戦略を選択する

     • 1 つのノード – 1 つの開発環境

       1 つのノード（Azure VM）は、1 つの開発環境（ワーカー、pod）のみをホストします。この例では、60 の開発環境（たとえば Standard D4s v3 （4 つの vCPU、16GB のメモリ））には、60 個の個別のノードが必要になります。

       • (+) オーバープロビジョニングなし: 各ノードは単一の開発環境によって完全に利用されます。

       • (+) フォールトトレランス: ノードに障害が発生した場合、影響を受ける開発環境は 1 つだけです。

       • (-) オーバーヘッドの増加: Kubernetes は各ノードのリソースの一部をシステムタスクに使用します。そのため、この例では各開発環境に 4 つの vCPU と 16GB のメモリが割り当てられますが、開発者が利用できるのは 3.8 つの vCPU と 14 ～ 15GB のメモリのみです。残りの 0.2vCPU と 1 ～ 2GB のメモリは Kubernetes のシステムタスクによって使用され、結果として 60 * (0.2 の vCPU と 1 ～ 2GB = 12vCPU と 60 ～ 120GB のオーバーヘッドが発生します。この問題は、より大きなインスタンスを使用することで解決できます。

       • (-) 起動時間が遅い: オートスケーラーは、新しい開発環境ごとに新しいノードをプロビジョニングする必要があります。

     • 1 つのノード – 複数の開発環境

       単一ノード（Azure VM）は複数の開発環境（ワーカー、pods）をホストします。60 の開発環境（合計 240 vCPU、960GB メモリ）の例では、この負荷を Standard D64s v3 （64 vCPU、256GB メモリ）や Standard D32s v3 （32 vCPU、128GB メモリ）など、4 ～ 6 ノードに分割できます。

       • (-) オーバープロビジョニング: 実行されている開発環境の数がノードに対応できる数より少ない場合、リソースが無駄になります。

       • (-) フォールトトレランス: ノードに障害が発生すると、複数の開発環境に影響がおよびます。

       • (+) オーバーヘッドの低減: 複数の開発環境が同じノードを共有するため、Kubernetes システムタスク（ノードあたり 0.2 vCPU と 1 ～ 2GB のメモリ）のオーバーヘッドが削減されます。この例では、4 ～ 6 ノードの場合、オーバーヘッドは 4 – 6 * (0.2 vCPU と 1 ～ 2GB = 0.8 – 1.2 vCPU と 4 ～ 12GB のメモリとなります。「1 ノード – 1 開発環境」戦略の場合の 12 vCPU と 60 ～ 120GB のオーバーヘッドと比較してみてください。

       • (+) 起動時間の短縮: ノードに使用可能なリソースがある場合、新しいノードがプロビジョニングされるのを待たずに、新しいワーカー pods をすぐに起動できます。

       • (+) 潜在的なコスト削減: 少数の大規模インスタンスを使用する方が、多数の小規模インスタンスを使用するよりもコスト効率が高くなる可能性があります。ただし、これはリソース使用量をどれだけ正確に予測できるか、開発環境をノードにどれだけ効率的に配置できるかに依存します。

   • Azure インスタンスタイプを選択する

     Azure インスタンスタイプを比較して選択するには、公式の Azure VM サイズのドキュメントを使用します。

     B、-family などのバースト可能なインスタンスタイプは避けてください。代わりに、Standard D や Standard E ファミリなどのコンピューティング最適化またはメモリ最適化インスタンスタイプの使用を検討してください。

2. 名前空間

   CodeCanvas アプリケーション専用の名前空間を作成します (NAMESPACE_PLACEHOLDER を実際の名前空間名に置き換えます)。

   kubectl create namespace NAMESPACE_PLACEHOLDER

3. Ingress コントローラー

   Kubernetes のセットアップと互換性のある Ingress コントローラーをインストールします。このガイドでは、ingress-nginx(英語) コントローラーを使用します。

4. CSI ドライバー

   クラスタに Azure ディスク CSI ドライバ（disk.csi.azure.com）をインストールしてください。CodeCanvas はこのドライバを使用して、開発環境の永続ボリュームとスナップショットを管理します。インストール手順については、Azure のドキュメントを参照してください。CodeCanvas の CSI について詳しく見る

5. ストレージクラス

   開発環境で使用される永続ボリュームをプロビジョニングするための Kubernetes StorageClass を作成します。以下の推奨構成を使用することも、パフォーマンスやコストの好みに応じて独自の構成を定義することもできます。

   推奨される構成では、開発環境のパフォーマンスが保証され、Azure StandardSSD_LRS マネージドディスクが使用されます。

   開発環境クラスターには複数のストレージクラスを設定できます。インスタンスタイプを作成する際に、利用可能なストレージクラスから選択できます。

   1. storage-class.yaml ファイルを作成し、以下のスニペットをコピーします。

      apiVersion: storage.k8s.io/v1 kind: StorageClass metadata: name: codecanvas-storage # You can change this name provisioner: disk.csi.azure.com parameters: skuName: StandardSSD_LRS # Recommended: # StandardSSD_LRS (equivalent to 'managed-csi') # Premium_LRS (equivalent to 'managed-csi-premium') kind: Managed allowVolumeExpansion: true reclaimPolicy: Delete volumeBindingMode: WaitForFirstConsumer

   2. 構成をクラスターに適用します。

      kubectl apply -f storage-class.yaml

   3. 組織の管理ポリシーに基づいて、storage-class.yaml ファイルを削除するか、保持します。

6. ボリュームスナップショットクラス

   Kubernetes VolumeSnapshotClass を作成して、開発環境で使用される永続ボリュームのスナップショットサポートを有効にします。以下の推奨ボリュームスナップショットクラス構成をご利用いただけます。

   開発環境クラスターには複数のボリュームスナップショットクラスを設定できます。インスタンスタイプを作成する際に、利用可能なクラスから選択できます。

   1. snapshot-class.yaml ファイルを作成し、以下のスニペットをコピーします。

      apiVersion: snapshot.storage.k8s.io/v1 kind: VolumeSnapshotClass metadata: name: codecanvas-volume-snapshot # You can change this name driver: disk.csi.azure.com deletionPolicy: Delete

   2. 構成をクラスターに適用します。

      kubectl apply -f snapshot-class.yaml

   3. 組織の管理ポリシーに基づいて、snapshot-class.yaml ファイルを削除するか、保持します。

4. DNS と TLS を構成する

1. ドメイン名

   CodeCanvas インスタンスのドメイン名を登録します (例: codecanvas.example.com)。

2. DNS ゾーン

   DNS レコードを管理するには、CodeCanvas アプリケーションクラスターに ExternalDNS(英語) をインストールします。

3. TLS 証明書

   暗号化しましょうによって発行された TLS 証明書を管理するには、CodeCanvas アプリケーションクラスターに cert-manager(英語) をインストールします。

4. サブドメイン

   CodeCanvas アプリケーションコンポーネントのサブドメインを設定します。 custom.values.yaml の設定では、以下の DNS ドメイン名スキームが想定されています。

   • EXTERNAL_DOMAIN_PLACEHOLDER – メインの管理 UI と REST API を提供する CodeCanvas アプリケーションのメインドメイン。例: codecanvas.example.com

   • computeservice.EXTERNAL_DOMAIN_PLACEHOLDER – compute-service REST API（Kubernetes オペレーター用）を提供するサブドメイン。これは通常、開発環境 pods からのみアクセスされる内部ドメインです。

   • gateway.EXTERNAL_DOMAIN_PLACEHOLDER – gateway-relay サービス（リレーサーバー）を提供します。これは、ユーザーの IDE クライアントがアクセスする外部ドメインです。

   • ssh.EXTERNAL_DOMAIN_PLACEHOLDER – jump-server サービス（移動サーバー）の SSH サービスを提供します。これは、ユーザーの IDE クライアントがアクセスする外部ドメインです。

5. Azure ワークロード ID を構成する

CodeCanvas アプリケーションに BLOB ストレージなどの Azure リソースへのアクセスを許可するには、Azure ワークロード ID を使用する必要があります。これにより、静的な認証情報が不要になります。

Azure ワークロード ID ドキュメントの手順に従ってマネージド ID を構成し、AKS クラスターにバインドします。

マネージド ID に Azure BLOB ストレージへのアクセスに必要な権限があることを確認してください。例: ID に Storage Blob Data Contributor ロールを割り当て、ターゲットストレージアカウントへの書き込み権限を付与します。詳細については、Azure ストレージ認証ドキュメントを参照してください。

6. （オプション）SMTP サーバーを構成する

CodeCanvas は、ユーザー作成時の招待リンク、メール認証、その他の通知など、様々なメールをユーザーに送信するために SMTP サーバーを使用します。この機能を有効にするには、CodeCanvas アプリケーションクラスターからアクセスできる SMTP サーバーを用意してください。

1. custom.values.yaml を作成する

custom.values.yaml を作成し、以下のスニペットをコピーしてください。プレースホルダーは次の手順で実際の値に置き換えます。

2. ワークロード ID の割り当て

pre-installation では、マネージド ID を Kubernetes サービスアカウントにリンクするように Azure Workload Identity を構成しました。次に、この構成を適用します。custom.values.yaml で、AZURE_CLIENT_ID をマネージド ID のクライアント ID に置き換えます。

3. 外部ドメインを指定

custom.values.yaml では、すべての EXTERNAL_DOMAIN_PLACEHOLDER プレースホルダーを CodeCanvas インスタンスに登録したドメイン名に置き換えます。

4. cert-manager を設定する

custom.values.yaml では、すべての CERT_MANAGER_NAME_PLACEHOLDER プレースホルダーをクラスターで使用されている cert-manager(英語) の名前に置き換えます。

5. データベース設定を指定する

CodeCanvas をインストールすると、外部の PostgreSQL データベースを使用することになります。任意の PostgreSQL データベースを使用できますが、Azure Database for PostgreSQL の使用をお勧めします。

6. オブジェクトストレージ設定を指定する

CodeCanvas をインストールするには、外部オブジェクトストレージを使用する必要があります。以下の手順は Azure Blob Storage に適用されます。

7. マスターシークレットを作成する

CodeCanvas アプリケーションは、ユーザーシークレット（外部サービスへの認証情報など）を暗号化された形式でデータベースに保存します。これらのデータの暗号化と復号には、マスターシークレットが使用されます。

マスターシークレットは、任意の Base64 エンコード文字列にすることができます。例: openssl を使用してランダムな文字列を生成できます。

1. マスターシークレットを生成するには、以下を実行します。

   openssl rand -base64 32

2. custom.values.yaml で、MASTER_SECRET_PLACEHOLDER を生成された値に置き換えます。

8. （オプション）システム管理者アカウントを構成する

システム管理者アカウントは、インストール後に CodeCanvas へのログインと設定に使用されます。認証情報は手動で入力することも、システムによって自動生成することもできます。

1. 管理者アカウントを手動で設定するには、custom.values.yaml で次の行を置き換えます。

   • 必要な管理者資格情報を持つ ADMIN_USERNAME_PLACEHOLDER および ADMIN_PASSWORD_PLACEHOLDER

   • CodeCanvas からの管理者通知を受信するためのメールアドレスを持つ ADMIN_EMAIL_PLACEHOLDER

あるいは、custom.values.yaml から localAdministrator.username と localAdministrator.password のセクションを削除することもできます。この場合、デフォルトのユーザー名は admin になり、インストール時にランダムなパスワードが生成されます（チャートのデプロイ後に表示されます）。ただし、ADMIN_EMAIL_PLACEHOLDER の代わりにメールアドレスを指定する必要があります。

9. Ingress クラスを指定する

custom.values.yaml で、すべての INGRESS_CLASS_PLACEHOLDER プレースホルダーを、CodeCanvas アプリケーションクラスターに使用される Ingress クラスに置き換えます。

10. (オプション) CodeCanvas pod の Kubernetes サービスアカウントを指定する

アプリケーションクラスタにサービスアカウントを設定し、そのサービスアカウント名を Helm リリース名とは別のものにしたいとします。その場合、CodeCanvas Helm チャートが作成する Kubernetes サービスアカウントに特定の名前を指定する必要があるかもしれません。手順は以下のとおりです。

1. custom.values.yaml の対応するセクションに次のパラメーターを追加します。

   application: serviceAccount: name: "CODECANVAS_KSA_NAME"

2. CODECANVAS_KSA_NAME をサービスアカウントの希望の名前に置き換えます。

11. (オプション) Sysbox コンテナーランタイムを構成する

デフォルトでは、CodeCanvas はワーカーコンテナーを --privileged モードで実行します（コンテナーはホストノード上でルート権限を持ちます）。セキュリティ上の理由からこれを回避したい場合は、こちらの説明に従って Sysbox Container Runtime をインストールしてください。

12. コンピューティングプラットフォームを構成する

CodeCanvas におけるコンピューティングプラットフォームは、開発環境を実行するインフラストラクチャを表します。これは、CodeCanvas オペレーター、Relay、踏み台サーバーを含む Kubernetes クラスターで構成されます。

• リレーサーバー – ユーザーマシン上の JetBrains Client と開発環境（SSL/TLS 経由）間の中継。リレーがなければ、JetBrains IDE を開発環境で使用することはできません。

• 移動サーバー – 開発環境の SSH デーモンとユーザーマシン間の間接 SSH 接続のための中間サーバー。移動サーバーがないと、ユーザーは SSH を使用して開発環境に接続したり、リモート開発に VS Code/Cursor を使用したりすることができません。

• CodeCanvas 演算子 –ワーカーインスタンス (開発環境を実行する pods) のライフサイクルを管理します。Kubernetes API と対話して、ワーカーインスタンスを作成、監視、削除します。

13. ライセンス契約に同意する

custom.values.yaml では、ACCEPTANCE_PLACEHOLDER を true に置き換えて、CodeCanvas ライセンス契約(英語)を明示的に受け入れます。

14. CodeCanvas チャートをインストールする

custom.values.yaml にパラメータープレースホルダーが残っていないことを確認してください。すべてが正しく入力されている場合は、以下を実行してください。

ここに:

• NAMESPACE_PLACEHOLDER は Kubernetes の名前空間です

• codecanvas は Helm のリリース名です。必要に応じて変更できます。

1. CodeCanvas pods の状態を確認する

実行:

すべての pods は Running 状態である必要があります。平均して、デプロイから pod がアクティブになるまで約 2 分かかります。

pods が Running でない場合は、次のコマンドを実行して原因を見つけてみてください。

および

2. ドメイン名解決の検証

ドメイン名は Ingress ロードバランサーに解決される必要があります。これは次のコマンドで確認できます。

出力にはエラーが含まれていてはなりません。

3. CodeCanvas アプリケーションを確認する

ブラウザーで CodeCanvas インスタンスを開きます。CodeCanvas にログインする際は、インストール時に提供された管理者の資格情報を使用してください。