Skip to content

Commit 262c3a1

Browse files
committed
added diagrams
1 parent d8d681e commit 262c3a1

File tree

2 files changed

+12
-7
lines changed

2 files changed

+12
-7
lines changed

DEV.md renamed to devel/architecture/kgateway/DEV.md

Lines changed: 10 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,8 @@ Going down further, to enable these goals we use [KRT](https://github.com/istio/
1212
- The ability to complement controllers of custom Intermediate Representation (henceforth IR).
1313
- Automatically track object dependencies and changes and only invoke logic that depends on the object that changed.
1414

15-
# CRD Journey
15+
# CRD Lifecycle
16+
1617
How does a user CRD make it into envoy?
1718

1819
We have 3 main translation lifecycles: Routes & Listeners, Clusters and Endpoints.
@@ -23,15 +24,13 @@ Envoy Routes & Listeners translate from Gateways, HttpRoutes, and user policies
2324

2425
## Policies (Contributed by Plugins)
2526

27+
To add a policy to KGateway, it needs to be contributed through a **plugin**. Each plugin acts as an independent Kubernetes controller that provides Kgateway with a **KRT collection of IR policies** (this is done by translating the policy CRD to a policy IR). The second important thing a plugin provides is a function that allocates a **translation pass** for the gateway translation phase. This will be used when doing xDS translation. More on that later.
28+
2629
To add a policy to Kgateway we need to 'contribute' it as a plugin. You can think of a plugin as an
2730
independent k8s controller that translates a CRD to an krt-collection of policies in IR form Kgateway can understand (it's called `ir.PolicyWrapper`).
2831
A plugin lifecycle is the length of the program - it doesn't reset on each translation (we will explain later where we hold translation state).
2932

30-
31-
The first step is to convert each user policy into an IR form. This is done by creating a collection of these objects from k8s, and transforming the collection to an IR representation.
32-
33-
When a plugin can contribute a policy to Kgateway, Kgateway uses policy collection to perform policy attachment - this is the process of assigning policies to the object they impact (like HttpRoutes) based on their targetRefs.
34-
It's the plugin responsibility to convert the policy CRD to the IR form. Ideally, the IR should look as close as possible to the envoy configuration, so this translation only happens when the policy CRD changes.
33+
When a plugin can contribute a policy to Kgateway, Kgateway uses policy collection to perform **policy attachment** - this is the process of assigning policies to the object they impact (like HttpRoutes) based on their targetRefs.
3534

3635
You can see in the Plugin interface a field called `ContributesPolicies` which is a map of GK -> `PolicyPlugin`.
3736
The policy plugin contains a bunch of fields, but for our discussion we'll focus on these two:
@@ -63,7 +62,7 @@ type PolicyWrapper struct {
6362
The system will make use of the targetRefs to attach the policy IR to Listners and HttpRoutes. You will then
6463
get access to the IR during translation (more on that later).
6564

66-
When translating a Policy to a PolicyIR, you'll want to take the translation as far as you can. For example, if your policy will result in an envoy
65+
When translating a Policy to a PolicyIR, you'll want to take the translation **as close as you can** to envoy's config structures. For example, if your policy will result in an envoy
6766
PerFilterConfig on a route, the PolicyIR should contain the proto.Any that will be applied there. Doing most of the policy translation at this phase as advantages:
6867
- Policy will only re-translate when the policy CRD changes
6968
- We can expose errors in translation on the policy CRD status as soon as the policy is written (no need to depend on later translation phases).
@@ -98,3 +97,7 @@ This allows us for example translate a route, and in response to that hold state
9897
When it translates GW-api route rules to envoy routes, it reads the `AttachedPolicies` and calls the appropriate function in the `ProxyTranslationPass` and passes in
9998
the attached policy IR. This let's the policy plugin code the modify the route or listener as needed, based on the policy IR (add filters, add filter route config, etc..).
10099
Then policy plugins are invoked with the attached policy IR, and can modify the envoy protbufs as needed
100+
101+
# Diagram of the translation lifecycle
102+
103+
![](translation.svg)

devel/architecture/kgateway/translation.svg

Lines changed: 2 additions & 0 deletions
Loading

0 commit comments

Comments
 (0)