Unreal Cloud DDC のセットアップ方法

Unreal Cloud DDC は、クラウドベースの 派生データ キャッシュ (DDC) として主に使用される分散ストレージ サービスです。

Unreal Cloud DDC は、ワールド全体にレプリケートできるコンテンツアドレス指定可能なストアでコンパクトなバイナリ オブジェクトを格納します。コンパクトなバイナリ オブジェクトは自己記述型キー値オブジェクト (JSON と同様) であり、これには適切なバイナリ シリアル化と幅広い型システムが含まれています。

キー型の 1 つに アタッチメント 型があり、これは大きな BLOB を含むことなく参照するオブジェクトをサポートしています。BLOB は、画像、オーディオ ファイル、または他のマルチメディア コンテンツなどのバイナリ データ ファイルです。このようなアタッチされたペイロードはコンテンツアドレス指定であり、ペイロードのハッシュがその識別子として使用されます。コンテンツアドレス指定は、特に git など分散ストレージ システムで一般的な方法です。コンテンツアドレス指定には、ペイロードの不変の識別子を生成する機能があり、キャッシュで使用可能かどうか、別の場所にレプリケートする必要があるかどうかを迅速に判定することができます。

Unreal Cloud DDC を使用すると、ユーザーがリモートの場合など、準備したローカル (ファイル共有) キャッシュがない場合に、Unreal Engine でチームがクック処理を大幅にスピードアップすることができます。

ライセンス

Unreal Cloud DDC のソースは、通常の Unreal Engine ソース ライセンスでカバーされています。

コンテナ イメージは、GitHub で提供されています。これらのコンテナは MIT ライセンスで提供されています。

ディレクトリ

• Jupiter - ほとんどの Unreal Cloud DDC 機能。
• Jupiter.Common - Lib - Unreal Cloud DDC 外で使用できる機能を備えたレガシー ライブラリ。
• Helm - すべてのコンポーネントの Helm チャーター。
• Benchmark - 単純な HTTP ベンチマーク ユーザー SuperBenchmark (sb)、および Vegeta を使用してベンチマークを実行するために使用できる Docker コンテナを実行するための便利なテンプレート。
• Composes - ローカルのデプロイメントとテストを容易にするためのさまざまな Docker compose ファイルのコレクション。

依存関係

• DotNet Core 6 (および Visual Studio 2022 または VS Code)
• Docker
• Scylla
• BLOB ストレージ (S3、Azure Blob Store またはローカル ファイルシステム)

他の便利なツール

• MongoDB
• Minio
• Docker Compose

機能テストの要件

テストを開始する前に、次のコマンドラインを使用して前提条件サービスを開始します。

コマンドライン

docker-compose -f Composes\docker-compose-tests.yml -p jupiter-test up
Copy full snippet

docker-compose -f Composes\docker-compose-tests.yml -p jupiter-test up

ローカルに実行する

Unreal Cloud DDC を試す場合、docker-compose を使用して起動します。Unreal Cloud DDC ではさまざまなバックエンドをサポートしているため、各ユースケースにさまざまな構成が提供されています。

起動するには、次を実行します。

コマンドライン

docker-compose -f Composes\docker-compose.yml -f Composes\docker-compose-aws.yml up --build
Copy full snippet

docker-compose -f Composes\docker-compose.yml -f Composes\docker-compose-aws.yml up --build

Azure で使用可能なものに近いサービスを使用して実行する場合、AWS compose ファイルを docker-compose-azure.yml に置き換えることができます。

Docker compose 設定では認証を無効にして、すぐに開始できるようにします。一般的に、Unreal Cloud DDC を OIDC プロバイダに接続してから、これをデプロイすることをお勧めします。

デプロイメント

Unreal Cloud DDC は、現在、AWS のプロダクションでのみ実行されますが、ストレージおよびデータベースの要件は汎用的で抽象化されています。

Azure サービスの基本的な (未テスト) サポートが用意されています。

helm 値 (/Helm の下) を提供し、これを Kubernetes への Epic 内部デプロイメントに使用しますが、Kubernetes は要件ではありません。

Docker イメージは、Epic Games GitHub の組織 に公開されています。

Scylla

Unreal Cloud DDC が通信できるように Scylla クラスタを設定する必要があります。

Unreal Cloud DDC では、Scylla オープン ソース (無料) または有料サービスによる実行をサポートしています。有料サービスを使用すると、Scylla マネージャーがメンテナンス タスクに役立つため、クラスタの管理に必要な作業量を減らすことができます。

マルチリージョン クラスタの設定方法の詳細については、Scylla ドキュメントの「Create a ScyllaDB Cluster - Multi Data Centers (DC)」を参照してください。

オープン ソース バージョンの Scylla は ここ でダウンロードしてください。

Scylla では、クラウド環境で使用するためのマシン イメージを提供しています。

AWS

これは、Epic での運用方法であるため、最もテストされたデプロイメント形式です。各リージョンの Kubernetes クラスタにインストールする helm チャートは、このリポジトリで提供されています。

オンプレミス

Unreal Cloud DDC は、クラウド リソースを使用せずにオンプレミスでデプロイできます。このために (1 つのリージョンでのみこれを実行する場合) MongoDB データベースを設定することも、オンプレミスの複数のリージョンでこれを実行する場合は Scylla を設定することもできます。

1 つのリージョンで開始するが、後で拡張する場合、Scylla の使用をお勧めします。これを使用すると、直接スケーリングできますが、MongoDB では既存のすべての状態を削除する必要があります。

Azure

AWS にデプロイするには、Azure をクラウド プロバイダとして設定し、Azure.ConnectionString 設定を Azure Blob Storage への接続文字列とともに指定する必要があります。

デプロイメントをテストする

デプロイメントを設定して実行すると、マシンに接続して curl コマンドを実行して、正常に動作することを確認します。

最初に、ヘルス チェックの使用を試すことができます。文字列 Health を返される必要があります。

コマンドライン

curl http://localhost/health/live
Copy full snippet

curl http://localhost/health/live

次に、名前空間でのコンテンツの追加および取得を試みることができます。これにより、テスト文字列 (test) が test-namespace に挿入されます。設定によっては、異なる名前空間を使用することが必要になる場合があります。これは、認証が無効になっていることも前提としています。200 ステータス コードが空の「needs」リストとともに返されます

コマンドライン

curl http://localhost/api/v1/refs/test-namespace/default/00000000000000000000000000000000000000aa -X PUT --data 'test' -H 'content-type: application/octet-stream' -H 'X-Jupiter-IoHash: 4878CA0425C739FA427F7EDA20FE845F6B2E46BA' -i
Copy full snippet

curl http://localhost/api/v1/refs/test-namespace/default/00000000000000000000000000000000000000aa -X PUT --data 'test' -H 'content-type: application/octet-stream' -H 'X-Jupiter-IoHash: 4878CA0425C739FA427F7EDA20FE845F6B2E46BA' -i

その後、このオブジェクトを取得できます。これによって、「test」文字列と 200 ステータス コードが出力されます。

コマンドライン

curl http://localhost/api/v1/refs/test-namespace/default/00000000000000000000000000000000000000aa.raw -i
Copy full snippet

curl http://localhost/api/v1/refs/test-namespace/default/00000000000000000000000000000000000000aa.raw -i

監視する

Datadog を使用して、サービスを監視します。そのため、Unreal Cloud DDC は、そのサービスと連携するようにインストルメント化されています。ただし、すべてのログを構造化されたログとして stdout に出力されるため、構造化されたログを認識するすべての監視サービスはこれを適切に監視できる必要があります。

ヘルス チェック

すべての Unreal Cloud DDC サービスはヘルス チェックを使用して、自分自身、実行可能なすべてのバックグラウンド サービス、含まれている可能性のあるすべての依存サービス (DB / Blob ストアなど) を監視します。

/health/live と /health/ready で、それぞれライブ チェックと準備チェック用にヘルス チェックにアクセスできます。準備チェックは、サービスが機能することを検証するために使用されます。準備チェックで false が返された場合、アプリケーションはトラフィックを取得しません (ロード バランサーではこれを無視します)。ライブ チェックは、ポッドが正しく機能することを検証するために使用されます。ライブ チェックで false が返された場合、ポッド全体が強制終了されます。Kubernetes クラスタで実行している場合のみ、これが適用されます。

認証

Unreal Cloud DDC では、認証用に JWT 検証を実行する OIDC プロバイダの使用をサポートしています。Okta を Epic で使用しているので、これはテストされていますが、他の OIDC も互換性がある必要があります。

認証を設定するには、IdentityProvider (IdP) を設定してから、名前空間ごとに承認を設定します。

IdentityProvider 設定

auth 設定で認証スキームを指定します。

認証設定

auth:
    defaultScheme: Bearer
    schemes:
      Bearer: 
        implementation: "JWTBearer"
        jwtAudience: "api://unreal"
        jwtAuthority: "<url-to-your-idp>
Copy full snippet

auth: defaultScheme: Bearer schemes: Bearer: implementation: "JWTBearer" jwtAudience: "api://unreal" jwtAuthority: "<url-to-your-idp>

最初で唯一のスキームである場合、スキーム Bearer に名前を付けることをお勧めします。複数のスキームを使用して複数の IdP に対して接続できます。これは、移行中に最も役立ちます。

実装フィールドは通常、JWTBearer ですが、Okta をカスタム認証サーバーとともに使用している場合、Okta フィールドが提供されています。org 認証サーバーを使用する Okta の場合、JWTBearer も使用する必要があります。

名前空間のアクセス

Unreal Cloud DDC 内の操作へのアクセスは、一連のアクションを使用して制御されます。

• ReadObject
• WriteObject
• DeleteObject
• DeleteBucket
• DeleteNamespace
• ReadTransactionLog
• WriteTransactionLog
• AdminAction

これらは各名前空間ポリシーの acl を使用して名前空間ごとに割り当てることも、認証設定で acl に割り当てることもできます (名前空間全体および名前空間に関連付けられていない操作に適用します)。

以下にコンフィギュレーションの例を示します。アクセス権のあるユーザーにトランザクション ログ アクセス権を設定し、管理者用管理アクセス権を設定してから名前空間ごとのアクセス権を設定します。

auth:
    acls:
    - claims: 
        - groups=app-ddc-storage-transactionlog
        actions:
        - ReadTransactionLog
        - WriteTransactionLog

    - claims:
        - groups=app-ddc-storage-admin
        actions:
        - ReadObject
        - WriteObject
        - DeleteObject
        - DeleteBucket
        - DeleteNamespace
        - AdminAction

namespace:
  policies:
    example-namespace:
      acls:
      - actions: 
        - ReadObject
        - WriteObject
        claims: 
        - ExampleClaim
     - actions: 
        - ReadObject
        - WriteObject
        claims: 
        - AnotherClaim
    open-namespace:
      acls:
      - actions: 
        - ReadObject
        - WriteObject
        claims: 
        - "*"
Copy full snippet

auth: acls: - claims: - groups=app-ddc-storage-transactionlog actions: - ReadTransactionLog - WriteTransactionLog - claims: - groups=app-ddc-storage-admin actions: - ReadObject - WriteObject - DeleteObject - DeleteBucket - DeleteNamespace - AdminAction namespace: policies: example-namespace: acls: - actions: - ReadObject - WriteObject claims: - ExampleClaim - actions: - ReadObject - WriteObject claims: - AnotherClaim open-namespace: acls: - actions: - ReadObject - WriteObject claims: - "*"

要求配列内で複数の要求を指定する場合、これらは論理積になり、すべての要求は true に評価される必要があります。A=B のような要求文では要求 A には値 B が含まれている必要があります (配列の場合、値 B を含む)。

* 要求も指定できます。これは、含まれている要求に関係なく、すべての有効なトークンにアクセス権を付与します。これはデバッグ シナリオとテスト シナリオ用であるため、プロダクション データに使用しないでください。

ネットワーキング設定

Unreal Cloud DDC では、VPN トンネルに依存することなく、通常のインターネット接続を使用して多くのパフォーマンスを派生させます。したがって、パブリック インターネット エンドポイントで Unreal Cloud DDC を公開することを強くお勧めします。HTTPS を使用し、このページで説明したように認証を設定して、誰もこのデータにアクセスできないようにします。

Unreal Cloud DDC では複数のポートを提供し、これを使用して API のアクセス レベルを制御できます。

パブリック ポート

これは、パブリック インターネットに公開するポートであり、ほとんどのユーザーがサービスにアクセスするために使用するものです。このポートはより機密性の高い API (たとえば、すべてのコンテンツを列挙する API) を公開しません。これはポート 80 で公開され、Kubernetes 内では http として公開されます。単一リージョンのみを操作している場合、これは公開する必要がある唯一のポートです。

プライベート ポート

これは Corp ポートとも呼ばれます。イントラネットに公開されるルートがある場合、これを使用します。その目的は、イントラネットでユーザーにのみ公開される機密性の高い特定の名前空間を保持することです。名前空間ポリシーで IsPublicNamespace (false に設定) を使用して、これを有効にします。

DDC にこれを使用することはお勧めしません。ユーザー WFH (在宅勤務) が VPN なしで名前空間にアくセスできなくなるためです (通常、DDC ユースケースで非常に遅くなります)。

これは通常、ポート 8008 で公開され、Kubernetes 内では corp-http として公開されます。

        "PublicApiPorts": [ 80, 8081 ],
        "CorpApiPorts": [ 8008, 8082 ],
        "InternalApiPorts": [ 8080, 8083 ]
Copy full snippet

"PublicApiPorts": [ 80, 8081 ], "CorpApiPorts": [ 8008, 8082 ], "InternalApiPorts": [ 8080, 8083 ]

内部ポート

内部ポートは、他の Unreal Cloud DDC インスタンスのみが到達可能である必要があります。これは、プライベート ポートが行うすべてのものを公開しますが、(主にレプリケーション ログでコンテンツを列挙する) 機密性の高いとみなされる特定の API も公開します。

これはポート 8080 で公開され、Kubernetes 内では internal-http として公開されます。

プライベート VPC を介するか、IP 範囲の許可リストなどを使用して、他の Unreal Cloud DDC インスタンスへのこのイングレスを維持することをお勧めします。

このポートは、主に投機的 BLOB レプリケーションに使用されます (このページの「BLOB レプリケーションを設定する」を参照してください)。

一般的な操作

ローカル インスタンスに対してローカル クックを実行する

ローカル インスタンスを実行している場合、これに対してローカル クックを実行するには、オプション -UE-CloudDataCacheHost=http://localhost を渡します。これは、プロジェクトが Cloud DDC を使用するように設定されていて、UE-CloudDataCacheHost=None をホスト オーバーライドとして使用していることを前提としています (これはプロジェクト間で異なります)。

これが意図したとおりに機能する場合、クッカーに以下のように出力が表示されます。

コンソール出力

DerivedDataCache http://localhost: HTTP DDC: Healthy
Copy full snippet

DerivedDataCache http://localhost: HTTP DDC: Healthy

新しいリージョンを追加する

新しいリージョンには以下のものが含まれている必要があります。

• S3 ストレージ

• コンピュート (Kubernetes クラスタまたは VM)

• Scylla デプロイメント

新しいリージョンを追加するために Unreal Cloud DDC を設定するには、すべてのノードでクラスタ設定を更新して新しいリージョンの DNS を含めます。

新しいリージョン用に LocalKeyspaceReplicationStrategy を設定する必要もあります。

Scylla コンフィギュレーションについては、「Adding a New Data Center Into an Existing ScyllaDB Cluster」を参照してください。

特に重要な部分は、キースペースの更新です。

ALTER KEYSPACE jupiter WITH replication = { 'class' : 'NetworkTopologyStrategy', '<exiting_dc>' : 3, <new_dc> : 3};
ALTER KEYSPACE system_auth WITH replication = { 'class' : 'NetworkTopologyStrategy', '<exiting_dc>' : 3, <new_dc> : 3};
ALTER KEYSPACE system_distributed WITH replication = { 'class' : 'NetworkTopologyStrategy', '<exiting_dc>' : 3, <new_dc> : 3};
ALTER KEYSPACE system_traces WITH replication = { 'class' : 'NetworkTopologyStrategy', '<exiting_dc>' : 3, <new_dc> : 3};
Copy full snippet

ALTER KEYSPACE jupiter WITH replication = { 'class' : 'NetworkTopologyStrategy', '<exiting_dc>' : 3, <new_dc> : 3}; ALTER KEYSPACE system_auth WITH replication = { 'class' : 'NetworkTopologyStrategy', '<exiting_dc>' : 3, <new_dc> : 3}; ALTER KEYSPACE system_distributed WITH replication = { 'class' : 'NetworkTopologyStrategy', '<exiting_dc>' : 3, <new_dc> : 3}; ALTER KEYSPACE system_traces WITH replication = { 'class' : 'NetworkTopologyStrategy', '<exiting_dc>' : 3, <new_dc> : 3};

どの場所でもレプリケーション係数 3 を使用するため、新しいリージョン (DC) の名前を追加します。

local キースペースのそれぞれを変更して、新しいリージョン用にレプリケーション係数を 0 に設定する必要もあります (このセクションの LocalKeyspaceReplicationStrategy に関連する手順を参照してください)。

ALTER KEYSPACE jupiter_local_regionA WITH replication = { 'class' : 'NetworkTopologyStrategy', 'regionA' : 2, 'regionB' : 0}
ALTER KEYSPACE jupiter_local_regionB WITH replication = { 'class' : 'NetworkTopologyStrategy', 'regionA' : 0, 'regionB' : 2}
Copy full snippet

ALTER KEYSPACE jupiter_local_regionA WITH replication = { 'class' : 'NetworkTopologyStrategy', 'regionA' : 2, 'regionB' : 0} ALTER KEYSPACE jupiter_local_regionB WITH replication = { 'class' : 'NetworkTopologyStrategy', 'regionA' : 0, 'regionB' : 2}

これにより、ローカル キースペースがローカル リージョンにのみ書き込まれるようになります。これは不可欠ではありませんが、このデータはそのリージョン内でのみリクエストされます。そのため、これにより Scylla クラスタ内で多くの帯域幅とストレージが節約されます。

この新しいリージョンからレプリケートするために、Unreal Cloud DDC ワーカーのコンフィギュレーションでレプリケーターを更新することが必要になる場合があります。

BLOB レプリケーションを設定する

Unreal Cloud DDC には、2 つの方法のレプリケーションがあります。

• オンデマンド レプリケーション

• 投機的レプリケーション

オンデマンド レプリケーション では、必要な BLOB が欠落しているリージョン B でリクエストが発生するため、リージョン A からリージョン B に BLOB をコピーします。このタイプのレプリケーションは、名前空間ポリシーで OnDemandReplication を true に設定することによる名前空間ごとのオプトインです。

応答時間が非常に変化しやすくなるため、DDC の名前空間にこれを設定することはお勧めしません。DDC の場合、キャッシュ ミスを受け入れてコンテンツを再ビルドすることをお勧めしますが、通常、BLOB を転送するために投機的レプリケーションに依存するため、レイテンシーを追加することなく、あらゆる場所で使用できます。

投機的レプリケーション は、参照を追加してレプリケートするコンテンツを認識するため、各リージョンで維持されるジャーナルを使用します。これは名前空間で変更が発生すると追従し、この新しい参照によって参照されているすべての BLOB をコピーします。実際にローカル リージョンで使用されず、必要でないコンテンツを含め、すべてのコンテンツがコピーされますが、参照が解決すると、ほとんどの場合、使用可能なローカルの BLOB を持つ利点があります。

応答時間を短く抑えることが重要な DDC の場合、投機的レプリケーションに依存することをお勧めします。

これを設定するには、以下のようなワーカー コンフィギュレーションにセクションを追加します (「example-values-ABC.yaml」を参照)。

example-values-ABC.yaml

worker:
  config:
    Replication:
      Enabled: true
      Replicators: 
      - ReplicatorName: DEF-to-ABC-test-namespace
        Namespace: test-namespace
        ConnectionString: http://url-to-region-DEF.com
Copy full snippet

worker: config: Replication: Enabled: true Replicators: - ReplicatorName: DEF-to-ABC-test-namespace Namespace: test-namespace ConnectionString: http://url-to-region-DEF.com

レプリケーター名は、このレプリケーターを一意に識別する文字列にできます (レプリケーターの状態の格納およびログ記録で使用されます)。

Namespace は、レプリケートする名前空間です。

ConnectionString は、Unreal Cloud DDC デプロイメントの他のリージョンへの接続に使用する URL です。

これは、内部ポートを使用して公開する必要があります (「Networking setup」を参照)。使用する Unreal Cloud DDC に認証情報を設定する必要もあります (ServiceCredentials セクション内)。この認証情報は、ReadTransactionLog アクセス権が付与されている必要があります。