Skip to content

Docker Compose Service Specification

Docker Compose Service Specification Overview

Omnistrate extends the Docker Compose specification, which allows custom extensions using the syntax x-, and supports a subset of the standard specifications. Omnistrate leverages the standard spec and those extensions together to complete the spec for your SaaS. We will go over the extensions below in more detail.

Note

When using build-from-repo command, Omnistrate will automatically generate a docker compose file for you if one doesn't already exist in your project. This generated compose file will include the necessary configuration based on your container image and any environment variables you specify during the build process.

Docker Compose File Format

The Compose file is a YAML file defining:

  • Version (Optional)
  • Services (Required)
  • Networks
  • Volumes
  • Configs
  • Secrets

The default path for a Compose file is compose.yaml.

Omnistrate support Docker Compose 3.9 specification

  version: '3.9'

Basic Structure

services:
  web:
    image: nginx:latest
    ports:
      - "80:80"
    volumes:
      - ./html:/usr/share/nginx/html
    environment:
      - ENV_VAR=value

volumes:
  data:

networks:
  frontend:

Supported Native Tags

Here are the native tags Omnistrate supports either natively or with an optimized implementation:

image

Specifies the image to start the container from. The image must follow the Open Container Specification addressable image format, as [<registry>/][<project>/]<image>[:<tag>|@<digest>].

services:
  web:
    image: redis
    # or
    image: redis:5
    # or
    image: redis@sha256:0ed5d5928d4737458944eb604cc8509e245c3e19d02ad83935398bc4b991aac7
    # or
    image: my_private.registry:5000/redis

Native support for all public registries and private registries with credentials.

expose

Defines the (incoming) port or a range of ports that Compose exposes from the container. These ports must be accessible to linked services and should not be published to the host machine.

services:
  web:
    expose:
      - "3000"
      - "8000"
      - "8080-8085/tcp"

ports

Exposes container ports. Port mapping must not be used with network_mode: host.

Short syntax:

services:
  web:
    ports:
      - "3000"
      - "3000-3005"
      - "8000:8000"
      - "9090-9091:8080-8081"
      - "127.0.0.1:8001:8001"
      - "6060:6060/udp"

Long syntax:

services:
  web:
    ports:
      - name: web
        target: 80
        protocol: tcp

volumes

Define mount host paths or named volumes that are accessible by service containers.

Short syntax:

services:
  web:
    volumes:
      - /var/lib/mysql
      - /opt/data:/var/lib/mysql
      - ./cache:/tmp/cache
      - ~/configs:/etc/configs/:ro

Long syntax:

services:
  web:
    volumes:
      - type: volume
        source: mydata
        target: /data
        volume:
          nocopy: true
      - type: bind
        source: ./static
        target: /opt/app/static

environment

Defines environment variables set in the container. Environment variables can use either an array or a map.

Map syntax:

services:
  web:
    environment:
      RACK_ENV: development
      SHOW: "true"
      USER_INPUT:

Array syntax:

services:
  web:
    environment:
      - RACK_ENV=development
      - SHOW=true
      - USER_INPUT

env_file

Adds environment variables to the container based on the file content.

services:
  web:
    env_file: .env
    # or
    env_file:
      - ./a.env
      - ./b.env

Env file format: Each line in an .env file must be in VAR[=[VAL]] format. The following syntax rules apply:

  • Lines beginning with # are processed as comments and ignored
  • Blank lines are ignored
  • Values can optionally be quoted
  • Variable interpolation is supported using ${VARIABLE_NAME} syntax

Example .env file:

# Set Rails/Rack environment
RACK_ENV=development
VAR="quoted"
DB_HOST=${DB_HOST}

depends_on

Expresses startup and shutdown dependencies between services.

Short syntax:

services:
  web:
    depends_on:
      - db
      - redis
  redis:
    image: redis
  db:
    image: postgres

Long syntax:

services:
  web:
    depends_on:
      db:
        condition: service_healthy
        restart: true
      redis:
        condition: service_started

entrypoint

Declares the default entrypoint for the service container. This overrides the ENTRYPOINT instruction from the service's Dockerfile.

services:
  web:
    entrypoint: /code/entrypoint.sh
    # or
    entrypoint:
      - php
      - -d
      - zend_extension=/usr/local/lib/php/extensions/no-debug-non-zts-20100525/xdebug.so
      - -d
      - memory_limit=-1
      - vendor/bin/phpunit

command

Overrides the default command declared by the container image.

services:
  web:
    command: bundle exec thin -p 3000
    # or
    command: ["bundle", "exec", "thin", "-p", "3000"]

init

Runs an init process (PID 1) inside the container that forwards signals and reaps processes. Tag is ignored and supported through cluster_init action hooks, which runs as a job.

container_name / hostname

These tags are ignored. Omnistrate has a fully managed DNS service that doesn't require any explicit configuration to work.

networks

Networks tags are ignored as Omnistrate auto-configures network and ports as part of the tenancy model.

tmpfs

These tags are ignored. Omnistrate automatically mounts a temp file on /tmp folder.

logging

These tags are ignored. Omnistrate offers its own managed logging system as integration that can be enabled by adding the x-customer-integrations custom spec followed by the logs item. This tag is ignored and supported through x-customer-integrations.

healthcheck

These tags are ignored. Healthchecks are configured via x-omnistrate-action-hooks. Declares a check that's run to determine whether or not the service containers are "healthy". This tag is ignored and supported through x-omnistrate-action-hooks.

user

User definition is achieved via SECURITY_CONTEXT environment variables according to the UID and GID.

services:
  web:
    user: "1001"
    # or
    user: "1001:1001"

ulimits

Overrides the default ulimits for a container.

services:
  web:
    ulimits:
      nproc: 65535
      nofile:
        soft: 20000
        hard: 40000

cap_add / cap_drop

Specifies additional container capabilities or capabilities to drop.

services:
  web:
    cap_add:
      - ALL
    cap_drop:
      - NET_ADMIN
      - SYS_ADMIN

sysctls

These tags are ignored. Omnistrate sets up default configuration.

labels

Allows you to specify custom metadata for resources, such as custom resource names or descriptions.

services:
  web:
    labels:
      - "name=Your Resource Name"
      - "description=Your Resource Description"
    # or
    labels:
      com.example.description: "Accounting webapp"
      com.example.department: "Finance"

platform

Defines the target platform the containers for the service run on. It uses the os[/arch[/variant]] syntax. 

services:
  web:
    platform: linux/amd64
    # or
    platform: linux/arm64

The supported values by Omnistrate are linux/amd64 and linux/arm64. It is only used when an instance type is not explicitly defined.

deploy

Specifies the configuration for the deployment and lifecycle of services. This includes resource constraints and requirements.

services:
  web:
    deploy:
      resources:
        limits:
          cpus: '1000m'
          memory: 256M
        reservations:
          cpus: '100m'
          memory: 100M

Resource configuration:

  • limits: Define the maximum resources the container can use
  • cpus: Maximum CPU allocation (can be specified as decimal or with 'm' suffix for millicores)
  • memory: Maximum memory allocation (supports units like M, G)
  • reservations: Define the minimum resources guaranteed to the container
  • cpus: Minimum CPU allocation
  • memory: Minimum memory allocation

privileged

Configures the service container to run with elevated privileges. Support and actual impacts are platform specific.

services:
  web:
    privileged: true

Custom Tags

In addition, Omnistrate also supports several custom tags as follows.

x-omnistrate-service-plan

x-omnistrate-service-plan allows you to configure the Plan for your SaaS in the compose specification file.

x-omnistrate-service-plan:
  name: 'Mysql Free Tier'
  tenancyType: 'OMNISTRATE_DEDICATED_TENANCY'
  features:
    CUSTOM_NETWORKS:
    CUSTOM_DEPLOYMENT_CELL_PLACEMENT:
      maximumDeploymentsPerCell: 1
  deployment:
    hostedDeployment:
      awsAccountId: "<AWS_ACCOUNT_ID>"
      awsBootstrapRoleAccountArn: arn:aws:iam::<AWS_ACCOUNT_ID>:role/omnistrate-bootstrap-role
      gcpProjectId: "<GCP_INFO>"
      gcpProjectNumber: "<GCP_INFO>"
      gcpServiceAccountEmail: "<GCP_INFO>"
      azureSubscriptionId: '<AZURE_INFO>'
      azureTenantId: '<AZURE_INFO>'

Configuration fields:

  • name: The name of the Plan
  • tenancyType: The tenancy type
  • deployment: The deployment type of the Plan. Options:
  • hostedDeployment: The deployed instances of the plan is deployed on your account
  • byoaDeployment: The deployed instances of the plan is deployed on your customer's account
  • Omitted: Omnistrate will host the deployed instances for you

x-omnistrate-service-plan.name

Name of the service plan for your service.

x-omnistrate-service-plan:
  name: 'Service Plan Name'

x-omnistrate-service-plan.tenancyType

Define the tenancy type for your service:

x-omnistrate-service-plan:
  tenancyType: 'OMNISTRATE_DEDICATED_TENANCY'

tenancyType: The tenancy type of the Plan. Options:

  • OMNISTRATE_DEDICATED_TENANCY: Infrastructure dedicated to a single customer deployment
  • OMNISTRATE_MULTI_TENANCY: Infrastructure shared among multiple customers and deployments
  • CUSTOM_TENANCY: Not valid for compose specification, only used by Plan Specification.

x-omnistrate-service-plan.deployment.hostedDeployment

Configure the accounts for your hosted service Plan.

x-omnistrate-service-plan:
  deployment:
    hostedDeployment:
    byoaDeployment:
      awsAccountId: "<AWS_ACCOUNT_ID>"
      awsBootstrapRoleAccountArn: arn:aws:iam::<AWS_ACCOUNT_ID>:role/omnistrate-bootstrap-role
      gcpProjectId: "<GCP_INFO>"
      gcpProjectNumber: "<GCP_INFO>"
      gcpServiceAccountEmail: "<GCP_INFO>"
      azureSubscriptionId: '<AZURE_INFO>'
      azureTenantId: '<AZURE_INFO>'

x-omnistrate-service-plan.deployment.byoaDeployment

Configure the intermediate account for your control plane that will act as provisioner for the services running on your customer accounts (BYOC). Customers will provide the configured account permissions to manage their services.

x-omnistrate-service-plan:
  deployment:
    byoaDeployment:
      awsAccountId: "<AWS_ACCOUNT_ID>"
      awsBootstrapRoleAccountArn: arn:aws:iam::<AWS_ACCOUNT_ID>:role/omnistrate-bootstrap-role

x-omnistrate-service-plan.deployment.onPremCopilotDeployment

Configure the intermediate account for your control plane that will act as a provisioner for the services running on your customer accounts using BYOC Copilot mode. Customers will provide the configured account permissions to manage their services.

x-omnistrate-service-plan:
  deployment:
    onPremCopilotDeployment:
      awsAccountId: "<AWS_ACCOUNT_ID>"
      awsBootstrapRoleAccountArn: arn:aws:iam::<AWS_ACCOUNT_ID>:role/omnistrate-bootstrap-role

x-omnistrate-service-plan.features.CUSTOM_DEPLOYMENT_CELL_PLACEMENT

The CUSTOM_DEPLOYMENT_CELL_PLACEMENT feature allows you to control how many deployments can be co-located on the same host cluster (deployment cell / Kubernetes cluster). This provides fine-grained control over deployment isolation and resource allocation.

x-omnistrate-service-plan:
  name: 'PostgreSQL Service'
  features:
    CUSTOM_DEPLOYMENT_CELL_PLACEMENT:
      maximumDeploymentsPerCell: 1

x-omnistrate-service-plan.features.CUSTOM_NETWORKS

The CUSTOM_NETWORKS feature allows your customers to define network partitioning on a dedicated stack while keeping the service deployed in the Service Provider Account. This provides complete isolation by provisioning a dedicated stack that is not shared with other customers, enabling private network connectivity while maintaining self-service capabilities.

x-omnistrate-service-plan:
  name: 'PostgreSQL Service'
  features:
    CUSTOM_NETWORKS:

Note: For deployment, replace the account numbers, project id and other information with your own account information.

x-omnistrate-my-account (deprecated)

x-omnistrate-my-account is deprecated allows you to configure your cloud provider account details for hosted deployments. Use x-omnistrate-service-plan.deployment.hostedDeployment tag to configure your cloud account.

x-omnistrate-byoa (deprecated)

x-omnistrate-byoa is deprecated allows you to configure your cloud provider account details for hosted deployments. Use x-omnistrate-service-plan.deployment.byoaDeployment tag to configure your cloud account.

x-omnistrate-mode-internal

x-omnistrate-mode-internal tag allows you to tag any Resource in the compose specification as internal.

services:
  internal-service:
    image: my-internal-service
    x-omnistrate-mode-internal: true
  • Possible values are true or false
  • Default value is false
  • If set to true, this Resource will be internal and won't be exposed to your customers
  • If set to false, the Resource will be exposed to your customers to configure and provision them

x-omnistrate-api-params

x-omnistrate-api-params allows you to define API params in addition to environment variables.

services:
  database:
    image: postgres
    x-omnistrate-api-params:
      - key: writerInstanceType
        description: Writer Instance Type
        name: Writer Instance Type
        type: String
        modifiable: true
        required: true
        export: true

Each API parameter can be configured to specify:

  • key: Unique identifier for the parameter
  • name: Display name of the parameter
  • description: Description for the parameter
  • type: Type of the parameter (String, Float64, Boolean, etc.)
  • required: Specify if this field is a required parameter
  • export: Configures if this field will be returned as part of the describe call
  • modifiable: Configure if this field is modifiable once configured
  • defaultValue: Default value for this field
  • options: List of options for the user to choose from
  • labeledOptions: List of options with user-friendly labels
  • limits: Minimum and maximum values for this field
  • regex: Regex pattern to validate the input

Example with options:

x-omnistrate-api-params:
  - key: writerInstanceType
    description: Writer Instance Type
    name: Writer Instance Type
    type: String
    modifiable: true
    required: true
    export: true
    options:
      - t4g.small
      - t4g.medium
      - t4g.large

Example with labeled options:

x-omnistrate-api-params:
  - key: writerInstanceType
    description: Writer Instance Type
    name: Writer Instance Type
    type: String
    modifiable: true
    required: true
    export: true
    labeledOptions:
      Small: t4g.small
      Medium: t4g.medium
      Large: t4g.large

Example with limits:

x-omnistrate-api-params:
  - key: postgresqlRootPassword
    description: Postgresql Root Password
    name: Postgresql Root Password
    type: String
    modifiable: true
    required: true
    export: true
    limits:
      minLength: 8
      maxLength: 64
  - key: postgresqlPort
    description: Postgresql Port
    name: Postgresql Port
    type: Float64
    modifiable: true
    required: true
    export: true
    limits:
      min: 1024
      max: 65535

Example with default value:

x-omnistrate-api-params:
  - key: postgresqlUsername
    description: Postgresql Username
    name: Postgresql Username
    type: String
    modifiable: true
    required: true
    export: true
    defaultValue: postgres

Example with regex validation:

x-omnistrate-api-params:
  - key: postgresqlPassword
    description: Default DB Password
    name: Password
    type: String
    modifiable: false
    required: true
    export: false
    regex: ^[a-zA-Z0-9!@#$%^&*()_+]{8,32}$

API Parameter Types:

The valid parameter types are:

  • boolean: A true or false value
  • string: A sequence of characters
  • password: A sensitive string for passwords, stored securely and masked in outputs
  • float64: A 64-bit floating-point number
  • bytes: A sequence of bytes
  • json: A JSON formatted string
  • any: Any of the supported types
  • resource: Used for resource linking to enforce creating a linked resource before creating a parent resource

An API parameter of resource type can be used to link any resource with another resource to enforce creating a linked resource before creating a parent resource.

services:
  Proxy:
    image: omnistrate/pgadmin4:7.5
    x-omnistrate-api-params:
      - key: database
        description: backend database
        name: database
        type: Resource
        export: false
        required: true
        modifiable: false
  Database:
    image: 'bitnami/postgresql:latest'

In this example, customers must create a Database instance first, then create a Proxy instance by specifying which Database instance to link to.

You can map API parameters between dependent resources:

services:
  Cluster:
    image: omnistrate/noop
    depends_on:
      - Writer
      - Reader
    x-omnistrate-api-params:
      - key: instanceType
        description: Instance Type
        name: Instance Type
        type: String
        modifiable: true
        required: true
        export: true
        defaultValue: t4g.small
        parameterDependencyMap:
          Writer: writerInstanceType
          Reader: readerInstanceType

This maps the instanceType parameter of the Cluster resource to writerInstanceType of the Writer resource and readerInstanceType of the Reader resource.

Note: All environment variables are automatically added as API parameters if x-omnistrate-api-params is not specified.

x-omnistrate-actionhooks

x-omnistrate-actionhooks allows you to configure action hooks for a given Resource.

services:
  database:
    image: postgres
    x-omnistrate-actionhooks:
      - scope: CLUSTER
        type: INIT
        commandTemplate: >
          PGPASSWORD={{ $var.postgresqlRootPassword }} psql -U postgres
          -h writer {{ $var.postgresqlDatabase }} -c "create extension vector"

Action hooks allow you to inject custom code at different phases of the lifecycle of your control plane operations. In the above example, we are enabling vector extension for Postgres on cluster initialization.

Action hooks are categorized into two scopes:

Node Scope - runs for every node of the Resource:

  • HEALTH_CHECK: Periodic health checks mapped to Kubernetes liveness probes
  • READINESS_CHECK: Determines service readiness for traffic (defaults to HEALTH_CHECK)
  • STARTUP_CHECK: Ensures service startup completion (defaults to HEALTH_CHECK)
  • POST_START: Executes after node starts
  • ADD: Triggers when a new node is added
  • REMOVE: Triggers when a node is removed
  • INIT: Runs initialization before node starts
  • PROMOTE: Triggers when a node is promoted to primary role
  • DEMOTE: Triggers when a node is demoted before replacement

Cluster Scope - runs for the entire Resource:

  • POST_START: Executes after all nodes have started
  • PRE_START: Runs before all nodes are started
  • POST_STOP: Executes after all nodes are stopped
  • PRE_STOP: Runs before all nodes are stopped
  • POST_UPGRADE: Executes after all nodes are upgraded
  • PRE_UPGRADE: Runs before all nodes are upgraded
  • INIT: Runs initialization before all nodes are started

Action hooks support additional configuration options:

services:
  high-performance-db:
    image: postgres:15
    x-omnistrate-actionhooks:
      - image: busybox:1.37
        scope: NODE
        type: INIT
        command:
          - /bin/sh
          - -c
        commandTemplate: |
          # Set the AIO max number of events
          sysctl -w fs.aio-max-nr='102052'

Configuration fields:

  • image: Custom container image for the action hook
  • command: Command array to execute
  • commandTemplate: Template for the command with variable interpolation
  • scope: NODE or CLUSTER
  • type: Action hook type as listed above

x-omnistrate-compute

x-omnistrate-compute allows you to customize the compute parameters of a Resource.

You can customize the following:

  • Number of replicas
  • Instance type across cloud providers
  • Size of the root volume (GiB) across instances
services:
  web:
    image: nginx
    x-omnistrate-compute:
      replicaCountAPIParam: numReplicas
      instanceTypes:
        - cloudProvider: aws
          name: t4g.small
        - cloudProvider: gcp
          name: e2-medium
        - cloudProvider: azure
          name: Standard_B2als_v2
      rootVolumeSizeGi: 10

In the above example, replicaCountAPIParam is configured dynamically using numReplicas parameter. The users of your service can decide how many replicas they want. Similarly, instanceTypes can also be dynamic if you want your customers to specify the machine type among the list of options. For rootVolumeSizeGi, you can specify any integer between 10 and 16384 (up to 16 TB).

x-omnistrate-compute.instanceTypes.configurationOverrides.acceleratorConfiguration

GPU accelerator configuration enables you to specify dedicated GPU resources and is only required to attach for some instance types on GCP.

  1. External GPU attachment using acceleratorConfiguration (N1 instances + Tesla GPUs only)
  2. Built-in GPU instances (G2, A2, A3, A4 families with modern GPUs)

The acceleratorConfiguration feature allows declarative specification of GPU accelerators attached to compute instances on GCP.

Warning: External GPU attachment is only supported with N1 instances and Tesla series GPUs (T4, V100, P100, P4) on GCP

Configuration in x-omnistrate-compute:

services:
  gpu-service:
    image: tensorflow/tensorflow:latest-gpu
    x-omnistrate-compute:
      instanceTypes:
        - name: n1-standard-8
          cloudProvider: gcp
          configurationOverrides:
            acceleratorConfiguration:   
              type: "nvidia-tesla-t4"
              count: 1

Multi-GPU Configuration:

services:
  gpu-cluster:
    image: pytorch/pytorch:latest
    x-omnistrate-compute:
      instanceTypes:
        - name: n1-standard-16
          cloudProvider: gcp
          configurationOverrides:
            acceleratorConfiguration:   
              type: "nvidia-tesla-t4"
              count: 4

For AWS, Azure and modern GPUs in GCP (L4, A100, H100) , instance families come with GPUs mounted:

G2 Family - NVIDIA L4 GPUs:

services:
  modern-gpu-service:
    image: nvidia/cuda:12.0-runtime-ubuntu20.04
    x-omnistrate-compute:
      instanceTypes:
        - name: g2-standard-8
          cloudProvider: gcp
          # No acceleratorConfiguration needed - L4 GPU is built-in

x-omnistrate-storage

To define a persistent volumes that can survive service restarts and nodes replacements you can use x-omnistrate-storage tag.

You can optionally define the volume:

volumes:
  pg_master_data:
    driver: local

services:
  database:
    image: postgres
    volumes:
      - source: pg_master_data
        target: /var/lib/postgresql/data
        type: volume
        x-omnistrate-storage:
          aws:
            instanceStorageType: AWS::EBS_GP3
            instanceStorageSizeGi: 10
            instanceStorageIOPS: 3000
            instanceStorageThroughputMiBps: 125
          gcp:
            instanceStorageType: GCP::PD_BALANCED
            instanceStorageSizeGi: 100
          azure:
            instanceStorageType: AZURE::PREMIUM_SSD
            instanceStorageSizeGi: 100

x-omnistrate-storage allows you to customize the storage parameters of a Resource.

You can customize the following:

  • Storage type from block device to blobs or both
  • Size of the volume
  • Storage IOPS
  • Storage throughput

Note

This type of persistent volume are not shared across Resources. If you need to share the volume data across resources look a at configuring Shared File System or Blob Storage instead.

volumes.driver: sharedFileSystem

Shared file systems allow you to save data in a persistent volume and share it across different pods within the same deployment cluster. This is ideal for scenarios like AI model training where multiple workers need access to the same dataset, or when you need to scale storage dynamically without downtime.

Define shared file system using volumes in your compose specification:

volumes:
  file_system_data:
    driver: sharedFileSystem
    driver_opts:
      # efs configuration
      efsThroughputMode: provisioned
      efsPerformanceMode: generalPurpose
      efsProvisionedThroughputInMibps: 100
      # filestore configuration
      filestoreCapacity: "1TiB"
      filestoreTier: "BASIC_HDD"

services:
  database:
    image: postgres
    volumes:
    volumes:
      - source: file_system_data
        target: /var/lib/redis/data
        type: volume
        x-omnistrate-storage:
          aws:
            clusterStorageType: AWS::EFS
      - source: file_system_data
        target: /var/lib/postgresql/data
        type: volume
        x-omnistrate-storage:
          aws:
            clusterStorageType: AWS::EFS
          gcp: 
            clusterStorageType: GCP::FILESTORE
          azure: 
            clusterStorageType: AZURE::FILE_STORAGE

Configuration options:

  • driver: Must be set to sharedFileSystem to enable Omnistrate shared file system
  • driver_opts: Customize the shared file system behavior
  • efsThroughputMode: EFS Throughput mode (provisioned, bursting)
  • efsPerformanceMode: EFS Performance mode (generalPurpose, maxIO)
  • efsProvisionedThroughputInMibps: EFS Provisioned throughput in MiB/s (when using provisioned mode)
  • filestoreCapacity: Filestore capacity in Tib or Gib
  • filestoreTier: Filestore tier
  • filestoreMaxIopsPerTb: Filestore throughput per Tb

Mount configuration:

  • source: Name of the volume defined in the volumes section
  • target: Path where you want to mount the volume in the container
  • type: Must be set to volume
  • x-omnistrate-storage: Storage configuration with clusterStorageType: AWS::EFS, clusterStorageType: GCP::FILESTORE, and clusterStorageType: AZURE::FILE_STORAGE for each cloud provider.

volumes.driver: blob

Blob storage allows you to define blob storage buckets and their mount paths across Resources. Omnistrate manages the lifecycle of storage volumes (creation and deletion with instance) and mounts them as local volumes.

Note: Blob storage is not available for the Omnistrate hosted model.

Define blob storage in the compose specification:

volumes:
  bucket_data:
    driver: blob
services:
  app:
    image: myapp
    volumes:
      - source: bucket_data
        target: /mnt/blob-data
        type: volume
        x-omnistrate-storage:
          aws:
            clusterStorageType: AWS::S3
          gcp:
            clusterStorageType: GCP::GCS
          azure:
            clusterStorageType: AZURE::BLOB_STORAGE

Mount configuration:

  • bucket_data is the name of the volume, you can opt for a name of your choice.
  • driver: blob is the driver type required to enable using Blob storage.
  • x-omnistrate-storage defines the type of storage for each cloud provider.

This configuration will provision a new Blob storage (bucket/container) for each instance deployed. On the pod itself, it will appear just like any other volume. The underlying storage driver does not restrict or synchronize access, so your application itself needs to make sure it doesn't end up overriding data.

x-omnistrate-capabilities

x-omnistrate-capabilities allows you to add capabilities to your Resources.

services:
  web:
    image: nginx
    x-omnistrate-capabilities:
      httpReverseProxy:
        targetPort: 80
      enableMultiZone: true
      enableEndpointPerReplica: true
      customDNS:
        targetPort: 80
      autoscaling:
        maxReplicas: 1
        minReplicas: 1
      serverlessConfiguration:
        enableAutoStop: true
        minimumNodesInPool: 5
        targetPort: 3306

Supported capabilities are custom DNS, custom sidecars, stable egress ip, process core dump, service account policies, backup configuration, autoscaling, serverless configuration.

x-omnistrate-capabilities.customDNS

The customDNS capability enables endpoint aliases for your Resources, allowing users to assign specific aliases to deployment or resource instance endpoints. This provides enhanced branding, customization, and control over infrastructure.

services:
  web:
    image: nginx
    x-omnistrate-capabilities:
      customDNS:
        targetPort: 80

Configuration fields:

  • targetPort: The port number where your HTTP service is listening

x-omnistrate-capabilities.sidecars

The sidecars capability allows you to enhance your SaaS product's functionality without changing its core service. Sidecars are add-on containers that run alongside your main application container, providing additional features or capabilities while maintaining isolation from the main application.

services:
  web:
    image: nginx
    x-omnistrate-capabilities:
      sidecars:
        tooling:
          imageNameWithTag: "busybox:stable"
        monitoring:
          imageNameWithTag: "prometheus/node-exporter:latest"
          securityContext:
            runAsUser: 10
            runAsGroup: 99
            runAsNonRoot: true
            capabilities:
              add:
                - SYS_RESOURCE
          resourceLimits:
            cpu: "250m"
            memory: "256Mi"
          command:
            - "/bin/node_exporter"
          args:
            - "--path.rootfs=/host"
            - "--collector.filesystem.ignored-mount-points"

Configuration fields:

  • imageNameWithTag: Container image with tag for the sidecar (required)
  • securityContext: Security context configuration for the sidecar
  • runAsUser: User ID to run the container
  • runAsGroup: Group ID to run the container
  • runAsNonRoot: Whether to run as non-root user
  • capabilities: Linux capabilities to add or drop
  • resourceLimits: Resource constraints for the sidecar
  • cpu: CPU limit (e.g., "250m" for 250 millicores)
  • memory: Memory limit (e.g., "256Mi" for 256 MiB)
  • command: Entry point command for the sidecar container
  • args: Arguments to pass to the command

x-omnistrate-capabilities.stableEgressIP

The stableEgressIP capability provides a stable egress IP address for outbound traffic from your Resources. This is useful when you need to whitelist your service's IP address with external services or APIs.

services:
  web:
    image: nginx
    x-omnistrate-capabilities:
      stableEgressIP: true

x-omnistrate-capabilities.processCoreDump

The processCoreDump capability enables process core dump collection for debugging application crashes and analyzing process failures.

services:
  database:
    image: postgres
    x-omnistrate-capabilities:
      processCoreDump: /var/lib/data/cores/core.%e.%p.%t

Configuration:

  • Specify the path where core dumps should be stored
  • Use format specifiers for core dump file naming:
  • %e: Executable name
  • %p: Process ID
  • %t: Timestamp

x-omnistrate-capabilities.serviceAccountPolicies

The serviceAccountPolicies capability enables your application to securely access cloud-native services by configuring appropriate service account permissions.

services:
  app:
    image: myapp
    x-omnistrate-capabilities:
      serviceAccountPolicies:
        aws:
          - MSK_CONNECT
          - SECRETS_MANAGER
          - LAMBDA
          - SQS
        gcp:
          - WORKLOAD_IDENTITY_IAM_BINDING

AWS Policies:

  • MSK_CONNECT: Enables AWS MSK Connect access
  • SECRETS_MANAGER: Enables AWS Secrets Manager access
  • LAMBDA: Enables AWS Lambda access (including Serverless framework permissions)
  • SQS: Enables Amazon SQS access

GCP Policies:

  • WORKLOAD_IDENTITY_IAM_BINDING: Binds resource workload identity to IAM service account, granting additional GCP permissions (Logs, Metrics, Secrets)

x-omnistrate-capabilities.backupConfiguration

The backupConfiguration capability enables automatic backup and point-in-time restore for your Resources, providing data protection and recovery capabilities.

services:
  database:
    image: postgres
    x-omnistrate-capabilities:
      backupConfiguration:
        backupRetentionInDays: 7
        backupPeriodInHours: 2

Configuration fields:

  • backupRetentionInDays: Number of days to retain backups
  • backupPeriodInHours: Frequency of backup creation in hours

Storage Volume Backup Control: You can disable backups for specific storage volumes by adding disableBackup: true in the volume configuration:

services:
  database:
    image: postgres
    volumes:
      - source: temp_data
        target: /tmp/data
        type: volume
        x-omnistrate-storage:
          aws:
            instanceStorageType: AWS::EBS_GP2
            instanceStorageSizeGi: 50
            disableBackup: true

Note: Backup capability is only available for Tenant-Aware Resources and applies to AWS EBS, GCP Persistent Disk, and Azure Disk storage types. When backup retention is updated, changes only apply to new backups.

x-omnistrate-capabilities.autoscaling

For autoscaling based on custom application metrics instead of default CPU/memory metrics:

x-omnistrate-capabilities:
  autoscaling:
    scalingMetric:
      metricEndpoint: "http://localhost:9187/metrics"
      metricLabelName: "application_name"
      metricLabelValue: "psql"
      metricName: "pg_stat_activity_count"

x-omnistrate-capabilities.serverlessConfiguration

For complex serverless scenarios requiring custom metrics, session state preservation, or proxy configuration control, you can use advanced serverless mode:

x-omnistrate-capabilities:
  autoscaling:
    maxReplicas: 5
    minReplicas: 1
    idleMinutesBeforeScalingDown: 2
    idleThreshold: 20
    overUtilizedMinutesBeforeScalingUp: 3
    overUtilizedThreshold: 80
  serverlessConfiguration:
    targetPort: 3306
    enableAutoStop: true
    minimumNodesInPool: 5

x-omnistrate-load-balancer

x-omnistrate-load-balancer allows you to configure a load balancer for your Resources in the compose specification file adding L7-L4 capabilities.

Adding L7 load balancing capabilities to your Resources allows to route traffic based on the URL path, while L4 routes traffic based on the port number.

version: '3.9'

x-omnistrate-load-balancer:
  https:
    - name: PGAdmin
      description: L7 Load Balancer for PGAdmin - New
      paths:
        - associatedResourceKey: admin
          path: /
          backendPort: 80

  tcp:
    - name: Writer
      description: L4 Load Balancer for Writer
      ports:
        - associatedResourceKeys:
            - writer
          ingressPort: 5432
          backendPort: 5432

services:
  admin:
    image: dpage/pgadmin4

  writer:
    image: postgres

  reader:
    image: postgres

x-omnistrate-job-config

x-omnistrate-job-config allows you to configure a Resource as a job that runs one time during create, update, or modification operations of a deployment.

When a Resource is configured with job settings, it will execute once during the deployment lifecycle and complete its task. This is useful for initialization scripts, data migrations, setup tasks, or any one-time operations.

services:
  hello-world:
    build:
      context: ./jobs/hello-world
      dockerfile: Dockerfile
    environment:
      RAY_ADDRESS: "ray://{{ $var.rayClusterAddress }}:10001"
      SCRIPT_PATH: "submit_job.py"
    deploy:
      resources:
        reservations:
          cpus: "0.1"
          memory: 256M
        limits:
          cpus: "0.5"
          memory: 1G
    privileged: true
    platform: linux/amd64
    volumes:
      - source: ./jobs/hello-world
        target: /app
        type: bind
      - source: ./tmp
        target: /tmp
        type: bind
    x-omnistrate-compute:
      replicaCountApiParam: numReplicas
    x-omnistrate-job-config:
      backoffLimit: 0
      activeDeadlineSeconds: 3600

Job-specific configurations:

  • backoffLimit: Number of retries before considering the job as failed (set to 0 to disable retries)
  • activeDeadlineSeconds: Maximum duration (in seconds) the job is allowed to run before termination

Note: Jobs are designed to run to completion and then terminate. They are not meant for long-running services.

x-omnistrate-image-registry-attribute

x-omnistrate-image-registry-attributes allows you to configure image registries.

x-omnistrate-image-registry-attributes:
  docker.io:
    auth:
      username: username
      password: password

Note: For private image registries, username and password are required. Images will only be downloaded in your account (hosted mode) or in your customers' account (BYOA mode).

x-omnistrate-integrations (deprecated)

x-omnistrate-integrations allows you to add integrations to your service. This tag is deprecated, use x-customer-integrations.

x-customer-integrations

x-customer-integrations allows you to configure customer-specific integrations such as licensing, logs, and metrics.

x-customer-integrations:
  logs:
  metrics:

x-customer-integrations.licensing

The licensing protection system ensures that only authorized subscribed users can access and use your software. This is particularly important for BYOA/BYOC deployments and on-premises installations.

x-customer-integrations:
  licensing: 
    licenseExpirationInDays: 7
    productPlanUniqueIdentifier: 'PRODUCT-SAMPLE-SKU-UNIQUE-VALUE'

Configuration fields:

  • licensing: Configure licensing integration
  • licenseExpirationInDays: Number of days before license expires (default: 7 days)
  • productPlanUniqueIdentifier: Unique identifier for the product plan SKU (optional, defaults to product tier ID)

x-customer-integrations.logs

The following configuration enables collecting and exposing logs using an Omnistrate managed Prometheus server. 

x-customer-integrations:
  logs:
  metrics:

You can choose to use a different provider to publish the logs to.

When using BYOC (Bring Your Own Cloud) provider: native integrates with the cloud provider's native observability platform (CloudWatch for AWS, Operations Suite for GCP, Application Insights for Azure). End customers can visualize the logs on their own account.

x-customer-integrations:
  logs:
    provider: native 
  metrics:
    provider: native

x-customer-integrations.metrics

The following configuration enables collecting and exposing metrics using an Omnistrate managed Prometheus server.

x-customer-integrations:
  logs:
  metrics:

You can choose to a different providers to publish the customer visible metrics.

When using BYOC (Bring Your Own Cloud) provider: native integrates with the cloud provider's native observability platform (CloudWatch for AWS, Operations Suite for GCP, Application Insights for Azure). End customers can visualize the metrics on their own account.

x-customer-integrations:
  logs:
    provider: native 
  metrics:
    provider: native

x-internal-integrations

x-internal-integrations allows you to configure internal integrations that are not exposed to customers.

x-internal-integrations:
  logs:
  metrics:
    additionalMetrics:
      postgres:
        prometheusEndpoint: "http://localhost:9187/metrics"
        metrics:
          pg_settings_enable_sort: # shared with customer
          pg_settings_autovacuum: # internal only metric

This extension allows you to define metrics and other integrations that are only visible internally and not exposed to your customers.

Internal Observability Options

Omnistrate Native:

  • logs: Enable real-time logging for your support team to manage the customer fleet
  • metrics: Enable real-time infrastructure metrics dashboard

OpenTelemetry Providers: You can ship metrics and logs to third-party providers like NewRelic, Signoz, or Datadog:

x-internal-integrations:
  metrics:
    provider: newRelic  # or signoz, datadog
    endpoint: https://otlp.nr-data.net
    secretLocators:
      aws: arn:aws:secretsmanager:us-west-2:xxxxxxxxxxx:secret:mySecret123456-abc123
      gcp: projects/xxxxxxxxxxx/secrets/mySecret123456-abc123/versions/latest
      azure: KeyVaultName/SecretName
    serviceComponentsConfiguration:
      postgres:
        prometheusEndpoint: "http://localhost:9187/metrics"
  logs:
    provider: newRelic
    endpoint: https://otlp.nr-data.net
    secretLocators:
      aws: arn:aws:secretsmanager:us-west-2:xxxxxxxxxxx:secret:mySecret123456-abc123

Cloud Native: Enable integration with cloud provider's native observability platform:

x-internal-integrations:
  logs:
    provider: native 
  metrics:
    provider: native

Custom Metrics Configuration

For additional application metrics, you can specify custom metrics with aggregation functions and label filters:

x-internal-integrations:
  metrics:
    additionalMetrics:
      postgres:
        prometheusEndpoint: "http://localhost:9187/metrics"
        metrics:
          pg_stat_activity_count:
            average_active_activity:
              aggregationFunction: avg
              labelFilters:
                state: active
            max_postgres_activity:
              aggregationFunction: max
              labelFilters:
                datname: postgres

Supported aggregation functions: sum, avg, max, min

x-internal-integrations.multiTenantGpu

GPU slicing enables multiple workloads to efficiently share GPU resources, maximizing utilization and reducing costs. Omnistrate supports both NVIDIA time-slicing and Multi-Instance GPU (MIG) technologies.

Enable GPU slicing using the x-internal-integrations extension:

x-internal-integrations: 
  multiTenantGpu: 
    instanceType: g4dn.xlarge
    timeSlicingReplicas: 2
    migProfile: 1g.5gb  # optional: for MIG-capable GPUs

Configuration parameters:

  • instanceType: GPU-enabled EC2 instance type (g4dn.xlarge, p3.2xlarge, p4d.24xlarge, etc.)
  • timeSlicingReplicas: Number of virtual GPU replicas (2, 4, 8, etc.)
  • migProfile: MIG profile for A100/H100 GPUs (optional)

Variable Interpolation and System Parameters

API Parameters

Access API parameters defined in x-omnistrate-api-params using $var.<parameter-key>:

services:
  database:
    image: postgres
    environment:
      - POSTGRES_PASSWORD=$var.postgresqlPassword
      - POSTGRES_DATABASE=$var.postgresqlDatabase
      - POSTGRES_USERNAME=$var.postgresqlUsername
    x-omnistrate-api-params:
      - key: postgresqlPassword
        type: String
        required: true
      - key: postgresqlDatabase
        type: String
        required: true
      - key: postgresqlUsername
        type: String
        required: true

Omnistrate System Parameters

Omnistrate provides system parameters that are replaced with actual values at runtime using the format $sys.<variable-name>. These parameters provide contextual information about the deployment environment.

Note: All variables are substituted with their original data type. If you want to use a variable as a string, wrap it in escaped quotes: \"$sys.deploymentCell.region\".

Fragments

You can use built-in YAML features to make your Compose file neater and more efficient.

Anchors and Aliases

Anchors are created using the & sign, and aliases use the * sign:

x-common-variables: &common-variables
  POSTGRES_DB: myapp
  POSTGRES_USER: postgres

services:
  db:
    image: postgres
    environment:
      <<: *common-variables
      POSTGRES_PASSWORD: secret

  backup:
    image: postgres
    environment: *common-variables