Kubernetes API Reference

This document provides the complete reference for TinySystems Custom Resource Definitions (CRDs).

TinyNode

Represents an instance of a component in a flow.

apiVersion/kind

apiVersion: operator.tinysystems.io/v1alpha1
kind: TinyNode

Metadata

metadata:
  name: string               # Unique name within namespace
  namespace: string          # Kubernetes namespace
  labels:                    # Standard labels
    tiny.systems/flow-id: string      # Flow identifier
    tiny.systems/project-id: string   # Project identifier
  annotations: {}            # Optional annotations

Spec

spec:
  module: string            # Module identifier (e.g., "github.com/tiny-systems/common-module")
  component: string         # Component name (e.g., "router")
  version: string           # Optional: specific version

  edges:                    # Outgoing connections
    - id: string            # Unique edge identifier
      port: string          # Source port name
      to: string            # Target node name
      toPort: string        # Target port name
      configuration: {}     # Data mapping/transformation

  run: boolean              # Whether to process signals

Status

status:
  observedGeneration: int64  # Last processed generation
  moduleName: string         # Resolved module name
  component: string          # Component name
  version: string            # Module version
  error: string              # Error message if any

  ports:                     # Port definitions from component
    - name: string           # Port name
      label: string          # Display label
      position: string       # left, right, top, bottom
      source: boolean        # true = output port
      schema: {}             # JSON Schema
      configuration: {}      # Current configuration

  metadata: {}               # Custom metadata (for state propagation)

Example

apiVersion: operator.tinysystems.io/v1alpha1
kind: TinyNode
metadata:
  name: order-router
  namespace: tinysystems
  labels:
    tiny.systems/flow-id: "flow-123"
spec:
  module: github.com/tiny-systems/common-module
  component: router
  edges:
    - id: "edge-1"
      port: "out_success"
      to: "process-order"
      toPort: "input"
      configuration:
        orderId: "{{$.data.orderId}}"
        status: "{{$.data.status}}"
    - id: "edge-2"
      port: "out_default"
      to: "error-handler"
      toPort: "input"
status:
  observedGeneration: 1
  moduleName: common-module
  component: router
  version: "1.5.0"
  ports:
    - name: input
      label: Input
      position: left
      source: true
      schema:
        type: object
    - name: out_success
      label: Success
      position: right
      source: false

---

TinyModule

Represents a deployed module in the cluster.

apiVersion/kind

apiVersion: operator.tinysystems.io/v1alpha1
kind: TinyModule

Metadata

metadata:
  name: string               # Module deployment name
  namespace: string          # Kubernetes namespace

Spec

spec:
  image: string              # Container image

Status

status:
  addr: string               # gRPC service address
  version: string            # Module version
  components:                # Available components
    - name: string           # Component name
      info:                  # Component information
        name: string
        description: string
        icon: string
        tags: []

Example

apiVersion: operator.tinysystems.io/v1alpha1
kind: TinyModule
metadata:
  name: common-module-v1
  namespace: tinysystems
spec:
  image: ghcr.io/tiny-systems/common-module:v1.5.0
status:
  addr: "common-module-v1:50051"
  version: "1.5.0"
  components:
    - name: router
      info:
        name: router
        description: "Route messages based on conditions"
        icon: "IconRouter"
        tags: ["routing", "control-flow"]
    - name: modify
      info:
        name: modify
        description: "Transform message data"
        icon: "IconTransform"
        tags: ["transform"]

---

TinySignal

Triggers message processing on a node.

apiVersion/kind

apiVersion: operator.tinysystems.io/v1alpha1
kind: TinySignal

Metadata

metadata:
  name: string               # Signal name
  namespace: string          # Kubernetes namespace

Spec

spec:
  node: string               # Target TinyNode name
  port: string               # Target port name
  data: {}                   # Message data

Status

status:
  processed: boolean         # Whether signal was processed
  error: string              # Error if processing failed

Example

apiVersion: operator.tinysystems.io/v1alpha1
kind: TinySignal
metadata:
  name: trigger-order-process
  namespace: tinysystems
spec:
  node: order-router
  port: input
  data:
    orderId: "ord-12345"
    status: "new"
    customer:
      id: "cust-789"
      email: "customer@example.com"

---

Field Reference Tables

TinyNode.spec

Field	Type	Required	Description
module	string	Yes	Module identifier
component	string	Yes	Component name
version	string	No	Specific version
edges	[]Edge	No	Outgoing connections
run	boolean	No	Enable signal processing

TinyNode.spec.edges[]

Field	Type	Required	Description
id	string	Yes	Unique edge identifier
port	string	Yes	Source port name
to	string	Yes	Target node name
toPort	string	Yes	Target port name
configuration	object	No	Data mapping

TinyNode.status

Field	Type	Description
observedGeneration	int64	Last processed spec generation
moduleName	string	Resolved module name
component	string	Component name
version	string	Module version
error	string	Error message
ports	[]Port	Port definitions
metadata	map[string]string	Custom metadata

TinyModule.spec

Field	Type	Required	Description
image	string	Yes	Container image reference

TinyModule.status

Field	Type	Description
addr	string	gRPC service address
version	string	Module version
components	[]ComponentInfo	Available components

TinySignal.spec

Field	Type	Required	Description
node	string	Yes	Target TinyNode name
port	string	Yes	Target port name
data	object	No	Message payload

---

Labels and Annotations

Standard Labels

Label	Description
tiny.systems/flow-id	Flow identifier
tiny.systems/project-id	Project identifier
tiny.systems/workspace-id	Workspace identifier
tiny.systems/module	Module name
tiny.systems/component	Component name

Standard Annotations

Annotation	Description
tiny.systems/created-by	Creator identifier
tiny.systems/created-at	Creation timestamp
tiny.systems/last-modified	Last modification timestamp

---

RBAC Requirements

Minimum Permissions

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: tinysystems-controller
rules:
  - apiGroups: ["operator.tinysystems.io"]
    resources: ["tinynodes", "tinymodules", "tinysignals"]
    verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
  - apiGroups: ["operator.tinysystems.io"]
    resources: ["tinynodes/status", "tinymodules/status", "tinysignals/status"]
    verbs: ["get", "update", "patch"]