Skip to content
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.

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

Update (rewrite) eventing specs #25

Merged
merged 65 commits into from
Jul 22, 2021
Merged
Show file tree
Hide file tree
Changes from 57 commits
Commits
Show all changes
65 commits
Select commit Hold shift + click to select a range
99aea7b
Checkpoint work on eventing specs
Apr 30, 2021
e07658d
More work on data plane & control plane. Mostly need to finish contro…
May 1, 2021
70d7e8b
Add at-least-once detail on data plane.
May 3, 2021
dc743ca
Finish off most of lifecycle
May 5, 2021
8ef8f61
Update (rewrite) overview, motivation, and data plane
May 6, 2021
86f9c55
Update lifecycle to be a bit clearer and cover more fields
May 7, 2021
e90a3ad
Fill in detailed resources.
evankanderson May 8, 2021
0d7b246
Document event delivery (Broker & Channel)
evankanderson May 9, 2021
0a33307
Updates from n3wscott review
evankanderson May 9, 2021
7e9b26b
Clean up no longer needed files.
evankanderson May 9, 2021
4964fd7
Updates from n3wscott review
evankanderson May 9, 2021
6216969
Update data-plane language per Ville's suggestions.
May 10, 2021
e776f36
Overview revisions based on vaikas feedback.
May 10, 2021
f4c3b09
Merge remote-tracking branch 'origin/re-spect-part-1' into re-spect
May 10, 2021
8cffd9c
Merge branch 'main' of https://github.com/knative/specs into re-spect
May 10, 2021
5d0c5b4
Updates from comments in #25
May 10, 2021
b140c4d
Merge remote-tracking branch 'origin/re-spect-part-1' into re-spect
May 10, 2021
17a9ae1
Address remaining Scott and Ville comments.
evankanderson May 11, 2021
111c55b
Merge remote-tracking branch 'origin/re-spect' into re-spect
May 13, 2021
0a54751
Updates from #25 review.
May 13, 2021
2f1cbb0
Feedback from #25 and speling check
May 13, 2021
e3ef6ad
Merge remote-tracking branch 'origin/re-spect-part-1' into re-spect
May 13, 2021
438f242
Merge branch 'main' of https://github.com/knative/specs into re-spect
May 13, 2021
b7d30e5
Update with matezw / slinkydeveloper feedback
May 19, 2021
83c531e
Merge remote-tracking branch 'origin/re-spect-part-1' into re-spect
May 19, 2021
07fcbde
Update with matezw / slinkydeveloper feedback
May 19, 2021
bd9f695
Merge remote-tracking branch 'origin/re-spect-part-1' into re-spect
May 19, 2021
917eac3
Updates from slinky, travis, ville, matzew
May 20, 2021
d9b1322
Merge remote-tracking branch 'origin/re-spect-part-1' into re-spect
May 20, 2021
7bd0161
Link to upgrade header.
May 20, 2021
59784fb
Merge remote-tracking branch 'origin/re-spect-part-1' into re-spect
May 20, 2021
fae7a87
Finish up TODOs, fix some typos.
May 25, 2021
99bb2e0
Merge remote-tracking branch 'origin/re-spect-part-1' into re-spect
May 25, 2021
9e33332
Address a number of duglin comments
May 25, 2021
cb526ff
Merge remote-tracking branch 'origin/re-spect-part-1' into re-spect
May 25, 2021
f69b8c8
Remove abandoned SVG images.
May 25, 2021
ea4f14c
Update overview with Doug's suggestions.
May 26, 2021
2c6aa43
Merge remote-tracking branch 'origin/re-spect-part-1' into re-spect
May 26, 2021
1797c7e
Update with duglin suggestions.
May 27, 2021
a299f12
Merge remote-tracking branch 'origin/re-spect-part-1' into re-spect
May 27, 2021
8c870de
Update with additional duglin review changes.
May 27, 2021
693cce6
One more set of edits.
May 27, 2021
218f965
Merge remote-tracking branch 'origin/re-spect-part-1' into re-spect
May 27, 2021
41abb8c
Add control-plane header, internal type links to schemas.
May 28, 2021
55ee647
Address duglin and lionelvillard suggestions
Jun 3, 2021
22b85c9
Refactor error signalling to a common location
Jun 3, 2021
4af35db
Address duglin comments
evankanderson Jun 13, 2021
22a8d56
Merge branch 're-spect-part-1' into re-spect
evankanderson Jun 13, 2021
2479d26
Address Doug's comments
evankanderson Jun 14, 2021
3a9519f
Address duglin feedback
Jun 17, 2021
68d499f
Merge remote-tracking branch 'origin/re-spect-part-1' into re-spect
Jun 17, 2021
c584076
Merge remote-tracking branch 'origin/re-spect' into re-spect
Jun 17, 2021
6832976
Fix lowercase 'may'
Jun 17, 2021
9b97e59
Clarify 202 no-reply behavior.
Jun 17, 2021
bc872bd
Merge remote-tracking branch 'origin/re-spect-part-1' into re-spect
Jun 17, 2021
04439f5
Highlight that 202 responses MUST NOT be processed even if the status…
Jul 15, 2021
87c871a
Address duglin comments.
Jul 20, 2021
ba78f25
Normalize "Field Type" annotations for spec.
Jul 20, 2021
8aa07df
A few updates to clarify that the control-plane specification indicat…
Jul 20, 2021
7a678bd
Require that Subscriptions reference Channels in the same namespace.
Jul 21, 2021
fad55f5
Allow additional Destinaiton resolution mechanisms.
Jul 22, 2021
8333aa7
Fix two Doug nits.
Jul 22, 2021
bef17aa
Remove schema requirements.
Jul 22, 2021
ac54635
Align SHOULD NOT / MUST NOT
Jul 22, 2021
f5d15dc
Capitalize "MAY"
Jul 22, 2021
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
155 changes: 155 additions & 0 deletions specs/common/error-signalling.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,155 @@
# Error Signalling

<!-- copied from ../serving/knative-api-specification-1.0.md#error-signalling -->

Knative APIs use the
[Kubernetes Conditions convention](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#typical-status-properties)
to communicate errors and problems to the user. Note that Knative customizes the
general Kubernetes recommendation with a `severity` field, and does not include
`lastHeartbeatTime` for scalability reasons. Each user-visible resource
described in Resource Overview MUST have a `conditions` field in `status`, which
MUST be a list of `Condition` objects described by the following table.

Fields in the condition which are not marked as "REQUIRED" MAY be omitted to
indicate the default value (i.e. a Condition which does not include a `status`
field is equivalent to a `status` of `"Unknown"`). As `Conditions` are an output
API, an implementation MAY never set these fields; the OpenAPI document MUST
still describe these fields. The actual API object types in an OpenAPI document
might be named `FooCondition` (for a `Foo` resource, for example) to allow
better code generation and disambiguation between similar fields in the same
`apiGroup`.

<table>
<tr>
<td><strong>Field</strong>
</td>
<td><strong>Type</strong>
</td>
<td><strong>Description</strong>
</td>
<td><strong>Default Value If Unset</strong>
</td>
</tr>
<tr>
<td><code>type</code>
</td>
<td><code>string</code>
</td>
<td>The category of the condition, as a short, CamelCase word or phrase.
<p>
This is the primary key of the Conditions list when viewed as a map and MUST be
unique across Conditions for a given resource.
</td>
<td>REQUIRED – No default
</td>
</tr>
<tr>
<td><code>status</code>
</td>
<td>Enum:<ul>

<li>"True"
<li>"False"
<li>"Unknown"</li></ul>

</td>
<td>The last measured status of this condition.
</td>
<td>"Unknown"
</td>
</tr>
<tr>
<td><code>reason</code>
</td>
<td>string
</td>
<td>One-word CamelCase reason for the condition's last transition.
</td>
<td>""
</td>
</tr>
<tr>
<td><code>message</code>
</td>
<td>string
</td>
<td>Human-readable sentence describing the last transition.
</td>
<td>""
</td>
</tr>
<tr>
<td><code>severity</code>
</td>
<td>Enum:<ul>

<li>""
<li>"Warning"
<li>"Info"</li></ul>

</td>
<td>If present, represents the severity of the condition. An empty severity represents a severity level of "Error".
Copy link
Contributor

Choose a reason for hiding this comment

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

When I read the sentence below:

Each resource MUST have either a Ready condition (for ongoing systems) or Succeeded condition (for resources that run to completion) with severity=""...

it reads kind of like there MUST be a severity=Error even when everything is ok. What am I missing?

Copy link
Member Author

Choose a reason for hiding this comment

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

This is exactly what caused agony before and why we changed "Error" to be "". This is saying that a working Broker should look like:

status:
  conditions:
    - type: Ready
      status: True
      severity: ""

You're conflating status (whether the condition is true) with severity (how bad is it for the condition to be False).

</td>
<td>""
</td>
</tr>
<tr>
<td><code>lastTransitionTime</code>
</td>
<td>Timestamp
</td>
<td>Last update time for this condition.
</td>
<td>(no timestamp specified)
</td>
</tr>
</table>

Additionally, the resource's `status.conditions` field MUST be managed as
follows to enable clients (particularly user interfaces) to present useful
diagnostic and error message to the user. In the following section, conditions
are referred to by their `type` (aka the string value of the `type` field on the
Condition).

1. Each resource MUST have a summary `Ready` condition (for ongoing systems) or
`Succeeded` condition (for resources that run to completion) with
`severity=""`, which MUST use the `"True"`, `"False"`, and `"Unknown"`
status values as follows:

1. `"False"` MUST indicate a failure condition.
1. `"Unknown"` SHOULD indicate that reconciliation is not yet complete and
success or failure is not yet determined.
1. `"True"` SHOULD indicate that the resource is fully reconciled and
operating correctly.

`"Unknown"` and `"True"` are specified as SHOULD rather than MUST
requirements because there might be errors which prevent functioning which
cannot be determined by the API stack (e.g. DNS record configuration in
certain environments). Implementations are expected to treat these as "MUST"
for factors within the control of the implementation.

1. For non-`Ready` conditions, any conditions with `severity=""` (aka "Error
conditions") MUST be aggregated into the "Ready" condition as follows:

1. If the condition is `"False"`, `Ready`'s status MUST be `"False"`.
1. If the condition is `"Unknown"`, `Ready`'s status MUST be `"False"` or
`"Unknown"`.
1. If the condition is `"True"`, `Ready`'s status can be any of `"True"`,
`"False"`, or `"Unknown"`.

Implementations MAY choose to report that `Ready` is `"False"` or
`"Unknown"` even if all Error conditions report a status of `"True"` (i.e.
there might be additional hidden implementation conditions which feed into
the `Ready` condition which are not reported.)

1. Conditions with a `status` other than `"True"` SHOULD provide `message` and
`reason` fields indicating the reason that the `status` is not `"True"`.
Conditions where the `status` is `"False"` MUST provide a failure `reason`
in the condition. (`"Unknown"` conditions might not have been reconciled,
and so MAY have an empty `reason`.)

Conditions type names SHOULD be chosen to describe positive conditions where
`"True"` means that the condition has been satisfied. Some conditions MAY be
transient (for example, `ResourcesAllocated` might change between `"True"` and
`"False"` as an application scales to and from zero). It is RECOMMENDED that
transient conditions be indicated with a `severity="Info"`.
13 changes: 2 additions & 11 deletions specs/eventing/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,14 +12,5 @@ Docs in this directory:

- [Motivation and goals](motivation.md)
- [Resource type overview](overview.md)
- [Interface contracts](interfaces.md)
- [Object model specification](spec.md)
- [Channel specification](channel.md)
- [Sources specification](sources.md)
- [Error conditions and reporting](https://knative.dev/docs/serving/spec/knative-api-specification-1.0/#error-signalling)

See the
[Knative Eventing Docs Architecture](https://www.knative.dev/docs/eventing/#architecture)
for more high level details.

<!-- TODO(#498): Update the docs/Architecture page. -->
- [Control Plane specification](control-plane.md)
- [Data Plane specification](data-plane.md)
Loading