Choosing Your Service Specification Approach¶

This guide helps you understand when to use Compose-based specifications versus Plan specifications for defining your SaaS service in Omnistrate, with clear decision criteria and template references.

Quick Decision Matrix¶

Compose-based Specification¶

When to Use¶

✅ Choose Compose-based specification when:

• Your application is containerized and can be fully described using Docker Compose
• You want to define your entire service specification in a single file
• Your infrastructure requirements are straightforward (standard containers, volumes, networks)
• You prefer Docker Compose syntax and workflows
• You're building a new containerized application from scratch
• You want rapid prototyping and simpler configuration management

Key Characteristics¶

• Single file approach: Everything defined in compose.yaml
• Omnistrate extensions: Uses x-omnistrate-* tags within the compose file
• Built-in parameter management: API parameters defined directly in the compose spec
• Automatic infrastructure: Omnistrate handles Kubernetes deployment automatically
• Simpler learning curve: Familiar Docker Compose syntax with Omnistrate extensions

Template and Examples¶

📋 Template Repository: omnistrate-community/compose-based-template

Example structure:

version: "3.8"

x-omnistrate-service-plan:
  name: 'My Service Plan'
  tenancyType: 'OMNISTRATE_DEDICATED_TENANCY'

services:
  web:
    image: nginx:latest
    ports:
      - "80:80"
    x-omnistrate-api-params:
      - key: instanceType
        description: Instance Type
        name: Instance Type
        type: String
        required: true
    x-omnistrate-compute:
      instanceTypes:
        - cloudProvider: aws
          name: t3.medium

Best For¶

• Web applications with standard containerized architectures
• Microservices that can be orchestrated with Docker Compose
• Development and testing environments
• Simple to moderate complexity deployments
• Teams familiar with Docker Compose

Plan Specification¶

When to Use¶

✅ Choose Plan specification when:

• You're using Helm charts, Operators, Kustomize, or Terraform
• You need complex Kubernetes configurations beyond what Compose can express
• You have existing infrastructure as code (Helm charts, Terraform modules)
• You require advanced Kubernetes features (CRDs, operators, complex networking)
• You need multi-cloud Terraform deployments
• You want separation of concerns between service definition and plan configuration

Key Characteristics¶

• Separate specification file: Plan defined in spec.yaml, separate from your infrastructure code
• Technology agnostic: Works with Helm, Operators, Kustomize, and Terraform
• Advanced configurations: Supports complex Kubernetes and cloud provider features
• Flexible deployment models: Better support for BYOA (Bring Your Own Account) scenarios
• Enterprise features: Advanced networking, security, and compliance capabilities

Template and Examples¶

📋 Template Repository: omnistrate-community/plan-spec-template

Example structure:

# spec.yaml
name: "PostgreSQL Service"
deployment:
  hostedDeployment:
    awsAccountId: "123456789012"
    awsBootstrapRoleAccountArn: "arn:aws:iam::123456789012:role/omnistrate-bootstrap-role"

services:
  - name: "database"
    apiParameters:
      - key: "instanceType"
        description: "Database Instance Type"
        type: "string"
        required: true
    compute:
      instanceTypes:
        - name: "t3.medium"
          cloudProvider: "aws"
    helmChartConfiguration:
      chartName: "postgresql"
      chartVersion: "12.1.2"
      chartRepoName: "bitnami"
      chartRepoURL: "https://charts.bitnami.com/bitnami"
      chartValues:
        auth:
          postgresPassword: "$var.postgresPassword"

Best For¶

• Helm-based applications with complex chart configurations
• Kubernetes Operators requiring custom resources and controllers
• Kustomize deployments with sophisticated overlays and patches
• Terraform infrastructure spanning multiple cloud providers
• Enterprise applications with advanced security and compliance requirements
• Existing infrastructure as code that you want to SaaS-ify

Getting Started¶

For Compose-based Specification¶

1. Clone the template: git clone https://github.com/omnistrate-community/compose-based-template
2. Follow the guide: Build from Compose
3. Reference documentation: Compose Specification

For Plan Specification¶

1. Clone the template: git clone https://github.com/omnistrate-community/plan-spec-template
2. Choose your technology:
3. Build from Helm
4. Build from Operators
5. Build from Kustomize
6. Build from Terraform
7. Reference documentation: Plan Specification

Summary¶

Choose Compose-based specification for straightforward containerized applications that fit well within Docker Compose paradigms. It offers simplicity and rapid development.

Choose Plan specification for complex deployments using Helm, Operators, Kustomize, or Terraform, especially when you need advanced Kubernetes features or have existing infrastructure as code.

Both approaches are fully supported by Omnistrate and can be used to build production-ready SaaS Product. The choice depends on your technology stack, complexity requirements, and team expertise.