Skip to content

Build from Kubernetes Operators

Use this guide when you already have a Kubernetes Operator, or you want to build your product lifecycle around an operator-managed custom resource.

Omnistrate does not replace your operator. Your operator continues to reconcile the application. Omnistrate provides the surrounding control plane: service plan versioning, tenant and subscription management, Customer Portal, generated APIs, cloud account onboarding, deployment cells, networking, observability, backups, restores, upgrades, and fleet operations.

For the complete current example, start from the operator spec template. It defines a CloudNativePG PostgreSQL service plan using operator Helm dependencies, systemWorkflows, backup configuration, snapshot metadata, and restore workflows.

When to Use This Path

Choose the operator path when:

  • Your product lifecycle is already modeled by Kubernetes CRDs.
  • You need day-2 operations such as scale, stop, start, backup, restore, or delete-backup.
  • You want Omnistrate to expose those operations through the Customer Portal, APIs, and operations workflows.
  • You want to keep using standard Kubernetes, Argo Workflow-style YAML, Helm charts, and optionally Terraform.

If your application is only a basic container deployment, start with Build from Compose. If it is a standard Helm chart without custom resources, start with Build from Helm charts.

Operator Service Plan Flow

  1. Install the operator

Add the operator Helm chart under operatorCRDConfiguration.helmChartDependencies, or install shared operators as deployment-cell amenities when many tenant instances share the same cluster-level operator.

  1. Define customer inputs

Add apiParameters for values such as instance type, storage size, replica count, database name, and backup storage settings.

  1. Expose endpoints

Add endpointConfiguration so customers can find writer, reader, HTTP, metrics, or other service endpoints after the operator creates the underlying Kubernetes services.

  1. Define lifecycle workflows

Define at least create, modify, and delete so Omnistrate can provision, update, and remove the managed resource through standard lifecycle APIs. Add optional systemWorkflows such as start, stop, backup, restore, and deleteBackup only when the service plan supports those operations.

  1. Optionally define provider operations

Use customWorkflows only when your product needs operations beyond the standard platform lifecycle APIs, such as repair, compact, diagnostics, or other provider-defined administrative tasks.

  1. Build and release the plan

Build the service plan with omnistrate-ctl, then create a test instance from the Customer Portal or CLI.

Quick Start from the Template

git clone https://github.com/omnistrate-community/operator-spec-template
cd operator-spec-template
omnistrate-ctl build -f spec.yaml --name "Postgres Operator" --release-as-preferred --spec-type ServicePlanSpec

The template includes:

  • CloudNativePG and Barman Cloud plugin Helm dependencies.
  • apiParameters for PostgreSQL credentials, replica count, storage size, instance type, and S3 backup settings.
  • Public writer and reader endpoint configuration.
  • capabilities.backupConfiguration for periodic backups, retention, and snapshot-before-delete.
  • systemWorkflows.create and modify to apply the CNPG Cluster.
  • systemWorkflows.start and stop to toggle CNPG hibernation.
  • systemWorkflows.addCapacity and removeCapacity to change replica count.
  • systemWorkflows.backup, restore, and deleteBackup to integrate Omnistrate snapshots with operator backup resources.

Note

The template uses operatorCRDConfiguration.helmChartDependencies to install the operator. Deprecated fields such as operatorCRDConfiguration.template, supplementalFiles, and readinessConditions are intentionally omitted; lifecycle resources and readiness checks are modeled with systemWorkflows.

Workflow Syntax

Operator lifecycle workflows use an Argo Workflow-style structure:

systemWorkflows:
  create:
    workflow:
      entrypoint: create
      arguments:
        parameters:
          - name: namespace
            value: "{{ $sys.namespace }}"
          - name: instanceId
            value: "{{ $sys.instanceId }}"
      templates:
        - name: create
          dag:
            tasks:
              - name: applycluster
                template: apply-cluster
        - name: apply-cluster
          resource:
            action: apply
            successCondition: status.conditions.#(type=="Ready").status == True
            failureCondition: status.phase == failed
            manifest: |
              apiVersion: postgresql.cnpg.io/v1
              kind: Cluster
              metadata:
                name: "{{inputs.parameters.instanceId}}"
                namespace: "{{inputs.parameters.namespace}}"

The workflow body uses familiar Argo concepts: entrypoint, arguments.parameters, templates, DAG tasks, and Kubernetes resource templates. Omnistrate renders $sys.*, $var.*, $secret.*, and $func.* expressions before execution.

For the detailed operator service plan model, see Build with Kubernetes Operators. For all supported service spec fields, see the Plan Specification.

Validate Your First Instance

After you create an instance, check:

  • The operator Helm charts are installed.
  • The tenant namespace exists.
  • The service plan defines the required systemWorkflows.create, systemWorkflows.modify, and systemWorkflows.delete lifecycle hooks.
  • The custom resources created by systemWorkflows.create exist in the tenant namespace.
  • The operator writes the status fields used by successCondition, failureCondition, and output parameters.
  • The Customer Portal shows the expected endpoints and supported operations.
  • Manual backup and restore work before enabling automated backup schedules.

If readiness stalls or a workflow fails, open the workflow details in Operations Center and use Deployment Cell Access to inspect the Kubernetes resources directly.

More Real-World Examples

Dive Deeper

Now that you have a working Operator-based SaaS Product, explore the build guides to customize and extend your deployment: