Key Concepts
KakaoCloud Pub/Sub is a non-installation message queue (MQ) service for high-volume events and data analytics. You can classify and manage message data using topics and subscriptions.
Architecture
Pub/Sub architecture
Message
A message is the data and attributes delivered to a subscription.
- By default, messages are delivered at least once, regardless of order.
- Messages may rarely be delivered more than once even after acknowledgment.
(Duplicate messages share the same unique message ID as the original.)
Topic
A topic is a logical grouping unit for a specific message or event type.
Multiple subscriptions can be attached to a single topic.
Subscription
Messages published to a topic are received through subscriptions. The following three types of subscriptions are supported:
| Type | Description | Acknowledgment |
|---|---|---|
| Pull | User manually requests message delivery - Includes message request and acknowledgment | - Requires explicit acknowledgment (ack) after message is received - Retries if not acknowledged: ㄴ When acknowledgment is not received within the wait time ㄴ When acknowledgment deadline is extended (action: skip) |
| Push | Pub/Sub delivers messages automatically - Requires an HTTP/HTTPS server endpoint - Security group rules must be configured for the endpoint - Message Push is available only to endpoint URLs using KakaoCloud public IPs per region | - Automatically acknowledged upon receiving HTTP status code 102, 200, 201, 202, or 204 - Retries if: ㄴ No HTTP response from user-defined endpoint within wait time ㄴ Non-success HTTP status code is returned |
| Object Storage | Messages are exported to a bucket via Pub/Sub - Requires an Object Storage bucket | No acknowledgment required |
Subscription status and lifecycle
A subscription can exist in various states such as created, updated, or deleted.
These states allow users to understand the current lifecycle status and manage accordingly.
Available actions vary depending on the state. Errors or policies may limit usage, so it's important to regularly check the status and take action as needed.
Refer to the subscription lifecycle chart below for stable operations.
Subscription lifecycle
Subscription status
Details of each subscription status are as follows:
| Status | Description |
|---|---|
Active | Active and functioning |
Creating | In progress (creating subscription) |
Deleting | In progress (deleting subscription) |
Updating | In progress (updating subscription) |
Seeking | In progress (rewinding subscription) |
Error | Subscription encountered an issue and cannot operate normally - Only deletion is allowed |
Expired | No recent activity; disabled due to expiration policy - Internal resources are deleted; only deletion is allowed * Expiration Policy: - Pull, Push: Becomes Expired if unprocessed messages ≥ 10,000 for 1 hour- Object Storage: Does not transition to Expired |
InvalidBucket | Associated Object Storage bucket was deleted - Automatically changes to Export stopped status - Can be reused by updating bucket info |
Unauthorized | Bucket permission for Object Storage subscription has changed - Automatically changes to Export stopped status - Can be reused after correcting bucket permissions |
Subscriber
A subscriber is an entity that receives and processes messages for a specific topic.
Subscribers subscribe to a topic and are notified whenever a new message is published, then process those messages.
Publisher
A publisher is an entity that creates data or events and publishes them to the Pub/Sub system.
Publishers generate or collect messages for a specific topic and deliver them to all subscribers of that topic.
Service agent
The Pub/Sub service agent is created automatically when the Pub/Sub service starts.
For more information, see the Service agent account documentation.
Role and permission
Pub/Sub role management follows KakaoCloud's IAM role-based access control (RBAC).
Default project roles (Project Manager, Project Member, Project Leader) defined in IAM provide project-level permissions.
However, management of Pub/Sub resources (topics, subscriptions) and message-handling permissions must be granted using dedicated Pub/Sub service roles.
See IAM > Key concepts and Project role types for details.
Relationship between project roles and service roles
- Project roles: Provide permissions to manage project resources
- Pub/Sub service roles: Provide permissions to manage topics and subscriptions, and handle messages
Due to enhanced granularity in Pub/Sub role-based permissions, message receive permission will be removed from the Project Leader role starting September 7, 2025.
If message reception is required, assign the Pub/Sub Subscriber role.
Pub/Sub role-based permissions
Pub/Sub provides four role types. Each role allows fine-grained control over actions such as topic/subscription creation, editing, viewing, deletion, and message processing.
| Role | Permissions |
|---|---|
| Pub/Sub Manager | Full management permissions for Pub/Sub resources (topics and subscriptions) - Create, update, delete topics and subscriptions - View topics and subscriptions - Publish messages to topics - Receive and process messages - Rewind subscription timestamp - Configure export channels for Object Storage subscriptions *Includes all permissions of Publisher, Subscriber, and Viewer |
| Pub/Sub Publisher | Publish messages to topics |
| Pub/Sub Subscriber | Receive and process messages |
| Pub/Sub Viewer | View topics and subscriptions |