Skip to content

Plan specification

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

Info

When using docker compose there is no need to set up this file as the information for the Plan can be defined on the docker compose spec. More information under Getting started / Setup using Compose

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

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

Parameters VSCode

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:

Property Type Description
name string The name of the Plan.
deployment deployment schema The deployment type of the Plan. The possible values are hostedDeployment and byoaDeployment.
features features schema The list of features enabled for the Plan. The possible values are INTERNAL and EXTERNAL.
services array A list of service configurations for the plan. Required.
pricing pricing schema A list of pricing dimensions for the plan.
metering metering schema The configuration for metering.
billingProviders billing provider schema A list of billing providers.
maxNumberOfInstancesAllowed integer The maximum number of instances allowed.
loadBalancers load balancers schema The configuration for load balancers.

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.

Property Type Description
awsAccountId string AWS Account ID.
awsBootstrapRoleAccountArn string ARN of the AWS bootstrap role.
gcpProjectId string GCP Project ID.
gcpProjectNumber string GCP Project number.
gcpServiceAccountEmail string Email of the GCP service account.
azureSubscriptionId string Azure Subscription GUID.
azureTenantId string Azure Tenant GUID.

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.

Property Type Description
INTERNAL string Features scoped to SaaS Providers
CUSTOMER string Feature scoped to end customer

Supported INTERNAL Features

Property Type Description
logs string Enable SaaS Provider logs on the operational log dashboard

Supported CUSTOMER Features

Property Type Description
logs string Enable customer visible logs
licensing string Enable software license management

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.

Property Type Description
name string The name of the Resources.
internal boolean Defines if the Resource can be created by customers or is an internal resource used by other Resources
dependsOn array List of Resources defined on this service that need to be created before this Resource
apiParameters api parameters schema List of parameters for the Resource.
compute compute schema The compute resources allocated for the service.
network network schema Network-related configuration for the service, including ports.
capabilities capabilities schema Defines Resource characteristics like running on more than one AZ.
helmChartConfiguration helm schema Helm chart configuration, if the Resource is defined using Helm.
operatorCRDConfiguration operator schema Operator CRD configuration for provisioning the Resource, if the service is component is defined as an Operator
kustomizeConfiguration kustomize schema Kustomize configuration for provisioning the Resource if the Resource is defined using Kustomize.
terraformConfigurations terraform schema Terraform configuration for provisioning the Resource on each cloud provider, if the Resource requires a terraform stack.

API parameters schema

Defines the list of API parameters for the Resource

Property Type Description
key string The key of the parameter.
description string Description of the parameter.
name string The display name of the parameter.
type string The type of the parameter (e.g., string).
modifiable boolean Indicates if the parameter is modifiable.
required boolean Indicates if the parameter is required.
export boolean If true, the parameter is exportable.
defaultValue string Default value of the parameter.
regex string A regular expression to validate the parameter value.
options array Available options for the parameter.
labeledOptions object A set of labeled options as key-value pairs.
limits object Limit settings for the parameter.
dependentResourceKey string Key for dependent resources.
parameterDependencyMap object Dependency map for other parameters.

The valid types are described on the api parameters build guide

Compute schema

Configuration for compute resources for the Resource.

Property Type Description
instanceTypes array List of instance types supported.
rootVolumeSizeGi integer The size of the root volume in Gi.
cpuArchitecture string The CPU architecture for the resource.

Instance Type schema

Property Type Description
name string The name of the instance type.
apiParam string The API parameter name associated with the instance type.
cloudProvider string The cloud provider for the instance type (e.g., AWS, GCP, Azure).

Network schema

Configuration for network interfaces for the Resource

Property Type Description
ports array A list of ports (integer values) that are configured for the network.

Capabilities schema

Specifies capabilities enabled for the Resource.

Property Type Description
enableMultiZone boolean Whether multi-zone support is enabled.

Helm chart configuration schema

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

Info

You can use system parameters to customize Helm Chart values. A detailed list of system parameters be found on Build Guide / System Parameters.

Property Type Description
chartName string Name of the Helm chart. Required.
chartVersion string Version of the Helm chart. Required.
chartRepoName string Name of the chart repository. Required.
chartRepoURL string URL of the chart repository. Required.
chartValues object Values to be passed to the Helm chart.
authProvider object Username and password to access private Helm cart repo.

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

Info

You can use system parameters to customize Operators CRD. A detailed list of system parameters be found on Build Guide / System Parameters.

Property Type Description
template string The template for the operator CRD configuration.
readinessConditions object Conditions that determine the readiness state of the CRD.
supplementalFiles array A list of supplemental files (inline defined as multi-line strings) for the CRD.
outputParameters object A map of output parameters with string values.
helmChartDependencies array A list of Helm chart dependencies referenced by the CRD.

Helm chart dependency schema

Property Type Description
chartName string The name of the Helm chart dependency.
chartVersion string The version of the Helm chart dependency.
chartRepoName string Name of the chart repository.
chartRepoURL string URL of the chart repository.
chartValues object Values to be passed to the Helm chart.
authProvider object Username and password to access private Helm cart repo.

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.

Property Type Description
kustomizePath string The path to the Kustomize configuration.
gitConfiguration git access schema Configuration for Git access related to Kustomize files.

Terraform configuration schema

When defining a Terraform stack to be executed to provision the Resource we 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.

Info

You can use system parameters to pass input parameters to your Terraform stack. A detailed list of system parameters be found on Build Guide / System Parameters.

Property Type Description
terraformPath string The file path to the Terraform configuration.
terraformExecutionIdentity string The identity to use for executing Terraform.
gitConfiguration git access schema Configuration for Git access related to Terraform stack.

Git configuration schema

Defines the configuration for Git access.

Property Type Description
userName string Git user name.
accessToken string Access token for Git authentication.
reference string Reference to the Git branch or commit. Required.
repositoryUrl string URL of the Git repository. Required.

Pricing schema

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

Property Type Description
dimension string The name of the pricing dimension (e.g., "CPU").
unit string (Optional) The unit of measurement for the dimension.
timeUnit string (Optional) The time unit for billing (e.g., "hour").
price number The price per unit.

Info

For more detailed information on the pricing, metering, billingProviders configuration, please see End-to-End Billing and Usage Metering.

Metering schema

Defines the configuration for metering.

Property Type Description
s3BucketArn string The ARN of the S3 bucket for metering.
s3BucketRegion string The region of the S3 bucket.
gcsBucketName string The name of the GCS bucket.

Billing Provider schema

Defines a billing provider.

Property Type Description
name string The name of the billing provider. Use stripe (case-insensitive) for Stripe integration or the name you set for your bring-your-own (BYO) billing provider.
externalProductID string (Stripe only) The external product ID.
enablePaywall boolean (Stripe only) Specifies if a paywall is enabled.
isDefault boolean Specifies if this is the default provider.

Load Balancers schema

Defines the configuration for L7 and L4 load balancers.

Property Type Description
https array A list of L7 load balancer configurations.
tcp array A list of L4 load balancer configurations.

L7 Load Balancer Configuration schema

Property Type Description
name string The name of the L7 load balancer.
description string A description of the L7 load balancer.
enableCustomDNS boolean Specifies if custom DNS is enabled.
paths array A list of L7 load balancer paths.

L7 Load Balancer Path Configuration schema

Property Type Description
targetKubernetesServiceName string The name of the target Kubernetes service.
associatedResourceKey string The associated resource key.
path string The path for the load balancer rule.
backendPort integer The backend port.

L4 Load Balancer Configuration schema

Property Type Description
name string The name of the L4 load balancer.
description string A description of the L4 load balancer.
ports array A list of L4 load balancer ports.

L4 Load Balancer Port Configuration schema

Property Type Description
associatedResourceKeys array A list of associated resource keys.
backendPort integer The backend port.
ingressPort integer The ingress port.