Omnistrate Service Specification¶

Omnistrate Service Specification Overview (Helm, Operators, Kustomize, Terraform, OpenTofu)¶

When defining a service using Helm, Operators, Kustomize, Terraform or OpenTofu we need to define the details of the Plan using a specification file.

A complete list of settings that can be configured on the Service Spec file is included below.

The default path for a Plan specification file is spec.yaml.

Using Schema Validation¶

To simplify the definition of this specification file Omnistrate provide a JSON schema that can be used for validation. You can use the JSON schema in IDEs that use the YAML Language Server (eg: VSCode / NeoVim).

# yaml-language-server: $schema=https://api.omnistrate.cloud/2022-09-01-00/schema/service-spec-schema.json

For IntelliJ replace the top line with the following line to set up the yaml schema

# $schema: https://api.omnistrate.cloud/2022-09-01-00/schema/service-spec-schema.json

Plan schema definitions¶

This Service Schema defines the structure for a Plan specification in Omnistrate. It consists of several key components such as API parameters, capabilities, compute resources, network configurations, etc. Each component is detailed below.

Root schema¶

The root of the schema includes the following properties:

Deployment schema¶

The deployment type of the Plan. The possible values are hostedDeployment and byoaDeployment. Within the deployment type we need to add the information for the cloud provide account to use. If you are planning to use a single cloud provider, there is no need to add information for the others.

Features schema¶

Defines the available features for both internal and customer-facing use cases. Features are categorized into INTERNAL and CUSTOMER, specifying their respective functionalities.

Supported INTERNAL Features¶

Supported CUSTOMER Features¶

CUSTOMER.metrics schema (advanced metrics and dashboards)¶

Use features.CUSTOMER.metrics to define how customer-facing metrics are collected and visualized.

features:
  CUSTOMER:
    metrics:
      scrapeTargets:
        - name: postgres
          podSelector:
            app.kubernetes.io/name: postgresql
          endpoint:
            portNumber: 9187
            path: /metrics
            scheme: http
      additionalMetrics:
        postgres:
          metrics:
            pg_stat_activity_count:
              "Active Sessions":
                aggregationFunction: sum
                labelFilters:
                  datname: postgres
                  state: active
            pg_locks_count:
              "Locks by Mode":
                aggregationFunction: sum
                groupByLabels:
                  - mode
                labelFilters:
                  datname: postgres
          dashboards:
            exporter:
              title: "Postgres Exporter"
              sections:
                - title: "Sessions and Locks"
                  panels:
                    - title: "Active Sessions"
                      type: timeseries
                      unit: short
                      targets:
                        - ref: "Active Sessions"
                    - title: "Locks by Mode"
                      type: timeseries
                      unit: short
                      targets:
                        - ref: "Locks by Mode"

Configuration structure and intent:

• scrapeTargets: defines where metrics are scraped from.
• Use podSelector and/or serviceSelector to discover endpoints.
• endpoint supports portName or portNumber, plus path, scheme, and optional query params.
• additionalMetrics.<resource>.metrics: models raw metrics into stable named series.
• <resource> should match your service component name (for example, postgres).
• First key is raw metric name (for example, pg_stat_activity_count).
• Nested key is exported series name (for example, "Active Sessions"), referenced by dashboards.
• Optional per-series controls:
  • aggregationFunction: sum, min, max, avg
  • groupByLabels: preserves selected dimensions in the output
  • labelFilters: filters label key/value pairs before aggregation
• additionalMetrics.<resource>.dashboards: builds custom dashboards from modeled series.
• title: dashboard title override
• sections[]: ordered dashboard sections
• panels[]: panel definitions (timeseries, stat, gauge, table)
• targets[]:
  • ref: reference a modeled series name from metrics
  • expr: raw PromQL (optional override)
  • legend, axis: optional display controls
• Optional panel fields: description, unit, min, max, thresholds, tags

Dashboard property details:

Practical guidance:

• Start by validating scrapeTargets first; missing scrape configuration is the most common reason custom panels stay empty.
• Use modeled series names in targets.ref so dashboard layout stays stable if raw metric labels change.
• Apply labelFilters before aggregation to avoid mixing unrelated dimensions.
• For copy/paste panel templates (health stat, saturation trend, distribution table), see Build Guide / Integrations.
• For legacy-to-advanced migration steps, see Build Guide / Integrations.

Service schema¶

Each Plan has a list of Resources that need to be created as part of the Plan. For each service component we need to define a set of properties.

API parameters schema¶

Defines the list of API parameters for the Resource

The valid types are described on the api parameters build guide

See Scoped API Parameters for usage examples.

Compute schema¶

Configuration for compute resources for the Resource.

Instance Type schema¶

Network schema¶

Configuration for network interfaces for the Resource.

Capabilities schema¶

Specifies capabilities enabled for the Resource.

Helm chart configuration schema¶

When defining a Resource using Helm charts we need to specify the Helm chart definition and values

Chart affinity control schema¶

Controls automatic injection of Kubernetes affinity rules into Helm chart manifests. By default, Omnistrate automatically injects node affinity and pod anti-affinity rules to ensure proper scheduling on Omnistrate-managed nodes. For more details, see Helm Chart Customization.

Operator CRD schema¶

When defining a Resource using Operators CRD we need to specify the CDR information as test and add a reference to the required Helm charts

Helm chart dependency schema¶

Kustomize configuration schema¶

When defining a Resource using Kustomize you need to specify a reference to the GitHub repository where the Kustomize stack is defined.

Deployment target schema¶

Specifies the target account for resource deployment. Only supported for Terraform resources in BYOC deployments. Once set, the account value cannot be changed.

For usage details and restrictions, see Deployment Target.

Terraform configuration schema¶

When defining a Terraform (or OpenTofu) stack to be executed to provision the Resource, you need to add a reference to the GitHub repository where the stack definition is stored. A different Terraform stack can be defined for each cloud provider using the configurationPerCloudProvider property.

Terraform per-cloud-provider configuration schema¶

Each key under configurationPerCloudProvider (aws, gcp, azure) accepts the following properties:

Example:

terraformConfigurations:
  configurationPerCloudProvider:
    aws:
      terraformPath: /terraform/aws
      variablesValuesFileOverride: |
        vpc_id = "{{ $sys.deploymentCell.cloudProviderNetworkID }}"
        region = "{{ $sys.deploymentCell.region }}"
      gitConfiguration:
        reference: refs/heads/main
        repositoryUrl: https://github.com/your-org/infra-repo.git
    gcp:
      terraformPath: /terraform/gcp
      gitConfiguration:
        reference: refs/heads/main
        repositoryUrl: https://github.com/your-org/infra-repo.git

For more details, see Terraform Overview, Multi-Cloud Configuration, and Input Parameters and Output Mapping.

Git configuration schema¶

Defines the configuration for Git access.

Pricing schema¶

Defines the pricing structure for the plan based on various dimensions.

Metering schema¶

Defines the configuration for metering.

Billing Provider schema¶

Defines a billing provider.

Load Balancers schema¶

Defines the configuration for L7 and L4 load balancers.

L7 Load Balancer Configuration schema¶

L7 Load Balancer Path Configuration schema¶

L4 Load Balancer Configuration schema¶

L4 Load Balancer Port Configuration schema¶