Prerequisites

CloudSmith supports two deployment models. PaaS (Azure Container Apps) is the primary track for most operators. On-Premises is available for environments without internet access or with existing Hyper-V infrastructure. Select the section that matches your deployment target.

PaaS prerequisites

Deployment authentication

CloudSmith PaaS deploys to Azure using the Azure Developer CLI (azd). Two authentication patterns are supported. Choose the one that fits your organization.

Option A — Interactive (personal Azure account)

Use your own Azure account. This is the simplest path for individual operators and evaluation deployments.

Required role assignments on the target subscription:

The Owner role covers both. Contributor alone is not sufficient because the Bicep template creates a role assignment internally.

No Entra ID directory roles are required. No app registration or service principal is needed for deployment.

az login
azd up

Option B — Pre-provisioned deployment identity (enterprise / CI/CD)

A privileged administrator creates a User-Assigned Managed Identity once and assigns it the required roles. Individual operators and automated pipelines then deploy without needing personal subscription permissions.

One-time admin setup:

az identity create --name id-cloudsmith-deploy --resource-group <your-platform-rg>
MI_PRINCIPAL=$(az identity show --name id-cloudsmith-deploy --resource-group <your-platform-rg> --query principalId -o tsv)
SUB_ID=$(az account show --query id -o tsv)
az role assignment create --assignee $MI_PRINCIPAL --role "Contributor"                             --scope /subscriptions/$SUB_ID
az role assignment create --assignee $MI_PRINCIPAL --role "Role Based Access Control Administrator" --scope /subscriptions/$SUB_ID

Deploy from any of:

• Azure Cloud Shell (MI attached automatically if configured)
• An Azure VM with the MI attached
• GitHub Actions or Azure DevOps using Workload Identity Federation targeting the MI

azd picks up the identity automatically via DefaultAzureCredential — no secrets or credentials are stored in code or configuration files.

Optional: Entra SSO

If you want portal users to sign in with their corporate Microsoft identity, configure an Entra ID identity provider after CloudSmith is running. This is set up through the portal under Platform Management → Identity Providers, not during initial deployment.

Why an App Registration is required (and why a Managed Identity cannot replace it)

When operators sign into the CloudSmith portal using their Entra credentials, the portal runs an OAuth2 Authorization Code flow — the browser redirects to Microsoft’s login page, users authenticate, and an identity token is returned to the portal. This flow requires a registered application with a redirect URI. Managed Identities handle non-interactive workload-to-workload authentication and cannot initiate browser-based OAuth2 flows.

Entra directory roles needed for the App Registration:

To create the App Registration manually before setup, or to delegate the one-time creation to an Entra admin, see Identity configuration.

Local tooling

Install the following on the workstation from which you run azd up:

# Verify before proceeding
az version
azd version

Azure region service availability

The Bicep pack requires both Azure Container Apps and Azure Database for PostgreSQL Flexible Server in your chosen region. Verify before deploying:

$region = 'eastus'   # Replace with your target region

az provider show --namespace Microsoft.App `
    --query "resourceTypes[?resourceType=='containerApps'].locations" `
    --output table

az provider show --namespace Microsoft.DBforPostgreSQL `
    --query "resourceTypes[?resourceType=='flexibleServers'].locations" `
    --output table

If either service is unavailable in your chosen region, select an alternate region before proceeding.

On-premises prerequisites

Management host

The management host is a Windows Server 2025 machine that runs the CloudSmith control plane. It is separate from the clusters you manage — it is a dedicated or shared management machine with network access to those clusters.

Operating system:

• Windows Server 2025 (Standard or Datacenter)
• Hyper-V role installed and running
• PowerShell 7.4 or later

Hardware minimums:

Nested virtualization (management host running as a VM):

If the management host is itself a Hyper-V VM, enable nested virtualization on the parent host before running the installer:

# Run on the parent Hyper-V host — not inside the management VM
Set-VMProcessor -VMName '<management-vm-name>' -ExposeVirtualizationExtensions $true

Network ports

Inbound (to management host):

Outbound (from management host / Relay):

See System requirements for the complete reference including on-premises hardware specs and the Linux VM provisioned by the installer.

Relay host

The CloudSmith Relay runs as a Docker container on a dedicated Linux host inside your cluster network. This host is separate from the management host and from the Hyper-V hosts you manage.

Operating system and runtime:

• Any Linux distribution with Docker Engine 20.10 or later
• Ubuntu 22.04 LTS or 24.04 LTS recommended

Hardware minimums:

Firewall requirements:

The relay host does not need any inbound access from the internet. All PaaS connections are outbound from the relay.

See Install the CloudSmith Relay for the full deployment procedure.

Managed hosts (agent)

Install the CloudSmith Agent on every Hyper-V host you want CloudSmith to manage.

Operating system:

• Windows Server 2019, 2022, or 2025 (Standard or Datacenter)

Runtime:

• .NET 9 Runtime — or use the self-contained agent binary which includes the runtime

Network access:

Rights:

• Local administrator or SYSTEM rights are required to install and run a Windows Service.

See Install the CloudSmith Agent for the full installation procedure.