# Overview of the infrastructure
> Learn what Self-Hosted Deployment installs in your Kubernetes cluster, and what you provide
## Infrastructure components
Self-Hosted Deployment runs entirely within your own Kubernetes cluster. The release creates and manages the following components inside the cluster:
| Component | Description |
| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Percona Server for MongoDB (PSMDB) | Document database for asset metadata and application data |
| PostgreSQL (via PG Operator) | Relational database for Keycloak and other services |
| RabbitMQ | Message broker for asynchronous communication between services |
| Valkey | In-memory data store for caching and session management |
| Elasticsearch | Search engine for asset indexing and discovery |
| Garage | Distributed S3-compatible object storage for transformation step logs, MongoDB backups, and Unity Studio publications. Deployed as a 3-node cluster by default, unless you bring your own S3-compatible buckets (`configuration.objectStore.provider: s3`). |
| Traefik | Ingress controller and load balancer |
| Keycloak (version 26) | Identity and access management, based on the official upstream Keycloak 26 image |
| Argo Workflows | Workflow engine for transformations and 3D streaming |
| Istio (optional) | Service mesh for traffic management and observability |
| Loki and Alloy (optional) | Log collection and aggregation |
| Percona Monitoring and Management (optional) | Database monitoring |
| Prometheus (optional) | Metrics collection. Ships with a curated set of cluster and workload alerting rules out of the box. |
## What the release installs and what you provide
Self-Hosted Deployment installs the whole platform into your Kubernetes cluster from one release. You provide the cluster and the services around it.
```mermaid
flowchart LR
subgraph yours["You provide"]
k8s["Kubernetes 1.34+ cluster
3+ general nodes, transformation node pools
metrics API, target namespace"]
sc["Storage classes
default block + ReadWriteMany"]
lb["Load balancer, DNS name and TLS certificate"]
reg["Container registry
or direct pulls from the Unity registry"]
sec["Secret values
ideally from your secret manager"]
opt["Optional: identity provider for SSO, S3-compatible buckets,
your own Prometheus Operator, ArgoCD and a Git repository"]
end
subgraph release["Installed by the release, in your cluster"]
edge["Traefik ingress
Keycloak and Mini-USF"]
apps["Asset Manager services, Unity Studio
Argo Workflows transformations
UVCS, Unity Licensing Server, notifications"]
data["PostgreSQL, MongoDB, Elasticsearch
RabbitMQ, Valkey"]
store["Garage object storage
unless you bring your own buckets"]
optional["Optional: Istio, Prometheus stack,
Loki and Alloy, PMM"]
end
lb --> edge
reg -. images .-> apps
sec -. Kubernetes Secrets .-> apps
sc --> data
sc --> store
```
| Dependency | Installed by the release | What you can bring instead | Manifest setting |
| ----------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
| Kubernetes cluster | — | Required: Kubernetes 1.34 or later, at least 3 schedulable general nodes, and the `argocpu` transformation node pool. Recommended: the `argocpu-large` pool for memory-intensive transformations | `configuration.kubernetes.namespace` |
| Storage | — | Required: a cluster-default storage class and a ReadWriteMany storage class | `configuration.kubernetes.storage` |
| Ingress | Traefik | Your load balancer in front of Traefik's service | `configuration.networking.ingress.traefik` |
| DNS and TLS | — | Required: a hostname that points at the load balancer, and a certificate for it | `configuration.networking.appDomain`, `configuration.networking.ingress.traefik.tls` |
| Container images | — | Direct pulls from the Unity registry, or a mirror in your own registry | `configuration.kubernetes.docker`, `configuration.kubernetes.imagePullSecret` |
| Identity | Keycloak and Mini-USF | Federation to your identity provider for single sign-on, set up in Keycloak after deployment | — |
| Databases, search, messaging, cache | PostgreSQL, MongoDB, Elasticsearch, RabbitMQ, Valkey | — | `configuration.infrastructure` (sizing) |
| Object storage | Garage | Your own S3-compatible buckets | `configuration.objectStore.provider: s3` |
| Secrets | Kubernetes Secrets generated by shdctl | Values from your own secret manager, fed into the secrets import file (`shdctl secret generate --import`) | — |
| Metrics | Prometheus stack (optional) | Your own Prometheus Operator | `configuration.monitoring.prometheus.enabled`, `configuration.monitoring.prometheus.installedInCluster` |
| Logs | Loki and Alloy (optional) | — | `configuration.monitoring.logCollection.enabled` |
| Database monitoring | PMM (optional) | — | `configuration.monitoring.database.enabled` |
| Service mesh | Istio (optional) | — | `configuration.networking.serviceMesh.istio.enabled` |
| Deployment | — | ArgoCD and a Git repository (recommended), or Helm, run by shdctl | `deployment.argocd` |
> **Note:**
>
> Unity Studio publications are user data, and no backup that the release configures covers them. Back up the bucket that holds them yourself: the in-cluster store's `studio-assets` bucket, or the bucket you name in `configuration.objectStore.buckets.studioAssets`.
## Infrastructure sizing
The deployment supports named sizing profiles that control CPU, memory, and storage allocations for infrastructure components. You configure the sizing profile in the manifest file:
* `small`: suitable for development and testing environments
* `medium` (default): suitable for typical production workloads
* `large`: suitable for high-traffic production environments
You can also override resource allocations for individual components. Read more about the configuration of the manifest in the [deployment procedure](./deployment.md).
## Deployment waves
To satisfy dependencies, the deployment installs components in waves:
1. **Wave -3**: cluster configuration, Istio base, and Prometheus stack
2. **Wave -2**: operators and infrastructure services — Istio, Elasticsearch operator, database operators, Traefik, monitoring, and Loki
3. **Wave -1**: databases, caching, storage, and foundational services — Elasticsearch, PostgreSQL, MongoDB, RabbitMQ, Valkey, Garage, UVCS, Argo Workflows, and the Alloy log collector
4. **Wave 0**: Keycloak and the application services — Asset Manager, automations, catalog, collaboration, and other microservices
5. **Wave 1**: the notification service
6. **Wave 2**: post-deployment jobs — onboarding, the automation apps and built-in workflow templates, and the PMM integration
## Ingress
Traefik is deployed as the ingress controller. You configure the load balancer type and annotations in the manifest to match your environment, for example, an AWS Network Load Balancer (NLB), an Azure load balancer, or a bare-metal load balancer.
`configuration.networking.allowedIngressCIDRs` restricts who can reach the deployment only with the `LoadBalancer` service type, the default: it becomes the Traefik Service's `loadBalancerSourceRanges`. With `NodePort` or `ClusterIP` behind your own load balancer, the setting has no effect, so put your allowlist on that load balancer or your firewall.
Whichever allowlist you use, include your cluster's own outbound addresses, usually its NAT gateway's. Unity Studio calls the deployment back at its public `appDomain`, so those calls arrive from the address your cluster's traffic leaves by. If that address isn't allowed in, Studio fails while the rest of the deployment stays healthy.
### Optional ingress routes for the ArgoCD, Argo Workflows, and PMM user interfaces
The release can expose the ArgoCD, Argo Workflows, and PMM user interfaces at `argocd.`, `argoworkflows.`, and `pmm.`. All three routes are disabled by default. Leave them disabled unless you put authentication in front of them: the Argo Workflows server runs unauthenticated, and its permissions allow submitting workflows and reading namespace secrets, so exposing it grants those capabilities to anyone who can reach your load balancer. Omitting the DNS record doesn't protect a route, because the client supplies the hostname.
To enable the routes, first restrict access to trusted sources: with `allowedIngressCIDRs` on the `LoadBalancer` service type, or on your own load balancer or firewall with `NodePort` or `ClusterIP`. Then set:
```yaml
configuration:
overrides:
traefik:
values:
ingressRoutes:
argocd:
enabled: true
# only if your ArgoCD release isn't named `argocd`
serviceName: -argocd-server
argoWorkflows:
enabled: true
pmm:
enabled: true
```
Then create a DNS record for each hostname you enable, pointing at your load balancer.
## Next steps
[Prerequisites](./prerequisites.md) for the deployment