Documentation

Support

Unity Cloud

Get Started

Asset Manager SDKs and services

Open Unity Dashboard

Unity Cloud

Deploy the solution on premises

Deploy Unity Virtual Private Cloud on premises using the vpctl tool
Read time 5 minutesLast updated 9 hours ago
Before deployment, check the prerequisites. The deployment on premises uses the vpctl tool to manage the entire release lifecycle. If all prerequisites are met, the deployment takes 30 to 60 minutes. This time doesn't include the subsequent administration tasks, such as setting up an identity provider for single sign-on (SSO). Follow these steps to deploy Virtual Private Cloud to your Kubernetes cluster.

1. Configure the registry credentials

Before you can pull releases, configure your ORAS registry credentials. This is a one-time setup.

1.1 Run the interactive configuration or set the credentials non-interactively

To run the interactive configuration, complete these steps:
  1. Run this command: 
    vpctl configure
  2. Specify this information:
    • Registry URL
    • Username
    • Password
    Credentials are stored securely in your home directory.
Alternatively, use the non-interactive command: 
vpctl configure set uccmpprivatecloud.azurecr.io --username <username> --password <password>

1.2 Verify your configuration

To verify your configuration, run this command: 
vpctl configure get

2. Initialize the manifest file

The manifest file 
manifest.yaml
contains your deployment configuration. If you already have a manifest file, you can skip this procedure. The vpctl tool automatically discovers the 
manifest.yaml
file in the current directory or in the parent directories. If you don't have the manifest file, create it:
  1. Run this command: 
    vpctl manifest init
  2. Specify this information:
    • Platform: 
      onprem
    • Release version
    • Source registry and target image registry
    • Application domain
    • Kubernetes namespace and image pull secret
    • Autoscaling settings: min and max replicas
    • Monitoring options: database monitoring, Prometheus, log collection
    • Infrastructure sizing profile
    • Traefik service type
    • ArgoCD settings, if ArgoCD is installed
The manifest file is created in your current directory as 
manifest.yaml
.

Configure the manifest file

The manifest file controls the entire deployment. Here is an example of a minimal configuration: 
platform: onpremreleaseVersion: 0.9.0artifactSync:  sourceRepository: uccmpprivatecloud.azurecr.ioconfiguration:  networking:    appDomain: example.com    allowedIngressCIDRs:      - "10.0.0.0/8"    ingress:      traefik:        type: LoadBalancer    serviceMesh:      istio:        enabled: false  kubernetes:    namespace: asset-solutions    docker:      repository: <your-registry-url>      namespace: <your-registry-namespace>    imagePullSecret: regcred    autoscaling:      minReplicas: 1      maxReplicas: 10    storage:      defaultStorageClass: <your-default-storage-class>      readWriteManyStorageClass: <your-rwx-storage-class>  infrastructure:    sizing: medium
You can customize these sections:
  • networking: Set the application domain, allowed ingress CIDRs, Traefik configuration, and optional Istio service mesh.
  • kubernetes: Configure the target namespace, container registry, image pull secrets, autoscaling, and storage classes.
  • transformations: Set the maximum number of concurrent transformation workflows (
    parallelism
    ).
  • monitoring: Enable or disable database monitoring, Prometheus, and log collection (Loki and Alloy).
  • authentication: Configure optional X.509 client certificate authentication for Keycloak.
  • infrastructure:
    • Select a sizing profile: small, medium, or large.
    • Optionally, override resource allocations per component: MongoDB, PostgreSQL, RabbitMQ, UVCS, RustFS, Elasticsearch.

Deploy the solution using ArgoCD

If you use ArgoCD for continuous delivery, add the 
deployment.argocd
section to your manifest: 
deployment:argocd:    repoURL: "https://github.com/org/repo.git"    pathPrefix: "onprem/cluster1"    destinationServer: "https://kubernetes.default.svc"    targetRevision: "main"

3. Pull the release

  1. Download the release package from the registry. The system reads the version from the manifest automatically: 
    vpctl release pull --clean-output
    The system downloads the release archive and extracts it to this directory: 
    ./extracted-release
    .
  2. To pull a specific version, run this command: 
    vpctl release pull --version 0.9.0 --clean-output

4. Sync the artifacts

Before deploying, sync the Docker images and ORAS artifacts from the Unity source registry to your private registry.

4.1 Authenticate to both registries

You must authenticate to the source and target registries before syncing: 
docker login uccmpprivatecloud.azurecr.iodocker login <your-registry-url>

4.2 Run the preflight check

Verify that your credentials are working before running a full sync: 
vpctl artifact sync preflight
This command syncs one Docker image and one ORAS artifact as a test. If it fails, it prints troubleshooting hints.

4.3 Sync the Docker images

Preview the sync commands first: 
vpctl artifact sync images --dry-run
Run the sync: 
vpctl artifact sync images
Optionally, you can use these flags: 
  • --skip-existing
    : Skip images that already exist on the target registry.
  • --cleanup
    : To save disk space, remove the local images after each successful push.
  • --name
    : Sync only the images that match a name pattern.
  • --concurrency
    : Number of images to sync in parallel. The default value is 
    1
    . You can also set this in the manifest under 
    artifactSync.concurrency
    .

4.4 Sync the ORAS artifacts

ORAS artifacts include OCI artifacts used by Helm charts. The sync reads authentication from the Docker credential store (
~/.docker/config.json
) automatically. Preview the sync commands first: 
vpctl artifact sync oras --dry-run
Run the sync: 
vpctl artifact sync oras
Optionally, you can use these flags: 
  • --name
    : Sync only the ORAS artifacts that match a name pattern.
  • --concurrency
    : Number of artifacts to sync in parallel. The default value is 
    1
    .

5. Generate and deploy the secrets

Generate the secrets

To generate the secrets, complete these steps:
  1. Create a secrets import file based on the provided example: 
    secrets.import.example.yaml
    .     This file contains secret values organized by secret name. Values are in plain text. Encoding is handled automatically. 
     # UVCS SSL Certificate PEMcustom-ca-certificate-pem:  ssl-certificate.pem: "<your-certificate-pem>"# Elasticsearch Secretselasticsearch-apps-credentials:  password: "<your-password>"# Mini-usf Secretsmini-usf:  MINIUSF_Keycloak__ClientSecret: "<your-client-secret>"# Novu API Secretsnovu-api:  JWT_SECRET: "<your-jwt-secret>"  STORE_ENCRYPTION_KEY: "<your-encryption-key>"# PSMDB Secrets - MongoDB/Percona Server for MongoDB secretspsmdb-secrets:  MONGODB_BACKUP_PASSWORD: "<your-password>"  MONGODB_CLUSTER_ADMIN_PASSWORD: "<your-password>"  MONGODB_CLUSTER_MONITOR_PASSWORD: "<your-password>"  MONGODB_DATABASE_ADMIN_PASSWORD: "<your-password>"  MONGODB_USER_ADMIN_PASSWORD: "<your-password>"  # PMM_SERVER_TOKEN: "<your-pmm-token>" (optional only if PMM is deployed)# PMM Admin Password (optional only if PMM is deployed)# pmm-admin-password:#   GF_SECURITY_ADMIN_PASSWORD: "<your-password>"# PSMDB Asset Manager Passwordpsmdb-asset-manager-password:  password: "<your-password>"# PostgreSQL Secretspg-db-pguser-assetsolutions:  password: "<your-password>"# PostgreSQL PMM Server token (optional only if PMM is deployed)# pg-pmm-secret:#   PMM_SERVER_TOKEN: "<your-pmm-token>"# RabbitMQ Admin Usernamerabbitmq-asset-solutions-import-admin-user:  password: "<your-password>"# RustFS S3 API Storage Credentialss3-api-storage-credentials:  RUSTFS_ACCESS_KEY: "<your-access-key>"  RUSTFS_SECRET_KEY: "<your-secret-key>"# UVCS Licenseuvcs-license:  plasticd.lic: "<your-license-content>"# UVCS configurationuvcs-configuration:  UVCS_USER_PASSWORD: "<your-password>"  UVCS_ADMIN_PASSWORD: "<your-password>"# Valkey Users ACLvalkey-users:  users.acl.password: "<your-password>"
  2. Generate the Kubernetes secret manifests: 
    vpctl secret generate --import secrets.import.yaml --use-defaults

Deploy the secrets

  1. To preview the deployment, run this command: 
    vpctl secret deploy --dry-run
  2. To deploy the secrets to your cluster, run this command: 
    vpctl secret deploy

6. Generate and deploy the charts

Choose your deployment method: Helm or ArgoCD.

Option A: Helm deployment

Generate the Helm charts

vpctl release generate --clean-output

Deploy with Helm

  1. Preview the deployment first. Run this command: 
    vpctl release deploy --dry-run
    For a first-time deployment, deploy the release in waves, starting with the lowest wave, for example, 
    -3
    . Then, validate each wave before deploying the next. This method ensures that dependencies are satisfied.     
    vpctl release deploy --wave -3vpctl release deploy --wave -2vpctl release deploy --wave -1vpctl release deploy --wave 0
  2. Deploy all charts: 
    vpctl release deploy

Verify the deployment

To check the status of the deployments: 
kubectl get pods --all-namespaces --watch
Ensure that all pods eventually move to the Running state. If a pod isn't running, describe it and check its logs to find the issue.

Option B: ArgoCD deployment

Generate ArgoCD application configuration

If the 
deployment.argocd
section is set in the manifest, generate the ArgoCD charts. Run this command: 
vpctl release generate --format argocd --clean-output

Commit charts to Git

ArgoCD deploys from a Git repository. To commit the generated charts, run this command: 
git add generated-charts/git commit -m "Add release charts"git push

Deploy the ArgoCD application

  1. To preview the deployment, run this command: 
    vpctl release deploy --format argocd --dry-run
  2. To run the deployment, run this command: 
    vpctl release deploy --format argocd

7. Configure the DNS and certificates

To make the solution secure and accessible, configure the DNS records and the TLS certificates for your domain.
  1. Register a fully qualified domain name (FQDN) for the frontend, for example, 
    example.com
    .
  2. Point the DNS record to the external IP or hostname of the Traefik load balancer. To find this infion, run this command: 
    kubectl get svc -n <namespace> traefik
  3. Configure a TLS certificate for the domain. You can use the Traefik ingress annotations in the manifest to reference your certificate, or configure it through your load balancer.

Next steps

Postdeployment