Service Reference
This section provides detailed API reference documentation for all SPOG services, including their NATS endpoints, events, subscriptions, and dependencies.
Control Plane Services
Control plane services run in the center namespace and provide centralized management capabilities.
center-middleware
Central middleware for cluster discovery, service registry, and request routing
Type: control-plane | Version: 1.0.0
Endpoints
| Endpoint | Description | Request | Response |
|---|---|---|---|
GetClusterInfo |
Retrieve information for a specific cluster (internal, no auth) | cluster_id (required) |
cluster_id, labels, connected |
GetAllClusters |
Retrieve all clusters (internal, no authorization) | - | clusters |
GetClusterServices |
Retrieve services available in all clusters (internal) | - | clusters |
GetClusterInfo |
Retrieve information for a specific cluster (with authorization) | cluster_id (required) |
cluster_id, labels, connected |
GetAllClusters |
Retrieve all clusters visible to current user (with authorization) | - | clusters |
GetClusterUpdates |
Check for available cluster updates (push-to-pull pattern) | - | updates_available, timestamp |
GetClusterServices |
Retrieve services available in clusters (with authorization) | - | clusters |
GetServices |
Retrieve central service registry state | - | services |
Events Emitted
| Event | Version | Description |
|---|---|---|
ClusterInfoAdd |
v1 |
Emitted when a new cluster is discovered and added to the registry |
ClusterInfoUpdate |
v1 |
Emitted when cluster information is updated |
ClusterUpdateAvailable |
v1 |
Notification that cluster updates are available (push-to-pull) |
ClusterServicesUpdate |
v1 |
Emitted when cluster services state changes |
Update |
v1 |
Emitted when service registry state changes |
Event Subscriptions
| Event | Version | Source Service | Description |
|---|---|---|---|
AnnounceCluster |
v1 |
cluster-info |
Subscribe to cluster announcements from edge clusters |
Update |
v1 |
service-registry |
Subscribe to service registry updates from edge clusters |
Dependencies
| Service | Version | Endpoints |
|---|---|---|
cluster-info |
v1 |
GetClusterInfo |
policy |
v1 |
CanReadClusterSnapshot |
service-registry |
v1 |
GetServices |
center-policy
Authorization and authentication service using REGO policies
Type: control-plane | Version: 1.0.0 | NATS Namespace: glass.public
Endpoints
| Endpoint | Description | Request | Response |
|---|---|---|---|
GetPermissions |
Get permissions for a user across multiple clusters | token (required), cluster_ids (required) |
clusters, claims |
CanCallClusterEndpoint |
Check if user can call a specific endpoint in a cluster | token (required), cluster_id (required), endpoint_name (required), args |
allowed, claims |
CanCallClustersEndpoint |
Check if user can call a specific endpoint across multiple clusters | token (required), cluster_ids (required), endpoint_name (required), args |
clusters, claims |
CanReadClusterSnapshot |
Check if user can read a specific cluster snapshot | token (required), cluster_ids (required), snapshot_name (required) |
allowed_clusters, claims |
CheckUserNatsAccess |
Verify user has NATS access and get allowed pub/sub topics | token (required) |
allowed, principal, pub_topics, sub_topics, claims |
CheckMachineNatsAccess |
Verify machine has NATS access and get allowed pub/sub topics | token (required) |
allowed, principal, pub_topics, sub_topics, claims |
GetGlobalFlags |
Get global permission flags for specified terms | token (required), terms (required), arguments |
results, claims |
WhoAmI |
Get the authenticated identity from a token | token (required) |
* |
DebugListPolicyFiles |
List all loaded policy files with metadata | - | files |
DebugGetPolicyFile |
Retrieve the content of a specific policy file | path (required) |
content, package, rules |
DebugEvaluateQuery |
Evaluate a REGO query with optional policy overrides | query (required), input (required), policy_overrides |
result, evaluation_time_ms |
DebugSimulateEndpoint |
Simulate policy evaluation for an endpoint with custom clusters | endpoint (required), input (required), cluster_definitions (required) |
results |
DebugRunTestSuite |
Run a batch of policy test cases | test_cases (required) |
summary, results |
DebugGetPolicySchema |
Get the input schema for policy evaluation | - | input_schema |
Dependencies
| Service | Version | Endpoints |
|---|---|---|
cluster-discovery |
v1 |
- |
center-service-multiplexer
Multi-cluster service call router with authorization enforcement
Type: control-plane | Version: 1.0.0 | NATS Namespace: glass.public
Endpoints
| Endpoint | Description | Request | Response |
|---|---|---|---|
Call |
Multiplex a service call across multiple clusters with authorization | call (required), clusterIDs (required), majorVersion (required), timeout |
{cluster_id} |
Events Emitted
| Event | Version | Description |
|---|---|---|
MultiplexedCall |
v1 |
Audit event emitted for every multiplexed call |
Dependencies
| Service | Version | Endpoints |
|---|---|---|
policy |
v1 |
CanCallClustersEndpoint |
{dynamic-target-service} |
{majorVersion} |
- |
center-snapshot-mirror
Mirror snapshots from cluster services to control plane with authorization
Type: control-plane | Version: 1.0.0 | NATS Namespace: glass.public
Endpoints
| Endpoint | Description | Request | Response |
|---|---|---|---|
Get |
Retrieve consolidated cluster snapshot with authorization filtering | - | clusters |
GetCluster |
Retrieve state for a specific cluster with authorization | cluster_id (required) |
clusters |
GetClusters |
Retrieve state for multiple clusters with authorization | cluster_ids (required) |
clusters |
Events Emitted
| Event | Version | Description |
|---|---|---|
Update |
v1 |
Emitted when cluster snapshot state changes |
Event Subscriptions
| Event | Version | Source Service | Description |
|---|---|---|---|
{target-update-event} |
{target-event-version} |
{target-service} |
Subscribe to target service update events per cluster (configurable) |
Dependencies
| Service | Version | Endpoints |
|---|---|---|
policy |
v1 |
CanReadClusterSnapshot |
dynamic-snapshots |
v1 |
GetSnapshotState |
{target-service} |
{target-version} |
- |
center-cluster-overview
Cluster overview service for listing clusters and managing instance sets
Type: control-plane | Version: 1.0.0 | NATS Namespace: glass.public
Endpoints
| Endpoint | Description | Request | Response |
|---|---|---|---|
ListClusters |
List all clusters with their current state, labels, and detailed pod information | - | status |
ListClusterIds |
List all cluster IDs and their labels to identify which cluster to query | - | status |
GetClusterStatus |
Get detailed status of a specific cluster including products, instance sets, and pods | cluster_id (required) |
status |
GetProductStatus |
Get status of a specific product (recursor, authoritative, dnsdist) in a cluster | cluster_id (required), product (required) |
status |
RestartInstanceSet |
Restart an instance set in a cluster | instance_set_name (required), cluster_id (required) |
status |
ListClusterIssues |
Get health summary of all clusters focusing on issues (disconnected clusters, non-running pods) | - | status |
Dependencies
| Service | Version | Endpoints |
|---|---|---|
center-middleware |
v1 |
GetAllClusters |
cc-state |
v1 |
Get |
multiplexer |
v1 |
Call |
center-event-monitor
Event monitoring service for audit logging
Type: control-plane | Version: 1.0.0 | NATS Namespace: glass.internal
Event Subscriptions
| Event | Version | Source Service | Description |
|---|---|---|---|
MultiplexedCall |
v1 |
multiplexer |
Monitors MultiplexedCall events for audit purposes (configurable via flags) |
global-config
Watches a config file and exposes it as a NATS service snapshot
Type: control-plane | Version: 1.0.0 | NATS Namespace: glass.public
Endpoints
| Endpoint | Description | Request | Response |
|---|---|---|---|
Get |
Retrieves the current global configuration state | - | * |
Events Emitted
| Event | Version | Description |
|---|---|---|
Update |
v1 |
Emitted when the watched configuration file changes |
auth-users
Handle authorization of user tokens for SPOG NATS access
Type: control-plane | Version: 0.0.1 | NATS Namespace: glass.public
Endpoints
| Endpoint | Description | Request | Response |
|---|---|---|---|
Handle |
System NATS authentication request handler - validates user tokens and returns NATS permissions | ConnectOptions.Token (required), UserNkey (required), Server.ID (required) |
Jwt, Error |
Dependencies
| Service | Version | Endpoints |
|---|---|---|
policy |
v1 |
CheckUserNatsAccess |
Instrumentation Services
Instrumentation services are deployed per CloudControl cluster and provide local data collection and processing.
edge-disco
Edge discovery service providing service registry and cluster announcements
Type: instrumentation | Version: 1.0.0 | NATS Namespace: glass.internal
Endpoints
| Endpoint | Description | Request | Response |
|---|---|---|---|
GetServices |
Retrieves the current service registry state for the cluster | - | services |
GetClusterInfo |
Retrieves current cluster information and labels | - | cluster_id, labels |
Heartbeat |
Cluster liveness check endpoint | - | status, timestamp |
Events Emitted
| Event | Version | Description |
|---|---|---|
Update |
v1 |
Emitted when service discovery state changes (service announce/signoff) |
AnnounceCluster |
v1 |
Cluster announcement heartbeat (emitted on startup and every 30 seconds) |
Event Subscriptions
| Event | Version | Source Service | Description |
|---|---|---|---|
announce |
v1 |
service-discovery |
Subscribes to service announcements within the cluster to populate registry |
signoff |
v1 |
service-discovery |
Subscribes to service signoff notifications to remove services from registry |
edge-dynamic-snapshots
Dynamic snapshots service for real-time state monitoring and polling
Type: instrumentation | Version: 1.0.0 | NATS Namespace: glass.internal
Endpoints
| Endpoint | Description | Request | Response |
|---|---|---|---|
GetSnapshotState |
Retrieves the current state of a dynamic snapshot (creates if not exists) | name (required), serviceName (required), serviceVersion (required), endpoint (required), arguments, pollingInterval |
* |
Events Emitted
| Event | Version | Description |
|---|---|---|
{snapshotName}Update |
v1 |
Emitted when a snapshot's state changes during polling (dynamic event name) |
Dependencies
| Service | Version | Endpoints |
|---|---|---|
dynamic |
`` | - |
dns-check
DNS query service for debugging DNS infrastructure
Type: instrumentation | Version: 1.0.0 | NATS Namespace: glass.internal
Endpoints
| Endpoint | Description | Request | Response |
|---|---|---|---|
Query |
Execute DNS queries against discovered targets | dnsQuery (required), target (required), options |
queryResults |
Events Emitted
| Event | Version | Description |
|---|---|---|
dns-query-completed |
v1 |
Emitted when a DNS query completes |
k8s-manager
Kubernetes resource manager for managing pod and instance set lifecycle
Type: instrumentation | Version: 1.0.0 | NATS Namespace: glass.internal
Endpoints
| Endpoint | Description | Request | Response |
|---|---|---|---|
RestartInstanceSet |
Restart a Kubernetes Deployment or StatefulSet by triggering a rollout | name (required) |
status, kind, message |
DeletePod |
Delete a Kubernetes Pod in the managed namespace | name (required) |
status, message |
Dependencies
| Service | Version | Endpoints |
|---|---|---|
cc-api-adapter |
v1 |
State |
log-streamer
Kubernetes pod log streamer for real-time and historical log aggregation
Type: instrumentation | Version: 1.0.0 | NATS Namespace: glass.internal
Endpoints
| Endpoint | Description | Request | Response |
|---|---|---|---|
Stream |
Stream logs from Kubernetes pods with optional filtering and following | podName (required), containerName (required), eventName (required), regexFilter, previousSeconds, fromBeginning, previous, follow |
status |
GetPodMetadata |
Retrieve metadata about a pod including restart counts and events | podName (required), namespace |
podName, namespace, restartCounts, podEvents, ownerInfo, ownerEvents |
Events Emitted
| Event | Version | Description |
|---|---|---|
{eventName} |
v1 |
Log lines published to the dynamic event name from Stream request |
{eventName} |
v1 |
Status updates published to same event name (started, stopped, kept_alive) |
rest-api-adapter
REST API adapter translating OpenAPI schemas into SPOG endpoints
Type: instrumentation | Version: 1.0.0 | NATS Namespace: glass.public
Endpoints
| Endpoint | Description | Request | Response |
|---|---|---|---|
GetSchema |
Returns the raw OpenAPI schema JSON | - | * |
{DynamicOperationID} |
Dynamic endpoints generated from OpenAPI operations. | ||
| Endpoint name is derived from operationID using camelCase conversion. | |||
| Example: flush_auth_cache -> FlushAuthCache | |||
{path_parameters}, {query_parameters}, {body} |
* |
Dependencies
| Service | Version | Endpoints |
|---|---|---|
External REST API |
`` | - |
Infrastructure Services
Infrastructure services are CLI tools and utilities used during deployment and testing, or run as one-off jobs rather than persistent services.
center-jwt-mint
CLI tool for minting JWT tokens and storing them as Kubernetes secrets
Type: infrastructure | Version: 1.0.0 | Mode: CLI Tool
Commands
mint - Mint and print a machine token for a given cluster ID
Arguments:
cluster-id(required): Cluster identifierkey:value(multiple): Custom claims in key:value format
Flags:
| Flag | Type | Default | Description |
|---|---|---|---|
--signing-key-file |
string | signing.key |
Path to the signing key file |
Output: Prints the generated JWT token to stdout
mint-robot - Mint and print a token for a robot account
Arguments:
robot-name(required): Robot account namekey:value(multiple): Custom claims in key:value format
Flags:
| Flag | Type | Default | Description |
|---|---|---|---|
--signing-key-file |
string | signing.key |
Path to the signing key file |
Output: Prints the generated JWT token to stdout
mint-robot-secret - Mint a robot token and store it in a Kubernetes secret
Arguments:
robot-name(required): Robot account namekey:value(multiple): Custom claims in key:value format
Flags:
| Flag | Type | Default | Description |
|---|---|---|---|
--signing-key-file |
string | signing.key |
Path to the signing key file |
--namespace |
string | default |
Kubernetes namespace |
--name |
string | - | Secret name (required) |
--labels |
string | - | Comma-separated key=value pairs for labels |
--annotations |
string | - | Comma-separated key=value pairs for annotations |
--overwrite |
boolean | False |
Overwrite existing secret |
--owner-helm-release |
string | - | Name of owning Helm release |
--owner-helm-release-version |
string | 1 |
Version of owning Helm release |
--template |
string | - | Template string where %%TOKEN%% will be replaced with the JWT |
--data-key |
string | token |
Key to use in the secret data map |
Output: Creates Kubernetes Secret with robot JWT token
mint-machine-secret - Mint a machine token and store it in a Kubernetes secret
Arguments:
cluster-id(required): Cluster identifierkey:value(multiple): Custom claims in key:value format
Flags:
| Flag | Type | Default | Description |
|---|---|---|---|
--signing-key-file |
string | signing.key |
Path to the signing key file |
--namespace |
string | default |
Kubernetes namespace |
--name |
string | - | Secret name (required) |
--labels |
string | - | Comma-separated key=value pairs for labels |
--annotations |
string | - | Comma-separated key=value pairs for annotations |
--overwrite |
boolean | False |
Overwrite existing secret |
--owner-helm-release |
string | - | Name of owning Helm release |
--owner-helm-release-version |
string | 1 |
Version of owning Helm release |
--template |
string | - | Template string where %%TOKEN%% will be replaced with the JWT |
--data-key |
string | token |
Key to use in the secret data map |
Output: Creates Kubernetes Secret with machine JWT token
k8s-nkey-generator
CLI tool for generating NATS NKeys and storing them as Kubernetes secrets
Type: infrastructure | Version: 1.0.0 | Mode: CLI Tool
Commands
createSecret - Generate NATS NKey pair and store as Kubernetes secret
Flags:
| Flag | Type | Default | Description |
|---|---|---|---|
--namespace |
string | default |
Kubernetes namespace |
--name |
string | - | Secret name (required) |
--labels |
string | - | Comma-separated key=value pairs for labels |
--annotations |
string | - | Comma-separated key=value pairs for annotations |
--overwrite |
boolean | False |
Overwrite existing secret |
--separate-secrets |
boolean | False |
Create separate secrets for public and private keys |
--owner-helm-release |
string | - | Name of owning Helm release |
--owner-helm-release-version |
string | 1 |
Version of owning Helm release |
Output: Creates Kubernetes Secret(s) with NKey data
k8s-plain-password-generator
CLI tool for generating random passwords and storing them as Kubernetes secrets
Type: infrastructure | Version: 1.0.0 | Mode: CLI Tool
Commands
createSecret - Generate random password and store as Kubernetes secret
Flags:
| Flag | Type | Default | Description |
|---|---|---|---|
--namespace |
string | default |
Kubernetes namespace |
--name |
string | - | Secret name (required) |
--labels |
string | - | Comma-separated key=value pairs for labels |
--annotations |
string | - | Comma-separated key=value pairs for annotations |
--overwrite |
boolean | False |
Overwrite existing secret |
--password-length |
integer | 8 |
Length of generated password in bytes before base64 |
--no-number-start |
boolean | False |
Prevent password from starting with a number |
--owner-helm-release |
string | - | Name of owning Helm release |
--owner-helm-release-version |
string | 1 |
Version of owning Helm release |
Output: Creates Kubernetes Secret with password