Skip to content

[WIP] trigger and broker to have a description via 'kubectl explain' #3832

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
nlopezgi wants to merge 2 commits into from
Closed

[WIP] trigger and broker to have a description via 'kubectl explain' #3832

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
da2f61a
add content for triggar and broker to have a description via
Aug 13, 2020
27bfded
fix review nits
Aug 13, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
94 changes: 94 additions & 0 deletions config/core/resources/broker.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,100 @@ spec:
name: v1
served: true
storage: false
schema:
openAPIV3Schema:
type: object
description: 'Broker collects a pool of events that are consumable using Triggers.
Brokers provide a well-known endpoint for event delivery that senders can
use with minimal knowledge of the event routing strategy. Subscribers use
Triggers to request delivery of events from a Broker''s pool to a specific
URL or Addressable endpoint.'
properties:
spec:
description: 'Spec defines the desired state of the Broker.'
type: object
properties:
config:
description: 'Config is a KReference to the configuration that specifies
configuration options for this Broker. For example, this could
be a pointer to a ConfigMap.'
type: object
properties:
apiVersion:
description: 'API version of the referent.'
type: string
kind:
description: 'Kind of the referent. More info:
https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds'
type: string
name:
description: 'Name of the referent. More info:
https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names'
type: string
namespace:
description: 'Namespace of the referent. More info:
https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/
This is optional field, it gets defaulted to the object
holding it if left out.'
type: string
delivery:
description: 'Delivery is the delivery specification for Events within
the Broker mesh. This includes things like retries, DLQ, etc.'
type: object
properties:
backoffDelay:
description: 'BackoffDelay is the delay before retrying. More
Copy link
Copy Markdown
Contributor

@liu-cong liu-cong Aug 13, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: is there any convention in using single or double quotes in description?

Copy link
Copy Markdown
Contributor Author

@nlopezgi nlopezgi Aug 13, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

decided to use single quotes as its can be applied homogeneously (i.e., double quotes are not good in some cases)

information on Duration format: - https://www.iso.org/iso-8601-date-and-time-format.html
- https://en.wikipedia.org/wiki/ISO_8601 For linear policy,
backoff delay is the time interval between retries. For
exponential policy , backoff delay is backoffDelay*2^<numberOfRetries>.'
type: string
backoffPolicy:
description: ' BackoffPolicy is the retry backoff policy (linear,
exponential).'
type: string
deadLetterSink:
description: 'DeadLetterSink is the sink receiving event that
could not be sent to a destination.'
type: object
properties:
ref:
description: 'Ref points to an Addressable.'
type: object
properties:
apiVersion:
description: 'API version of the referent.'
type: string
kind:
description: 'Kind of the referent. More info:
https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds'
type: string
name:
description: 'Name of the referent. More info:
https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names'
type: string
namespace:
description: 'Namespace of the referent. More
info: https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/
This is optional field, it gets defaulted
to the object holding it if left out.'
type: string
uri:
description: 'URI can be an absolute URL(non-empty
scheme and non-empty host) pointing to the target
or a relative URI. Relative URIs will be resolved
using the base URI retrieved from Ref.'
type: string
retry:
description: 'Retry is the minimum number of retries the sender
should attempt when sending an event before moving it
to the dead letter sink.'
type: integer
format: int32
status:
description: 'Status represents the current state of the Broker. This data
may be out of date.'
type: object
names:
kind: Broker
plural: brokers
Expand Down
27 changes: 17 additions & 10 deletions config/core/resources/trigger.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,22 +55,22 @@ spec:
properties:
broker:
type: string
description: "Broker that this trigger receives events from. If not specified, will default to 'default'."
description: 'Broker that this trigger receives events from. If not specified, will default to "default".'
filter:
type: object
properties:
attributes:
type: object
description: "Map of CloudEvents attributes used for filtering events. If not specified, will default to all events"
description: 'Map of CloudEvents attributes used for filtering events. If not specified, will default to all events'
additionalProperties:
type: string
subscriber:
type: object
description: "the destination that should receive events."
description: 'the destination that should receive events.'
properties:
ref:
type: object
description: "a reference to a Kubernetes object from which to retrieve the target URI."
description: 'a reference to a Kubernetes object from which to retrieve the target URI.'
required:
- apiVersion
- kind
Expand All @@ -90,7 +90,7 @@ spec:
minLength: 1
uri:
type: string
description: "the target URI or, if ref is provided, a relative URI reference that will be combined with ref to produce a target URI."
description: 'the target URI or, if ref is provided, a relative URI reference that will be combined with ref to produce a target URI.'
status:
type: object
x-kubernetes-preserve-unknown-fields: true
Expand All @@ -101,31 +101,37 @@ spec:
schema:
openAPIV3Schema:
type: object
description: 'Trigger represents a request to have events delivered to a subscriber from a Broker''s event pool.'
properties:
spec:
description: 'Spec defines the desired state of the Trigger.'
required:
- subscriber
- broker
type: object
properties:
broker:
type: string
description: "Broker that this trigger receives events from."
description: 'Broker that this trigger receives events from.'
filter:
type: object
description: 'Filter is the filter to apply against all events from
the Broker. Only events that pass this filter will be sent to
the Subscriber. If not specified, will default to allowing all
events.'
properties:
attributes:
type: object
description: "Map of CloudEvents attributes used for filtering events. If not specified, will default to all events"
description: 'Map of CloudEvents attributes used for filtering events. If not specified, will default to all events'
additionalProperties:
type: string
subscriber:
type: object
description: "the destination that should receive events."
description: 'the destination that should receive events.'
properties:
ref:
type: object
description: "a reference to a Kubernetes object from which to retrieve the target URI."
description: 'a reference to a Kubernetes object from which to retrieve the target URI.'
required:
- apiVersion
- kind
Expand All @@ -145,8 +151,9 @@ spec:
minLength: 1
uri:
type: string
description: "the target URI or, if ref is provided, a relative URI reference that will be combined with ref to produce a target URI."
description: 'the target URI or, if ref is provided, a relative URI reference that will be combined with ref to produce a target URI.'
status:
description: 'Status represents the current state of the Trigger. This data may be out of date.'
type: object
x-kubernetes-preserve-unknown-fields: true
names:
Expand Down
2 changes: 1 addition & 1 deletion pkg/apis/eventing/v1/broker_types.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ import (

// Broker collects a pool of events that are consumable using Triggers. Brokers
// provide a well-known endpoint for event delivery that senders can use with
// minimal knowledge of the event routing strategy. Receivers use Triggers to
// minimal knowledge of the event routing strategy. Subscribers use Triggers to
// request delivery of events from a Broker's pool to a specific URL or
// Addressable endpoint.
type Broker struct {
Expand Down
2 changes: 1 addition & 1 deletion pkg/apis/eventing/v1/trigger_types.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ const (
// +genreconciler
// +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object

// Trigger represents a request to have events delivered to a consumer from a
// Trigger represents a request to have events delivered to a subscriber from a
// Broker's event pool.
type Trigger struct {
metav1.TypeMeta `json:",inline"`
Expand Down