Skip to main content
Adaptive Engine can be easily deployed in your own infrastructure - cloud or on-premises - using our Helm chart. This guide will walk you through an overview of the deployment process and key configuration areas. For the most up-to-date and precise instructions, refer to the Adaptive Engine Helm chart repository.
In self-hosting, customers enjoy a high level of privacy. Adaptive ML has no requirement for external connectivity nor telemetry.

​
Prerequisites & dependencies

This section details necessary prerequisites to a self-hosted Adaptive Engine deployment.

​
Commercial contract

Adaptive Engine containers are private and available only upon signature of a commercial contract with Adaptive ML.

​
Infrastructure landing zone

Adaptive Engine requires the following infrastructure dependencies:
  1. A Kubernetes cluster with:
    • One or multiple GPU VM(s) to host the harmony compute plane container(s).
    • One or multiple CPU VM(s) to host the control-plane and recipe-runner containers.
  2. A PostgreSQL database, that can be local or remote.
  3. A Redis data store, that can be local or remote.
  4. A shared storage, that can be local or remote, POSIX or S3-compliant.
  5. An OIDC client (Google Workspace, Azure Entra ID, Amazon Cognito, Keycloak, etc.).
  6. A domain name that routes to the Adaptive Engine deployment and serve both the UI and the API.
The PostgreSQL database, Redis data store and shared storage can be local or remote. For production, we recommend to host them on remote, durable services.
The system architecture section of the documentation explains the role of each component. The architecture observations provides comments and best practices.
To assist with setting up the infrastructure landing zone, Adaptive ML maintains optional Terraform infrastructure-as-code templates for Microsoft Azure and for AWS (available upon request).

​
Kubernetes & VM configuration

The Kubernetes environment must fit the following prerequisites:
  • Kubernetes version equal or above 1.28.
  • Helm 3.8.0 or higher.
  • NVIDIA GPU operator installed in Kubernetes.
  • CUDA greater or equal to 12.8 with driver greater or equal to 570.172.08.
Read more in the Helm chart’s README.

​
Deployment checklist

1

GPU quota verification

If deploying in the cloud, verify that your GPU quota are high enough to accommodate the desired instance type and count. If it is not, work with your cloud account team to get the quota approved.
2

Infrastructure provisioning

Deploy the above infrastructure landing zone.
3

Adaptive ML Docker image access

Obtain access to Adaptive Engine private container registry. This requires the signature of a commercial contract with Adaptive ML.
4

Set deployment details in Helm

Pull the chart from the GitHub OCI registry. Personalize the Helm values.yaml file as indicated in the Helm configuration highlights section below. The Helm values.yaml file centralizes key deployment configuration, including the infrastructure landing zone (storage, compute resources, domain name, OIDC configuration) and the Adaptive Engine cluster settings, notably permissions.
5

Deploy 🚀

Deploy Adaptive Engine using helm install
We recommend copying Adaptive Engine container images to your own registry to avoid production dependency on our registry.
Adaptive Engine administrator emails must be set in the administrator emails list before those users log in to Adaptive Engine. We strongly recommend to specify at least one administrator email in the administrator email list when launching a new cluster.

​
Helm configuration highlights

The values.yaml file contains all the configuration options for the Adaptive Engine Helm chart. Below are some of the key sections to be edited.

​
Container Registry Information

You will need to provide the details for the container registry where the Adaptive Engine images are stored. 
containerRegistry: <aws_account_id>.dkr.ecr.<region>.amazonaws.com
harmony:
  image:
    repository: adaptive-repository # Adaptive Repository you have been granted access to
    tag: harmony:latest # Harmony image tag

controlPlane:
  image:
    repository: adaptive-repository # Adaptive Repository you have been granted access to
    tag: control-plane:latest # Control plane image tag

​
Resource Limits

Adjust the resource limits based on your cluster’s capabilities and workload requirements. harmony.gpusPerNode should match the available GPU resources for each node in the cluster where Adaptive Harmony will be deployed. For example: 
harmony:
    replicaCount: 1
    # Should be equal to, or a divisor of the # of GPUs on each node
    gpusPerReplica: 8
    resources:
        limits:
            cpu: 8
            memory: 64Gi
        requests:
            cpu: 8
            memory: 60Gi

​
Configuration Secrets

The chart requires several secrets for configuration, such as S3 bucket URLs, database connection strings, and authentication provider details. You can set these directly in values.yaml or use an external secrets manager. 
secrets:
  # S3 bucket for model registry
  modelRegistryUrl: "s3://bucket-name/model_registry"
  # Use same bucket as above and can use a different prefix
  sharedDirectoryUrl: "s3://bucket-name/shared"

  # Postgres database connection string
  dbUrl: "postgres://username:password@db_address:5432/db_name"
  # Secret used to sign cookies. Must be the same on all servers of a cluster and >= 64 chars
  cookiesSecret: "change-me-secret-db40431e-c2fd-48a6-acd6-854232c2ed94-01dd4d01-dr7b-4315" # Must be >= 64 chars

  auth:
    oidc:
      providers:
        # Name of your OpenId provider displayed in the ui
        - name: "Google"
          # Key of your provider, the callback url will be '<rootUrl>/api/v1/auth/login/<key>/callback'
          key: "google"
          issuer_url: "https://accounts.google.com" # openid connect issuer url
          client_id: "replace_client_id" # client id
          client_secret: "replace_client_secret" # client_secret, optional
          scopes: ["email", "profile"] # scopes required for auth, requires email and profile
          # true if your provider supports pkce (recommended)
          pkce: true
          # if true, user account will be created if it does not exist
          allow_sign_up: true
If you set allow_sign_up: true, any member of your OIDC provider will be able to connect to Adaptive Engine. To restrict user access, set it to false and create users with SDK instead.
For information on using an external secrets manager, refer to the “Using External Secret Management” section in the helm chart’s README.