Project: Kusk Gateway (Orchestration & Management / API Gateway)
File: envoyfleet.md

This resource defines the Envoy Fleet, which is the implementation of the gateway in Kubernetes based on Envoy Proxy. Once the resource manifest is deployed to Kubernetes, it is used by Kusk Gateway Manager to set up K8s Envoy Proxy Deployment, ConfigMap and Service. The ConfigMap config bootstraps Envoy Proxy to connect to the service of the KGW Manager to retrieve the configuration. In its initial state there is a minimal configuration, you have to deploy API or StaticRoute resource to set up the routing. If the Custom Resource is uninstalled, the Manager deletes the created K8s resources. You can deploy multiple Envoy Fleets and have multiple Gateways available. Once the Fleet is deployed, its status field shows the success of the process (Deployed, Failed), so it can be shown with ```kubectl describe envoyfleet``` command. Currently, only the success of K8s resources deployment is shown, not if the Envoy Proxy pods are alive or if the Service has the External IP Address allocated. Supported parameters: metadata.name and metadata.namespace* - Used as the Envoy Fleet ID. The Manager will supply the configuration for this specific ID - Envoy will connect to the KGW Manager with it. API/Static Route can be deployed to this fleet using their fleet name field. spec.image* - The Envoy Proxy container image tag, usually envoyproxy/envoy-alpine. spec.service* - Defines the configuration of the K8s Service that exposes the Envoy Proxy deployment. It is similar to the K8s Service configuration but with a limited set of fields. spec.service.type* - Select the Service Type (NodePort, ClusterIP, LoadBalancer). spec.service.ports* - Expose TCP ports (80, 443 or any other) routed to the ports names that Deployment exposes (http, https); ports to which the Envoy Proxy listener binds. spec.service.annotations* - Add annotations to the Service that will control load balancer configuration in the specific cloud providers implementations (e.g. to set up the internal Google Cloud Platform load balancer in the Google Cloud Engine, we annotate Service with the related annotation). spec.service.loadBalancerIP* - Used to specify the pre-allocated Load Balancer IP address so it won't be deleted in case the Service is deleted. spec.service.externalTrafficPolicy - Optional parameter that denotes if this Service routes external traffic to node-local or cluster-wide endpoints. Local preserves the client source IP and avoids a second hop for LoadBalancer and Nodeport type services, but risks potentially imbalanced traffic spreading. Cluster* obscures the client source IP and may cause a second hop to another node, but should have good overall load-spreading. For the preservation of the real client IP in access logs, choose "Local" spec.size* - Optional parameter to specify the number of Envoy Proxy pods in the K8s deployment. If not specified, defaults to 1. spec.resources* - Optional parameter that configures the Envoy Proxy container CPU/Memory requests and limits. Read for the details. By default, no requests or limits are specified.

- Optional parameter that adds additional annotations to the Envoy Proxy pods, e.g. for Prometheus scraping. spec.nodeSelector, spec.tolerations and spec.affinity* - Optional parameters that provide the Envoy Proxy deployment settings for the K8s Pod scheduler. Read to understand how can you bind Envoy pods to some types of nodes (e.g. non-preemtible node type pool) and how to ensure that Envoy pods are placed onto the different nodes for High Availability. See the YAML example below, too. The structure of these fields are the same as for K8s Deployment. These options can be used simultaneously, influencing each other. spec.accesslog - Optional parameter that defines Envoy Proxy stdout HTTP requests logging. Each Envoy pod can stream the access log to stdout. If not specified, no streaming occurs. If specified, you must chose the format* and, optionally, the text or JSON template to tune the output. spec.accesslog.format - Required parameter that specifies the format of the output: JSON (structured) or text*. Note that JSON format doesn't preserve fields order. spec.accesslog.text_template|json_template* - Optional parameters that could be used to specify the exact Envoy request data to log. See for the details. If not specified, Kusk Gateway provided defaults. spec.tls* - Optional parameter that defines TLS settings for the Envoy Fleet. If not specified, the Envoy Fleet will accept only HTTP traffic. spec.tls.cipherSuites* - An optional field that, when specified, the TLS listener will only support the specified cipher list when negotiating TLS 1.0 or 1.2 (this setting has no effect when negotiating TLS 1.3). If not specified, a default list will be used. Defaults are different for server (downstream) and client (upstream) TLS configurations. For more information see: . spec.tls.tlsMinimumProtocolVersion* - An optional field specifying the minimum TLS protocol version. By default, TLSv12 for clients and TLSv10 for servers. spec.tls.tlsMaximumProtocolVersion* - An optional field specifying the maximum TLS protocol version. By default, TLSv12 for clients and TLSv13 for servers. spec.tls.https_redirect_hosts* - An optional field specifying the domain names to force use of HTTPS with. Non-secure HTTP requests with the matched Host header will be automatically redirected to secure HTTPS with the "301 Moved Permanently" code. spec.tls.tlsSecrets* - Secret name and namespace combinations for locating TLS secrets containing TLS certificates. More than one may be specified. Kusk Gateway Manager pulls the certificates from the secrets, extracts the matching hostnames from the SubjectAlternativeNames (SAN) certificate field and configures Envoy to use that certificate for those hostnames. spec.tls.tlsSecrets.secretRef* - The name of the Kubernetes secret containing the TLS certificate. spec.tls.tlsSecrets.namespace* - The namespace where the Kubernetes secret resides. ```yaml apiVersion: gateway.kusk.io/v1alpha1 kind: EnvoyFleet metadata: name: default namespace: default spec: image: "envoyproxy/envoy-alpine:v1.20.0" service: type: LoadBalancer ports: name: http port: 80 targetPort: http name: https port: 443 targetPort: http resources: requests: cpu: 10m memory: 100M size: 1 accesslog: format: text text_template: | "[%STARTTIME%]" "%REQ(:METHOD)%" "%REQ(X-ENVOY-ORIGINAL-PATH?:PATH)%" "%RESPONSECODE%" "%DURATION%" json_template: starttime: "%STARTTIME%" method: "%REQ(:METHOD)%" path: "%REQ(X-ENVOY-ORIGINAL-PATH?:PATH)%" responsecode: "%RESPONSECODE%" duration: "%DURATION%" ```