From e4f610a02498c8705a12bfbdce4ac13b24634061 Mon Sep 17 00:00:00 2001 From: Michael Nairn Date: Fri, 9 Feb 2024 08:58:14 +0000 Subject: [PATCH] docs: add tls and dns policy docs * Add dnspolicy overview and reference docs * Add tlspolicy overview and reference docs --- doc/dns.md | 281 +++++++++++++++++++++++++++++++++ doc/reference/dnspolicy.md | 87 ++++++++++ doc/reference/tlspolicy.md | 35 ++++ doc/tls.md | 72 +++++++++ doc/user-guides/gateway-dns.md | 5 - doc/user-guides/gateway-tls.md | 5 - 6 files changed, 475 insertions(+), 10 deletions(-) create mode 100644 doc/dns.md create mode 100644 doc/reference/dnspolicy.md create mode 100644 doc/reference/tlspolicy.md create mode 100644 doc/tls.md diff --git a/doc/dns.md b/doc/dns.md new file mode 100644 index 000000000..33e22a6f6 --- /dev/null +++ b/doc/dns.md @@ -0,0 +1,281 @@ +# Kuadrant DNS + +A Kuadrant DNSPolicy custom resource: + +1. Targets Gateway API networking resources [Gateways](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1.Gateway) to provide dns management by managing the lifecycle of dns records in external dns providers such as AWS Route53 and Google DNS. + +## How it works + +A DNSPolicy and its targeted Gateway API networking resource contain all the statements to configure both the ingress gateway and the external DNS service. +The needed dns names are gathered from the listener definitions and the IPAdresses | CNAME hosts are gathered from the status block of the gateway resource. + +### The DNSPolicy custom resource + +#### Overview + +The `DNSPolicy` spec includes the following parts: + +* A reference to an existing Gateway API resource (`spec.targetRef`) +* DNS Routing Strategy (`spec.routingStrategy`) +* LoadBalancing specification (`spec.loadBalancing`) +* HealthCheck specification (`spec.healthCheck`) + +#### High-level example and field definition + +```yaml +apiVersion: kuadrant.io/v1alpha1 +kind: DNSPolicy +metadata: + name: my-dns-policy +spec: + # reference to an existing networking resource to attach the policy to + # it can only be a Gateway API Gateway resource + # it can only refer to objects in the same namespace as the DNSPolicy + targetRef: + group: gateway.networking.k8s.io + kind: Gateway + name: mygateway + + # (optional) routing strategy to use when creating DNS records, defaults to `loadbalanced` + # determines what DNS records are created in the DNS provider + # check out Kuadrant RFC 0005 https://github.com/Kuadrant/architecture/blob/main/rfcs/0005-single-cluster-dnspolicy.md to learn more about the Routing Strategy field + # One-of: simple, loadbalanced. + routingStrategy: loadbalanced + + # (optional) loadbalancing specification + # use it for providing the specification of how dns will be configured in order to provide balancing of load across multiple clusters when using the `loadbalanced` routing strategy + # Primary use of this is for multi cluster deployments + # check out Kuadrant RFC 0003 https://github.com/Kuadrant/architecture/blob/main/rfcs/0003-dns-policy.md to learn more about the options that can be used in this field + loadBalancing: + # (optional) weighted specification + # use it to control the weight value applied to records + weighted: + # use it to change the weight of a record based on labels applied to the target meta resource i.e. Gateway in a single cluster context or ManagedCluster in multi cluster with OCM + custom: + - weight: 200 + selector: + matchLabels: + kuadrant.io/lb-attribute-custom-weight: AWS + # (optional) weight value that will be applied to weighted dns records by default. Integer greater than 0 and no larger than the maximum value accepted by the target dns provider, defaults to `120` + defaultWeight: 100 + # (optional) geo specification + # use it to control the geo value applied to records + geo: + # (optional) default geo to be applied to records + defaultGeo: IE + + # (optional) health check specification + # health check probes with the following specification will be created for each DNS target + healthCheck: + allowInsecureCertificates: true + endpoint: / + expectedResponses: + - 200 + - 201 + - 301 + failureThreshold: 5 + port: 443 + protocol: https +``` + +Check out the [API reference](../reference/dnspolicy.md) for a full specification of the DNSPolicy CRD. + +## Using the DNSPolicy + +### DNS Provider and ManagedZone Setup + +A DNSPolicy acts against a target Gateway by processing its listeners for hostnames that it can create dns records for. +In order for it to do this, it must know about dns providers, and what domains these dns providers are currently hosting. +This is done through the creation of ManagedZones and dns provider secrets containing the credentials for the dns provider account. + +If for example a Gateway is created with a listener with a hostname of `echo.apps.hcpapps.net`: +```yaml +apiVersion: gateway.networking.k8s.io/v1 +kind: Gateway +metadata: + name: my-gw +spec: + listeners: + - allowedRoutes: + namespaces: + from: All + name: api + hostname: echo.apps.hcpapps.net + port: 80 + protocol: HTTP +``` + +In order for the DNSPolicy to act upon that listener, a ManagedZone must exist for that hostnames' domain. + +```yaml +apiVersion: kuadrant.io/v1alpha1 +kind: ManagedZone +metadata: + name: apps.hcpapps.net +spec: + domainName: apps.hcpapps.net + description: "apps.hcpapps.net managed domain" + dnsProviderSecretRef: + name: my-aws-credentials +``` + +The managed zone references a secret containing the external DNS provider services credentials. + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: my-aws-credentials + namespace: +data: + AWS_ACCESS_KEY_ID: + AWS_REGION: + AWS_SECRET_ACCESS_KEY: +type: kuadrant.io/aws +``` + +### Targeting a Gateway networking resource + +When a DNSPolicy targets a Gateway, the policy will be enforced on all gateway listeners that have a matching ManagedZone. + +Target a Gateway by setting the `spec.targetRef` field of the DNSPolicy as follows: + +```yaml +apiVersion: kuadrant.io/v1beta2 +kind: DNSPolicy +metadata: + name: +spec: + targetRef: + group: gateway.networking.k8s.io + kind: Gateway + name: +``` + +### DNSRecord Resource + +The DNSPolicy will create a DNSRecord resource for each listener hostname with a suitable ManagedZone configured. The DNSPolicy resource uses the status of the Gateway to determine what dns records need to be created based on the clusters it has been placed onto. + +Given the following multi cluster gateway status: +```yaml +status: + addresses: + - type: kuadrant.io/MultiClusterIPAddress + value: kind-mgc-workload-1/172.31.201.1 + - type: kuadrant.io/MultiClusterIPAddress + value: kind-mgc-workload-2/172.31.202.1 + listeners: + - attachedRoutes: 1 + conditions: [] + name: kind-mgc-workload-1.api + supportedKinds: [] + - attachedRoutes: 1 + conditions: [] + name: kind-mgc-workload-2.api + supportedKinds: [] +``` + +A DNSPolicy targeting this gateway would create an appropriate DNSRecord based on the routing strategy selected. + +#### loadbalanced +```yaml +apiVersion: kuadrant.io/v1alpha1 +kind: DNSRecord +metadata: + name: echo.apps.hcpapps.net + namespace: +spec: + endpoints: + - dnsName: 24osuu.lb-2903yb.echo.apps.hcpapps.net + recordTTL: 60 + recordType: A + targets: + - 172.31.202.1 + - dnsName: default.lb-2903yb.echo.apps.hcpapps.net + providerSpecific: + - name: weight + value: "120" + recordTTL: 60 + recordType: CNAME + setIdentifier: 24osuu.lb-2903yb.echo.apps.hcpapps.net + targets: + - 24osuu.lb-2903yb.echo.apps.hcpapps.net + - dnsName: default.lb-2903yb.echo.apps.hcpapps.net + providerSpecific: + - name: weight + value: "120" + recordTTL: 60 + recordType: CNAME + setIdentifier: lrnse3.lb-2903yb.echo.apps.hcpapps.net + targets: + - lrnse3.lb-2903yb.echo.apps.hcpapps.net + - dnsName: echo.apps.hcpapps.net + recordTTL: 300 + recordType: CNAME + targets: + - lb-2903yb.echo.apps.hcpapps.net + - dnsName: lb-2903yb.echo.apps.hcpapps.net + providerSpecific: + - name: geo-country-code + value: '*' + recordTTL: 300 + recordType: CNAME + setIdentifier: default + targets: + - default.lb-2903yb.echo.apps.hcpapps.net + - dnsName: lrnse3.lb-2903yb.echo.apps.hcpapps.net + recordTTL: 60 + recordType: A + targets: + - 172.31.201.1 + managedZone: + name: apps.hcpapps.net +``` + +After DNSRecord reconciliation the listener hostname should be resolvable through dns: + +```bash +dig echo.apps.hcpapps.net +short +lb-2903yb.echo.apps.hcpapps.net. +default.lb-2903yb.echo.apps.hcpapps.net. +lrnse3.lb-2903yb.echo.apps.hcpapps.net. +172.31.201.1 +``` + +#### simple +```yaml +apiVersion: kuadrant.io/v1alpha1 +kind: DNSRecord +metadata: + name: echo.apps.hcpapps.net + namespace: +spec: + endpoints: + - dnsName: echo.apps.hcpapps.net + recordTTL: 60 + recordType: A + targets: + - 172.31.201.1 + - 172.31.202.1 + managedZone: + name: apps.hcpapps.net +``` + +After DNSRecord reconciliation the listener hostname should be resolvable through dns: + +```bash +dig echo.apps.hcpapps.net +short +172.31.201.1 +``` + +### Examples + +Check out the following user guides for examples of using the Kuadrant DNSPolicy: + +[//]: # (ToDo mnairn) +[//]: # (* [Multicluster LoadBalanced DNSPolicy](../how-to/multicluster-loadbalanced-dnspolicy.md)) + +### Known limitations + +* One Gateway can only be targeted by one DNSPolicy. +* DNSPolicies can only target Gateways defined within the same namespace of the DNSPolicy. diff --git a/doc/reference/dnspolicy.md b/doc/reference/dnspolicy.md new file mode 100644 index 000000000..97f74ee30 --- /dev/null +++ b/doc/reference/dnspolicy.md @@ -0,0 +1,87 @@ +# The DNSPolicy Custom Resource Definition (CRD) + +- [DNSPolicy](#DNSPolicy) +- [DNSPolicySpec](#dnspolicyspec) + - [HealthCheckSpec](#healthcheckspec) + - [AdditionalHeadersRef](#additionalheadersref) + - [LoadBalancingSpec](#loadbalancingspec) + - [LoadBalancingWeighted](#loadbalancingweighted) + - [CustomWeight](#customweight) + - [LoadBalancingGeo](#loadbalancinggeo) +- [DNSPolicyStatus](#dnspolicystatus) + +## DNSPolicy + +| **Field** | **Type** | **Required** | **Description** | +|-----------|------------------------------------------------|:------------:|------------------------------------------------| +| `spec` | [DNSPolicySpec](#dnspolicyspec) | Yes | The specification for DNSPolicy custom resource | +| `status` | [DNSPolicyStatus](#dnspolicystatus) | No | The status for the custom resource | + +## DNSPolicySpec + +| **Field** | **Type** | **Required** | **Description** | +|-------------------|---------------------------------------------------------------------------------------------------------------------------------------------|:--------------:|----------------------------------------------------------------| +| `targetRef` | [Gateway API PolicyTargetReference](https://gateway-api.sigs.k8s.io/geps/gep-713/?h=policytargetreference#policy-targetref-api) | Yes | Reference to a Kuberentes resource that the policy attaches to | +| `healthCheck` | [HealthCheckSpec](#healthcheckspec) | No | HealthCheck spec | +| `loadBalancing` | [LoadBalancingSpec](#loadbalancingspec) | No | LoadBancking Spec | +| `routingStrategy` | String | Yes | Routing Strategy to use, one of "simple" or "loadbalacned" | + +## HealthCheckSpec + +| **Field** | **Type** | **Description** | +|-----------------------------|-----------------------------------------------|------------------------------------------------------------------------------------------------------------------------| +| `endpoint` | String | The endpoint to connect to (e.g. IP address or hostname of a clusters loadbalancer) | +| `port` | Number | The port to use | +| `protocol` | String | The protocol to use for this request (e.g. Https;Https) | +| `failureThreshold` | Number | Failure Threshold | +| `additionalHeadersRef` | [AdditionalHeadersRef](#additionalheadersref) | Secret ref which contains k/v: headers and their values that can be specified to ensure the health check is successful | +| `expectedResponses` | []Number | HTTP response codes that should be considered healthy (defaults are 200 and 201) | +| `allowInsecureCertificates` | Boolean | Allow using invalid (e.g. self-signed) certificates, default is false | +| `interval` | [Kubernetes meta/v1.Duration](https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#Duration) | How frequently this check would ideally be executed | + +## AdditionalHeadersRef + +| **Field** | **Type** | **Description** | +|-----------|------------|-------------------------------------------------------------| +| `name` | String | Name of the secret containing additional header information | + +## LoadBalancingSpec + +| **Field** | **Type** | **Description** | +|------------|-------------------------------------------------|-----------------------| +| `weighted` | [LoadBalancingWeighted](#loadbalancingweighted) | Weighted routing spec | +| `geo` | [LoadBalancingGeo](#loadbalancinggeo) | Geo routing spec | + +## LoadBalancingWeighted + +| **Field** | **Type** | **Description** | +|-----------------|----------------------------------|-----------------------------------------------------------------------| +| `defaultWeight` | Number | Default weight to apply to created records | +| `custom` | [][CustomWeight](#customweight) | Custom weights to manipulate records weights based on label selectors | + +## CustomWeight + +| **Field** | **Type** | **Description** | +|------------|----------------------|--------------------------------------------------------------------------| +| `selector` | metav1.LabelSelector | Label Selector to specify resources that should have this weight applied | +| `weight` | Number | Weight value to apply for matching resources | + +## LoadBalancingGeo + +| **Field** | **Type** | **Description** | +|--------------|----------|---------------------------------| +| `defaultGeo` | String | Default geo to apply to records | + +## DNSPolicyStatus + +| **Field** | **Type** | **Description** | +|----------------------|-----------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------| +| `observedGeneration` | String | Number of the last observed generation of the resource. Use it to check if the status info is up to date with latest resource spec. | +| `conditions` | [][Kubernetes meta/v1.Condition](https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#Condition) | List of conditions that define that status of the resource. | +| `healthCheck` | [HealthCheckStatus](#healthcheckstatus) | HealthCheck status. | + +## HealthCheckStatus + +| **Field** | **Type** | **Description** | +|---------------|-----------------------------------|-------------------------------------------------------------------------------------------------------------------------------------| +| `conditions` | [][Kubernetes meta/v1.Condition](https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#Condition) | List of conditions that define that status of the resource.
| diff --git a/doc/reference/tlspolicy.md b/doc/reference/tlspolicy.md new file mode 100644 index 000000000..f2ce44162 --- /dev/null +++ b/doc/reference/tlspolicy.md @@ -0,0 +1,35 @@ +# The TLSPolicy Custom Resource Definition (CRD) + +- [TLSPolicy](#TLSPolicy) +- [TLSPolicySpec](#tlspolicyspec) +- [TLSPolicyStatus](#tlspolicystatus) + +## TLSPolicy + +| **Field** | **Type** | **Required** | **Description** | +|-----------|-------------------------------------|:------------:|-------------------------------------------------| +| `spec` | [TLSPolicySpec](#tlspolicyspec) | Yes | The specification for TLSPolicy custom resource | +| `status` | [TLSPolicyStatus](#tlspolicystatus) | No | The status for the custom resource | + +## TLSPolicySpec + +| **Field** | **Type** | **Required** | **Description** | +|------------------------|----------------------------------------------------------------------------------------------------------------------------------------------|:------------:|--------------------------------------------------------------------------------------------------------------------------------------------------| +| `targetRef` | [Gateway API PolicyTargetReference](https://gateway-api.sigs.k8s.io/geps/gep-713/?h=policytargetreference#policy-targetref-api) | Yes | Reference to a Kuberentes resource that the policy attaches to | +| `issuerRef` | [CertManager meta/v1.ObjectReference](https://cert-manager.io/v1.13-docs/reference/api-docs/#meta.cert-manager.io/v1.ObjectReference) | Yes | IssuerRef is a reference to the issuer for the created certificate | +| `commonName` | String | No | CommonName is a common name to be used on the created certificate | +| `duration` | [Kubernetes meta/v1.Duration](https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#Duration) | No | The requested 'duration' (i.e. lifetime) of the created certificate. | +| `renewBefore` | [Kubernetes meta/v1.Duration](https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#Duration) | No | How long before the currently issued certificate's expiry cert-manager should renew the certificate. | +| `usages` | [][CertManager v1.KeyUsage](https://cert-manager.io/v1.13-docs/reference/api-docs/#cert-manager.io/v1.KeyUsage) | No | Usages is the set of x509 usages that are requested for the certificate. Defaults to `digital signature` and `key encipherment` if not specified | +| `revisionHistoryLimit` | Number | No | RevisionHistoryLimit is the maximum number of CertificateRequest revisions that are maintained in the Certificate's history | +| `privateKey` | [CertManager meta/v1.CertificatePrivateKey](https://cert-manager.io/v1.13-docs/reference/api-docs/#cert-manager.io/v1.CertificatePrivateKey) | No | Options to control private keys used for the Certificate | + + +**IssuerRef certmanmetav1.ObjectReference** + +## TLSPolicyStatus + +| **Field** | **Type** | **Description** | +|----------------------|-----------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------| +| `observedGeneration` | String | Number of the last observed generation of the resource. Use it to check if the status info is up to date with latest resource spec. | +| `conditions` | [][Kubernetes meta/v1.Condition](https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#Condition) | List of conditions that define that status of the resource. | diff --git a/doc/tls.md b/doc/tls.md new file mode 100644 index 000000000..ee74963a4 --- /dev/null +++ b/doc/tls.md @@ -0,0 +1,72 @@ +# TLS + +A Kuadrant TLSPolicy custom resource: + +1. Targets Gateway API networking resources [Gateways](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1.Gateway) to provide tls for gateway listeners by managing the lifecycle of tls certificates using [`CertManager`](https://cert-manager.io). + +## How it works + +[//]: # (ToDo mnairn) + +### The TLSPolicy custom resource + +#### Overview + +[//]: # (ToDo mnairn) + +The `TLSPolicy` spec includes the following parts: + +* A reference to an existing Gateway API resource (`spec.targetRef`) + +#### High-level example and field definition + +[//]: # (ToDo mnairn) + +```yaml +apiVersion: kuadrant.io/v1alpha1 +kind: TLSPolicy +metadata: + name: my-tls-policy +spec: + # reference to an existing networking resource to attach the policy to + # it can only be a Gateway API Gateway resource + # it can only refer to objects in the same namespace as the TLSPolicy + targetRef: + group: gateway.networking.k8s.io + kind: Gateway + name: mygateway +``` + +Check out the [API reference](../reference/tlspolicy.md) for a full specification of the TLSPolicy CRD. + +## Using the TLSPolicy + +[//]: # (ToDo mnairn) + +### Targeting a Gateway networking resource + +When a TLSPolicy targets a Gateway, the policy will be enforced on all gateway listeners that have a valid TLS section. + +Target a Gateway by setting the `spec.targetRef` field of the TLSPolicy as follows: + +```yaml +apiVersion: kuadrant.io/v1beta2 +kind: TLSPolicy +metadata: + name: +spec: + targetRef: + group: gateway.networking.k8s.io + kind: Gateway + name: +``` + +### Examples + +Check out the following user guides for examples of using the Kuadrant TLSPolicy: + +[//]: # (ToDo mnairn) + +### Known limitations + +[//]: # (ToDo mnairn) diff --git a/doc/user-guides/gateway-dns.md b/doc/user-guides/gateway-dns.md index 361a10bb5..2b48e36f4 100644 --- a/doc/user-guides/gateway-dns.md +++ b/doc/user-guides/gateway-dns.md @@ -26,11 +26,6 @@ Setup the environment: make local-setup ``` -Deploy policy controller and install DNSPolicy CRD: -```shell -make deploy-policy-controller -``` - Create a namespace: ```shell kubectl create namespace my-gateways diff --git a/doc/user-guides/gateway-tls.md b/doc/user-guides/gateway-tls.md index 3e9a7245a..a5e583727 100644 --- a/doc/user-guides/gateway-tls.md +++ b/doc/user-guides/gateway-tls.md @@ -25,11 +25,6 @@ Setup the environment: make local-setup ``` -Deploy policy controller and install TLSPolicy CRD: -```shell -make deploy-policy-controller -``` - Create a namespace: ```shell kubectl create namespace my-gateways