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.

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, limits, properties. There are 3 other properties associated with each API parameter:
    • 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
    • Modifiable: configure if this field is modifiable once configured.

Note

Please note that all the environment variables are also injected 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-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

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.

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