[release/v1.6] v1.6.0 docs + fix make doc in MacOS (#7487)

[release/v1.6] v1.6.0 docs

Signed-off-by: Rudrakh Panigrahi <[email protected]>

Author: rudrakhp

site/content/en/v1.6/_index.md

@@ -0,0 +1,15 @@
++++
+title = "Welcome to Envoy Gateway"
+linktitle = "Documentation"
+description = "Envoy Gateway Documents"
+
+[[cascade]]
+type = "docs"
++++
+
+Envoy Gateway is an open source project for managing [Envoy Proxy](https://www.envoyproxy.io/) as a standalone or Kubernetes-based application
+gateway. [Gateway API](https://gateway-api.sigs.k8s.io/) resources are used to dynamically provision and configure the managed Envoy Proxies.
+
+![architecture](/img/traffic.png)
+
+## Ready to get started?

site/content/en/v1.6/api/_index.md

@@ -0,0 +1,5 @@
+---
+title: "API References"
+description: This section includes API References.
+weight: 80
+---

site/content/en/v1.6/api/extension_types.md

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

site/content/en/v1.6/api/gateway_api/_index.md

@@ -0,0 +1,170 @@
++++
+title = "BackendTLSPolicy"
++++
+
+
+    The `BackendTLSPolicy` resource is GA and has been part of the Standard
+    Channel since `v1.4.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.
+- [SubjectAltNames][subjectAltNames] - Specifies one or more Subject Alternative Names that the backend certificate must match. When specified, the certificate must have at least one matching SAN. This field enables separation between SNI (hostname) and certificate identity validation.  A maximum of 5 SANs are allowed.  
+- [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.
+- [Options][options] - A map of key/value pairs enabling extended TLS configuration for implementations that choose to provide support.  Check your implementation's documentation for details.  
+
+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<br>[]SubjectAltName: subjectAltNames"]]  
+    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"]
+    httproute["HTTP<BR>Route"]
+    service["Service"]
+    pod1["Pod"]
+    pod2["Pod"]
+    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.
+
+#### Subject Alternative Names
+
+
+    This field was added to BackendTLSPolicy in `v1.2.0`
+The subjectAltNames field enables basic mutual TLS configuration between Gateways and backends, as well as the optional use of SPIFFE. When subjectAltNames is specified, the certificate served by the backend must have at least one Subject Alternative Name matching one of the specified values. This is particularly useful for SPIFFE implementations where URI-based SANs may not be valid SNIs.  
+Subject Alternative Names may contain one of either a Hostname or URI field, and must contain a Type specifying whether Hostname or URI is chosen.  
+
+
+    - IP addresses and wildcard hostnames are not allowed. (see the description for Hostname above for more details). 
+    - Hostname: DNS name format
+    - URI: URI format (e.g., SPIFFE ID)
+
+#### TLS Options
+
+
+    This field was added to BackendTLSPolicy in `v1.2.0`
+The options field allows specification of implementation-specific TLS configurations. This can include:  
+
+- Vendor-specific mutual TLS automation configuration  
+- Minimum supported TLS version restrictions
+- Supported cipher suite configurations
+
+Check your implementation documentation for details.  
+
+###
+#### 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/reference/1.4/spec/#backendtlspolicy
+[validation]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#backendtlspolicyvalidation
+[caCertificateRefs]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#localobjectreference
+[wellKnownCACertificates]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#localobjectreference
+[hostname]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#precisehostname
+[rfc-3986]: https://tools.ietf.org/html/rfc3986
+[targetRefs]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#localpolicytargetreferencewithsectionname
+[subjectAltNames]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#subjectaltname
+[options]: https://gateway-api.sigs.k8s.io/reference/1.4/spec/#backendtlspolicyspec

site/content/en/v1.6/api/gateway_api/backendtlspolicy.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.