Skip to main content

Pub/Sub quickstart

In about 10 minutes you will create a topic, attach a subscription, publish a message, pull it back, acknowledge it, and clean up. Every command shows its expected output so you can verify each step.

Before you begin​

  • You have a platform account. There is no self-service sign-up — ask your administrator for an account or an invitation link.
  • You have the platformctl CLI installed.
  • You are an admin of your project. Members can publish and pull, but creating topics and subscriptions requires the admin role. See projects and access.
  • You can reach the Pub/Sub API. In this alpha there is no public API hostname: you need either kubectl access to the cluster (for a port-forward, shown below) or an API endpoint provided by your administrator.
  • For the curl steps you need a token: your session token or an API key.
No cloud bill

This platform runs on your own cluster. Nothing in this quickstart creates a charge on a cloud provider account.

1. Log in and pick your project​

platformctl login

The CLI caches a session token that lasts 12 hours. Then tell it which project to use. Your project ID is the UUID in the console URL (#/projects/<id>/...), or run platformctl projects list.

export CAI_PROJECT="<your-project-id>"

2. Set up API access for curl​

Creating topics and subscriptions is not in the CLI yet, so this quickstart uses curl for those steps. Port-forward the Pub/Sub API and export your token:

kubectl -n cai-system port-forward svc/pubsub-api 8080:8080 &
export API=http://localhost:8080
export CAI_TOKEN="<your-api-key-or-session-token>"

If your administrator gave you a reachable API endpoint instead, set API to that and skip the port-forward.

3. Create a topic​

A topic is a named channel. This one reserves 16 MiB of your project's 1 GiB storage budget and drops its oldest messages if it ever fills up (discard: old).

curl -sX POST "$API/v1/projects/$CAI_PROJECT/topics" \
  -H "Authorization: Bearer $CAI_TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"orders","max_bytes":"16Mi","discard":"old"}'

You should see:

{"name":"orders","path":".../topics/orders","max_bytes":"16Mi","discard":"old",
 "created_at":"...","address":"persistent://p-<short>/main/orders",
 "state":{"phase":"Pending","ready":false,...}}

The topic exists immediately; "phase":"Pending" means the broker side is still converging, which takes a few seconds.

4. Create a subscription — before you publish​

Subscriptions first

A message is kept only while a subscription owes an acknowledgement for it. Publishing to a topic with no subscriptions succeeds — and the message is quietly reclaimed. Always create the subscription first.

curl -sX POST "$API/v1/projects/$CAI_PROJECT/topics/orders/subscriptions" \
  -H "Authorization: Bearer $CAI_TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"workers","type":"shared","ack_deadline_seconds":30,"start_from":"all"}'

You should see:

{"name":"workers","topic":"orders","type":"shared","ack_deadline_seconds":30,
 "max_deliver":5,"start_from":"all","max_ack_pending":1000,
 "deliver":{"mode":"pull"},"created_at":"...","state":{...}}

type: shared means the subscription behaves like a queue: if you run several consumers, each message goes to one of them.

5. Publish a message​

Any project member can publish. The CLI covers this:

platformctl pubsub topics publish orders --message "hello" --attribute region=eu

You should see a message ID in ledger:entry form:

1234:0

That ID is your proof the message was stored.

6. Pull it back and acknowledge it​

platformctl pubsub subscriptions pull workers --topic orders --max 10 --ack

You should see the message table on stdout and the acknowledgement on stderr:

ID      KEY  DATA
1234:0  -    hello
acknowledged 1 message(s)

--ack acknowledges the messages after pulling them, so they are never redelivered. Without --ack, anything you pull comes back after the ack deadline (30 seconds here).

7. Check your storage budget​

curl -s "$API/v1/projects/$CAI_PROJECT/pubsub/quota" \
  -H "Authorization: Bearer $CAI_TOKEN"

You should see:

{"limit_bytes":1073741824,"allocated_bytes":16777216,...,
 "human":"16.0MiB of 1.0GiB claimed by 1 topic(s); 0B stored, 0B unacknowledged",
 "topics":1,"provisioned":true}

Note that the topic claims its full max_bytes (16 MiB) the moment it exists, even while empty. The budget is spent by claim, not by stored bytes — see Topics and subscriptions.

Clean up​

Deleting the topic also deletes its subscriptions:

curl -sX DELETE "$API/v1/projects/$CAI_PROJECT/topics/orders" \
  -H "Authorization: Bearer $CAI_TOKEN"

You should see:

{"name":"orders","status":"deleting"}

Verify it's gone (deletion completes within a few seconds):

curl -s -o /dev/null -w '%{http_code}\n' "$API/v1/projects/$CAI_PROJECT/topics/orders" \
  -H "Authorization: Bearer $CAI_TOKEN"

You should see:

404

Finally, stop the port-forward:

kill %1

Next steps​