Merge branch 'main' into envoy-als

.github/markdown_lint_config.json

@@ -29,7 +29,7 @@
   "MD028": false,
   "MD029": false,
   "MD030": false,
-  "MD031": true,
+  "MD031": false,
   "MD032": false,
   "MD033": false,
   "MD034": false,

site/content/en/docs/api/_index.md

@@ -1,5 +1,5 @@
 ---
-title: "API"
-description: This section includes APIs of Envoy Gateway.
+title: "API References"
+description: This section includes API References.
 weight: 80
 ---

site/content/en/docs/api/extension_types.md

@@ -1,5 +1,6 @@
 +++
-title = "API Reference"
+title = "Gateway API Extensions"
+description = "Envoy Gateway provides these extensions to support additional features not available in the Gateway API today"
 +++
 
 

site/content/en/docs/api/gateway_api/_index.md

@@ -0,0 +1,5 @@
+---
+title: "Kubernetes Gateway API"
+description: This section includes APIs of Kubernetes Gateway API.
+weight: 80
+---

site/content/en/docs/api/gateway_api/backendtlspolicy.md

@@ -0,0 +1,146 @@
++++
+title = "BackendTLSPolicy"
++++
+
+
+    The `BackendTLSPolicy` resource is Alpha and has been part of
+    the Experimental Channel since `v1.0.0`. For more information on release
+    channels, refer to our [versioning guide](https://gateway-api.sigs.k8s.io/concepts/versioning).
+
+[BackendTLSPolicy][backendtlspolicy] is a Gateway API type for specifying the TLS configuration
+of the connection from the Gateway to a backend pod/s via the Service API object.
+
+## Background
+
+`BackendTLSPolicy` specifically addresses the configuration of TLS in order to convey HTTPS from the Gateway
+dataplane to the backend.  This is referred to as "backend TLS termination" and enables the Gateway to know
+how to connect to a backend pod that has its own certificate.  
+
+While there are other API objects provided for TLS to be configured for **passthrough** and **edge** termination,
+this API object allows users to specifically configure **backend** TLS termination.  For more information on TLS
+configuration in Gateway API, see [TLS Configuration](https://gateway-api.sigs.k8s.io/guides/tls/).
+
+![Image showing three TLS Termination Types](https://gateway-api.sigs.k8s.io/images/tls-termination-types.png)
+
+BackendTLSPolicy is a Direct [PolicyAttachment](https://gateway-api.sigs.k8s.io/reference/policy-attachment/) without defaults or overrides,
+applied to a Service that accesses a backend, where the BackendTLSPolicy resides in the same namespace as the
+Service to which it is applied. The BackendTLSPolicy and the Service must reside in the same namespace in order
+to prevent the complications involved with sharing trust across namespace boundaries.  
+
+All Gateway API Routes that point to a referenced Service should respect a configured BackendTLSPolicy.
+
+## Spec
+
+The specification of a [BackendTLSPolicy][backendtlspolicy] consists of:
+
+- [TargetRefs][targetRefs] - Defines the targeted API object of the policy.  Only Service is allowed.
+- [Validation][validation] - Defines the configuration for TLS, including hostname, CACertificateRefs, and
+WellKnownCACertificates.
+- [Hostname][hostname] - Defines the Server Name Indication (SNI) that the Gateway uses to connect to the backend.
+- [CACertificateRefs][caCertificateRefs] - Defines one or more references to objects that contain PEM-encoded TLS certificates,
+which are used to establish a TLS handshake between the Gateway and backend Pod.  Either CACertificateRefs or
+WellKnownCACertificates may be specified, but not both.
+- [WellKnownCACertificates][wellKnownCACertificates] - Specifies whether system CA certificates may be used in the TLS
+handshake between the Gateway and backend Pod.  Either CACertificateRefs or WellKnownCACertificates may be specified, but not both.
+
+The following chart outlines the object definitions and relationship:
+```mermaid
+flowchart LR
+    backendTLSPolicy[["<b>backendTLSPolicy</b> <hr><align=left>BackendTLSPolicySpec: spec<br>PolicyStatus: status</align>"]]
+    spec[["<b>spec</b><hr>PolicyTargetReferenceWithSectionName: targetRefs <br> BackendTLSPolicyValidation: tls"]]
+    status[["<b>status</b><hr>[ ]PolicyAncestorStatus: ancestors"]]
+    validation[["<b>tls</b><hr>LocalObjectReference: caCertificateRefs<br>wellKnownCACertificatesType: wellKnownCACertificates/<br>PreciseHostname: hostname"]]
+    ancestorStatus[["<b>ancestors</b><hr>AncestorRef: parentReference<br>GatewayController: controllerName<br>[]Condition: conditions"]]
+    targetRefs[[<b>targetRefs</b><hr>]]
+    service["<b>service</>"]
+    backendTLSPolicy -->spec
+    backendTLSPolicy -->status
+    spec -->targetRefs & validation
+    status -->ancestorStatus
+    targetRefs -->service
+    note[<em>choose only one<hr> caCertificateRefs OR wellKnownCACertificates</em>]
+    style note fill:#fff
+    validation -.- note
+```
+
+The following illustrates a BackendTLSPolicy that configures TLS for a Service serving a backend:
+```mermaid
+flowchart LR
+    client(["client"])
+    gateway["Gateway"]
+    style gateway fill:#02f,color:#fff
+    httproute["HTTP<BR>Route"]
+    style httproute fill:#02f,color:#fff
+    service["Service"]
+    style service fill:#02f,color:#fff
+    pod1["Pod"]
+    style pod1 fill:#02f,color:#fff
+    pod2["Pod"]
+    style pod2 fill:#02f,color:#fff
+    client -.->|HTTP <br> request| gateway
+    gateway --> httproute
+    httproute -.->|BackendTLSPolicy|service
+    service --> pod1 & pod2
+```
+
+### Targeting backends
+
+A BackendTLSPolicy targets a backend Pod (or set of Pods) via one or more TargetRefs to a Service.  This TargetRef is a
+required object reference that specifies a Service by its Name, Kind (Service), and optionally its Namespace and Group.
+TargetRefs identify the Service/s for which your HTTPRoute requires TLS.
+
+
+    - Cross-namespace certificate references are not allowed.
+
+### BackendTLSPolicyValidation
+
+A BackendTLSPolicyValidation is the specification for the BackendTLSPolicy and defines the configuration for TLS,
+including hostname (for server name indication) and certificates.
+
+#### Hostname
+
+Hostname defines the server name indication (SNI) the Gateway should use in order to connect to the backend, and must
+match the certificate served by the backend pod. A hostname is the fully qualified domain name of a network host, as
+defined by [RFC 3986][rfc-3986]. Note the following deviations from the “host” part of the URI as defined in the RFC:
+
+- IP addresses are not allowed.
+
+Also note:
+
+
+    - Wildcard hostnames are not allowed.
+
+#### Certificates
+
+The BackendTLSPolicyValidation must contain a certificate reference of some kind, and contains two ways to configure the
+certificate to use for backend TLS, CACertificateRefs and WellKnownCACertificates.  Only one of these may be used per
+BackendTLSPolicyValidation.
+
+##### CACertificateRefs
+
+CACertificateRefs refer to one or more PEM-encoded TLS certificates.
+
+
+    - Cross-namespace certificate references are not allowed.
+
+##### WellKnownCACertificates
+
+If you are working in an environment where specific TLS certificates are not required, and your Gateway API
+implementation allows system or default certificates to be used, e.g. in a development environment, you may
+set WellKnownCACertificates to "System" to tell the Gateway to use a set of trusted CA Certificates. There may be
+some variation in which system certificates are used by each implementation. Refer to documentation from your
+implementation of choice for more information.
+
+### PolicyStatus
+
+Status defines the observed state of the BackendTLSPolicy and is not user-configurable.  Check status in the same
+way you do for other Gateway API objects to verify correct operation.  Note that the status in BackendTLSPolicy
+uses `PolicyAncestorStatus` to allow you to know which parentReference set that particular status.
+
+[backendtlspolicy]: https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1alpha3.BackendTLSPolicy
+[validation]: https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1alpha3.BackendTLSPolicy.Validation
+[caCertificateRefs]: https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1alpha3.BackendTLSPolicyValidation.CACertificateRefs
+[wellKnownCACertificates]: https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1alpha3.BackendTLSPolicyValidation.WellKnownCACertificates
+[hostname]: https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1.PreciseHostname
+[rfc-3986]: https://tools.ietf.org/html/rfc3986
+[targetRefs]: https://gateway-api.sigs.k8s.io/references/spec/#gateway.networking.k8s.io/v1alpha2.PolicyTargetReference

site/content/en/docs/api/gateway_api/gateway.md

@@ -0,0 +1,54 @@
++++
+title = "Gateway"
++++
+
+
+    The `Gateway` resource is GA and has been part of the Standard Channel since
+    `v0.5.0`. For more information on release channels, refer to our [versioning
+    guide](https://gateway-api.sigs.k8s.io/concepts/versioning).
+
+A `Gateway` is 1:1 with the lifecycle of the configuration of infrastructure.
+When a user creates a `Gateway`, some load balancing infrastructure is
+provisioned or configured (see below for details) by the `GatewayClass`
+controller. `Gateway` is the resource that triggers actions in this API. Other
+resources in this API are configuration snippets until a Gateway has been
+created to link the resources together.
+
+The `Gateway` spec defines the following:
+
+*   `GatewayClassName`- Defines the name of a `GatewayClass` object used by
+    this Gateway.
+*   `Listeners`-  Define the hostnames, ports, protocol, termination, TLS
+    settings and which routes can be attached to a listener.
+*   `Addresses`- Define the network addresses requested for this gateway.
+
+If the desired configuration specified in Gateway spec cannot be achieved, the
+Gateway will be in an error state with details provided by status conditions.
+
+### Deployment models
+
+Depending on the `GatewayClass`, the creation of a `Gateway` could do any of
+the following actions:
+
+* Use cloud APIs to create an LB instance.
+* Spawn a new instance of a software LB (in this or another cluster).
+* Add a configuration stanza to an already instantiated LB to handle the new
+  routes.
+* Program the SDN to implement the configuration.
+* Something else we haven’t thought of yet...
+
+The API does not specify which one of these actions will be taken.
+
+### Gateway Status
+
+`GatewayStatus` is used to surface the status of a `Gateway` relative to the
+desired state represented in `spec`. `GatewayStatus` consists of the following:
+
+- `Addresses`- Lists the IP addresses that have actually been bound to the
+  Gateway.
+- `Listeners`- Provide status for each unique listener defined in `spec`.
+- `Conditions`- Describe the current status conditions of the Gateway.
+
+Both `Conditions` and `Listeners.conditions` follow the conditions pattern used
+elsewhere in Kubernetes. This is a list that includes a type of condition, the
+status of the condition and the last time this condition changed.

site/content/en/docs/api/gateway_api/gatewayclass.md

@@ -0,0 +1,146 @@
++++
+title = "GatewayClass"
++++
+
+
+    The `GatewayClass` resource is GA and has been part of the Standard Channel since
+    `v0.5.0`. For more information on release channels, refer to our [versioning
+    guide](https://gateway-api.sigs.k8s.io/concepts/versioning).
+
+[GatewayClass][gatewayclass] is cluster-scoped resource defined by the
+infrastructure provider. This resource represents a class of Gateways that can
+be instantiated.
+
+> Note: GatewayClass serves the same function as the
+> [`networking.IngressClass` resource][ingress-class-api].
+
+```yaml
+kind: GatewayClass
+metadata:
+  name: cluster-gateway
+spec:
+  controllerName: "example.net/gateway-controller"
+```
+
+We expect that one or more `GatewayClasses` will be created by the
+infrastructure provider for the user. It allows decoupling of which mechanism
+(e.g. controller) implements the `Gateways` from the user. For instance, an
+infrastructure provider may create two `GatewayClasses` named `internet` and
+`private` to reflect `Gateways` that define Internet-facing vs private, internal
+applications.
+
+```yaml
+kind: GatewayClass
+metadata:
+  name: internet
+  ...
+---
+kind: GatewayClass
+metadata:
+  name: private
+  ...
+```
+
+The user of the classes will not need to know *how* `internet` and `private` are
+implemented. Instead, the user will only need to understand the resulting
+properties of the class that the `Gateway` was created with.
+
+### GatewayClass parameters
+
+Providers of the `Gateway` API may need to pass parameters to their controller
+as part of the class definition. This is done using the
+`GatewayClass.spec.parametersRef` field:
+
+```yaml
+# GatewayClass for Gateways that define Internet-facing applications.
+kind: GatewayClass
+metadata:
+  name: internet
+spec:
+  controllerName: "example.net/gateway-controller"
+  parametersRef:
+    group: example.net
+    kind: Config
+    name: internet-gateway-config
+---
+apiVersion: example.net/v1alpha1
+kind: Config
+metadata:
+  name: internet-gateway-config
+spec:
+  ip-address-pool: internet-vips
+  ...
+```
+
+Using a Custom Resource for `GatewayClass.spec.parametersRef` is encouraged
+but implementations may resort to using a ConfigMap if needed.
+
+### GatewayClass status
+
+`GatewayClasses` MUST be validated by the provider to ensure that the configured
+parameters are valid. The validity of the class will be signaled to the user via
+`GatewayClass.status`:
+
+```yaml
+kind: GatewayClass
+...
+status:
+  conditions:
+  - type: Accepted
+    status: False
+    ...
+```
+
+A new `GatewayClass` will start with the `Accepted` condition set to
+`False`. At this point the controller has not seen the configuration. Once the
+controller has processed the configuration, the condition will be set to
+`True`:
+
+```yaml
+kind: GatewayClass
+...
+status:
+  conditions:
+  - type: Accepted
+    status: True
+    ...
+```
+
+If there is an error in the `GatewayClass.spec`, the conditions will be
+non-empty and contain information about the error.
+
+```yaml
+kind: GatewayClass
+...
+status:
+  conditions:
+  - type: Accepted
+    status: False
+    Reason: BadFooBar
+    Message: "foobar" is an FooBar.
+```
+
+### GatewayClass controller selection
+
+The `GatewayClass.spec.controller` field determines the controller implementation
+responsible for managing the `GatewayClass`. The format of the field is opaque
+and specific to a particular controller. The GatewayClass selected by a given
+controller field depends on how various controller(s) in the cluster interpret
+this field.
+
+It is RECOMMENDED that controller authors/deployments make their selection
+unique by using a domain / path combination under their administrative control
+(e.g. controller managing of all `controller`s starting with `example.net` is the
+owner of the `example.net` domain) to avoid conflicts.
+
+Controller versioning can be done by encoding the version of a controller into
+the path portion. An example scheme could be (similar to container URIs):
+
+```text
+example.net/gateway/v1   // Use version 1
+example.net/gateway/v2.1 // Use version 2.1
+example.net/gateway      // Use the default version
+```
+
+[gatewayclass]: https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1.GatewayClass
+[ingress-class-api]: https://kubernetes.io/docs/concepts/services-networking/ingress/#ingress-class