Service plan specification

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

Info

When using docker compose there is no need to set up this file as the information for the service 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

Service plan schema definitions

This Service Schema defines the structure for a service 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:

Parameter	Type	Description
name	string	The name of the service plan.
deployment	deployment schema	The deployment type of the service plan. The possible values are hostedDeployment and byoaDeployment.
services	array	A list of service configurations for the plan. Required.

Deployment schema

The deployment type of the service 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.

Parameter	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.

Service schema

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

Property	Type	Description
name	string	The name of the service components.
internal	boolean	Defines if the service component can be created by customers or is an internal resource used by other service components
dependsOn	array	List of service components defined on this service that need to be created before this service component
apiParameters	api parameters schema	List of parameters for the service component.
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 service component characteristics like running on more than one AZ.
helmChartConfiguration	helm schema	Helm chart configuration, if the service component is defined using Helm.
operatorCRDConfiguration	operator schema	Operator CRD configuration for provisioning the service component, if the service is component is defined as an Operator
kustomizeConfiguration	kustomize schema	Kustomize configuration for provisioning the service component if the service component is defined using Kustomize.
terraformConfigurations	terraform schema	Terraform configuration for provisioning the service component on each cloud provider, if the service component requires a terraform stack.

API parameters schema

Defines the list of API parameters for the service component

Parameter	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.
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.

Compute schema

Configuration for compute resources for the service component.

Parameter	Type	Description
instanceTypes	array	List of instance types supported.

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).

Network schema

Configuration for network interfaces for the service component

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

Capabilities schema

Specifies capabilities enabled for the service component.

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

Helm chart configuration schema

When defining a service component 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 Guides / System Parameters.

Parameter	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 service component 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 Guides / 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 file paths (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.

Kustomize configuration schema

When defining a service component 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 service component 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 Guides / System Parameters.

Property	Type	Description
terraformPath	string	The file path to the Terraform configuration.
gitConfiguration	git access schema	Configuration for Git access related to Terraform stack.
privateModuleGitAccessTokens	object	Tokens for accessing private Git modules.

Git configuration schema

Defines the configuration for Git access.

Parameter	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.