Skip to content

Compose specification

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.

Here is a list of the supported and unsupported specifications, to better understand what you can and cannot specify via docker-compose on the Omnistrate platform and what you can expect to be supported in the future.

Supported compose tags

This is a list of specs supported in the compose specification, including native and custom tags.

Native tags

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

  • image - native support for all public registries and private registries with credentials
  • expose - native support for exposing ports
  • ports - native support for port mapping
  • volumes - native support for volumes and volume mapping, configuration, and management
  • environment - native support for environment variables
  • depends_on - native support for service dependencies
  • entrypoint - native support for entrypoint scripts
  • commands - native support for commands
  • init - tag is ignored and supported through cluster_init action hooks, which runs as a job.
  • container_name and hostname - tags are ignored, Omnistrate has a fully managed DNS service that doesn't require any explicit configuration to work.
  • network and port mapping host:container - tag is ignored as Omnistrate auto-configures network and ports as part of the tenancy model.
  • tmpfs - Omnistrate already creates a default tmpfs volume
  • logging - Omnistrate offers its own managed logging system as integration that can be enabled by adding the x-omnistrate-integrations custom spec followed by the omnistrateLogging item
  • read only volumes - currently ignored
  • healthcheck - achieved via x-omnistrate-action-hooks
  • user definition - achieved via SECURITY_CONTEXT environment variables according to the UID and GID.
  • Shared volumes (efs) - currently mapping the volume to the container path
  • ulimits
  • Capabilities
  • Sysctl

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

Custom Tags

x-omnistrate-mode-internal

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

Here is an example:

x-omnistrate-mode-internal: true
  • Possible values are true or false.
  • Default value is false
  • If set to true, this service component will be internal and won't be exposed to your customers.
  • If set to false, the service component 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.

Here is an example:

x-omnistrate-api-params:
  - key: writerInstanceType
    description: Writer Instance Type
    name: Writer Instance Type
    type: String
    modifiable: true
    required: true
    export: true
  • It contains collection of API parameters
  • Each API parameter can be configured to specify the name, description, type and a few other properties.
    • Required: specify if this field is a required parameter for the user of this SaaS service
    • Export: configures if this field will be returned as part of the describe call on this component to your users
    • Modifiable: configure if this field is modifiable once configured
    • Default Value: allows you to specify a default value for this field
    • Options: allows you to specify a list of options for the user to choose from for this field
    • Labeled Options: allows you to specify a list of options for the user to choose from for this field with a label
    • Limits: allows you to specify the minimum and maximum values for this field

Here is an example that defines a parameter with options to choose from:

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

Alternatively, you can label each option with a more user-friendly name:

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

In addition, you can configure limits for a parameter. Here's an example for a DB password parameter (string) and a DB port parameter (integer):

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

You can also define a default value for a parameter. Here's an example for a DB username parameter:

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

Note

Please note that all the 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 service component.

Here is an example:

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

Action hooks allows you to inject custom code at different phase of the lifecycle of your control plane operations. As an example, in the above case, we are enabling vector extension for Postgres on cluster initialization

For more details and examples on action hooks, please see this

x-omnistrate-integrations

x-omnistrate-integrations allows you to add integrations to your service.

Here is an example:

x-omnistrate-integrations:
  - omnistrateLogging
  - omnistrateMetrics

In the above example, we are enabling omnistrate native metrics and logging extensions.

For the full list of integrations, please see this

x-omnistrate-compute

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

You can customize the following:

  • number of replicas
  • instance type across cloud providers
  • size of the root volume (GiB) across instances

Here is an example:

x-omnistrate-compute:
  replicaCountAPIParam: numReplicas
  instanceTypes:
    - cloudProvider: aws
      name: t4g.small
    - cloudProvider: gcp
      name: e2-medium
  rootVolumeSizeGi: 10

In the above example, replicaCountAPIParam is configured dynamically using numReplicas parameter i.e. the users of your service can decide how many replicas they want. In the same way 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).

Note that the actual value of each of the fields could be static or dynamic.

x-omnistrate-storage

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

Here is an example:

x-omnistrate-storage:
  aws:
    instanceStorageType: AWS::EBS_GP3
    instanceStorageSizeGi: 100
    instanceStorageIOPSAPIParam: instanceStorageIOPS
    instanceStorageThroughputAPIParam: instanceStorageThroughput
  gcp:
    instanceStorageType: GCP::PD_BALANCED
    instanceStorageSizeGi: 100

You can customize the following:

  • storage type from block device to blobs or both
  • size of the volume
  • storage IOPS
  • storage throughput

Like above, the actual value of each of the fields could be static or dynamic.

x-omnistrate-capabilities

x-omnistrate-capabilities allows you to add capabilities to your service components.

Here is an example:

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

To learn more about capabilities, please see this page

x-omnistrate-load-balancer

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

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

Here is an example:

version: "3"
x-omnistrate-integrations:
  - omnistrateLogging
  - omnistrateMetrics
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:
    ...

  Writer:
    ...

  Reader:
    ...

x-omnistrate-service-plan

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

Here is an example:

x-omnistrate-service-plan:
  name: 'Mysql Free Tier'
  tenancyType: 'OMNISTRATE_DEDICATED_TENANCY'
  deployment:
    hostedDeployment:
      AwsAccountId: '123456789012'
      AwsBootstrapRoleAccountArn: 'arn:aws:iam::123456789012:role/omnistrate-bootstrap-role'
      GcpProjectId: 'test-account'
      GcpProjectNumber: '1234567890123'
      GcpServiceAccountEmail: '[email protected]'

In the above example, we are configuring the service plan for the SaaS service. The service plan contains the following fields:

  • name: The name of the service plan.
  • tenancyType: The tenancy type of the service plan. The possible values are OMNISTRATE_DEDICATED_TENANCY and OMNISTRATE_MULTI_TENANCY.
  • (CTL only) deployment: The deployment type of the service plan. The possible values are hostedDeployment and byoaDeployment. If you choose to use Omnistrate hosted deployment or not building the service using CTL, then please omit this field.

x-omnistrate-my-account

x-omnistrate-my-account allows you to configure your SaaS to deploy in your account (Hosted mode).

Here is an example:

x-omnistrate-my-account:
  AwsAccountId: '123456789012'
  AwsBootstrapRoleAccountArn: 'arn:aws:iam::123456789012:role/omnistrate-bootstrap-role'
  GcpProjectId: 'test-account'
  GcpProjectNumber: '1234567890123'
  GcpServiceAccountEmail: '[email protected]'

Note

Please don't forget to replace the account numbers, project id and other information with your own account information

  • It contains cloud provider config
  • You can choose to specify one cloud providers or all the available cloud providers
  • If you choose to only configure one cloud provider (say AWS), your service will only be launched in AWS

x-omnistrate-byoa

x-omnistrate-byoa allows you to configure your SaaS to deploy in your customers' account (BYOA mode).

Here is an example:

x-omnistrate-byoa:
  AwsAccountId: '123456789012'
  AwsBootstrapRoleAccountArn: 'arn:aws:iam::123456789012:role/omnistrate-bootstrap-role'
  GcpProjectId: 'test-account'
  GcpProjectNumber: '1234567890123'
  GcpServiceAccountEmail: '[email protected]'

Note

Please don't forget to replace the account numbers, project id and other information with your own account information

  • It contains cloud provider config
  • You can choose to specify one cloud providers or all the available cloud providers
  • If you choose to only configure one cloud provider (say AWS), your service will only be launched in AWS

x-omnistrate-image-registry-attributes

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

Here is an example:

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

Note

For private image registries, username and password are required. We will only download your images in your account (hosted mode) or in your customers' account (BYOA mode)

On the roadmap

This is a list of specs currently not supported that are on our roadmap. In case you would like to see one of these specs prioritized, please send us an email at support@omnistrate.com with more details on your use case.

  • Env files mapped to a local directory (cli / server APIs) or variable susbtitution - currently done via running docker-compose config before submitting the service definition
  • Context (cli / build-packs)

For more details on the compose specification, please refer to the official docker-compose documentation.