CTL Reference
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 docker-compose files, manage service plans, and interact with the Omnistrate platform efficiently.
Getting started video with developer CLI
Obtaining CTL
We provide CTL in the following formats:
CTL Binaries
To run the CTL in your local environment, you can use the CTL binaries. To obtain the latest version of the CTL binaries, execute the following command in your terminal:
This command will automatically download and install the latest version of the CTL binaries onto your system.
Run the following command to verify the installation. If the installation was successful, you should see the version number of the CTL displayed in the terminal.
Homebrew Tap
CTL can be installed using Homebrew. Homebrew can be installed on MacOS or Linux. It can be installed following the instructions in https://docs.brew.sh/Installation To install the latest version of CTL using Homebrew, execute the following command in your terminal:
Homebrew will automatically download and install the latest version of the CTL binaries onto your system.
Docker Image
To integrate CTL into your CI/CD pipeline, you can use the CTL docker image.
The latest version of the CTL can be found in the docker image ghcr.io/omnistrate/ctl:latest.
Please refer to the Using CTL with Docker section for more information.
CTL usage
Usage:
omnistrate-ctl [flags]
omnistrate-ctl [command]
Available Commands:
build Build a service from a Docker Compose file
completion Generate the autocompletion script for the specified shell
describe Get detailed information about a service
help Help about any command
list List all available services
login Log in to the Omnistrate platform
logout Logout from the Omnistrate platform
remove Remove a service from the Omnistrate platform
Flags:
-h, --help help for omnistrate-ctl
Using CTL with Docker
The latest version of the CTL is packaged and released in a docker container. The container can be use to execute omnistrate-ctl
To log into the container and execute a series of commands, run the following command
To persist the credentials across multiple container runs, run the following command
Getting Started
To start using CTL, you first need to log in to the Omnistrate platform. You can do this by running either of the following command:
# Option 1: provide email and password as arguments
omnistrate-ctl login --email email --password password
# Option 2: store password in a file
cat ~/omnistrate_pass.txt | omnistrate-ctl login --email email --password-stdin
# Option 3: store password in an environment variable
echo $OMNISTRATE_PASSWORD | omnistrate-ctl login --email email --password-stdin
Building a Service
Before you can build a service, you need to have a docker-compose file that defines the service. The docker-compose file should include the service plan configuration in the x-omnistrate-service-plan section. Here is an example of a docker-compose file with a service plan configuration:
version: "3"
x-omnistrate-service-plan:
name: 'Your Service Plan Name'
tenancyType: 'OMNISTRATE_DEDICATED_TENANCY'
deployment:
hostedDeployment:
AwsAccountId: '0123456789'
AwsBootstrapRoleAccountArn: 'arn:aws:iam::0123456789:role/YOUR_AWS_BOOTSTRAP_ROLE'
services:
...
To build a service from a docker-compose file, use the build command:
This command will create a new service named "Your Service Name" using the docker-compose file docker-compose.yaml.
If the service is built successfully, you will see a message like this:
Service built successfully
Check the service plan result at https://omnistrate.cloud/product-tier/build?serviceId=s-lfuFlBuRlD&productTierId=pt-TcSiyeoXEA
Consume it at https://omnistrate.cloud/access?serviceId=s-lfuFlBuRlD&environmentId=se-hC4Z5oHUVd
If you want to release the service after building it, you can use the --release-as-preferred or --release flag in the build command.
To update the service with a new compose spec, use the same command as above with the updated compose spec file.
Listing Services
To list all the services you have created, use the list command:
This command will display a list of all your services, along with their status and other details.
Describing a Service
To get more detailed information about a specific service, use the describe command:
Replace <service-id> with the ID of the service you want to describe. This command will display detailed information about the specified service.
Removing a Service
To remove a service from the Omnistrate platform, use the remove command:
Replace <service-id> with the ID of the service you want to remove. This command will remove the specified service from the platform.
Examples
Example 1: Creating a Service with Multiple Plans
To start, create a free tier plan for the Postgres service. This plan is designed to be cost-effective by leveraging multitenancy and serverless configuration, which includes auto-stop to minimize costs when the service is not in use. Run the following command:
Contents ofpostgres-free-v1.yaml:
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
Next, enhance the Postgres service by adding a premium plan. This plan offers dedicated tenancy with enhanced performance and resource allocation for users who require more robust features and higher limits. Execute the following command:
Contents ofpostgres-premium-v1.yaml:
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
Example 2: Updating the Service with a New Compose Spec
Based on the previous example, update the Postgres service's free tier plan to include logs and metrics integration and enable autoscaling. This enhancement provides better monitoring and scalability to handle varying workloads. Run the following command:
Contents of postgres-free-v2.yaml:
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
Example 3: Creating a Postgres Service with Configuration and Secret Files
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 docker-compose 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
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 docker-compose 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.