Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

initial-design file #4

Merged
merged 6 commits into from
Feb 15, 2017
+90 −0
Merged

initial-design file #4

Changes from 4 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
dc16c78
initial-design file
Feb 13, 2017
b2306cc
fix broken table
Feb 13, 2017
4a4b8c7
Add Design/Configuration section
iterion Feb 13, 2017
49fb86d
Document compatibility with route53-kubernetes
iterion Feb 13, 2017
30c04fb
Tweak configuration section
iterion Feb 13, 2017
d9825d7
be more elaborate regarding required annotations, compatibility
Feb 14, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
85 changes: 85 additions & 0 deletions docs/initial-design.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@
# Proposal: Design of External DNS

## Background

**Note: This DOC is WIP**

[Project proposal](https://groups.google.com/forum/#!searchin/kubernetes-dev/external$20dns%7Csort:relevance/kubernetes-dev/2wGQUB0fUuE/9OXz01i2BgAJ)

[Initial discussion](https://docs.google.com/document/d/1ML_q3OppUtQKXan6Q42xIq2jelSoIivuXI8zExbc6ec/edit#heading=h.1pgkuagjhm4p)

This document describes the initial design proposal

External DNS is purposed to fill the existing gap of creating DNS records for Kubernetes resources. While there exist alternative solutions, this project is meant to be a standard way of managing DNS records for Kubernetes. The current project is a fusion of the following projects and driven by its maintainers:

1. [Kops DNS Controller](https://github.com/kubernetes/kops/tree/master/dns-controller)
2. [Mate](https://github.com/zalando-incubator/mate)
3. [wearemolecule/route53-kubernetes](https://github.com/wearemolecule/route53-kubernetes)

## Example use case:

User runs `kubectl create -f ingress.yaml`, this will create an ingress as normal.
Typically the user would then have to manually create a DNS record pointing the ingress endpoint
If the external-dns controller is running on the cluster, it could automatically configure the DNS records instead, by observing the host attribute in the ingress object.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here we say we create records by observing the host attribute. I assume that means the host field specified here: https://kubernetes.io/docs/api-reference/v1.5/#ingressrule-v1beta1. But, later we specify an annotation to do the same (external-dns.kubernetes.io/hostname). Are both required?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In my point of view only ingress host is required. In this doc it is mentioned this annotation is only required for other types of resources (which is only loadbalancer service at the moment). But this is certainly open for discussion

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, I see, to check my understanding. If you're using ingress resources ingress host is required. But, if you are using services then you must specify both of the annotations?

Copy link
Author

@ideahitme ideahitme Feb 13, 2017 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, the host is specified when ingress is created. For services both annotations are required per my understanding

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To make this clear perhaps we should add a section under design, maybe something like:

### Configuration

DNS records will be automatically created in multiple situations:
1. Setting `spec.rules.host` on an ingress object.
2. Specifying two annotations (`external-dns.kubernetes.io/controller` and `external-dns.kubernetes.io/hostname`) on a `type=LoadBalancer` service object.

Copy link
Author

@ideahitme ideahitme Feb 13, 2017 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@iterion yup, seems good to me. You can push to this branch, this PR is for us to agree on same design basis :) we can fix it any time later. anyways as time goes we will probably need to create separate file(s) for configuration/how to run/use-cases/annotations etc

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, pushed.


## Goals

1. Support AWS Route53 and Google Cloud DNS providers
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is Azure out of scope?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry, it's listed below, pls ignore.

2. DNS for Kubernetes services(type=Loadbalancer) and Ingress
3. Create/update/remove records as according to Kubernetes resources state
4. It should address main requirements and support main features of the projects mentioned above

## Design

### Extensibility

New cloud providers should be easily pluggable. Initially only AWS/Google platforms are supported. However, in the future we are planning to incorporate CoreDNS and Azure DNS as possible DNS providers

### Configuration

DNS records will be automatically created in multiple situations:
1. Setting `spec.rules.host` on an ingress object.
2. Specifying two annotations (`external-dns.kubernetes.io/controller` and `external-dns.kubernetes.io/hostname`) on a `type=LoadBalancer` service object.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same here: why are two annotations needed? I would assume external-dns.kubernetes.io/controller to be optional in 99% of the use cases.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not necessary, I just grabbed it annotations section. It seems like external-dns.kubernetes.io/controller is optional since it has a default value. I'll correct this.


### Annotations

TODO:*This should probably be placed in a separate file*.

Record configuration should occur via resource annotations. Supported annotations:

| Annotations | |
|---|---|
|Tag |external-dns.kubernetes.io/controller |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we make this the default (configurable)? I want users to have the least amount of annotations possible. There is no need for people to specify this annotation if only one controller is running in the cluster (which will be the case for 99% of the cases).

|Description | Tells a DNS controller to process this service. This is useful when running different DNS controllers at the same time (or different versions of the same controller). The v1 implementation of dns-controller would look for service annotations `dns-controller` and `dns-controller/v1` but not for `mate/v1` or `dns-controller/v2` |
|Default | dns-controller |
|Example|dns-controller/v1|
|---|---|
|Tag |external-dns.kubernetes.io/hostname |
|Description | Fully qualified name of the desired record. Only required for services(Loadbalancer) |
|Default| none |
|Example|foo.example.org|

### Compatibility

External DNS should be compatible with annotations used by three above mentioned projects. The idea is that resources created and tagged with annotations for other projects should continue to be valid and now managed by External DNS.

TODO:*Add complete list here*
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

route53-kubernetes functions pretty simply and only works with properly annotated services. The README has more info: https://github.com/wearemolecule/route53-kubernetes

If I were to put it into the example table as given for Mate it would look like this:
Tag: domainName
Description: Hostname to be registered
Default: None (no DNS record would be created)
Example: foo.example.org

But, we would also need to include that it currently only functions on services (no support for ingress) and that a label dns: route53 must also be set on the service for which the user intends to create a DNS record.

All that being said, I could see how we may not want to support the above rules. It might be easier to support running route53-kubernetes and this project simultaneously until a user can correctly port everything.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@iterion I see your point and it feels right in route53-kubernetes case. in mate's case we do not tag resources which can/cannot be managed by mate. Hence running mate + external-dns at the same time might be problematic.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, agree that backwards compatibility for mate makes sense. If we can safely run both route53-kubernetes and external-dns I think it would be a good idea not to support its annotations. It's just less surface area that we'd ultimately probably just deprecate later. I'll add a small section documenting this.


**Mate**

|Annotations | |
|---|---|
|Tag |zalando.org/dnsname |
|Description | Hostname to be registered |
|Default | Empty(falls back to template based approach) |
|Example|foo.example.org|

**route53-kubernetes*
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

typo: missing star at the end of line


It should be safe to run both `route53-kubernetes` and `external-dns` simultaneously. Since `route53-kubernetes` only looks at services with the label `dns=route53` and does not support ingress there should be no collisions between annotations. If users desire to switch to `external-dns` they can run both controllers and migrate services over as they are able.


### Ownership

External DNS should be *responsible* for the created records. Which means that the records should be tagged (TODO:*describe how this supposed to work?*) and only tagged records are viable for future deletion/update. It should not mess with pre-existing records created via other means