API Reference

Resources

Gateway

Describes and configures a cloud event gateway, which is a service reponsible for authorizing, validating and persisting inbound events.

Name	Type	Required	Description
metadata	ResourceMetadata	yes	Describes the gateway.
spec	GatewaySpec	yes	The desired state of the gateway.
status	GatewayStatus	no	The actual status of the gateway.

Spec

Name	Type	Required	Description
authorization	CloudEventAuthorizationPolicy	no	The authorization policy that applies to cloud events of any source.
validation	CloudEventValidationPolicy	no	The validation policy that applies to cloud events of any source.
sources	CloudEventSourceDefinition[]	no	The configuration that applies to specific cloud event sources.
events	CloudEventIngestionConfiguration[]	no	A list containing event-specific ingestion configurations.
service	ServiceConfiguration	no	An object used to configure the gateway service, if any.

Status

Name	Type	Required	Description
healthStatus	string	no	The gateway's health status.
lastHealthCheckAt	dateTimeOffset	no	The date and time at which the last gateway health check has been performed.

Samples

JSON

{
  "apiVersion": "cloud-streams.io/v1",
  "kind": "Broker",
  "metadata": {
    "name": "broker",
    "creationTimestamp": "2023-07-28T10:07:33.3367152+00:00",
    "generation": 1,
    "resourceVersion": "D6B40743"
  },
  "spec": {
    "authorization": {
      "decisionStrategy": "consensus",
      "rules": [
        {
          "type": "attribute",
          "effect": "authorize",
          "attributeName": "source",
          "attributeValue": "https:\\/\\/(.*).cloud-streams.io\\/(.*)"
        }
      ]
    },
    "validation": {
      "skip": false,
      "validationStrategy": "fail",
      "dataSchema": {
        "required": true,
        "autoGenerate": false
      }
    },
    "sources": [
      {
        "uri": "https://cloud-streams.io/",
        "validation": {
          "skip": true
        }
      }
    ],
    "events": [
      {
        "source": "https:\\/\\/(.*).cloud-streams.io\\/(.*)",
        "type": ".*",
        "metadata": {
          "properties": [
            {
              "name": "$correlationId",
              "strategy": "attribute",
              "attribute": {
                "name": "subject"
              }
            },
            {
              "name": "$causationId",
              "strategy": "expression",
              "expression": "${ .data.causedById }"
            }
          ]
        }
      }
    ],
    "service": {
      "uri": "gateway.cloud-streams",
      "healthChecks": {
        "request": {
          "method": "GET",
          "path": "/healthz"
        }
      },
      "interval": "PT15S"
    }
  }
}

YAML

apiVersion: cloud-streams.io/v1
kind: Broker
metadata:
  name: broker
  creationTimestamp: '2023-07-28T10:07:33.3367152+00:00'
  generation: 1
  resourceVersion: D6B40743
spec:
  authorization:
    decisionStrategy: consensus
    rules:
    - type: attribute
      effect: authorize
      attributeName: source
      attributeValue: https:\/\/(.*).cloud-streams.io\/(.*)
  validation:
    skip: false
    validationStrategy: fail
    dataSchema:
      required: true
      autoGenerate: false
  sources:
  - uri: https://cloud-streams.io/
    validation:
      skip: true
  events:
  - source: https:\/\/(.*).cloud-streams.io\/(.*)
    type: .*
    metadata:
      properties:
        - name: $correlationId
          strategy: attribute
          attribute:
            name: subject
        - name: $causationId
          strategy: expression
          expression: '${ .data.causedById }'
  service:
    uri: gateway.cloud-streams
    healthChecks:
      request:
        method: GET
        path: /healthz
    interval: PT15S

Broker

Describes and configures a cloud event broker, which is a service that manages subscriptions and streams, filters, mutates and dispatches cloud events to subscribers.

Name	Type	Required	Description
metadata	ResourceMetadata	yes	Describes the gateway.
spec	BrokerSpec	yes	The desired state of the gateway.
status	BrokerStatus	no	The actual status of the gateway.

Spec

Name	Type	Required	Description
dispatch	BrokerDispatchConfiguration	no	An object used to configure the way the broker should dispatch cloud events.
selector	map[string, string]	no	A key/value mapping of the labels to select subscriptions by. If not set, the broker will attempt to pick up all inactive subscriptions.
service	ServiceConfiguration	no	An object used to configure the broker service, if any.

Status

Name	Type	Required	Description
healthStatus	string	no	The broker health status.
lastHealthCheckAt	dateTimeOffset	no	The date and time at which the last broker health check has been performed.
observedGeneration	ulong	no	The observed generation of the broker's spec the status describes. Divergence between resource and observed generation values should be handled during a reconciliation loop.
stream	CloudEventStreamStatus	no	An object used to describe the status of the broker's cloud event stream.

Samples

JSON

{

}

Subscription

Describes a cloud event subscription, managed by the broker(s) it has been picked up by.

Name	Type	Required	Description
metadata	ResourceMetadata	yes	Describes the subscription.
spec	SubscriptionSpec	yes	The desired state of the subscription.
status	SubscriptionStatus	no	The actual status of the subscription.

Spec

Name	Type	Required	Description
partition	PartitionReference	no	An object used to reference the partition to subscribe to, if any. If none has been set, the subscription receives all cloud events, regardless of their source, type or subject.
filter	CloudEventFilter	no	An object used to configure how to filter consumed cloud events. Prefer using partition whenever possible to reduce processing time for related brokers.
mutation	CloudEventMutation	no	An object used to configure how to mutate consumed cloud events.
stream	CloudEventStream	no	An object used to configure the subscription's cloud event stream.
subscriber	Subscriber	yes	An object used to configure the service to dispatch cloud events consumed by the subscription.

Status

Name	Type	Required	Description
phase	string	yes	The status phase of the described subscription. Possible values are: inactive: the subscription is inactive because its broker is inactive, or because the later did not pick it up active: the subscription is being monitored by its broker
observedGeneration	ulong	no	The observed generation of the subscription's spec the status describes. Divergence between resource and observed generation values should be handled during a reconciliation loop.
stream	CloudEventStreamStatus	no	An object used to describe the status of the subscription's cloud event stream

Samples

JSON

{

}

Models

Resource Metadata

Name	Type	Required	Description
name	string	yes	The described resource's name. Must start, end and be composed exlusively of a maximum of 63 alphanumeric characters, with the exception of -, _ and .
namespace	string	no	The namespace the described resource belongs to. Required in case the described resource has Namespaced scope, otherwise ignored.
labels	object	no	A key/value mappings of the described resource's labels, if any. Label keys and values must follow the DNS label standard as defined in RFC1123. Label values must start, end and be composed exlusively of a maximum of 63 alphanumeric characters, with the exception of -, _ and .
annotations	object	no	A key/value mappings of the described resource's annotations, if any.
creationTimestamp	dateTimeOffset	no	The date and time at which the described resource has been created.
generation	ulong	no	A value that represents the amount of revisions of the described resource's desired state (spec).
resourceVersion	string	no	A value that represents the version of the resource. Changes everytime any aspect of the described resource changes (including status).

Cloud Event Authorization Policy

Name	Type	Required	Description
decisionStrategy	string	yes	The strategy to use when deciding whether or not the authorization policy applies. Supported values are: consensus: a majority of rules should apply for the decision to be taken minority: at least one rule should apply for the decision to be taken unanimous: all rules should apply for the decision to be taken
rules	CloudEventAuthorizationRule[]	yes	A list containing the rules the policy is made out of.

Cloud Event Authorization Rule

Name	Type	Required	Description
type	string	yes	The rule's type. Supported values are: attribute: checks on cloud event context attributes payload: a policy that performs checks on cloud event payloads timeOfDay: a policy that grants or refuses accesss based on the time of day temporary: a policy that grants or refuses access over a given period of time
effect	string	yes	The rule's effect. Supported values are: authorize: grant authorization when rule applies forbid: forbid authorization when rule applies
from	DateTimeOffset	depends	The date and time the policy applies from. When type is set to timeOfDay, represents the time of the day starting from which the policy applies. The date component is ignored. When type is set to temporary, represents the date and time starting from which the policy applies.
to	DateTimeOffset	depends	The date and time the policy applies until. When type is set to timeOfDay, represents the time of the day until which the policy applies. The date component is ignored. When type is set to temporary, represents the date and time until which the policy applies.
attributeName	string	depends	The name of the required attribute. Required when type is set to attribute, otherwise ignored.
attributeValue	string	depends	The value of the required attribute. Supports regular expressions. Required when type is set to attribute, otherwise ignored.
maxSize	long	depends	The maximum size of incoming cloud events. Required when type is set to payload, otherwise ignored.

Cloud Event Validation Policy

Name	Type	Required	Description
skip	boolean	no	A boolean indicating whether or not to skip cloud event validation.
validationStrategy	string	yes	The strategy to use when validating inbound cloud events. Supported values are: none: no validation is performed warn: validation is performed but errors are treated as warnings fail: validation fails on errors
dataSchema	DataSchemaValidationPolicy	no	An object used to configure the JSON schema based validation of incoming cloud events.

Data Schema Validation Policy

Name	Type	Required	Description
required	boolean	no	A boolean indicating whether or not inbound cloud events should define a valid data schema. Defaults to true.
autoGenerate	boolean	no	A boolean indicating whether or not schemas for unknown inbound cloud events for be automatically generated and registered in the application's schema registry.

Cloud Event Source Definition

Name	Type	Required	Description
uri	uri	yes	The uri of the cloud event source to configure.
authorization	CloudEventAuthorizationPolicy	no	The policy to use to authorize cloud events produced by the source.
validation	CloudEventValidationPolicy	no	The validation policy that applies to cloud events produced by the source.

Cloud Event Ingestion Configuration

Name	Type	Required	Description
source	string	yes	The source (context attribute) of cloud events to configure the ingestion of. Supports regular expressions.
type	string	yes	The type (context attribute) of cloud events to configure the ingestion of. Supports regular expressions.
metadata	CloudEventMetadataResolutionConfiguration	no	An object used to configure the way the metadata of ingested cloud events should be resolved.

Cloud Event Metadata Resolution Configuration

Name	Type	Required	Description
properties	CloudEventMetadataPropertyResolver[]	no	A list containing the configuration of the resolution of a cloud event's metadata properties.

Cloud Event Metadata Property Resolver

Name	Type	Required	Description
name	string	yes	The name of the cloud event metadata property to resolve. Metadata properties used to partition events: $correlationId: an identifier used to correlate events. Typically references the aggregate that has produced the event. $causationId: a value used to identify the causation of a given event. Typically references the cause of an event produced by a given aggregate.
strategy	string	yes	The strategy to use to resolve the cloud event's metadata property. Supported values are: attribute: the metadata property is extracted from a context attribute expression: the metadata property is extracted by evaluating a runtime expression against the event
attribute	CloudEventAttributeFilter	depends	An object used to configure the cloud event context attribute to extract the metadata property from. Required if strategy has been set to attribute.
expression	string	depends	A runtime expression used to resolve the cloud event metadata property. Required if strategy has been set to expression.

Cloud Event Attribute Filter

Name	Type	Required	Description
name	string	yes	The name of the cloud event context attribute to filter.
value	string	no	The value of the cloud event context attribute to filter. Not setting any value configures the filter to only check if cloud events defined the attribute, no matter its value.

Service Configuration

Name	Type	Required	Description
uri	uri	yes	The base uri of the configured service.
healthChecks	ServiceHealthCheckConfiguration	no	An object used to configure the service's health checks, if any.

Service Health Check Configuration

Name	Type	Required	Description
request	HttpRequestConfiguration	yes	An object used to configure the HTTP-based health check request.
interval	string	no	The ISO8601 formatted amount of time to wait between every health check request.

Http Request Configuration

Name	Type	Required	Description
method	string	yes	The method of the HTTP request to perform (ex: GET, POST, PATCH, PUT, DELETE, etc.).
path	string	yes	The path of the HTTP request to perform.
headers	object	no	The headers of the HTTP request to perform, if any.
body	object	no	The request's body, if any.

Broker Dispatch Configuration

Name	Type	Required	Description
retryPolicy	HttpClientRetryPolicy	no	The retry policy that applies by default to all subscriptions managed by the broker.
sequencing	CloudEventSequencingConfiguration	no	An object used to configure the way the configured broker should sequence cloud events dispatched to consumers.

Http Client Retry Policy

Name	Type	Required	Description
statusCodes	integer[]	no	A list containing the http status codes the retry policy applies to. If not set, the policy will apply to all non-success (200-300) status codes.
circuitBreaker	CircuitBreakerPolicy	no	An object that configures the client's circuit breaker, if any.

Cloud Event Sequencing Configuration

Name	Type	Required	Description
strategy	string	yes	The sequencing strategy to use. Supported values are: none: events should not be sequenced by CloudStreams attribute: events should be sequenced by CloudStreams using the specified context attribute
attributeName	string	depends	The name of the context attribute to store the CloudStreams sequence into. Required if strategy has been set to attribute.
attributeConflictResolution	string	depends	The way to handle conflicts with existing attributes. Supported values are: overwrite: the value of the existing attribute should be overwriten fallback: the value be writen to a fallback attribute when the target attribute exists Required if strategy has been set to attribute.
fallbackAttributeName	string	depends	The name of the context attribute to fallback to when the attribute specified by attributeName already exists. Required if strategy has been set to attribute and attributeConflictResolution has been set to fallback.

Circuit Breaker Policy

Name	Type	Required	Description
breakAfter	integer	yes	The maximum attempts after which to break the circuit.
breakDuration	string	yes	The ISO8601 formatted duration during while the circuit remains broken.

Cloud Event Stream Status

Name	Type	Required	Description
ackedOffset	ulong	no	The acked offset in the cloud event stream starting from which to receive events.
fault	ProblemDetails	no	An object that describes the last fault that occured while streaming events to subscribers. Streaming is interrupted when fault is set, requiring a user to manually resume streaming.

Problem Details

Name	Type	Required	Description
type	uri	yes	An uri that reference the type of the described problem.
title	string	yes	A short, human-readable summary of the problem type. It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.
status	integer	yes	The status code produced by the described problem.
detail	string	no	A human-readable explanation specific to this occurrence of the problem.
instance	uri	no	A reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.
errors	object[]	no	An optional collection containing error messages mapped per error code.

Partition Reference

Name	Type	Required	Description
type	string	yes	The referenced stream partition's type. Supported values are: by-source: the partition by cloud event source (context attribute) by-type: the partition by cloud event type (context attribute) by-subject: partition by subject (context attribute) by-correlation-id: the partition by $correlationId metadata by-causation-id: the partition by $causationId metadata
id	string	yes	The id of the referenced stream partition.

Cloud Event Filter

Name	Type	Required	Description
type	string	yes	The filter's type. Supported values are: attributes: specifies a context attributes based filter expression: specifies an expression-based filter
attributes	object	depends	A key/value mapping of the context attributes by which to filter consumed cloud events. Required if 'type' has been set to attributes, otherwise ignored. Values support regular and runtime expressions. If no value has been supplied for a given key, it will match cloud events that define said attribute, no matter its value.
expression	string	depends	The runtime expression based condition to evaluate consumed cloud events against. Required if 'type' has been set to expression.

Cloud Event Mutation

Name	Type	Required	Description
type	string	yes	The mutation strategy to use. Supported values are: expression: an expression-based mutation webhook: a webhook-based mutation
expression	string	depends	The runtime expression string or object used to mutate consumed cloud events. Required if type has been set to expression.
webhook	Webhook	yes	An object used to configure the webhook request to perform in order to mutate the cloud event. Required if type has been set to webhook.

Webhook

Name	Type	Required	Description
serviceUri	uri	yes	The address of the service to post back to.

Cloud Event Stream

Name	Type	Required	Description
offset	long	no	The desired offset in the cloud event stream starting from which to receive events. 0: start of the stream -1: the end of stream. Defaults to -1.

Subscriber

Name	Type	Required	Description
uri	uri	yes	The address of the dispatch consumed cloud events to.
rateLimit	double	no	The maximum amount of events, if any, that can be dispatched per second to the subscriber.
retryPolicy	HttpClientRetryPolicy	no	The retry policy to use when dispatching cloud events to the subscriber. If not set, will fallback to the broker's default retry policy.