CPLN Task Runner

Overview

Control Plane Task Runner is a self-hosted HTTP task queue and scheduler, similar to Google Cloud Tasks. You enqueue a task over HTTP and the workers deliver it to its target URL, with automatic retries, delayed and scheduled execution, per-client rate limiting and a circuit breaker. This template deploys the API, the workers, and the Redis Sentinel cluster they persist to.

This template deploys into an existing GVC that you already have. It does not create, provision or manage a GVC.

/v1/enqueue has no authentication, which is why api.public.enabled defaults to false. An unknown client_id is accepted and auto-registered rather than rejected, so a client ID is not a credential. With public access on, anyone who finds the endpoint can make a worker send outbound HTTP requests with a method, headers and body of their choosing. See Public Access and the Open Queue.

What Gets Created

Resource	Name	Purpose	Optional
Workload	`RELEASE_NAME-task-runner-api`	HTTP API on port 8080 for enqueuing tasks and the `/admin/*` endpoints (serverless, autoscales 1 to 3)	`api.enabled: true` (default)
Workload	`RELEASE_NAME-task-runner-worker`	Delivers queued tasks to their target URLs; health port 8082 (serverless, autoscales 1 to 5)	`worker.enabled: true` (default)
Workload	`RELEASE_NAME-redis`	Redis task store (stateful, 3 replicas)	—
Workload	`RELEASE_NAME-sentinel`	Redis Sentinel on port 26379, tracks the Redis primary (stateful, 3 replicas)	—
Volume set	`RELEASE_NAME-redis-vs`	Redis data, daily snapshots kept 7 days	`redis.redis.persistence.enabled: true` (default)
Volume set	`RELEASE_NAME-sentinel-vs`	Sentinel state	`redis.sentinel.persistence.enabled: true` (default)
Secret	`task-runner-secrets`	Dictionary holding the bundled Redis and Sentinel passwords (name set by `secretName`)	`createSecret: true` (default)
Secret	`RELEASE_NAME-redis-config`, `RELEASE_NAME-sentinel-config`	Redis and Sentinel configuration	—
Identity	`RELEASE_NAME-task-runner-identity`	Identity used by the API and worker workloads	—
Policy	`RELEASE_NAME-task-runner-policy`	Grants that identity `reveal` on the Redis password secret and on your admin key secret, nothing else	—
Identity and policy	`RELEASE_NAME-redis-identity`, `RELEASE_NAME-sentinel-identity` and matching `-policy`	Grant Redis and Sentinel `reveal` on their own configuration and password secrets	—

The policies grant only the reveal permission on secrets. The template’s identities have no cloud access and no permission on any other Control Plane resource.

Prerequisites

One secret must exist before you install: the admin API key. The /admin/* endpoints create, edit and delete clients and rate-limit tiers, and they are guarded by the X-Admin-Key header. Secrets are org-level, so no GVC flag is involved.

Create the admin key secret

An opaque secret with encoding plain whose payload is the key itself:

printf '%s' "$(openssl rand -hex 32)" | cpln secret create-opaque --name SECRET_NAME --encoding plain -f -

Use printf, not echo. A trailing newline from echo becomes part of the key and then has to be sent in every admin request. Set api.admin.apiKeySecretName to this name.

Read the key back later

Pass -o yaml. A bare cpln secret reveal prints only a summary table, not the payload:

cpln secret reveal SECRET_NAME -o yaml

Create the secret before installing, or the deployment wedges silently. An install that names a secret which does not exist still reports success, and the API workload then never starts while the other workloads come up normally. The container never runs, so cpln logs returns zero lines. The one place the reason appears is status.versions[].message:

cpln workload get-deployments RELEASE_NAME-task-runner-api --gvc GVC_NAME -o yaml

The secret SECRET_NAME no longer exists. Workload updates are paused until the
secret is added or the reference to the secret removed.

Use get-deployments. Plain cpln workload get has no versions key. Once the secret exists the workload recovers on its own after several minutes, or run cpln workload force-redeployment RELEASE_NAME-task-runner-api --gvc GVC_NAME to skip the wait.

Nothing else is required. The bundled Redis and Sentinel passwords are ordinary values, since only the API and worker containers use them, but they are used exactly as written, so replace the change-me- defaults at install time.

Installation

Create the admin key secret first, then install with its name and your own Redis and Sentinel passwords:

cpln helm install RELEASE_NAME oci://ghcr.io/controlplane-com/templates/cpln-task-runner \
  --version 1.3.0 --gvc GVC_NAME \
  --set api.admin.apiKeySecretName=SECRET_NAME \
  --set redis.redisPassword='YOUR-REDIS-PASSWORD' \
  --set redis.sentinelPassword='YOUR-SENTINEL-PASSWORD'

For the other install methods, follow the instructions for your preferred tool:

UI

Browse, install, and manage templates visually

CLI

Manage templates from your terminal

Terraform

Declare templates in your Terraform configurations

Pulumi

Declare templates in your Pulumi programs

Configuration

Image

The same image runs both the API and the worker:

image: controlplanecorporation/cpln-task-runner:0.4

API Workload

api:
  enabled: true              # false = no API workload
  replicas:
    min: 1                   # autoscaling range
    max: 3
  port: 8080
  public:
    enabled: false           # DEFAULT. /v1/enqueue has no authentication; read Public Access and the Open Queue first
    pathPrefix: ""           # not used for routing by this chart version
  admin:
    apiKeySecretName: my-cpln-task-runner-admin-key   # REQUIRED: opaque secret whose payload is the X-Admin-Key value; "" is rejected while public.enabled is true
  resources:
    cpu: 500m
    memory: 512Mi
  env:
    logLevel: info           # debug, info, warn, error
    otelEndpoint: ""         # OpenTelemetry endpoint; empty disables tracing
    connectRetries: 30       # Redis connection attempts at startup
    retryIntervalSec: 2      # seconds between those attempts

Setting api.admin.apiKeySecretName to "" turns admin authentication off entirely. The chart permits that only while api.public.enabled is false.

Worker Workload

worker:
  enabled: true              # false = no worker workload
  replicas:
    min: 1                   # autoscaling range
    max: 5
  port: 8082                 # health checks only
  resources:
    cpu: 1
    memory: 1Gi
  env:
    logLevel: info
    concurrency: 10          # concurrent tasks per replica
    taskTimeoutSec: 1800     # per-task timeout in seconds
    maxRetry: 5              # maximum delivery attempts
    allowPrivateUrls: false  # true lets tasks target private and internal URLs
    cbFailureThreshold: 5    # circuit breaker: failures before it opens
    cbTimeoutSec: 30         # circuit breaker: seconds before it retries
    connectRetries: 30
    retryIntervalSec: 2
    otelEndpoint: ""

Workers fetch whatever URL a task carries. allowPrivateUrls: false is what keeps an enqueued task off internal addresses.

Secrets and Redis

createSecret: true                  # false = bring your own secret (see below)
secretName: task-runner-secrets     # org-level name of the secret this chart creates

redis:
  redisPassword: change-me-cpln-task-runner-redis        # used as written when createSecret is true; change it
  sentinelPassword: change-me-cpln-task-runner-sentinel  # used as written when createSecret is true; change it
  redis:
    auth:
      fromSecret:
        enabled: true
        name: task-runner-secrets   # must equal secretName, or your own secret's name
        passwordKey: redis-password
    persistence:
      enabled: true                 # false = no volume set, Redis data is not persisted
  sentinel:
    auth:
      fromSecret:
        enabled: true
        name: task-runner-secrets
        passwordKey: redis-sentinel-password
    persistence:
      enabled: true

The admin API key is never in this secret. It is always your own opaque secret, whatever createSecret is set to.

secretName is an org-level name and is not prefixed with the release name. A second install in the same org needs a different secretName, with both fromSecret.name values changed to match.
To bring your own secret, set createSecret: false, create a dictionary secret holding the two keys named by the passwordKey fields, and point both fromSecret.name values at it:

cpln secret create-dictionary --name SECRET_NAME \
  --entry redis-password='YOUR-REDIS-PASSWORD' \
  --entry redis-sentinel-password='YOUR-SENTINEL-PASSWORD'

Connecting

What	Address	Notes
API (internal, default)	`RELEASE_NAME-task-runner-api.GVC_NAME.cpln.local:8080`	Reachable from workloads in the same GVC. No credential for `/v1/`; `X-Admin-Key` for `/admin/`
API (public, opt-in)	the workload’s canonical endpoint	Only with `api.public.enabled: true`. Read it from `status.canonicalEndpoint`
Redis Sentinel	`RELEASE_NAME-sentinel.GVC_NAME.cpln.local:26379`	Master name `mymaster`; used by the API and worker
Admin key	your opaque secret	`cpln secret reveal SECRET_NAME -o yaml`
Redis passwords	`task-runner-secrets` (the `secretName` value)	`cpln secret reveal task-runner-secrets -o yaml`

Read the public endpoint, when enabled:

cpln workload get RELEASE_NAME-task-runner-api --gvc GVC_NAME -o yaml

To reach the private API from your machine, open a tunnel and check readiness. This uses the same /health/ready path as the workload readiness probe:

cpln port-forward RELEASE_NAME-task-runner-api 8080:8080 --gvc GVC_NAME
curl http://127.0.0.1:8080/health/ready

To see what happened to a delivered task, read the worker logs. The second form filters on the server, so put any text you expect in the line between the quotes:

cpln logs '{gvc="GVC_NAME", workload="RELEASE_NAME-task-runner-worker"}' --limit 50 --since 10m
cpln logs '{gvc="GVC_NAME", workload="RELEASE_NAME-task-runner-worker"} |= "ERROR"' --limit 50 --since 10m

Enqueuing Tasks

Post a task to /v1/enqueue. With the default private API, send it from a workload in the same GVC to http://RELEASE_NAME-task-runner-api.GVC_NAME.cpln.local:8080, or through the tunnel above to http://127.0.0.1:8080:

curl -X POST http://127.0.0.1:8080/v1/enqueue \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "my-service",
    "queue": "default",
    "task": {
      "url": "https://api.example.com/webhook",
      "method": "POST",
      "headers": {"Content-Type": "application/json"},
      "body": "{\"event\": \"user.created\"}"
    }
  }'

This request carries no credential, and none exists.

Admin Endpoints

Every /admin/* request needs the X-Admin-Key header, whose value is the payload of your api.admin.apiKeySecretName secret:

# List clients
curl http://127.0.0.1:8080/admin/clients \
  -H "X-Admin-Key: YOUR-ADMIN-KEY"

# Create or update a client
curl -X POST http://127.0.0.1:8080/admin/clients/set \
  -H "X-Admin-Key: YOUR-ADMIN-KEY" \
  -H "Content-Type: application/json" \
  -d '{"client_id": "new-service", "tier": "premium", "enabled": true}'

Rate Limiting

Rate limits apply per client, and a client tier is assigned through the admin API:

Tier	Requests/min	Max Concurrent
`free`	10	1
`basic`	100	5
`premium`	1,000	20
`enterprise`	5,000	50

OpenTelemetry

Set otelEndpoint under api.env and worker.env to export traces. In the GVC settings, set the Tracing Provider to Control Plane, then use the built-in HTTP collector endpoint:

tracing.controlplane:4318

Operations

Backing Up

The Redis volume set RELEASE_NAME-redis-vs takes a snapshot every day and keeps each one for 7 days. List the snapshots:

cpln volumeset snapshot get RELEASE_NAME-redis-vs --gvc GVC_NAME

Restoring a Backup

A restore procedure for this template has not been verified. Do not rely on the snapshots as a tested recovery path for queued tasks.

Rotating the Admin Key

Apply the whole secret with a new payload, confirm it, then force a redeployment of the API. A running replica keeps the old key until it is redeployed:

cat > rotate.yaml <<'EOF'
kind: secret
name: SECRET_NAME
type: opaque
data:
  encoding: plain
  payload: NEW-VALUE
EOF
cpln apply -f rotate.yaml
cpln secret reveal SECRET_NAME -o yaml
cpln workload force-redeployment RELEASE_NAME-task-runner-api --gvc GVC_NAME

Every admin caller must then send the new key.

Upgrading From 1.2.x

Two defaults change, and both break an existing workflow that relied on the old behaviour.

	`1.2.x`	`1.3.0`
Admin API key	`api.env.adminApiKey`, a value shipped empty, which disabled admin authentication	`api.admin.apiKeySecretName`, a required opaque secret you create
Public access	`api.public.enabled: true`	`api.public.enabled: false`
Bundled Redis passwords	A working published value	`change-me-` placeholders
`redis.admin.fromSecret`	Present	Removed. The admin key is its own secret whatever `createSecret` is set to

An upgrade that still carries api.env.adminApiKey or redis.admin.fromSecret, or an empty apiKeySecretName while public access is on, is rejected at render before anything is applied.

Create the admin key secret

Follow Prerequisites. Put the key you use today into it so existing admin callers keep working.

Drop the removed keys from your values

Remove api.env.adminApiKey and redis.admin.fromSecret, and set api.admin.apiKeySecretName instead.

Decide about public access

api.public.enabled now defaults to false. Read Public Access and the Open Queue before setting it back to true.

Upgrade

cpln helm upgrade RELEASE_NAME oci://ghcr.io/controlplane-com/templates/cpln-task-runner \
  --version 1.3.0 --gvc GVC_NAME \
  --set api.admin.apiKeySecretName=SECRET_NAME

The first upgrade after an install re-applies the bundled Redis even with identical values, which restarts it, and the API returns errors briefly while Redis comes back. Later upgrades are clean.

The bundled Redis and Sentinel passwords keep whatever you already set. Only their defaults changed.

Public Access and the Open Queue

api.public.enabled is false by default. Turning it on exposes the following:

/v1/enqueue requires no credential. There is no header, token or signature to supply.
An unknown client_id is auto-registered, not rejected. A client ID is therefore not a secret and not a control.
The API becomes a request relay. Anyone reaching it can make a worker send outbound HTTP with the method, headers and body they choose. worker.env.allowPrivateUrls: false keeps those requests off internal addresses.
/metrics is unauthenticated and its labels list every client_id.

No setting closes this, because the application has no client authentication. If you need submissions from outside the GVC, put an authenticating proxy of your own in front of the API and leave api.public.enabled at false. Access changes can take several minutes to take effect, so re-test over that window.

Scaling and Availability

The API and worker are serverless workloads that autoscale on concurrent requests within api.replicas and worker.replicas. Raise worker.replicas.max or worker.env.concurrency for more delivery throughput. Redis runs as three replicas with three Sentinels, which elect a new primary if the current one fails.

Troubleshooting

The API workload never starts and cpln logs returns nothing

Cause: the secret named by api.admin.apiKeySecretName does not exist. get-deployments shows

The secret SECRET_NAME no longer exists. Workload updates are paused until the secret is added or the reference to the secret removed.

Fix: create the secret as in Prerequisites. The workload recovers on its own, or run cpln workload force-redeployment RELEASE_NAME-task-runner-api --gvc GVC_NAME.

Install fails with apiKeySecretName is empty while api.public.enabled is true

Cause: api.admin.apiKeySecretName is "" and public access is on. The chart refuses to publish unauthenticated admin endpoints.Fix: set api.admin.apiKeySecretName to your admin key secret, or set api.public.enabled: false.

Install or upgrade fails with api.env.adminApiKey was REMOVED

Cause: your values still carry the 1.2.x admin key (api.env.adminApiKey or redis.admin.fromSecret).Fix: follow Upgrading From 1.2.x.

Admin requests are rejected

Cause: the X-Admin-Key header is missing or does not match the secret payload, for example because the key was created with echo and carries a trailing newline, or the secret was rotated without a redeployment.Fix: read the key with cpln secret reveal SECRET_NAME -o yaml, and redeploy the API after any rotation.

Tasks to internal addresses are never delivered

Cause: worker.env.allowPrivateUrls is false, so workers refuse private and internal targets.Fix: set it to true only if you accept that any enqueued task can then reach anything the worker can route to.

Important Notes

Create the admin key secret before installing. A missing secret wedges the API with no log output; the reason is in status.versions[].message.
Leave api.public.enabled at false unless an authenticating proxy fronts the API. /v1/enqueue is unauthenticated and auto-registers unknown client IDs.
Change the change-me- Redis and Sentinel passwords at install time. Once the volumes are initialised, changing them requires uninstalling (which deletes the volume sets) and reinstalling.
secretName is org-wide. Give each install in the same org its own secretName and matching fromSecret.name values.
Force a redeployment after rotating the admin key. A running replica keeps the old key.

External References

CPLN Task Runner Template

View the source files, default values, and chart definition

Task Runner Image

The container image used by the API and worker

Control Plane Secrets

Secret types and how workloads reference them

OpenTelemetry Documentation

OpenTelemetry distributed tracing documentation

Template Catalog

Templates

Overview

What Gets Created

Prerequisites

Installation

UI

CLI

Terraform

Pulumi

Configuration

Image

API Workload

Worker Workload

Secrets and Redis

Connecting

Enqueuing Tasks

Admin Endpoints

Rate Limiting

OpenTelemetry

Operations

Backing Up

Restoring a Backup

Rotating the Admin Key

Upgrading From 1.2.x

Public Access and the Open Queue

Scaling and Availability

Troubleshooting

Important Notes

External References

CPLN Task Runner Template

Task Runner Image

Control Plane Secrets

OpenTelemetry Documentation

​Overview

​What Gets Created

​Prerequisites

​Installation

UI

CLI

Terraform

Pulumi

​Configuration

​Image

​API Workload

​Worker Workload

​Secrets and Redis

​Connecting

​Enqueuing Tasks

​Admin Endpoints

​Rate Limiting

​OpenTelemetry

​Operations

​Backing Up

​Restoring a Backup

​Rotating the Admin Key

​Upgrading From 1.2.x

​Public Access and the Open Queue

​Scaling and Availability

​Troubleshooting

​Important Notes

​External References

CPLN Task Runner Template

Task Runner Image

Control Plane Secrets

OpenTelemetry Documentation

Overview

What Gets Created

Prerequisites

Installation

Configuration

Image

API Workload

Worker Workload

Secrets and Redis

Connecting

Enqueuing Tasks

Admin Endpoints

Rate Limiting

OpenTelemetry

Operations

Backing Up

Restoring a Backup

Rotating the Admin Key

Upgrading From 1.2.x

Public Access and the Open Queue

Scaling and Availability

Troubleshooting

Important Notes

External References