From 0104439b2226afecb007e3f0f34258b7481ff411 Mon Sep 17 00:00:00 2001 From: R-Lawton Date: Thu, 9 Jan 2025 15:56:28 +0000 Subject: [PATCH] Lint and moving sections to the correct location --- doc/overviews/dns.md | 27 +++++++++++---------- doc/overviews/rate-limiting.md | 1 - doc/reference/authpolicy.md | 3 +-- doc/reference/dnspolicy.md | 41 ++++++++++++++++---------------- doc/reference/kuadrant.md | 1 + doc/reference/ratelimitpolicy.md | 4 +--- 6 files changed, 37 insertions(+), 40 deletions(-) diff --git a/doc/overviews/dns.md b/doc/overviews/dns.md index 99e2d3348..5d493a884 100644 --- a/doc/overviews/dns.md +++ b/doc/overviews/dns.md @@ -6,7 +6,7 @@ Targets Gateway API networking resources [Gateways](https://gateway-api.sigs.k8s ## 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. +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 @@ -15,9 +15,9 @@ The needed dns names are gathered from the listener definitions and the IPAdress The `DNSPolicy` spec includes the following parts: -* A reference to an existing Gateway API resource (`spec.targetRef`) -* LoadBalancing specification (`spec.loadBalancing`) -* HealthCheck specification (`spec.healthCheck`) +- A reference to an existing Gateway API resource (`spec.targetRef`) +- LoadBalancing specification (`spec.loadBalancing`) +- HealthCheck specification (`spec.healthCheck`) Check out the [API reference](../reference/dnspolicy.md) for a full specification of the DNSPolicy CRD. @@ -25,11 +25,12 @@ Check out the [API reference](../reference/dnspolicy.md) for a full specificatio ### DNS Provider Setup -A DNSPolicy acts against a target Gateway by processing its listeners for hostnames that it can create dns records for. +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 the dns provider. This is done through the creation of dns provider secrets containing the credentials and configuration 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 @@ -61,7 +62,7 @@ data: type: kuadrant.io/aws ``` -By default, Kuadrant will list the available zones and find the matching zone based on the listener host in the gateway listener. If it finds more than one matching zone for a given listener host, it will not update any of those zones. +By default, Kuadrant will list the available zones and find the matching zone based on the listener host in the gateway listener. If it finds more than one matching zone for a given listener host, it will not update any of those zones. When providing a credential you should limit that credential down to just have write access to the zones you want Kuadrant to manage. Below is an example of a an AWS policy for doing this type of thing: ``` @@ -109,7 +110,6 @@ When providing a credential you should limit that credential down to just have w } ``` - ### Targeting a Gateway networking resource When a DNSPolicy targets a Gateway, the policy will be enforced on all gateway listeners. @@ -145,13 +145,12 @@ spec: sectionName: ``` - - ### DNSRecord Resource The DNSPolicy will create a DNSRecord resource for each listener hostname. 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: @@ -167,12 +166,13 @@ status: - attachedRoutes: 1 conditions: [] name: kind-mgc-workload-2.api - supportedKinds: [] + 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 @@ -238,6 +238,7 @@ lrnse3.lb-2903yb.echo.apps.hcpapps.net. ``` #### simple + ```yaml apiVersion: kuadrant.io/v1alpha1 kind: DNSRecord @@ -253,7 +254,7 @@ spec: - 172.31.201.1 - 172.31.202.1 providerRefs: - - name: my-aws-credentials + - name: my-aws-credentials ``` After DNSRecord reconciliation the listener hostname should be resolvable through dns: @@ -265,5 +266,5 @@ dig echo.apps.hcpapps.net +short ### Known limitations -* One Gateway can only be targeted by one DNSPolicy unless subsequent DNSPolicies choose to specific a sectionName in their targetRef. -* DNSPolicies can only target Gateways defined within the same namespace of the DNSPolicy. +- One Gateway can only be targeted by one DNSPolicy unless subsequent DNSPolicies choose to specific a sectionName in their targetRef. +- DNSPolicies can only target Gateways defined within the same namespace of the DNSPolicy. diff --git a/doc/overviews/rate-limiting.md b/doc/overviews/rate-limiting.md index 26bf55a87..3429043ce 100644 --- a/doc/overviews/rate-limiting.md +++ b/doc/overviews/rate-limiting.md @@ -44,7 +44,6 @@ The limit definitions (`limits`) can be declared at the top-level level of the s - ## Using the RateLimitPolicy ### Targeting a HTTPRoute networking resource diff --git a/doc/reference/authpolicy.md b/doc/reference/authpolicy.md index cb41a739a..ff669d40e 100644 --- a/doc/reference/authpolicy.md +++ b/doc/reference/authpolicy.md @@ -160,7 +160,6 @@ | `message` | String | Condition state description | | `lastTransitionTime` | Timestamp | Last transition timestamp | - #### High-level example ```yaml @@ -283,4 +282,4 @@ spec: callbacks: { … } when: […] patterns: { … } -``` \ No newline at end of file +``` diff --git a/doc/reference/dnspolicy.md b/doc/reference/dnspolicy.md index e328463c2..0accdf47e 100644 --- a/doc/reference/dnspolicy.md +++ b/doc/reference/dnspolicy.md @@ -2,15 +2,15 @@ - [DNSPolicy](#DNSPolicy) - [DNSPolicySpec](#dnspolicyspec) - - [excludeAddresses]() - - [ProviderRefs](#providerRefs) - - [HealthCheckSpec](#healthcheckspec) - - [LoadBalancingSpec](#loadbalancingspec) - - [LoadBalancingWeighted](#loadbalancingweighted) - - [CustomWeight](#customweight) - - [LoadBalancingGeo](#loadbalancinggeo) + - [excludeAddresses]() + - [ProviderRefs](#providerRefs) + - [HealthCheckSpec](#healthcheckspec) + - [LoadBalancingSpec](#loadbalancingspec) + - [LoadBalancingWeighted](#loadbalancingweighted) + - [CustomWeight](#customweight) + - [LoadBalancingGeo](#loadbalancinggeo) - [DNSPolicyStatus](#dnspolicystatus) - - [HealthCheckStatus](#healthcheckstatus) + - [HealthCheckStatus](#healthcheckstatus) ## DNSPolicy @@ -94,18 +94,18 @@ 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 - # it can target a specific listener using sectionName + # it can target a specific listener using sectionName targetRef: group: gateway.networking.k8s.io kind: Gateway name: mygateway sectionName: api # (optional) if not set policy applies to all listeners that do not have a policy attached directly - - # reference to an existing secret resource containing provider credentials and configuration - # it can only refer to Secrets in the same namespace as the DNSPolicy that have the type kuadrant.io/(provider) e.g kuadrant.io/aws + + # reference to an existing secret resource containing provider credentials and configuration + # it can only refer to Secrets in the same namespace as the DNSPolicy that have the type kuadrant.io/(provider) e.g kuadrant.io/aws providerRefs: - - name: my-aws-credentials - + - name: my-aws-credentials + # (optional) loadbalancing specification # use it for providing the specification of how dns will be configured in order to provide balancing of requests across multiple clusters. If not configured, a simple A or CNAME record will be created. If you have a policy with no loadbalancing defined and want to move to a loadbalanced configuration, you will need to delete and re-create the policy. loadBalancing: @@ -113,19 +113,19 @@ spec: defaultGeo: true # weighted specification. This will apply the given weight to the records created based on the targeted gateway listeners. If you have multiple gateways that share a listener host, you can set different weight values to influence how much traffic will be brought to a given gateway. weight: 100 - # This is the actual GEO location to set for records created by this policy. This can and should be different if you have multiple gateways across multiple geographic areas. - - # AWS: To see all regions supported by AWS Route 53, please see the official (documentation)[https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/resource-record-sets-values-geo.html]. With Route 53 when setting a continent code use a "GEO-" prefix otherwise it will be considered a country code. - + # This is the actual GEO location to set for records created by this policy. This can and should be different if you have multiple gateways across multiple geographic areas. + + # AWS: To see all regions supported by AWS Route 53, please see the official (documentation)[https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/resource-record-sets-values-geo.html]. With Route 53 when setting a continent code use a "GEO-" prefix otherwise it will be considered a country code. + # GCP: To see all regions supported by GCP Cloud DNS, please see the official (documentation)[https://cloud.google.com/compute/docs/regions-zones] - + #To see the different values you can use for the geo based DNS with Azure take a look at the following (documentation)[https://learn.microsoft.com/en-us/azure/traffic-manager/traffic-manager-geographic-regions] geo: IE # (optional) health check specification # health check probes with the following specification will be created for each DNS target, these probes constantly check that the endpoint can be reached. They will flag an unhealthy endpoint in the status. If no DNSRecord has yet been published and the endpoint is unhealthy, the record will not be published until the health check passes. healthCheck: - # the path on the listener host(s) that you want to check. + # the path on the listener host(s) that you want to check. path: /health # how many times does the health check need to fail before unhealthy. failureThreshold: 3 @@ -135,4 +135,3 @@ spec: additionalHeadersRef: name: headers ``` - diff --git a/doc/reference/kuadrant.md b/doc/reference/kuadrant.md index f3bfa7325..42045a93b 100644 --- a/doc/reference/kuadrant.md +++ b/doc/reference/kuadrant.md @@ -8,6 +8,7 @@ | `status` | [KuadrantStatus](#kuadrantstatus) | No | The status for the custom resources. | ## KuadrantSpec + Currently blank specification. ## KuadrantStatus diff --git a/doc/reference/ratelimitpolicy.md b/doc/reference/ratelimitpolicy.md index 9c62d00e1..ef5958658 100644 --- a/doc/reference/ratelimitpolicy.md +++ b/doc/reference/ratelimitpolicy.md @@ -94,8 +94,6 @@ | `message` | String | Condition state description | | `lastTransitionTime` | Timestamp | Last transition timestamp | - - #### High-level example ```yaml @@ -142,4 +140,4 @@ spec: # Mutually exclusive with `defaults` and with declaring `limits` at the top-level of the spec. overrides: limits: { … } -``` \ No newline at end of file +```