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 theomnistrateLogging
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:
- 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:
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.
- 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)
- Shared volumes (efs) - currently mapping the volume to the container path
- ulimits Capabilities
- Sysctl
For more details on the compose specification, please refer to the official docker-compose documentation.