@datocms/cubo NPM

Cubo CLI

Cubo is an opinionated CLI designed to simplify the deployment and management of containerized applications on AWS EKS. It serves as a local or CI/CD automation tool—your cluster remains lean, running only plain Kubernetes resources and your app.

With a "convention over configuration" approach, Cubo reads a single JSON manifest (cubo.json5) to:

Build and deploy your app:
- Support multiple environments targeting different clusters
- Choose between rolling or recreate deployment strategies
Wrap common kubectl commands with a Heroku-like developer experience:
- Run remote commands (cubo run and cubo run:detached)
- Toggle maintenance mode (cubo maintenance:on and cubo maintenance:off)
- Manage processes (cubo ps:scale, cubo ps:restart, etc.)
- Manage environment variables (cubo config:set, cubo config:unset, etc.)
- View/filter logs (cubo logs)

K8S requirements

To support Cubo deployments, your EKS Kubernetes cluster must have the following components installed:

KEDA: Enables event-driven autoscaling based on external metrics.
External Secrets: Manages secrets by syncing them from AWS Secrets Manager.

What You Can Do

Cubo allows you to define and manage different types of workloads:

HTTP servers: Exposed via AWS ALB, with optional autoscaling (CPU or queue-time based)
Workers: Long-running services with autoscaling (CPU or custom metrics, like queue latency)
Cron jobs: Schedule recurring tasks with safe concurrency controls
TCP/UDP servers: Exposed via AWS NLB for lower-level protocols

Installation

$ npm i --save-dev @datocms/cubo
$ cubo --help

Configuration via `cubo.json5`

All configuration for your deployment is handled through a single cubo.json5 file. This file defines how your services are built, deployed, and scaled.

To see all available configuration options and their structure, refer to the JSON Schema:

{
  "$schema": "https://unpkg.com/@datocms/cubo@<VERSION>/schemas/cubo-config-schema.json",
  // ...
}

Secrets Management

Cubo integrates AWS Secrets Manager and the External Secrets Operator to keep your environment variables secure and out of your codebase.

Create an AWS Secret with the exact name of your Kubernetes namespace (as defined by environment.kubernetes.namespace in your Cubo config).
Store your environment variables as a top-level JSON object in the secret.
Include a .dockerconfigjson key with your Docker auth JSON if pulling from private registries.

`queueTime` Scale Strategy

For deployments classified as web, you can implement a scaling strategy based on request queue times. When a request reaches your application, it will include the X-Request-Start header, indicating when the request first entered the proxy queue.

Your application must respond with an X-Queue-Time header. This value should represent the time difference between the current server time and the timestamp provided in X-Request-Start, effectively measuring how long the request waited in the queue.

These queue times are emitted as a StatsD metric via UDP, using the following format:

cloudwatch.cubo.http_queue_time.namespace.${environment.kubernetes.namespace}.deployment.${deploymentName}.storage-resolution.1

The StatsD server aggregates these values into a 30-second average, and forwards the result to CloudWatch. From there, a KEDA ScaledObject uses the queue time data to automatically scale your application based on traffic pressure.

`api` Scale Strategy

For deployments classified as background, you can implement a scaling strategy based on custom application metrics (such as queue latency). Your application must expose a JSON endpoint that provides the relevant metric.

A KEDA ScaledObject will periodically query this endpoint and use the reported value to drive autoscaling decisions, allowing your background processes to scale dynamically in response to workload demands.