Skip to content

Commit

Permalink
docs: add managedzone and provider docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@mikenairn
mikenairn committed Feb 12, 2024
1 parent cecc493 commit 559cc35
Show file tree
Hide file tree
Showing 3 changed files with 197 additions and 0 deletions.
82 changes: 82 additions & 0 deletions docs/managedzone.md
View file
Original file line number Diff line number Diff line change
@@ -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).
69 changes: 69 additions & 0 deletions docs/provider.md
View file
Original file line number Diff line number Diff line change
@@ -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)
46 changes: 46 additions & 0 deletions docs/reference/managedzone.md
View file
Original file line number Diff line number Diff line change
@@ -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) |

0 comments on commit 559cc35

Please sign in to comment.