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.

Start with the Omnistrate Operator Skill

Use the omnistrate-operator skill when an AI assistant is helping you onboard a Kubernetes operator. The skill guides the assistant through operator discovery, Plan specification (ServicePlanSpec) authoring, systemWorkflows, deployment, and lifecycle validation.

Before you begin:

  • Install omnistrate-ctl using the installation guide.
  • Authenticate with omnistrate-ctl login.
  • Use an AI assistant that supports Agent Skills.

Install the skill with the skills CLI:

npx skills add omnistrate-oss/agent-instructions \
  -s omnistrate-operator

For Claude Code, Codex, GitHub Copilot, and other supported assistants, see Installing the Skills in the Agent Instructions repository.

The skill uses omnistrate-ctl by default. If you want the assistant to call Omnistrate tools directly, configure the optional Omnistrate MCP server. The skill provides the operator onboarding workflow; MCP provides an agent connection to Omnistrate tools. MCP is not required when the assistant can run the CLI.

Start an onboarding session

Give the assistant the following information along with the omnistrate-operator skill:

Use the omnistrate-operator skill to onboard my Kubernetes operator to Omnistrate.

Operator: <operator name>
Operator Helm chart: <repository URL, chart name, and version>
CRD group/version/kind: <values>
Example custom resource: <file or repository path>
Deployment model: Hosted SaaS / BYOC Anywhere
Cloud and region: <values>
Required lifecycle operations: create, modify, stop, start, backup, restore, delete

Also provide the operator scope and watch namespace, CRD status conditions, operator-native stop/start mechanism, service names and ports, and cloud-account details. These facts let the assistant author a ServicePlanSpec against the operator's actual behavior instead of guessing its schema.

The skill will:

  1. Determine the operator's scope and select the correct CRD and controller installation pattern.
  2. Create a minimal ServicePlanSpec with systemWorkflows for the first supported lifecycle operations.
  3. Build and deploy the first instance, then debug workflow and custom-resource reconciliation failures.
  4. Add lifecycle operations, networking, endpoints, backups, and production settings incrementally.
  5. Validate the live custom resource and operator status before you harden the service for production.

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 and CRDs

    Determine whether the operator is cluster-scoped or namespace-scoped. Install a cluster-scoped operator and its CRDs once per deployment cell as a custom amenity. For a namespace-scoped operator, install its CRDs as a deployment-cell amenity and install the controller as a per-instance sibling service with helmChartConfiguration and crds.enabled: false. Do not add new operator chart entries under operatorCRDConfiguration.helmChartDependencies; that pattern is retained only by older examples.

  2. Define customer inputs

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

  3. Expose endpoints

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

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

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

  6. Build and release the plan

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

Note

Lifecycle behavior belongs in systemWorkflows. Use workflow task successCondition and failureCondition for readiness and failure handling, and define workflow-level outputs only when a successful task captures the resource status. Operator-created pods may also need explicit affinity to Omnistrate-managed nodes; the operator does not automatically inherit Omnistrate's placement settings.

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 public template uses operatorCRDConfiguration.helmChartDependencies for compatibility with its existing installation flow. For new integrations, use deployment-cell amenities for cluster-scoped operators or the namespace-scoped hybrid pattern described above. 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 live custom resource reaches the operator-specific ready condition.
  • The operator writes the status fields used by successCondition, failureCondition, and output parameters.
  • The Customer Portal shows the expected endpoints and supported operations.
  • Create, modify, stop, start, and delete have been exercised where the operator supports them, and deletion leaves no custom resources or secrets orphaned in the tenant namespace.
  • 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: