Services API

Services are the containers you run. Everything the dashboard's service pages do is available here: create a service, push a new image, deploy it, watch the rollout, and roll back if it goes wrong.

All paths below are relative to:

https://api.smll.io/api/v1/workspaces/{workspaceID}/vpcs/{vpcID}/services

Endpoints

Build and disk-backup endpoints are listed under Builds and Disk backups.

Create a service

curl -s -X POST -H "$AUTH" -H "Content-Type: application/json" \
  -d '{
        "name": "api",
        "service_type": "web",
        "instance_type": "smll.small",
        "image": "registry.smll.io/vpc-4f2c413b/api:v1",
        "port": 8080,
        "health_check_path": "/healthz",
        "min_replicas": 1,
        "max_replicas": 3
      }' \
  "$BASE/workspaces/$WORKSPACE_ID/vpcs/$VPC_ID/services"

Creation fails with 503 if the platform cannot reach Kubernetes, and no record is written. There is no half-created service to clean up.

Deploy

Deploying means pointing the service at an image and rolling the pods:

curl -s -X POST -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"image_tag":"v1.4.2"}' \
  "$BASE/workspaces/$WORKSPACE_ID/vpcs/$VPC_ID/services/$SERVICE_ID/deploy"

image_tag takes either form:

• A bare tag (v1.4.2), appended to the service's configured base image.
• A full reference (registry.smll.io/vpc-4f2c413b/api:v1.4.2), used as-is.

Use the full reference when the image lives somewhere other than the service's usual repository.

The call returns once the rollout has been requested, not once it is healthy. Poll the service detail endpoint and watch status to know when it has landed.

Roll back

Every deploy is recorded. List them, then roll back to one:

curl -s -H "$AUTH" \
  "$BASE/workspaces/$WORKSPACE_ID/vpcs/$VPC_ID/services/$SERVICE_ID/deployments"

curl -s -X POST -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"deployment_id":"7c4a..."}' \
  "$BASE/workspaces/$WORKSPACE_ID/vpcs/$VPC_ID/services/$SERVICE_ID/rollback"

A rollback is itself a deployment, so it appears in the history too.

Environment variables

PUT /env sets variables in one call. It takes the full list you want applied:

curl -s -X PUT -H "$AUTH" -H "Content-Type: application/json" \
  -d '{
        "variables": [
          {"key": "LOG_LEVEL", "value": "info"},
          {"key": "DATABASE_URL", "secret_id": "9f21...", "secret_key": "url"}
        ]
      }' \
  "$BASE/workspaces/$WORKSPACE_ID/vpcs/$VPC_ID/services/$SERVICE_ID/env"

Each entry is either a literal or a reference to a shared secret:

A secret reference means the value is never stored on the service, and updating the secret updates every service that links to it. Changing environment variables triggers a rollout so the new values take effect.

Builds

You can have SMLL build the image rather than pushing one yourself.

Disk backups

For services with a persistent volume:

Restoring scales the service down, replaces the volume contents, and scales it back up. Expect downtime for the length of the restore.

Shell access

GET /{serviceID}/exec upgrades to a WebSocket and attaches a shell to a running pod. It authenticates by query parameter, not the Authorization header, because browsers cannot set headers on a WebSocket handshake.

In practice, use the CLI:

smll services exec my-app
# or
smll shell my-app

Status values

status on a service reflects reality in the cluster, resynced on each read:

Because status is resynced against Kubernetes on every read, a service that died outside the platform still shows as crashed on the next GET.