From 559cc35fb94d36cbc51ec89cacc22f0a3e51eaf1 Mon Sep 17 00:00:00 2001
From: Michael Nairn <mnairn@redhat.com>
Date: Fri, 9 Feb 2024 14:30:19 +0000
Subject: [PATCH] docs: add managedzone and provider docs

---
 docs/managedzone.md           | 82 +++++++++++++++++++++++++++++++++++
 docs/provider.md              | 69 +++++++++++++++++++++++++++++
 docs/reference/managedzone.md | 46 ++++++++++++++++++++
 3 files changed, 197 insertions(+)
 create mode 100644 docs/managedzone.md
 create mode 100644 docs/provider.md
 create mode 100644 docs/reference/managedzone.md

diff --git a/docs/managedzone.md b/docs/managedzone.md
new file mode 100644
index 00000000..13837a8e
--- /dev/null
+++ b/docs/managedzone.md
@@ -0,0 +1,82 @@
+# Creating and using a ManagedZone resource.
+
+## What is a ManagedZone
+A ManagedZone is a reference to a [DNS zone](https://en.wikipedia.org/wiki/DNS_zone). 
+By creating a ManagedZone we are instructing the MGC about a domain or subdomain that can be used as a host by any gateways in the same namespace.
+These gateways can use a subdomain of the ManagedZone.
+
+If a gateway attempts to a use a domain as a host, and there is no matching ManagedZone for that host, then that host on that gateway will fail to function.
+
+A gateway's host will be matched to any ManagedZone that the host is a subdomain of, i.e. `test.api.hcpapps.net` will be matched by any ManagedZone (in the same namespace) of: `test.api.hcpapps.net`, `api.hcpapps.net` or `hcpapps.net`.
+
+When MGC wants to create the DNS Records for a host, it will create them in the most exactly matching ManagedZone.
+e.g. given the zones `hcpapps.net` and `api.hcpapps.net` the DNS Records for the host `test.api.hcpapps.net` will be created in the `api.hcpapps.net` zone.
+
+### Delegation
+Delegation allows you to give control of a subdomain of a root domain to MGC while the root domain has it's DNS zone elsewhere.
+
+In the scenario where a root domain has a zone outside Route53, e.g. `external.com`, and a ManagedZone for `delegated.external.com` is required, the following steps can be taken:
+- Create the ManagedZone for `delegated.external.com` and wait until the status is updated with an array of nameservers (e.g. `ns1.hcpapps.net`, `ns2.hcpapps.net`). 
+- Copy these nameservers to your root zone for `external.com`, you can create a NS record for each nameserver against the `delegated.external.com` record.
+
+For example:
+```
+delegated.external.com. 3600 IN NS ns1.hcpapps.net.
+delegated.external.com. 3600 IN NS ns2.hcpapps.net.
+```
+
+Now, when MGC creates a DNS record in it's Route53 zone for `delegated.external.com`, it will be resolved correctly.
+### Creating a ManagedZone
+
+To create a `ManagedZone`, you will first need to create a DNS provider Secret. To create one, see our [DNS Provider](provider.md) setup guide, and make note of your provider's secret name.
+
+
+#### Example ManagedZone
+To create a new `ManagedZone` with AWS Route, with a DNS Provider secret named `my-aws-credentials`:
+
+```bash
+kubectl apply -f - <<EOF
+apiVersion: kuadrant.io/v1alpha1
+kind: ManagedZone
+metadata:
+  name: my-test-aws-zone
+  namespace: multi-cluster-gateways
+spec:
+  domainName: mydomain.example.com
+  description: "My Managed Zone"
+  dnsProviderSecretRef:
+    name: my-aws-credentials
+EOF
+```
+
+This will create a new Zone in AWS, for `mydomain.example.com`, using the DNS Provider credentials in the `my-aws-credentials` Secret.
+
+If you'd like to create a `ManagedZone` for an _existing_ zone in AWS, note its Zone ID and run:
+
+```bash
+kubectl apply -f - <<EOF
+apiVersion: kuadrant.io/v1alpha1
+kind: ManagedZone
+metadata:
+  name: my-test-aws-zone
+  namespace: multi-cluster-gateways
+spec:
+  id: MYZONEID
+  domainName: mydomain.example.com
+  description: "My Managed Zone"
+  dnsProviderSecretRef:
+    name: my-aws-credentials
+EOF
+```
+
+#### dnsProviderSecretRef
+
+This is a reference to secret containing the credentials and other configuration for accessing your dns provider
+[dnsProvider](provider.md)
+
+**Note:** the Secret referenced in the `dnsProviderSecretRef` field must be in the same namespace as the ManagedZone.
+
+**Note:** as an `id` was specified, the Managed Gateway Controller will not re-create this zone, nor will it delete it if this `ManagedZone` is deleted.
+
+## Spec of a ManagedZone
+The ManagedZone is a simple resource with an uncomplicated API, see a sample [here](../config/samples/kuadrant.io_v1alpha1_managedzone.yaml).
diff --git a/docs/provider.md b/docs/provider.md
new file mode 100644
index 00000000..b17e3a3a
--- /dev/null
+++ b/docs/provider.md
@@ -0,0 +1,69 @@
+# Configuring a DNS Provider 
+
+In order to be able to interact with supported DNS providers, Kuadrant needs a credential that it can use.
+
+## Supported Providers
+
+Kuadrant Supports the following DNS providers currently
+
+- AWS Route 53 (AWS)
+- Google Cloud DNS (GCP)
+
+### AWS Route 53 Provider
+
+Kuadrant expects a `Secret` with a credential. Below is an example for AWS Route 53. It is important to set the secret type to `aws`:
+
+
+```bash
+kubectl create secret generic my-aws-credentials \
+  --namespace=kuadrant-dns-system \
+  --type=kuadrant.io/aws \
+  --from-literal=AWS_ACCESS_KEY_ID=XXXX \
+  --from-literal=AWS_REGION=eu-west-1 \
+  --from-literal=AWS_SECRET_ACCESS_KEY=XXX
+```
+
+| Key                      | Example Value           | Description                                           |
+|--------------------------|-------------------------|-------------------------------------------------------|
+| `AWS_REGION`             | `eu-west-1`             | AWS Region                                            |
+| `AWS_ACCESS_KEY_ID`      | `XXXX`                  | AWS Access Key ID (see note on permissions below)     |
+| `AWS_SECRET_ACCESS_KEY`  | `XXXX`                  | AWS Secret Access Key                                 |
+
+#### AWS IAM Permissions Required 
+We have tested using the available policy `AmazonRoute53FullAccess` however it should also be possible to restrict the credential down to a particular zone. More info can be found in the AWS docs:
+
+https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/access-control-managing-permissions.html
+
+### Google Cloud DNS Provider
+
+Kuadant expects a secret with a credential. Below is an example for Google DNS. It is important to set the secret type to `gcp`:
+
+```bash
+kubectl create secret generic my-test-gcp-credentials \
+  --namespace=kuadrant-dns-system \
+  --type=kuadrant.io/gcp \
+  --from-literal=PROJECT_ID=xxx \
+  --from-file=GOOGLE=$HOME/.config/gcloud/application_default_credentials.json
+```
+
+| Env Var      | Example Value                                                                                  | Description                                                                                                           |
+|--------------|------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------|
+| `GOOGLE`     | `{"client_id": "***","client_secret": "***","refresh_token": "***","type": "authorized_user"}` | This is the JSON created from either the credential created by the `gcloud` CLI, or the JSON from the Service account |
+| `PROJECT_ID` | `my_project_id`                                                                                | ID to the Google project                                                                                              |
+
+
+#### Google Cloud DNS Access permissions required
+See: https://cloud.google.com/dns/docs/access-control#dns.admin
+
+
+### Where to create the Secrets
+
+It is recommended that you create the secret in the same namespace as your `ManagedZones`. In the examples above, we've stored these in a namespace called `kuadrant-dns-system`.
+
+Now that we have the credential created we have a DNS provider ready to go and can start using it.
+
+## Using a Credential
+
+Once a `Secret` like the one shown above is created, in order for it to be used, it needs to be associated with a `ManagedZone`. 
+
+See [ManagedZone](managedzone.md)
diff --git a/docs/reference/managedzone.md b/docs/reference/managedzone.md
new file mode 100644
index 00000000..b6e2a607
--- /dev/null
+++ b/docs/reference/managedzone.md
@@ -0,0 +1,46 @@
+# The ManagedZone Custom Resource Definition (CRD)
+
+- [ManagedZone](#ManagedZone)
+- [ManagedZoneSpec](#managedzonespec)
+- [ManagedZoneStatus](#managedzonestatus)
+
+## ManagedZone
+
+| **Field** | **Type**                            | **Required** | **Description**                                |
+|-----------|-------------------------------------|:------------:|------------------------------------------------|
+| `spec`    | [ManagedZoneSpec](#managedzonespec) |    Yes       | The specification for ManagedZone custom resource |
+| `status`  | [ManagedZoneStatus](#managedzonestatus) |      No      | The status for the custom resource             | 
+
+## ManagedZoneSpec
+
+| **Field**              | **Type**                                       | **Required** | **Description**                                                          |
+|------------------------|------------------------------------------------|:------------:|--------------------------------------------------------------------------|
+| `id`                   | String                                         |      No      | ID is the provider assigned id of this zone (i.e. route53.HostedZone.ID) | 
+| `domainName`           | String                                         |     Yes      | Domain name of this ManagedZone                                          |
+| `description`          | String                                         |      No      | Description for this ManagedZone                                         |
+| `parentManagedZone`    | [ManagedZoneReference](#managedzonereference)  |      No      | Reference to another managed zone that this managed zone belongs to      |
+| `dnsProviderSecretRef` | [SecretRef](#secretref)                        |      No      | Reference to a secret containing provider credentials                    |
+
+## ManagedZoneReference
+
+| **Field**    | **Type** | **Required** | **Description**         |
+|--------------|----------|:------------:|-------------------------|
+| `name`       | String   |     Yes      | Name of a managed zone  | 
+
+## SecretRef
+
+| **Field**    | **Type** | **Required** | **Description**         |
+|--------------|----------|:------------:|-------------------------|
+| `name`       | String   |     Yes      | Name of the secret      | 
+| `namespace`  | String   |     Yes      | Namespace of the secret | 
+
+
+## ManagedZoneStatus
+
+| **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                                                                         |
+| `id`                 | String                                                                                               | The ID assigned by this provider for this zone (i.e. route53.HostedZone.ID)                                                        |
+| `recordCount`        | Number                                                                                               | The number of records in the provider zone                                                                                         |
+| `nameServers`        | []String                                                                                             | The NameServers assigned by the provider for this zone (i.e. route53.DelegationSet.NameServers)                                    |