From 865a1797b70c1f34a9679bd14c7ad08b6d400378 Mon Sep 17 00:00:00 2001 From: Pablo RUTH Date: Tue, 18 Jan 2022 17:44:36 +0100 Subject: [PATCH] update docs Signed-off-by: Pablo RUTH --- site/content/docs/main/config/annotations.md | 3 ++ .../docs/main/config/tls-delegation.md | 41 ++++++++++++++++--- 2 files changed, 38 insertions(+), 6 deletions(-) diff --git a/site/content/docs/main/config/annotations.md b/site/content/docs/main/config/annotations.md index 19ab0d16944..71ac5efcc7f 100644 --- a/site/content/docs/main/config/annotations.md +++ b/site/content/docs/main/config/annotations.md @@ -49,6 +49,7 @@ The `ingress.kubernetes.io/force-ssl-redirect` annotation takes precedence over - `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`. + - `projectcontour.io/tls-cert-namespace`: The namespace where all TLS secrets of this Ingress are searched. This is necessary to use [TLS Certificate Delegation][18] with Ingress v1 because the slash notation (ex: different-ns/app-cert) used by HTTPProxy and Ingress v1beta1 is not accepted. See [this issue][19] for details. ## Contour specific Service annotations @@ -88,3 +89,5 @@ A [Kubernetes Service][9] maps to an [Envoy Cluster][10]. Envoy clusters have ma [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 +[18]: ../config/tls-delegation/ +[19]: https://github.com/projectcontour/contour/issues/3544 \ No newline at end of file diff --git a/site/content/docs/main/config/tls-delegation.md b/site/content/docs/main/config/tls-delegation.md index 3e52ea9d4c7..0c949a212fe 100644 --- a/site/content/docs/main/config/tls-delegation.md +++ b/site/content/docs/main/config/tls-delegation.md @@ -2,9 +2,7 @@ In order to support wildcard certificates, TLS certificates for a `*.somedomain.com`, which are stored in a namespace controlled by the cluster administrator, Contour supports a facility known as TLS Certificate Delegation. This facility allows the owner of a TLS certificate to delegate, for the purposes of referencing the TLS certificate, permission to Contour to read the Secret object from another namespace. -Delegation works for both HTTPProxy and Ingress v1beta1 resources (however it does not work with Ingress v1). -TLS Certificate Delegation is not currently supported on Ingress v1 resources due to changes in the spec that make this impossible. -See [this issue][0] for details. +Delegation works for both HTTPProxy and Ingress resources, however it needs an annotation to work with Ingress v1. The [`TLSCertificateDelegation`][1] resource defines a set of `delegations` in the `spec`. Each delegation references a `secretName` from the namespace where the `TLSCertificateDelegation` is created as well as describing a set of `targetNamespaces` in which the certificate can be referenced. @@ -24,7 +22,13 @@ spec: - secretName: another-com-wildcard targetNamespaces: - "*" ---- +``` + +In this example, the permission for Contour to reference the Secret `example-com-wildcard` in the `admin` namespace has been delegated to HTTPProxy and Ingress objects in the `example-com` namespace. +Also, the permission for Contour to reference the Secret `another-com-wildcard` from all namespaces has been delegated to all HTTPProxy and Ingress objects in the cluster. + +To reference the secret from an HTTPProxy or Ingress v1beta1 you must use the slash syntax in the `secretName`: +```yaml apiVersion: projectcontour.io/v1 kind: HTTPProxy metadata: @@ -41,8 +45,33 @@ spec: port: 80 ``` -In this example, the permission for Contour to reference the Secret `example-com-wildcard` in the `admin` namespace has been delegated to HTTPProxy objects in the `example-com` namespace. -Also, the permission for Contour to reference the Secret `another-com-wildcard` from all namespaces has been delegated to all HTTPProxy objects in the cluster. +To reference the secret from an Ingress v1 you must use the `projectcontour.io/tls-cert-namespace` annotation: +```yaml +apiVersion: networking.k8s.io/v1 +kind: Ingress +metadata: + annotations: + projectcontour.io/tls-cert-namespace: www-admin + name: www + namespace: example-com +spec: + rules: + - host: foo2.bar.com + http: + paths: + - path: / + pathType: Prefix + backend: + service: + name: s1 + port: + number: 80 + tls: + - hosts: + - foo2.bar.com + secretName: example-com-wildcard +``` + [0]: https://github.com/projectcontour/contour/issues/3544 [1]: /docs/{{< param version >}}/config/api/#projectcontour.io/v1.TLSCertificateDelegation