Unreal Engine Cloud DDC Intra Cluster Module

Warning

Many of the links in this document lead back to the Unreal Engine source code hosted on GitHub. Access to the Unreal Engine source code requires that you connect your existing GitHub account to your Epic account. If you are seeing 404 errors when opening certain links, follow the instructions here to connect your accounts.

Unreal Cloud Derived Data Cache (source code) is a caching system that stores additional data required to use assets, such as compiled shaders. This allows the engine to quickly retrieve this data instead of having to regenerate it, saving time and disk space for the development team. For distributed teams, a cloud-hosted DDC enables efficient collaboration by ensuring all team members have access to the same cached data regardless of their location. This Terraform module deploys the Unreal Cloud DDC container image provided by the Epic Games GitHub organization. It also configures the necessary service accounts and IAM roles required to run the Unreal Cloud DDC service on AWS.

This module currently utilizes the Terraform EKS Blueprints Addons repository to install the following addons to the Kubernetes cluster, with the required IAM roles and service accounts:

• CoreDNS: Provides DNS services for the Kubernetes cluster, enabling reliable name resolution for the Unreal Cloud DDC service. Kube-Proxy: Manages network traffic routing within the cluster, ensuring seamless communication between the Unreal Cloud DDC service and other components.
• VPC-CNI: Implements the Kubernetes networking model within the AWS VPC, allowing the Unreal Cloud DDC service to be properly integrated with the network infrastructure.
• EBS CSI Driver: Provides persistent storage capabilities using Amazon Elastic Block Store (EBS), enabling the Unreal Cloud DDC service to store and retrieve cached data.

Deployment Architecture

Prerequisites

Note

This module is designed to be used in conjunction with the Unreal Cloud DDC Infra Module which deploys the required infrastructure to host the Cloud DDC service.

GitHub Secret

Next, for the module to be able to access the Unreal Cloud DDC container image, there are 2 things you must do. First, if you have not done so, you must connect your GitHub account to your Epic account, thereby granting you access to the container images in the Unreal Engine repository. Next, you will need to create a github_credentials secret which includes a username and access-token field.

Note

Instructions on creating a new access token can be found here. You will need to provide the read:package and repo permissions to the access token you create.

You can then upload the secret to AWS Secret Manager using the following AWS CLI command:

aws secretsmanager create-secret --name "ecr-pullthroughcache/github-credentials" --secret-string '{"username":"USERNAME-PLACEHOLDER","access-token":"ACCESS-TOKEN-PLACEHOLDER"}'

Note

Make sure to replace the GITHUB-USERNAME-PLACEHOLDER and GITHUB-ACCESS-TOKEN-PLACEHOLDER with the appropriate values from your GitHub account prior to running the command.

Warning

Note that the name of the secret must be prefixed with ecr-pullthroughcache/ and the fields must be called username and access-token for ECR to properly detect the secrets. If making changes to the above command, you must adhere to these rules.

Once the secret is created, pass the newly uploaded secret's ARN into the ghcr_credentials_secret_manager_arn variable.

Customizing Your Deployment

OIDC Secret

To use client secrets for OIDC authentication, a new secret must be uploaded to AWS Secrets Manager. You can upload the new secret to AWS Secret Manager using the following AWS CLI command:

Note

Make sure to replace the CLIENT-SECRET-PLACEHOLDER and CLIENT-ID-PLACEHOLDER with the appropriate values from your IDP prior to running the command.

aws secretsmanager create-secret --name "external-idp-oidc-credentials" --secret-string '{"client_secret":"CLIENT-SECRET-PLACEHOLDER","client_id":"CLIENT-ID-PLACEHOLDER"}'

The ARN for the newly created secret must then be passed to the oidc_credentials_secret_manager_arn variable. The secret is referenced using the following format and should be passed into the variable using the same format:

aws!arn:aws:secretsmanager:<region>:<aws-account-number>:secret:<secret-name>|<json-field>

Note

Note the prefix aws! and the postfix |<json-field> are added to the ARN of the newly created secret.

Note

While we highly encourage the use of OIDC tokens for production environments, users can use a bearer token in its place by providing the token to the unreal_cloud_ddc_helm_values variable. See DDC sample for an example implementation.

    unreal_cloud_ddc_helm_values = [
        templatefile("${path.module}/assets/unreal_cloud_ddc_single_region.yaml", {
            token = <bearer-token>
            # Other templatefile parameters...
        })
    ]

Chart Values (Helm Configurations)

The unreal_cloud_ddc_helm_values variable provides an open-ended way to configure the Unreal Cloud DDC deployment through the use of YAML files. We generally recommend you to use a template file. An example of a template file configuration can be found in the unreal-cloud-ddc-single-region sample located here. You can also find additional example templates provided by Epic here.

Requirements

Name	Version
terraform	>= 1.5
aws	>= 5.38
helm	>=2.9.0
kubernetes	>=2.24.0

Providers

Name	Version
aws	>= 5.38
helm	>=2.9.0
kubernetes	>=2.24.0

Modules

Name	Source	Version
aws_load_balancer_controller	git::https://github.com/aws-ia/terraform-aws-eks-blueprints-addon.git	327207ad17f3069fdd0a76c14d3e07936eff4582
cert_manager	git::https://github.com/aws-ia/terraform-aws-eks-blueprints-addon.git	327207ad17f3069fdd0a76c14d3e07936eff4582
ebs_csi_irsa_role	git::https://github.com/terraform-aws-modules/terraform-aws-iam.git//modules/iam-role-for-service-accounts-eks	ccb4f252cc340d85fd70a8a1fb1cae496a698c1f
eks_blueprints_all_other_addons	git::https://github.com/aws-ia/terraform-aws-eks-blueprints-addons.git	a9963f4a0e168f73adb033be594ac35868696a91
eks_service_account_iam_role	git::https://github.com/terraform-aws-modules/terraform-aws-iam.git//modules/iam-assumable-role-with-oidc	ccb4f252cc340d85fd70a8a1fb1cae496a698c1f
s3_iam_policy	git::https://github.com/terraform-aws-modules/terraform-aws-iam.git//modules/iam-policy	ccb4f252cc340d85fd70a8a1fb1cae496a698c1f

Resources

Name	Type
helm_release.unreal_cloud_ddc	resource
kubernetes_namespace.unreal_cloud_ddc	resource
kubernetes_service_account.unreal_cloud_ddc_service_account	resource
aws_eks_cluster.unreal_cloud_ddc_cluster	data source
aws_iam_policy_document.aws_load_balancer_controller	data source
aws_iam_policy_document.cert_manager	data source
aws_partition.current	data source
aws_s3_bucket.unreal_cloud_ddc_bucket	data source

Inputs

Name	Description	Type	Default	Required
cert_manager_hosted_zone_arns	List of ARNs to be passed to Certificate Manager Addon	list(string)	n/a	yes
cluster_name	Name of the EKS Cluster	string	n/a	yes
external_secrets_secret_manager_arn_list	List of ARNS for Secret Manager Secrets to use in Unreal Cloud DDC	list(string)	[]	no
oidc_provider_arn	ARN of the OIDC Provider from EKS Cluster	string	n/a	yes
s3_bucket_id	ID of the S3 Bucket for Unreal Cloud DDC to use	string	n/a	yes
unreal_cloud_ddc_helm_values	List of YAML files for Unreal Cloud DDC	list(string)	[]	no
unreal_cloud_ddc_namespace	Namespace for Unreal Cloud DDC	string	"unreal-cloud-ddc"	no

Outputs

No outputs.

Requirements

Name	Version
terraform	>= 1.10.3
aws	>=5.73.0
helm	>=2.16.0
kubernetes	>=2.33.0

Providers

Name	Version
aws	5.99.1
helm	2.17.0
kubernetes	2.37.1

Modules

Name	Source	Version
eks_blueprints_all_other_addons	git::https://github.com/aws-ia/terraform-aws-eks-blueprints-addons.git	a9963f4a0e168f73adb033be594ac35868696a91

Resources

Name	Type
aws_ecr_pull_through_cache_rule.unreal_cloud_ddc_ecr_pull_through_cache_rule	resource
aws_iam_policy.s3_secrets_manager_iam_policy	resource
aws_iam_role.ebs_csi_iam_role	resource
aws_iam_role.unreal_cloud_ddc_sa_iam_role	resource
aws_iam_role_policy_attachment.ebs_csi_policy_attacment	resource
aws_iam_role_policy_attachment.unreal_cloud_ddc_sa_iam_role_s3_secrets_policy_attachment	resource
helm_release.unreal_cloud_ddc	resource
kubernetes_namespace.unreal_cloud_ddc	resource
kubernetes_service_account.unreal_cloud_ddc_service_account	resource
aws_caller_identity.current	data source
aws_eks_cluster.unreal_cloud_ddc_cluster	data source
aws_iam_openid_connect_provider.oidc_provider	data source
aws_iam_policy_document.unreal_cloud_ddc_policy	data source
aws_lb.unreal_cloud_ddc_load_balancer	data source
aws_region.current	data source
aws_s3_bucket.unreal_cloud_ddc_bucket	data source

Inputs

Name	Description	Type	Default	Required
certificate_manager_hosted_zone_arn	ARN of the Certificate Manager for Ingress.	list(string)	[]	no
cluster_name	Name of the EKS Cluster	string	n/a	yes
cluster_oidc_provider_arn	ARN of the OIDC Provider from EKS Cluster	string	n/a	yes
enable_certificate_manager	Enable Certificate Manager for Ingress. Required for TLS termination.	bool	false	no
ghcr_credentials_secret_manager_arn	Arn for credentials stored in secret manager. Needs to be prefixed with 'ecr-pullthroughcache/' to be compatible with ECR pull through cache.	string	n/a	yes
name	Unreal Cloud DDC Workload Name	string	"unreal-cloud-ddc"	no
oidc_credentials_secret_manager_arn	Arn for oidc credentials stored in secret manager.	string	null	no
project_prefix	The project prefix for this workload. This is appended to the beginning of most resource names.	string	"cgd"	no
s3_bucket_id	ID of the S3 Bucket for Unreal Cloud DDC to use	string	n/a	yes
tags	Tags to apply to resources.	map(any)	{ "IaC": "Terraform", "ModuleBy": "CGD-Toolkit", "ModuleName": "Unreal DDC" }	no
unreal_cloud_ddc_helm_values	List of YAML files for Unreal Cloud DDC	list(string)	[]	no
unreal_cloud_ddc_namespace	Namespace for Unreal Cloud DDC	string	"unreal-cloud-ddc"	no
unreal_cloud_ddc_service_account_name	Name of Unreal Cloud DDC service account.	string	"unreal-cloud-ddc-sa"	no
unreal_cloud_ddc_version	Version of the Unreal Cloud DDC Helm chart.	string	"1.2.0"	no

Outputs

Name	Description
unreal_cloud_ddc_load_balancer_name	n/a
unreal_cloud_ddc_load_balancer_zone_id	n/a