Skip to content

Getting Started with Omnistrate CTL

Omnistrate CTL is a command line tool designed to streamline the creation, deployment, and management of your Omnistrate SaaS. Use it to build services from images / compose specs, manage service plans, and manage instance deployments efficiently.

Getting started video with Omnistrate CLI

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.

Obtaining CTL

Follow the instructions for omnistrate-ctl installation

Detailed documentation on the commands available can be found in the omnistrate-ctl manual

Getting Started

To start using CTL, you first need to log in to the Omnistrate platform. You can do this by either providing your email and password or using a single sign-on (SSO) provider. You can choose the login option by running the following command:

omnistrate-ctl login

For more login methods, refer to the Login to Omnistrate guide.

Build Service from Image

To build a service from an image, use the build command. Provide the following information:
- --image: The image to use for the service. Need to provide the complete image repository URL with the image name and tag (e.g., docker.io/namespace/my-image:v1.2)
- --name: The name of the service to create.
- --env-var(Optional): Environment variables to set in order to run your application. You can provide multiple environment variables by repeating the --env-var flag.
- image-registry-auth-username(Optional): The username for the image registry authentication. This is required if the image is hosted in a private registry.
- image-registry-auth-password(Optional): The password for the image registry authentication. This is required if the image is hosted in a private registry.

Here is an example of building a MySQL service from the mysql:5.7 image with environment variables:

omnistrate-ctl build --image docker.io/mysql:5.7 --name MySQL --env-var "MYSQL_ROOT_PASSWORD=password" --env-var "MYSQL_DATABASE=mydb"

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 service 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.
- --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 service 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 SaaS Portal and promoting the service plan to production. 

omnistrate-ctl build --file compose spec.yaml --name "Your Service Name" --interactive
You can always rerun the build command with the same service 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 offering and updating it as you evolve your service.

Launch SaaS Offer Example

In this example, we will create a SaaS offering for a Postgres service with a free tier plan, a premium plan, and walk you through service plan updates, releases, and launch to production. You can create instance deployments in your SaaS Offering 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 offerings.

Step 1: Create a SaaS Offering 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 postgres-free-v1.yaml --name "Postgres" --release-as-preferred --interactive
Follow the prompts to complete the service creation process, initializing the SaaS Portal, promoting the service plan to production, and waiting for production SaaS Portal to be ready. Once the SaaS Portal is ready, you can view it in your browser and start creating instance deployments.

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

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

Save postgres-premium-v1.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 postgres-premium-v1.yaml --name "Postgres" --release-as-preferred --interactive

Step 3: Update your SaaS Offering 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 postgres-free-v2.yaml with the following contents:

version: "3.9"
x-omnistrate-service-plan:
  name: 'Postgres Free'
  tenancyType: 'OMNISTRATE_MULTI_TENANCY'
x-omnistrate-integrations:
  - omnistrateMetrics
  - omnistrateLogging
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: bash omnistrate-ctl build --file postgres-free-v2.yaml --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 postgres-premium-v2.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 postgres-premium-v2.yaml --name "Postgres" --release-as-preferred --interactive