|
1 | 1 | # Resource Types |
2 | 2 |
|
3 | | -The primary resources in the Knative Serving API are Routes, Revisions, |
4 | | -Configurations, and Services: |
5 | | - |
6 | | -- A **Route** provides a named endpoint and a mechanism for routing traffic to |
7 | | - |
8 | | -- **Revisions**, which are immutable snapshots of code + config, created by a |
9 | | - |
10 | | -- **Configuration**, which acts as a stream of environments for Revisions. |
11 | | - |
12 | | -- **Service** acts as a top-level container for managing a Route and |
13 | | - Configuration which implement a network service. |
14 | | - |
15 | | - |
16 | | - |
17 | | -## Route |
18 | | - |
19 | | -**Route** provides a network endpoint for a user's service (which consists of a |
20 | | -series of software and configuration Revisions over time). A kubernetes |
21 | | -namespace can have multiple routes. The route provides a long-lived, stable, |
22 | | -named, HTTP-addressable endpoint that is backed by one or more **Revisions**. |
23 | | -The default configuration is for the route to automatically route traffic to the |
24 | | -latest revision created by a **Configuration**. For more complex scenarios, the |
25 | | -API supports splitting traffic on a percentage basis, and CI tools could |
26 | | -maintain multiple configurations for a single route (e.g. "golden path" and |
27 | | -“experiments”) or reference multiple revisions directly to pin revisions during |
28 | | -an incremental rollout and n-way traffic split. The route can optionally assign |
29 | | -addressable subdomains to any or all backing revisions. |
30 | | - |
31 | | -## Revision |
32 | | - |
33 | | -**Revision** is an immutable snapshot of code and configuration. A revision |
34 | | -references a container image. Revisions are created by updates to a |
35 | | -**Configuration**. |
36 | | - |
37 | | -Revisions that are not addressable via a Route may be garbage collected and all |
38 | | -underlying K8s resources will be deleted. Revisions that are addressable via a |
39 | | -Route will have resource utilization proportional to the load they are under. |
40 | | - |
41 | | -## Configuration |
42 | | - |
43 | | -A **Configuration** describes the desired latest Revision state, and creates and |
44 | | -tracks the status of Revisions as the desired state is updated. A configuration |
45 | | -will reference a container image and associated execution metadata needed by the |
46 | | -Revision. On updates to a Configuration's spec, a new Revision will be created; |
47 | | -the Configuration's controller will track the status of created Revisions and |
48 | | -makes the most recently created and most recently _ready_ Revisions available in |
49 | | -the status section. |
50 | | - |
51 | | -## Service |
52 | | - |
53 | | -A **Service** encapsulates a **Route** and **Configuration** which together |
54 | | -provide a software component. Service exists to provide a singular abstraction |
55 | | -which can be access controlled, reasoned about, and which encapsulates software |
56 | | -lifecycle decisions such as rollout policy and team resource ownership. Service |
57 | | -acts only as an orchestrator of the underlying Route and Configuration (much as |
58 | | -a kubernetes Deployment orchestrates ReplicaSets). Its usage is optional but |
59 | | -recommended. |
60 | | - |
61 | | -The Service's controller will track the statuses of its owned Configuration and |
62 | | -Route, reflecting their statuses and conditions as its own. |
63 | | - |
64 | | -The owned Configuration's Ready conditions are surfaced as the Service's |
65 | | -ConfigurationsReady condition. The owned Routes' Ready conditions are surfaced |
66 | | -as the Service's RoutesReady condition. |
67 | | - |
68 | | -## Orchestration |
69 | | - |
70 | | -Revisions are created indirectly when a Configuration is created or updated. |
71 | | -This provides: |
72 | | - |
73 | | -- a single referenceable resource for the route to perform automated rollouts |
74 | | -- a single resource that can be watched to see a history of all the revisions |
75 | | - created |
76 | | -- PATCH semantics for revisions implemented server-side, minimizing |
77 | | - read-modify-write implemented across multiple clients, which could result in |
78 | | - optimistic concurrency errors |
79 | | -- the ability to rollback to a known good configuration |
80 | | - |
81 | | -Update operations on the service enable scenarios such as: |
82 | | - |
83 | | -- _"Push image, keep config":_ Specifying a new revision with updated image, |
84 | | - inheriting configuration such as env vars from the configuration. |
85 | | -- _"Update config, keep image"_: Specifying a new revision as just a change to |
86 | | - configuration, such as updating an env variable, inheriting all other |
87 | | - configuration and image. |
88 | | -- _"Execute a controlled rollout"_: Updating the service's traffic spec allows |
89 | | - testing of revisions before making them live, and controlled rollouts. |
| 3 | +This file has been moved to the [Knative Specs Repository](https://github.com/knative/specs/blob/main/specs/serving/overview.md) |
0 commit comments