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. |
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 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 | (Optional) Tokens for accessing private Git modules, if not specified will use the default token. |
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. |