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
Env files - native support for specifying environment variables in a separate file. For example:
```
env_file:
  - .env
```
You can do variable interpolation using the syntax ${VARIABLE_NAME}. For example, if your .env file contains the environment variable DB_HOST=YOUR_DB_HOST, you can use it in your compose file like this:
```
environment:
  - DB_HOST=${DB_HOST}
```
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
labels - allows you to specify custom metadata for resources, such as custom resource names or descriptions. For example:
```
labels:
  - "name=Your Resource Name"
  - "description=Your Resource Description"
```

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
    - cloudProvider: azure
      name: Standard_B2als_v2
  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
  azure:
    instanceStorageType: AZURE::STANDARD_SSD
    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]'
      AzureSubscriptionId: 'xxxxxxxx-xxxx-xxx-xxxx-xxxxxxxxxx'
      AzureTenantId: 'xxxxxxxx-xxxx-xxx-xxxx-xxxxxxxxxx'
  pricing:
    - dimension: cpu
      unit: cores
      timeUnit: hour
      price: 0.01
    - dimension: memory
      unit: GiB
      timeUnit: hour
      price: 0.05
    - dimension: storage
      unit: GiB
      timeUnit: hour
      price: 0.02
  metering:
    s3BucketARN: arn:aws:s3:::my_billing_bucket_name
    gcsBucketName: my-billing-bucket-name
  validPaymentMethodRequired: false
  maxNumberOfInstancesAllowed: 10
  billingProductID: "prod_123"

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. Possible options are:
- OMNISTRATE_DEDICATED_TENANCY: The service plan is dedicated to a single customer.
- OMNISTRATE_MULTI_TENANCY: The service plan is shared among multiple customers.
deployment: The deployment type of the service plan. Possible options are:
- hostedDeployment: The service plan is deployed on your account.
- byoaDeployment: The service plan is deployed on your customer's account.
- Omitted: Omnistrate will host the service plan for you.
pricing: The usage-based pricing model of the service plan. It will be used to generate invoices at the end of the month. Make sure to enable tenant billing first before using this feature. For a detailed guide, see here. Please specify the pricing for the following dimensions:
- cpu: The pricing is based on the CPU usage.
  - unit: For now we only support cores.
  - timeUnit: For now we only support hour.
- memory: The pricing is based on the amount of memory (RAM) used.
  - unit: For now we only support GiB.
  - timeUnit: For now we only support hour.
- storage: The pricing is based on the amount of allocated storage.
  - unit: For now we only support GiB.
  - timeUnit: For now we only support hour.
metering: The metering configuration of the service plan. You can meter your infrastructure to capture the usage per customer, aggregate and store them at a defined location in your account. For a detailed step-by-step guide on configuring your bucket with the appropriate policy for storing metering data, please see here.
- s3BucketARN: The ARN of the S3 bucket where the metering data will be stored.
- gcsBucketName: The name of the GCS bucket where the metering data will be stored.
validPaymentMethodRequired: Whether a valid payment method is required for your customers to create resource instances. Possible options are:
- true: Your customers must provide a valid payment method before consuming the service.
- false(default): Your customers can consume the service without providing a valid payment method.
maxNumberOfInstancesAllowed: The maximum number of instances allowed per tenant. This limit is applied at the tenant organization level, e.g. each tenant organization can create up to N instances of this service plan. Possible options are:
- -1(default): No limit on the number of instances that can be created.
- N: Any positive integer.
billingProductID (optional): You can specify the billing product ID for your service plan. This can be used to identify the service plan in your billing system. The billing product ID is a unique identifier for the service plan and is used to track usage and generate invoices.

Note

For deployment, 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.

Context (cli / build-packs)

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