Skip to content

Commit 2e96771

Browse files
zirainzirain
committed
docs: generate v1.5 docs
Signed-off-by: zirain <[email protected]>
1 parent c14ebaf commit 2e96771

File tree

125 files changed

+35804
-15
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

125 files changed

+35804
-15
lines changed

‎VERSION‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
v1.5.0-rc.2
1+
v1.5.0

‎site/content/en/v1.5/_index.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
+++
2+
title = "Welcome to Envoy Gateway"
3+
linktitle = "Documentation"
4+
description = "Envoy Gateway Documents"
5+
6+
[[cascade]]
7+
type = "docs"
8+
+++
9+
10+
Envoy Gateway is an open source project for managing [Envoy Proxy](https://www.envoyproxy.io/) as a standalone or Kubernetes-based application
11+
gateway. [Gateway API](https://gateway-api.sigs.k8s.io/) resources are used to dynamically provision and configure the managed Envoy Proxies.
12+
13+
![architecture](/img/traffic.png)
14+
15+
## Ready to get started?

‎site/content/en/v1.5/api/_index.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
title: "API References"
3+
description: This section includes API References.
4+
weight: 80
5+
---

‎site/content/en/v1.5/api/extension_types.md‎

Lines changed: 5356 additions & 0 deletions
Large diffs are not rendered by default.

‎site/content/en/v1.5/api/gateway_api/_index.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
title: "Kubernetes Gateway API"
3+
description: This section includes APIs of Kubernetes Gateway API.
4+
weight: 80
5+
---

‎site/content/en/v1.5/api/gateway_api/backendtlspolicy.md‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
+++
2+
title = "BackendTLSPolicy"
3+
+++
4+
5+
6+
The `BackendTLSPolicy` resource is Alpha and has been part of
7+
the Experimental Channel since `v1.0.0`. For more information on release
8+
channels, refer to our [versioning guide](https://gateway-api.sigs.k8s.io/concepts/versioning).
9+
10+
[BackendTLSPolicy][backendtlspolicy] is a Gateway API type for specifying the TLS configuration
11+
of the connection from the Gateway to a backend pod/s via the Service API object.
12+
13+
## Background
14+
15+
`BackendTLSPolicy` specifically addresses the configuration of TLS in order to convey HTTPS from the Gateway
16+
dataplane to the backend. This is referred to as "backend TLS termination" and enables the Gateway to know
17+
how to connect to a backend pod that has its own certificate.
18+
19+
While there are other API objects provided for TLS to be configured for **passthrough** and **edge** termination,
20+
this API object allows users to specifically configure **backend** TLS termination. For more information on TLS
21+
configuration in Gateway API, see [TLS Configuration](https://gateway-api.sigs.k8s.io/guides/tls/).
22+
23+
![Image showing three TLS Termination Types](https://gateway-api.sigs.k8s.io/images/tls-termination-types.png)
24+
25+
BackendTLSPolicy is a Direct [PolicyAttachment](https://gateway-api.sigs.k8s.io/reference/policy-attachment/) without defaults or overrides,
26+
applied to a Service that accesses a backend, where the BackendTLSPolicy resides in the same namespace as the
27+
Service to which it is applied. The BackendTLSPolicy and the Service must reside in the same namespace in order
28+
to prevent the complications involved with sharing trust across namespace boundaries.
29+
30+
All Gateway API Routes that point to a referenced Service should respect a configured BackendTLSPolicy.
31+
32+
## Spec
33+
34+
The specification of a [BackendTLSPolicy][backendtlspolicy] consists of:
35+
36+
- [TargetRefs][targetRefs] - Defines the targeted API object of the policy. Only Service is allowed.
37+
- [Validation][validation] - Defines the configuration for TLS, including hostname, CACertificateRefs, and
38+
WellKnownCACertificates.
39+
- [Hostname][hostname] - Defines the Server Name Indication (SNI) that the Gateway uses to connect to the backend.
40+
- [CACertificateRefs][caCertificateRefs] - Defines one or more references to objects that contain PEM-encoded TLS certificates,
41+
which are used to establish a TLS handshake between the Gateway and backend Pod. Either CACertificateRefs or
42+
WellKnownCACertificates may be specified, but not both.
43+
- [WellKnownCACertificates][wellKnownCACertificates] - Specifies whether system CA certificates may be used in the TLS
44+
handshake between the Gateway and backend Pod. Either CACertificateRefs or WellKnownCACertificates may be specified, but not both.
45+
46+
The following chart outlines the object definitions and relationship:
47+
```mermaid
48+
flowchart LR
49+
backendTLSPolicy[["<b>backendTLSPolicy</b> <hr><align=left>BackendTLSPolicySpec: spec<br>PolicyStatus: status</align>"]]
50+
spec[["<b>spec</b><hr>PolicyTargetReferenceWithSectionName: targetRefs <br> BackendTLSPolicyValidation: tls"]]
51+
status[["<b>status</b><hr>[ ]PolicyAncestorStatus: ancestors"]]
52+
validation[["<b>tls</b><hr>LocalObjectReference: caCertificateRefs<br>wellKnownCACertificatesType: wellKnownCACertificates/<br>PreciseHostname: hostname"]]
53+
ancestorStatus[["<b>ancestors</b><hr>AncestorRef: parentReference<br>GatewayController: controllerName<br>[]Condition: conditions"]]
54+
targetRefs[[<b>targetRefs</b><hr>]]
55+
service["<b>service</>"]
56+
backendTLSPolicy -->spec
57+
backendTLSPolicy -->status
58+
spec -->targetRefs & validation
59+
status -->ancestorStatus
60+
targetRefs -->service
61+
note[<em>choose only one<hr> caCertificateRefs OR wellKnownCACertificates</em>]
62+
style note fill:#fff
63+
validation -.- note
64+
```
65+
66+
The following illustrates a BackendTLSPolicy that configures TLS for a Service serving a backend:
67+
```mermaid
68+
flowchart LR
69+
client(["client"])
70+
gateway["Gateway"]
71+
style gateway fill:#02f,color:#fff
72+
httproute["HTTP<BR>Route"]
73+
style httproute fill:#02f,color:#fff
74+
service["Service"]
75+
style service fill:#02f,color:#fff
76+
pod1["Pod"]
77+
style pod1 fill:#02f,color:#fff
78+
pod2["Pod"]
79+
style pod2 fill:#02f,color:#fff
80+
client -.->|HTTP <br> request| gateway
81+
gateway --> httproute
82+
httproute -.->|BackendTLSPolicy|service
83+
service --> pod1 & pod2
84+
```
85+
86+
### Targeting backends
87+
88+
A BackendTLSPolicy targets a backend Pod (or set of Pods) via one or more TargetRefs to a Service. This TargetRef is a
89+
required object reference that specifies a Service by its Name, Kind (Service), and optionally its Namespace and Group.
90+
TargetRefs identify the Service/s for which your HTTPRoute requires TLS.
91+
92+
93+
- Cross-namespace certificate references are not allowed.
94+
95+
### BackendTLSPolicyValidation
96+
97+
A BackendTLSPolicyValidation is the specification for the BackendTLSPolicy and defines the configuration for TLS,
98+
including hostname (for server name indication) and certificates.
99+
100+
#### Hostname
101+
102+
Hostname defines the server name indication (SNI) the Gateway should use in order to connect to the backend, and must
103+
match the certificate served by the backend pod. A hostname is the fully qualified domain name of a network host, as
104+
defined by [RFC 3986][rfc-3986]. Note the following deviations from the “host” part of the URI as defined in the RFC:
105+
106+
- IP addresses are not allowed.
107+
108+
Also note:
109+
110+
111+
- Wildcard hostnames are not allowed.
112+
113+
#### Certificates
114+
115+
The BackendTLSPolicyValidation must contain a certificate reference of some kind, and contains two ways to configure the
116+
certificate to use for backend TLS, CACertificateRefs and WellKnownCACertificates. Only one of these may be used per
117+
BackendTLSPolicyValidation.
118+
119+
##### CACertificateRefs
120+
121+
CACertificateRefs refer to one or more PEM-encoded TLS certificates.
122+
123+
124+
- Cross-namespace certificate references are not allowed.
125+
126+
##### WellKnownCACertificates
127+
128+
If you are working in an environment where specific TLS certificates are not required, and your Gateway API
129+
implementation allows system or default certificates to be used, e.g. in a development environment, you may
130+
set WellKnownCACertificates to "System" to tell the Gateway to use a set of trusted CA Certificates. There may be
131+
some variation in which system certificates are used by each implementation. Refer to documentation from your
132+
implementation of choice for more information.
133+
134+
### PolicyStatus
135+
136+
Status defines the observed state of the BackendTLSPolicy and is not user-configurable. Check status in the same
137+
way you do for other Gateway API objects to verify correct operation. Note that the status in BackendTLSPolicy
138+
uses `PolicyAncestorStatus` to allow you to know which parentReference set that particular status.
139+
140+
[backendtlspolicy]: https://gateway-api.sigs.k8s.io/references/spec#gateway.networking.k8s.io/v1alpha3.BackendTLSPolicy
141+
[validation]: https://gateway-api.sigs.k8s.io/references/spec#gateway.networking.k8s.io/v1alpha3.BackendTLSPolicy.Validation
142+
[caCertificateRefs]: https://gateway-api.sigs.k8s.io/references/spec#gateway.networking.k8s.io/v1alpha3.BackendTLSPolicyValidation.CACertificateRefs
143+
[wellKnownCACertificates]: https://gateway-api.sigs.k8s.io/references/spec#gateway.networking.k8s.io/v1alpha3.BackendTLSPolicyValidation.WellKnownCACertificates
144+
[hostname]: https://gateway-api.sigs.k8s.io/references/spec#gateway.networking.k8s.io/v1.PreciseHostname
145+
[rfc-3986]: https://tools.ietf.org/html/rfc3986
146+
[targetRefs]: https://gateway-api.sigs.k8s.io/references/spec#gateway.networking.k8s.io/v1alpha2.PolicyTargetReference

‎site/content/en/v1.5/api/gateway_api/gateway.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
+++
2+
title = "Gateway"
3+
+++
4+
5+
6+
The `Gateway` resource is GA and has been part of the Standard Channel since
7+
`v0.5.0`. For more information on release channels, refer to our [versioning
8+
guide](https://gateway-api.sigs.k8s.io/concepts/versioning).
9+
10+
A `Gateway` is 1:1 with the lifecycle of the configuration of infrastructure.
11+
When a user creates a `Gateway`, some load balancing infrastructure is
12+
provisioned or configured (see below for details) by the `GatewayClass`
13+
controller. `Gateway` is the resource that triggers actions in this API. Other
14+
resources in this API are configuration snippets until a Gateway has been
15+
created to link the resources together.
16+
17+
The `Gateway` spec defines the following:
18+
19+
* `GatewayClassName`- Defines the name of a `GatewayClass` object used by
20+
this Gateway.
21+
* `Listeners`- Define the hostnames, ports, protocol, termination, TLS
22+
settings and which routes can be attached to a listener.
23+
* `Addresses`- Define the network addresses requested for this gateway.
24+
25+
If the desired configuration specified in Gateway spec cannot be achieved, the
26+
Gateway will be in an error state with details provided by status conditions.
27+
28+
### Deployment models
29+
30+
Depending on the `GatewayClass`, the creation of a `Gateway` could do any of
31+
the following actions:
32+
33+
* Use cloud APIs to create an LB instance.
34+
* Spawn a new instance of a software LB (in this or another cluster).
35+
* Add a configuration stanza to an already instantiated LB to handle the new
36+
routes.
37+
* Program the SDN to implement the configuration.
38+
* Something else we haven’t thought of yet...
39+
40+
The API does not specify which one of these actions will be taken.
41+
42+
### Gateway Status
43+
44+
`GatewayStatus` is used to surface the status of a `Gateway` relative to the
45+
desired state represented in `spec`. `GatewayStatus` consists of the following:
46+
47+
- `Addresses`- Lists the IP addresses that have actually been bound to the
48+
Gateway.
49+
- `Listeners`- Provide status for each unique listener defined in `spec`.
50+
- `Conditions`- Describe the current status conditions of the Gateway.
51+
52+
Both `Conditions` and `Listeners.conditions` follow the conditions pattern used
53+
elsewhere in Kubernetes. This is a list that includes a type of condition, the
54+
status of the condition and the last time this condition changed.

‎site/content/en/v1.5/api/gateway_api/gatewayclass.md‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
+++
2+
title = "GatewayClass"
3+
+++
4+
5+
6+
The `GatewayClass` resource is GA and has been part of the Standard Channel since
7+
`v0.5.0`. For more information on release channels, refer to our [versioning
8+
guide](https://gateway-api.sigs.k8s.io/concepts/versioning).
9+
10+
[GatewayClass][gatewayclass] is cluster-scoped resource defined by the
11+
infrastructure provider. This resource represents a class of Gateways that can
12+
be instantiated.
13+
14+
> Note: GatewayClass serves the same function as the
15+
> [`networking.IngressClass` resource][ingress-class-api].
16+
17+
```yaml
18+
kind: GatewayClass
19+
metadata:
20+
name: cluster-gateway
21+
spec:
22+
controllerName: "example.net/gateway-controller"
23+
```
24+
25+
We expect that one or more `GatewayClasses` will be created by the
26+
infrastructure provider for the user. It allows decoupling of which mechanism
27+
(e.g. controller) implements the `Gateways` from the user. For instance, an
28+
infrastructure provider may create two `GatewayClasses` named `internet` and
29+
`private` to reflect `Gateways` that define Internet-facing vs private, internal
30+
applications.
31+
32+
```yaml
33+
kind: GatewayClass
34+
metadata:
35+
name: internet
36+
...
37+
---
38+
kind: GatewayClass
39+
metadata:
40+
name: private
41+
...
42+
```
43+
44+
The user of the classes will not need to know *how* `internet` and `private` are
45+
implemented. Instead, the user will only need to understand the resulting
46+
properties of the class that the `Gateway` was created with.
47+
48+
### GatewayClass parameters
49+
50+
Providers of the `Gateway` API may need to pass parameters to their controller
51+
as part of the class definition. This is done using the
52+
`GatewayClass.spec.parametersRef` field:
53+
54+
```yaml
55+
# GatewayClass for Gateways that define Internet-facing applications.
56+
kind: GatewayClass
57+
metadata:
58+
name: internet
59+
spec:
60+
controllerName: "example.net/gateway-controller"
61+
parametersRef:
62+
group: example.net
63+
kind: Config
64+
name: internet-gateway-config
65+
---
66+
apiVersion: example.net/v1alpha1
67+
kind: Config
68+
metadata:
69+
name: internet-gateway-config
70+
spec:
71+
ip-address-pool: internet-vips
72+
...
73+
```
74+
75+
Using a Custom Resource for `GatewayClass.spec.parametersRef` is encouraged
76+
but implementations may resort to using a ConfigMap if needed.
77+
78+
### GatewayClass status
79+
80+
`GatewayClasses` MUST be validated by the provider to ensure that the configured
81+
parameters are valid. The validity of the class will be signaled to the user via
82+
`GatewayClass.status`:
83+
84+
```yaml
85+
kind: GatewayClass
86+
...
87+
status:
88+
conditions:
89+
- type: Accepted
90+
status: False
91+
...
92+
```
93+
94+
A new `GatewayClass` will start with the `Accepted` condition set to
95+
`False`. At this point the controller has not seen the configuration. Once the
96+
controller has processed the configuration, the condition will be set to
97+
`True`:
98+
99+
```yaml
100+
kind: GatewayClass
101+
...
102+
status:
103+
conditions:
104+
- type: Accepted
105+
status: True
106+
...
107+
```
108+
109+
If there is an error in the `GatewayClass.spec`, the conditions will be
110+
non-empty and contain information about the error.
111+
112+
```yaml
113+
kind: GatewayClass
114+
...
115+
status:
116+
conditions:
117+
- type: Accepted
118+
status: False
119+
Reason: BadFooBar
120+
Message: "foobar" is an FooBar.
121+
```
122+
123+
### GatewayClass controller selection
124+
125+
The `GatewayClass.spec.controller` field determines the controller implementation
126+
responsible for managing the `GatewayClass`. The format of the field is opaque
127+
and specific to a particular controller. The GatewayClass selected by a given
128+
controller field depends on how various controller(s) in the cluster interpret
129+
this field.
130+
131+
It is RECOMMENDED that controller authors/deployments make their selection
132+
unique by using a domain / path combination under their administrative control
133+
(e.g. controller managing of all `controller`s starting with `example.net` is the
134+
owner of the `example.net` domain) to avoid conflicts.
135+
136+
Controller versioning can be done by encoding the version of a controller into
137+
the path portion. An example scheme could be (similar to container URIs):
138+
139+
```text
140+
example.net/gateway/v1 // Use version 1
141+
example.net/gateway/v2.1 // Use version 2.1
142+
example.net/gateway // Use the default version
143+
```
144+
145+
[gatewayclass]: https://gateway-api.sigs.k8s.io/reference/spec#gateway.networking.k8s.io/v1.GatewayClass
146+
[ingress-class-api]: https://kubernetes.io/docs/concepts/services-networking/ingress/#ingress-class

0 commit comments

Comments
 (0)