Prerequisites

Before you deploy Self-Hosted Deployment

읽는 시간 8분

최근 업데이트: 하루 전

Access to the container registry

Ensure that you have credentials for the Unity private container registry

uccmpprivatecloud.azurecr.io

. Unity provides these credentials. You need this information to download shdctl, pull release packages, and sync container images and ORAS artifacts to your private registry.

Tooling

Ensure that you have this tooling:

Access to a terminal, and basic knowledge of the command line
One of these tools if you use Microsoft Windows:
- Windows Subsystem for Linux (WSL)
- Git for Windows
ORAS CLI, for the shdctl install script, which downloads shdctl from the registry
Helm (version 3.9 or later), to install the Helm charts
kubectl, to interact with your Kubernetes cluster
Docker, to sync the container images to your private registry
ArgoCD (recommended), for continuous delivery via GitOps. If you choose the ArgoCD deployment method, install it in the target cluster before you deploy: shdctl applies a single bootstrap
```
Application
```
and ArgoCD takes over from there. Every application is created in the deployment namespace, so install ArgoCD in that namespace, or configure it to watch it: ArgoCD's "Applications in any namespace" needs the namespace in both its
```
application.namespaces
```
setting and the
```
default
```
project's
```
sourceNamespaces
```
. An ArgoCD that watches only its own namespace leaves the applications unsynced, and reports no error. If you deploy with Helm, you don't need ArgoCD at all.
shdctl is the Unity CLI tool that manages the entire deployment lifecycle. Its install steps, requirements, and registry credential setup are in Install shdctl. If you used vpctl before, install shdctl 1.0.0 or later: vpctl can't pull Self-Hosted Deployment 2.0.0 or later.

참고

Unity recommends ArgoCD as the deployment method. ArgoCD handles CRD installation ordering and detects configuration drift automatically, which makes ongoing operations more reliable. Helm is also fully supported if you prefer direct deployments without a GitOps workflow.

Kubernetes

The deployment requires a Kubernetes cluster that you manage.

Use Kubernetes version 1.34 or later.

Your cluster must include at least 3 schedulable nodes in the general workloads pool. MongoDB (Percona Server for MongoDB) and RabbitMQ run as 3-replica clusters by default and place each replica on a different node by using

podAntiAffinity

kubernetes.io/hostname

. PostgreSQL and Garage object storage also run 3 replicas by default, but don't require separate nodes. If your cluster has only two nodes, some pods remain in the

Pending

state because the scheduler can't satisfy the anti-affinity requirement.

Storage classes

The cluster must provide two storage classes:

A default storage class for general-purpose persistent volumes (block storage), marked as the cluster default with the
```
storageclass.kubernetes.io/is-default-class: "true"
```
annotation. For example, a local-path provisioner, a SAN-backed CSI driver, or any block storage provisioner.
A ReadWriteMany (RWX) storage class for shared volumes that multiple pods can mount simultaneously. For example, an NFS provisioner, a distributed filesystem, or any CSI driver that supports the
```
ReadWriteMany
```
access mode.

In the manifest file,

configuration.kubernetes.storage.readWriteManyStorageClass

names the RWX class.

defaultStorageClass

names the class for Garage and the Unity Licensing Server only: every other ReadWriteOnce volume uses the cluster's default storage class, so the cluster must have one even if the manifest names a class.

Metrics API

The cluster must serve the

metrics.k8s.io

API, which the platform's horizontal pod autoscalers require. Most distributions provide it through

metrics-server

. Without it, autoscaled workloads can't read their resource usage and don't scale.

Namespaces

Services come preconfigured for use within a single Kubernetes namespace. You configure the target namespace in the manifest file.

Create the namespace before you deploy. The deployment doesn't create it for you.

Node pools

The platform separates general application workloads from asset transformation jobs. Configure your cluster with three node pools (or equivalent node groups):

Node pool	Node label	Taint	Recommended node size	Purpose
General workloads	None required	None	8–32 vCPUs; compute, general-purpose, or memory-optimized instances	Application services, databases, messaging
Transformations	`aks-node-pool=argocpu`	None	8–32 vCPUs and at least 64 GiB of memory; general-purpose or memory-optimized instances	Transformation workflow pods
Transformations (large)	`aks-node-pool=argocpu-large`	`aks-node-pool=argocpu-large:NoSchedule`	32–64 vCPUs and at least 256 GiB of memory; general-purpose or memory-optimized instances	Escalation pool for memory-intensive transformations; only pods that explicitly tolerate the taint are scheduled here

Transformation steps request up to 32 GiB of memory on the

argocpu

pool, and their retries up to 220 GiB on the

argocpu-large

pool. A step that no node can fit stays

Pending

until its workflow times out.

The exact mechanism to create node pools depends on your Kubernetes distribution (for example, static node labels, a node autoscaler, or a cluster API provider). If an autoscaler other than Karpenter scales the transformation pool from zero,

shdctl cluster check

reports the pool as missing while it is empty; that failure is expected.

GPU nodes are optional. By default, transformation actions that can use a GPU run on the

argocpu

pool with a software renderer. If your cluster has GPU nodes that advertise the

nvidia.com/gpu

resource, for example through the NVIDIA device plugin, set

configuration.overrides.automation-manager.values.env.vpcGpuAvailable: true

in the manifest so that those actions request a GPU.

Network policies

During deployment to an existing cluster, you may need to control the flow of network traffic by using network policies. You can deploy most Kubernetes resources in a single namespace, which you can use to scope network isolation from other services that run in your cluster.

Clusters behind an HTTP proxy

If your AKS cluster sends its outbound traffic through an HTTP proxy (AKS HTTP proxy), AKS injects

HTTP_PROXY

HTTPS_PROXY

and

NO_PROXY

into every pod. Platform services call each other by their short Service names, which no

NO_PROXY

entry matches, so those calls go to the proxy and fail.

To keep the platform pods off the proxy, add the AKS opt-out annotation to every pod in the manifest file. Nodes still pull images through the proxy, but the pods get no internet access:


configuration:  kubernetes:    podAnnotations:      kubernetes.azure.com/no-http-proxy-vars: "true"

The automation-manager job pulls the release manifest from your registry itself, so it still needs the proxy. Unless your cluster reaches the registry without the proxy, pass it through the chart's overrides:


configuration:  overrides:    automation-manager:      values:        env:          httpsProxy: http://<proxy>:<port>          noProxy: .svc,.cluster.local,localhost,127.0.0.1

configuration.kubernetes.podAnnotations

applies to every pod the release creates. To change or remove an annotation for a single chart, refer to Per-chart Helm value overrides.

The

azure-baseline-example

in the release package can create such a cluster:

aks_http_proxy

sets the proxy,

aks_private_cluster_enabled

makes the API server private, and

aks_egress_via_proxy_only

denies all other outbound traffic from the cluster's subnet. Its README describes each variable.

What the proxy must allow

AKS's own outbound traffic. Nodes bootstrap and keep running through the proxy, so it must allow the destinations in AKS outbound network and FQDN rules, for example
```
mcr.microsoft.com
```
and
```
packages.aks.azure.com
```
.
Your container registry. Nodes pull every image through the proxy, and the automation-manager job reaches the registry through it too: the registry in
```
configuration.kubernetes.docker.repository
```
, or
```
uccmpprivatecloud.azurecr.io
```
if you pull from it directly. Allow the endpoints the registry serves image layers from as well; for Azure Container Registry, refer to Configure rules to access an Azure container registry behind a firewall.
Requests from the nodes. Pod traffic reaches the proxy from its node's address, so allow the node subnet as a source.
HTTP and HTTPS only. HTTPS goes through the proxy as
```
CONNECT
```
on port 443, and plain HTTP on port 80. Outbound traffic that isn't HTTP, such as SMTP or SSH, has no path through the proxy.
TLS inspection. If the proxy decrypts HTTPS, give the cluster its CA certificate (
```
trustedCa
```
in the AKS HTTP proxy configuration). The certificates must use subject alternative names.

Container registry

By default, the platform pulls container images directly from the Unity source registry (

uccmpprivatecloud.azurecr.io

). This is the simplest setup and doesn't require a separate registry.

If your environment is air-gapped or if you need full control over artifact distribution, you can mirror artifacts to your own private container registry. Any OCI-compliant registry is supported, for example Harbor, JFrog Artifactory, or a cloud-managed registry such as Amazon ECR or Azure Container Registry. Use these commands to mirror artifacts from the Unity source registry to your private registry:

```
shdctl artifact sync images
```
: this command syncs the Docker container images.
```
shdctl artifact sync oras
```
: this command syncs the ORAS artifacts, for example, the Pixyz workflow templates.
```
shdctl artifact sync verify
```
: this command checks that your registry holds every image your manifest needs.

System requirements

Ensure that you have these elements:

A valid hostname that can be updated to point to the IP of the load balancer
A valid Unity Version Control (UVCS) license to run the UVCS server
A valid Unity Asset Transformer SDK license to run transformations on assets

A valid Unity Asset Transformer license is required for all users who perform asset transformations. The platform uses static licenses, so a floating license server is not required.

Validate your cluster

Once your

manifest.yaml

exists, check the prerequisites on this page automatically. The command reads the namespace, the storage classes, and the ArgoCD settings from the manifest, and step 3 of the deployment runs it:


shdctl cluster check

The command verifies:

The Kubernetes version.
The number of schedulable nodes.
The transformation node pools.
The storage classes.
The target namespace.
The metrics API.
The in-cluster ArgoCD installation if your manifest configures ArgoCD. On the Helm deployment path, these checks are skipped.

The command reads from the cluster and doesn't change it. It prints a remediation hint for anything that doesn't pass.

Add

--probe-storage

to verify that each storage class can provision a volume, including

ReadWriteMany

support.

For the full list of checks and options, refer to shdctl cluster command.

Next steps

Deploy Self-Hosted Deployment

기술 자료

Development

User Acquisition

Monetization

산업 분야

Self-Hosted Deployment

Deploy on Kubernetes (recommended)

shdctl

AWS Terraform package

Azure Marketplace