Skip to content

Quick start with Command Line

What is Omnistrate CTL?

Omnistrate CTL is a command line tool that helps you build SaaS Products, manage Plans, and operate instance deployments efficiently. Install the CLI before you continue by following Installing Omnistrate CTL.

Quick start video

CTL Walthrough

Note: Some features may have been updated since the video was created. Refer to the omnistrate-ctl manual for the most up-to-date information.

Build Service from Compose Spec

Before you can build a service, you need to have a compose spec that defines the service. The compose spec file should include the Plan configuration in the x-omnistrate-service-plan section. For more information on creating a compose spec, refer to the Compose Spec Reference.

To build a service from a compose spec file, use the build command with the following information:

  • --file: The path to the compose spec file (optional will default to compose.yaml or spec.yaml)
  • --product-name: The name of the service to create.
  • --description(Optional): A description of the service.
  • --service-logo-url(Optional): The URL of the service logo.
  • --release(Optional): Flag to release the service. This will make the Plan available to create instance deployments.
  • --release-as-preferred(Optional): Flag to release the service as preferred. This will make the service the default version used to create instance deployments.
  • --environment(Optional): The name of the environment where the service will be built. Default is the dev environment.
  • --environment-type(Optional): The type of environment where the service will be built. Use together with the --environment flag. Default is the dev environment.
  • --interactive(Optional): Flag to enable interactive mode for building the service. This will prompt you to access your Customer Portal and promoting the Plan to production.
omnistrate-ctl build --file compose.yaml --product-name "Your product name" --interactive

You can always rerun the build command with the same product name to update the service with a new version of the compose spec file. Refer to the Example for a step-by-step guide on creating a SaaS Product and updating it as you evolve your service.

Launch SaaS Product Example

In this example, we will create a SaaS Product for a Postgres service with a free tier plan, a premium plan, and walk you through Plan updates, releases, and launch to production. You can create instance deployments in your SaaS Product and try it out. After completing this example, you will have a better understanding of how to use the CTL to build and manage your SaaS Products.

Step 1: Create a SaaS Product with a Free Tier Plan

To start, create a free tier plan for the Postgres service.

Save postgres-free-v1.yaml with the following contents:

version: "3.9"
x-omnistrate-service-plan:
  name: 'Postgres Free'
  tenancyType: 'OMNISTRATE_MULTI_TENANCY'
services:
  postgres:
    image: postgres
    ports:
      - '5432:5432'
    environment:
      - SECURITY_CONTEXT_USER_ID=999
      - SECURITY_CONTEXT_GROUP_ID=999
      - POSTGRES_USER=default
      - POSTGRES_PASSWORD=default
      - PGDATA=/var/lib/postgresql/data/dbdata
    volumes:
      - ./data:/var/lib/postgresql/data
    deploy:
      resources:
        limits:
          cpus: '0.50'
          memory: 50M
        reservations:
          cpus: '0.25'
          memory: 20M
    x-omnistrate-capabilities:
      autoscaling:
        minReplicas: 1
        maxReplicas: 5
      serverlessConfiguration:
        enableAutoStop: true
        minimumNodesInPool: 1
        targetPort: 5432

In this example, a free tier plan is created for the Postgres service, optimized for cost savings and scalability. The plan leverages multitenancy and serverless configuration, including auto-stop to minimize costs when the service is not in use.

Run the following command to build the service:

omnistrate-ctl build --file compose.yaml --product-name "Postgres" --release-as-preferred --interactive

Follow the prompts to complete the service creation process, initializing the Customer Portal, promoting the Plan to production, and waiting for production Customer Portal to be ready. Once the Customer Portal is ready, you can view it in your browser and start creating instance deployments.

Step 2: Enhance your SaaS Product by Adding a Premium Plan

Next, let's enhance the service by adding a premium plan.

Save compose.yaml with the following contents:

version: "3.9"
x-omnistrate-service-plan:
  name: 'Postgres Premium'
  tenancyType: 'OMNISTRATE_DEDICATED_TENANCY'
services:
  postgres:
    image: postgres
    ports:
      - '5432:5432'
    environment:
      - SECURITY_CONTEXT_USER_ID=999
      - SECURITY_CONTEXT_GROUP_ID=999
      - POSTGRES_USER=default
      - POSTGRES_PASSWORD=default
      - PGDATA=/var/lib/postgresql/data/dbdata
    volumes:
      - ./data:/var/lib/postgresql/data
    x-omnistrate-capabilities:
      autoscaling:
        minReplicas: 1
        maxReplicas: 5

This plan offers dedicated tenancy with enhanced performance and resource allocation for users who require more robust features and higher limits.

Run the following command to build the service and promote it to production following the same steps as before:

omnistrate-ctl build --file compose.yaml --product-name "Postgres" --release-as-preferred --interactive

Step 3: Update your SaaS Product as You Evolve your Service

Based on the previous example, let's update the Postgres service's free tier plan to include more features and capabilities.

Save compose.yaml with the following contents:

version: "3.9"
x-omnistrate-service-plan:
  name: 'Postgres Free'
  tenancyType: 'OMNISTRATE_MULTI_TENANCY'
x-customer-integrations:
  logs: 
  metrics: 
services:
  postgres:
    image: postgres
    ports:
      - '5432:5432'
    environment:
      - SECURITY_CONTEXT_USER_ID=999
      - SECURITY_CONTEXT_GROUP_ID=999
      - POSTGRES_USER=default
      - POSTGRES_PASSWORD=default
      - PGDATA=/var/lib/postgresql/data/dbdata
    volumes:
      - ./data:/var/lib/postgresql/data
    deploy:
      resources:
        limits:
          cpus: '0.50'
          memory: 50M
        reservations:
          cpus: '0.25'
          memory: 20M
    x-omnistrate-capabilities:
      autoscaling:
        minReplicas: 1
        maxReplicas: 5
      serverlessConfiguration:
        enableAutoStop: true
        minimumNodesInPool: 1
        targetPort: 5432

In this example, the free tier plan for the Postgres service is updated to include logs and metrics integration and enable autoscaling. These enhancements provide better monitoring and scalability for the service.

Run the following command to update the service and follow the prompts to promote the new version to production:

  omnistrate-ctl build --file compose.yaml --product-name "Postgres" --release-as-preferred --interactive

Step 4: Mounting Configuration and Secret Files (Optional)

The CTL allows users to define and manage configuration files and secret files required by their services. These files can be specified in the compose specification and will be automatically mounted to the specified paths in the service containers.

Configuration Files

To specify configuration files in the compose spec file, use the following format:

services:
  service:
    configs:
      - source: my_config # The name of the config
        target: /etc/config/my_config.txt # The target path in the container
configs:
  my_config: # The name of the config
    file: ./my_config.txt # The path to the config file in your local filesystem

This example shows how to define a config named my_config and mount it to the path /etc/config/my_config.txt within the service container.

Secret Files

Similarly, you can specify secret files as follows:

services:
  service:
    secrets:
      - source: server-certificate # The name of the secret
        target: /etc/ssl/certs/server.cert # The target path in the container
secrets:
  server-certificate: # The name of the secret
    file: ./server.cert # The path to the secret file in your local filesystem

Here is a comprehensive example of a compose spec file for a Postgres service that includes both configuration and secret files:

version: "3.9"
x-omnistrate-service-plan:
  name: 'Postgres Premium'
  tenancyType: 'OMNISTRATE_DEDICATED_TENANCY'
services:
  postgres:
    image: postgres
    configs:
      - source: postgres-config
        target: /etc/postgresql/postgresql.conf
    secrets:
      - source: postgres-secret
        target: /run/secrets/postgres.secret
    ports:
      - '5432:5432'
    environment:
      - SECURITY_CONTEXT_USER_ID=999
      - SECURITY_CONTEXT_GROUP_ID=999
      - POSTGRES_USER=default
      - POSTGRES_PASSWORD=default
      - PGDATA=/var/lib/postgresql/data/dbdata
    volumes:
      - ./data:/var/lib/postgresql/data
    x-omnistrate-capabilities:
      autoscaling:
        minReplicas: 1
        maxReplicas: 5

configs:
  postgres-config:
    file: ./config/postgres.conf

secrets:
  postgres-secret:
    file: ./secrets/postgres.secret

In this example, the postgres service uses a configuration file for Postgres settings and a secret file for sensitive information. These files are specified in the configs and secrets sections and mounted to the appropriate paths within the container.

Name the above file as compose.yaml and run the following command to build the service. Make sure the paths to the configuration and secret files are correct and accessible from the location where you run the CTL command.

omnistrate-ctl build --file compose.yaml --product-name "Postgres" --release-as-preferred --interactive