From 9fbce4028914a8cebc0bdff80f9afb941fb8f740 Mon Sep 17 00:00:00 2001 From: Michael Nairn Date: Tue, 21 Nov 2023 13:39:16 +0000 Subject: [PATCH] docs: Add API reference docs for policies Adds API reference docs for the DNSPolicy and TLSPolicy. Follows the same layout as kuadrant-operator policies (https://github.com/Kuadrant/kuadrant-operator/tree/main/doc/reference) --- docs/reference/dnspolicy.md | 87 +++++++++++++++++++++++++++++++++++++ docs/reference/tlspolicy.md | 35 +++++++++++++++ 2 files changed, 122 insertions(+) create mode 100644 docs/reference/dnspolicy.md create mode 100644 docs/reference/tlspolicy.md diff --git a/docs/reference/dnspolicy.md b/docs/reference/dnspolicy.md new file mode 100644 index 00000000..97f74ee3 --- /dev/null +++ b/docs/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/docs/reference/tlspolicy.md b/docs/reference/tlspolicy.md new file mode 100644 index 00000000..f2ce4416 --- /dev/null +++ b/docs/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. |