Release 1.18.3 docs

site/config.yaml

@@ -39,6 +39,7 @@ params:
     - main
     - v1.19.1
     - v1.19.0
+    - v1.18.3
     - v1.18.2
     - v1.18.1
     - v1.18.0

site/content/docs/v1.18.3/README.md

@@ -0,0 +1,26 @@
+## Overview
+Contour is an Ingress controller for Kubernetes that works by deploying the [Envoy proxy][1] as a reverse proxy and load balancer.
+Contour supports dynamic configuration updates out of the box while maintaining a lightweight profile.
+
+Contour also introduces a new ingress API [HTTPProxy][2] which is implemented via a Custom Resource Definition (CRD).
+Its goal is to expand upon the functionality of the Ingress API to allow for a richer user experience as well as solve shortcomings in the original design.
+
+## Prerequisites
+Contour is tested with Kubernetes clusters running version [1.16 and later][4].
+
+RBAC must be enabled on your cluster.
+
+## Get started
+Getting started with Contour is as simple as one command.
+See the [Getting Started][3] document.
+
+## Troubleshooting
+If you encounter issues review the [troubleshooting][5] page, [file an issue][6], or talk to us on the [#contour channel][7] on Kubernetes slack.
+
+[1]: https://www.envoyproxy.io/
+[2]: config/fundamentals.md
+[3]: /getting-started
+[4]: /resources/compatibility-matrix.md
+[5]: /docs/main/troubleshooting
+[6]: https://github.com/projectcontour/contour/issues
+[7]: https://kubernetes.slack.com/messages/contour

site/content/docs/v1.18.3/_index.md

@@ -0,0 +1,7 @@
+---
+cascade:
+  layout: docs
+  version: v1.18.3
+---
+
+{{% include-html README.md %}}

site/content/docs/v1.18.3/architecture.md

@@ -0,0 +1,39 @@
+# Contour Architecture
+
+The Contour Ingress controller is a collaboration between:
+
+* Envoy, which provides the high performance reverse proxy.
+* Contour, which acts as a management server for Envoy and provides it with configuration.
+
+These containers are deployed separately, Contour as a Deployment and Envoy as a Daemonset, although other configurations are possible.
+
+In the Envoy Pods, Contour runs as an initcontainer in `bootstrap` mode and writes a bootstrap configuration to a temporary volume.
+This volume is passed to the Envoy container and directs Envoy to treat Contour as its [management server][1].
+
+After initialisation is complete, the Envoy container starts, retrieves the bootstrap configuration written by Contour's `bootstrap` mode, and establishes a GRPC session with Contour to receive configuration.
+
+Envoy will gracefully retry if the management server is unavailable, which removes any container startup ordering issues.
+
+Contour is a client of the Kubernetes API.
+Contour watches Ingress, HTTPProxy, Secret, Service, and Endpoint objects, and acts as the management server for its Envoy sibling by translating its cache of objects into the relevant JSON stanzas: Service objects for CDS, Ingress for RDS, Endpoint objects for EDS, and so on).
+
+The transfer of information from Kubernetes to Contour is by watching the API with the SharedInformer framework.
+
+Kubernetes readiness probes are configured to check whether Envoy is ready to accept connections.
+The Envoy readiness probe sends GET requests to `/ready` in Envoy's administration endpoint.
+
+For Contour, a liveness probe checks the `/healthz` running on the Pod's metrics port.
+Readiness probe is a TCP check that the gRPC port is open.
+
+## Diagram
+Below are a couple of high level architectural diagrams of how Contour works inside a Kubernetes cluster as well as showing the data path of a request to a backend pod.
+
+A request to `projectcontour.io/blog` gets routed via a load balancer to an instance of an Envoy proxy which then sends the request to a pod.
+
+![architectural overview][2]
+
+![architectural overview 2][3]
+
+[1]: https://www.envoyproxy.io/docs/envoy/v1.13.0/api-docs/xds_protocol
+[2]: ../img/archoverview.png
+[3]: ../img/contour_deployment_in_k8s.png

site/content/docs/v1.18.3/config/access-logging.md

@@ -0,0 +1,126 @@
+# Access Logging
+
+## Overview
+
+Contour allows you to control Envoy's access logging.
+By default, HTTP and HTTPS access logs are written to `/dev/stdout` by the Envoy containers and look like following:
+
+```
+[2021-04-14T16:36:00.361Z] "GET /foo HTTP/1.1" 200 - 0 463 6 3 "-" "HTTPie/1.0.3" "837aa8dc-344f-4faa-b7d5-c9cce1028519" "localhost:8080" "127.0.0.1:8081"
+```
+
+The detailed description of each field can be found in [Envoy access logging documentation][7].
+
+
+## Customizing Access Log Destination and Formats
+
+You can change the destination file where the access log is written by using Contour [command line parameters][1] `--envoy-http-access-log` and `--envoy-https-access-log`.
+
+The access log can take two different formats, both can be customized
+
+* Text based access logs, like shown in the example above.
+* Structured JSON logging.
+
+### Text Based Access Logging
+
+Ensure that you have selected `envoy` as the access log format.
+Note that this is the default format if the parameters are not given.
+
+- Add `--accesslog-format=envoy` to your Contour startup line, or
+- Add `accesslog-format: envoy` to your configuration file.
+
+Customize the access log format by defining `accesslog-format-string` in your configuration file.
+
+```yaml
+accesslog-format-string: "[%START_TIME%] \"%REQ(:METHOD)% %REQ(X-ENVOY-ORIGINAL-PATH?:PATH)% %PROTOCOL%\" %RESPONSE_CODE% %RESPONSE_FLAGS% %BYTES_RECEIVED% %BYTES_SENT% %DURATION% %RESP(X-ENVOY-UPSTREAM-SERVICE-TIME)% \"%REQ(X-FORWARDED-FOR)%\" \"%REQ(USER-AGENT)%\" \"%REQ(X-REQUEST-ID)%\" \"%REQ(:AUTHORITY)%\" \"%UPSTREAM_HOST%\"\n"
+```
+After restarting Contour and successful validation of the configuration, the new format will take effect in a short while.
+
+Refer to [Envoy access logging documentation][7] for the description of the command operators, and note that the format string needs to end in a linefeed `\n`.
+
+### Structured JSON Logging
+
+Contour allows you to choose from a set of JSON fields that will be expanded into Envoy templates and sent to Envoy.
+There is a default set of fields if you enable JSON logging, and you may customize which fields you log.
+
+The list of available fields are discoverable in the following objects:
+- [jsonFields][2] are fields that have built in mappings to commonly used envoy operators.
+- [envoySimpleOperators][3] are the names of simple envoy operators that don't require arguments, they are case-insensitive when configured.
+- [envoyComplexOperators][4] are the names of complex envoy operators that require arguments.
+
+The default list of fields is available at [DefaultFields][5].
+
+#### Enabling the Feature
+
+To enable the feature you have two options:
+
+- Add `--accesslog-format=json` to your Contour startup line.
+- Add `accesslog-format: json` to your configuration file.
+
+Without any further customization, the [default fields][5] will be used.
+
+#### Customizing Logged Fields
+
+To customize the logged fields, add a `json-fields` list of strings to your configuration file.
+If the `json-fields` key is not specified, the [default fields][5] will be configured.
+
+To use a value from [jsonFields][2] or [envoySimpleOperators][3], simply include the name of the value in the list of strings.
+The jsonFields are case-sensitive, but envoySimpleOperators are not.
+
+To use [envoyComplexOperators][4] or to use alternative field names, specify strings as key/value pairs like `"fieldName=%OPERATOR(...)%"`.
+
+Unknown field names in non key/value fields will result in validation errors, as will unknown Envoy operators in key/value fields.
+Note that the `DYNAMIC_METADATA` and `FILTER_STATE` Envoy logging operators are not supported at this time due to the complexity of their validation.
+
+See the [example config file][6] to see this used in context.
+
+#### Sample Configuration File
+
+Here is a sample config:
+
+```yaml
+accesslog-format: json
+json-fields:
+  - "@timestamp"
+  - "authority"
+  - "bytes_received"
+  - "bytes_sent"
+  - "customer_id=%REQ(X-CUSTOMER-ID)%"
+  - "downstream_local_address"
+  - "downstream_remote_address"
+  - "duration"
+  - "method"
+  - "path"
+  - "protocol"
+  - "request_id"
+  - "requested_server_name"
+  - "response_code"
+  - "response_flags"
+  - "uber_trace_id"
+  - "upstream_cluster"
+  - "upstream_host"
+  - "upstream_local_address"
+  - "upstream_service_time"
+  - "user_agent"
+  - "x_forwarded_for"
+```
+
+## Using Access Log Formatter Extensions
+
+Envoy allows implementing custom access log command operators as extensions.
+Following extensions are supported by Contour:
+
+| Command operator | Description |
+|------------------|-------------|
+| [REQ_WITHOUT_QUERY][8] | Works the same way as REQ except that it will remove the query string. It is used to avoid logging any sensitive information into the access log. |
+
+
+
+[1]: ../configuration#serve-flags
+[2]: https://github.com/search?q=jsonFields+repo%3Aprojectcontour%2Fcontour+path%3A%2Fpkg%2Fconfig+filename%3Aaccesslog.go&type=Code
+[3]: https://github.com/search?q=envoySimpleOperators+repo%3Aprojectcontour%2Fcontour+path%3A%2Fpkg%2Fconfig+filename%3Aaccesslog.go&type=Code
+[4]: https://github.com/search?q=envoyComplexOperators+repo%3Aprojectcontour%2Fcontour+path%3A%2Fpkg%2Fconfig+filename%3Aaccesslog.go&type=Code
+[5]: https://github.com/search?q=DefaultFields+repo%3Aprojectcontour%2Fcontour+path%3A%2Fpkg%2Fconfig+filename%3Aaccesslog.go&type=Code
+[6]: {{< param github_url >}}/tree/{{< param latest_version >}}/examples/contour/01-contour-config.yaml
+[7]: https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage
+[8]: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/formatter/req_without_query/v3/req_without_query.proto

site/content/docs/v1.18.3/config/annotations.md

@@ -0,0 +1,90 @@
+# Annotations Reference
+
+<div id="toc" class="navigation"></div>
+
+Annotations are used in Ingress Controllers to configure features that are not covered by the Kubernetes Ingress API.
+
+Some of the features that have been historically configured via annotations are supported as first-class features in Contour's [HTTPProxy API][15], which provides a more robust configuration interface over annotations.
+
+However, Contour still supports a number of annotations on the Ingress resources.
+
+## Standard Kubernetes Ingress annotations
+
+The following Kubernetes annotations are supported on `Ingress` objects:
+
+### Ingress Class
+
+The Ingress class annotation can be used to specify which Ingress controller should serve a particular Ingress object.
+This annotation may be specified as the standard `kubernetes.io/ingress.class` or a Contour-specific `projectcontour.io/ingress.class`.
+In both cases, they will behave as follows, by default:
+
+* If not set, then all Ingress controllers serve the Ingress.
+* If specified as `kubernetes.io/ingress.class: contour`, then Contour serves the Ingress.
+* If any other value, Contour ignores the Ingress definition.
+
+You can override the default class `contour` by providing the `--ingress-class-name` flag to Contour. 
+This can be useful while you are migrating from another controller, or if you need multiple instances of Contour.
+If you do this, the behavior is as follows:
+* If the annotation is not set, Contour will ignore the Ingress.
+* If the annotation is set to any value other than the one passed to the `--ingress-class-name` flag, Contour will ignore the Ingress.
+* If the annotation matches the value that you passed to `--ingress-class-name` flag, Contour will serve the Ingress.
+
+This same logic applies for these annotations on HTTPProxy objects.
+
+_Note: Both `Ingress` and `HTTPProxy` now have an `IngressClassName` field in their spec. Going forward this is the preferred way to specify an ingress class, rather than using an annotation. If both the annotation and the spec field are specified on an object, the annotation takes preference for backwards compatibility._
+
+### Other annotations 
+
+ - `ingress.kubernetes.io/force-ssl-redirect`: Requires TLS/SSL for the Ingress to Envoy by setting the [Envoy virtual host option require_tls][16].
+ - `kubernetes.io/ingress.allow-http`: Instructs Contour to not create an Envoy HTTP route for the virtual host. The Ingress exists only for HTTPS requests. Specify `"false"` for Envoy to mark the endpoint as HTTPS only. All other values are ignored.
+
+The `ingress.kubernetes.io/force-ssl-redirect` annotation takes precedence over `kubernetes.io/ingress.allow-http`. If they are set to `"true"` and `"false"` respectively, Contour *will* create an Envoy HTTP route for the Virtual host, and set the `require_tls` virtual host option.
+
+## Contour specific Ingress annotations
+
+ - `projectcontour.io/ingress.class`: The Ingress class that should interpret and serve the Ingress. See the [main Ingress class annotation section](#ingress-class) for more details.
+ - `projectcontour.io/num-retries`: [The maximum number of retries][1] Envoy should make before abandoning and returning an error to the client. Applies only if `projectcontour.io/retry-on` is specified.
+ - `projectcontour.io/per-try-timeout`: [The timeout per retry attempt][2], if there should be one. Applies only if `projectcontour.io/retry-on` is specified.
+ - `projectcontour.io/response-timeout`: [The Envoy HTTP route timeout][3], specified as a [golang duration][4]. By default, Envoy has a 15 second timeout for a backend service to respond. Set this to `infinity` to specify that Envoy should never timeout the connection to the backend. Note that the value `0s` / zero has special semantics for Envoy.
+ - `projectcontour.io/retry-on`: [The conditions for Envoy to retry a request][5]. See also [possible values and their meanings for `retry-on`][6].
+ - `projectcontour.io/tls-minimum-protocol-version`: [The minimum TLS protocol version][7] the TLS listener should support. Valid options are `1.3`, `1.2` (default), `1.1`.
+ - `projectcontour.io/websocket-routes`: [The routes supporting websocket protocol][8], the annotation value contains a list of route paths separated by a comma that must match with the ones defined in the `Ingress` definition. Defaults to Envoy's default behavior which is `use_websocket` to `false`.
+
+## Contour specific Service annotations
+
+A [Kubernetes Service][9] maps to an [Envoy Cluster][10]. Envoy clusters have many settings to control specific behaviors. These annotations allow access to some of those settings.
+
+- `projectcontour.io/max-connections`: [The maximum number of connections][11] that a single Envoy instance allows to the Kubernetes Service; defaults to 1024.
+- `projectcontour.io/max-pending-requests`: [The maximum number of pending requests][13] that a single Envoy instance allows to the Kubernetes Service; defaults to 1024.
+- `projectcontour.io/max-requests`: [The maximum parallel requests][13] a single Envoy instance allows to the Kubernetes Service; defaults to 1024
+- `projectcontour.io/max-retries`: [The maximum number of parallel retries][14] a single Envoy instance allows to the Kubernetes Service; defaults to 3. This is independent of the per-Kubernetes Ingress number of retries (`projectcontour.io/num-retries`) and retry-on (`projectcontour.io/retry-on`), which control whether retries are attempted and how many times a single request can retry.
+- `projectcontour.io/upstream-protocol.{protocol}` : The protocol used to proxy requests to the upstream service.
+  The annotation value contains a comma-separated list of port names and/or numbers that must match with the ones defined in the `Service` definition.
+  This value can also be specified in the `spec.routes.services[].protocol` field on the HTTPProxy object, where it takes precedence over the Service annotation.
+  Supported protocol names are: `h2`, `h2c`, and `tls`:
+  - The `tls` protocol allows for requests which terminate at Envoy to proxy via TLS to the upstream.
+    This protocol should be used for HTTP/1.1 services over TLS.
+    _Note that validating the upstream TLS certificate requires additionally setting the [validation][17] field._
+  - The `h2` protocol proxies requests to the upstream using HTTP/2 over TLS.
+  - The `h2c` protocol proxies requests to the the upstream using cleartext HTTP/2.
+
+## Contour specific HTTPProxy annotations
+- `projectcontour.io/ingress.class`: The Ingress class that should interpret and serve the HTTPProxy. See the [main Ingress class annotation section](#ingress-class) for more details.
+
+[1]: https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/router_filter#config-http-filters-router-x-envoy-max-retries
+[2]: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/route/v3/route_components.proto#envoy-v3-api-field-config-route-v3-retrypolicy-retry-on
+[3]: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/route/v3/route_components.proto#envoy-v3-api-field-config-route-v3-routeaction-timeout
+[4]: https://golang.org/pkg/time/#ParseDuration
+[5]: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/route/v3/route_components.proto#envoy-v3-api-field-config-route-v3-retrypolicy-retry-on
+[6]: https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/router_filter#config-http-filters-router-x-envoy-retry-on
+[7]: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/transport_sockets/tls/v3/common.proto.html#extensions-transport-sockets-tls-v3-tlsparameters
+[8]: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/route/v3/route_components.proto#envoy-v3-api-field-config-route-v3-routeaction-upgrade-configs
+[9]: https://kubernetes.io/docs/concepts/services-networking/service/
+[10]: https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/intro/terminology
+[11]: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/cluster/v3/circuit_breaker.proto#envoy-v3-api-field-config-cluster-v3-circuitbreakers-thresholds-max-connections
+[12]: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/cluster/v3/circuit_breaker.proto#envoy-v3-api-field-config-cluster-v3-circuitbreakers-thresholds-max-pending-requests
+[13]: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/cluster/v3/circuit_breaker.proto#envoy-v3-api-field-config-cluster-v3-circuitbreakers-thresholds-max-requests
+[14]: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/cluster/v3/circuit_breaker.proto#envoy-v3-api-field-config-cluster-v3-circuitbreakers-thresholds-max-retries
+[15]: fundamentals.md
+[16]: https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/route/v3/route_components.proto#envoy-v3-api-field-config-route-v3-virtualhost-require-tls
+[17]: api/#projectcontour.io/v1.UpstreamValidation