From 0486f22819b09ebb0577d21afdcd28e29c84586d Mon Sep 17 00:00:00 2001 From: shashidharatd Date: Wed, 15 Mar 2017 00:14:53 +0530 Subject: [PATCH] Setting up CoreDNS as DNS provider for Cluster Federation --- _data/tutorials.yml | 1 + docs/tutorials/federation/Values.yaml | 10 ++ .../set-up-coredns-provider-federation.md | 126 ++++++++++++++++++ 3 files changed, 137 insertions(+) create mode 100644 docs/tutorials/federation/Values.yaml create mode 100644 docs/tutorials/federation/set-up-coredns-provider-federation.md diff --git a/_data/tutorials.yml b/_data/tutorials.yml index ccb84f2b47ab8..15e4d1026946d 100644 --- a/_data/tutorials.yml +++ b/_data/tutorials.yml @@ -63,3 +63,4 @@ toc: - title: Federated Cluster Administration section: - docs/tutorials/federation/set-up-cluster-federation-kubefed.md + - docs/tutorials/federation/set-up-coredns-provider-federation.md diff --git a/docs/tutorials/federation/Values.yaml b/docs/tutorials/federation/Values.yaml new file mode 100644 index 0000000000000..95f04cc8cc22b --- /dev/null +++ b/docs/tutorials/federation/Values.yaml @@ -0,0 +1,10 @@ +isClusterService: false +serviceType: "LoadBalancer" +middleware: + kubernetes: + enabled: false + etcd: + enabled: true + zones: + - "example.com." + endpoint: "http://etcd-cluster.my-namespace:2379" \ No newline at end of file diff --git a/docs/tutorials/federation/set-up-coredns-provider-federation.md b/docs/tutorials/federation/set-up-coredns-provider-federation.md new file mode 100644 index 0000000000000..4060845b3a098 --- /dev/null +++ b/docs/tutorials/federation/set-up-coredns-provider-federation.md @@ -0,0 +1,126 @@ +--- +title: Setting up CoreDNS as DNS provider for Cluster Federation +--- + +{% capture overview %} + +This page shows how to configure and deploy CoreDNS to be used as the +DNS provider for Cluster Federation. + +{% endcapture %} + + +{% capture objectives %} + +* Configure and deploy CoreDNS server +* Bringup federation with CoreDNS as dns provider +* Setup CoreDNS server in nameserver lookup chain + +{% endcapture %} + + +{% capture prerequisites %} + +You need to have a running Kubernetes cluster (which is +referenced as host cluster). Please see one of the +[getting started](/docs/getting-started-guides/) guides for +installation instructions for your platform. + +{% endcapture %} + + +{% capture lessoncontent %} + +## Deploying CoreDNS and etcd charts + +CoreDNS can be deployed in various configurations. Explained below is a +reference and can be tweaked to suit the needs of the platform and the +cluster federation. + +To deploy CoreDNS, we shall make use of helm charts. CoreDNS will be +deployed with [etcd](https://coreos.com/etcd) as the backend and should +be pre-installed. etcd can also be deployed using helm charts. Shown +below are the instructions to deploy etcd. + + helm install --namespace my-namespace --name etcd-operator stable/etcd-operator + helm upgrade --namespace my-namespace --set cluster.enabled=true etcd-operator stable/etcd-operator + +*Note: etcd default deployment configurations can be overridden, suiting the +host cluster.* + +After deployment succeeds, etcd can be accessed with the +[http://etcd-cluster.my-namespace:2379](http://etcd-cluster.my-namespace:2379) endpoint within the host cluster. + +The CoreDNS default configuration should be customized to suit the federation. +Shown below is the Values.yaml, which overrides the default +configuration parameters on the CoreDNS chart. + +{% include code.html language="yaml" file="Values.yaml" ghlink="/docs/tutorials/federation/Values.yaml" %} + +The above configuration file needs some explanation: + + - `isClusterService` specifies whether CoreDNS should be deployed as a +cluster-service, which is the default. You need to set it to false, so +that CoreDNS is deployed as a Kubernetes application service. + - `serviceType` specifies the type of Kubernetes service to be created +for CoreDNS. You need to choose either "LoadBalancer" or "NodePort" to +make the CoreDNS service accessible outside the Kubernetes cluster. + - Disable `middleware.kubernetes`, which is enabled by default by +setting `middleware.kubernetes.enabled` to false. + - Enable `middleware.etcd` by setting `middleware.etcd.enabled` to +true. + - Configure the DNS zone (federation domain) for which CoreDNS is +authoritative by setting `middleware.etcd.zones` as shown above. + - Configure the etcd endpoint which was deployed earlier by setting +`middleware.etcd.endpoint` + +Now deploy CoreDNS by running + + helm install --namespace my-namespace --name coredns -f Values.yaml stable/coredns + +Verify that both etcd and CoreDNS pods are running as expected. + + +## Deploying Federation with CoreDNS as DNS provider + +The Federation control plane can be deployed using `kubefed init`. CoreDNS +can be chosen as the DNS provider by specifying two additional parameters. + + --dns-provider=coredns + --dns-provider-config=coredns-provider.conf + +coredns-provider.conf has below format: + + [Global] + etcd-endpoints = http://etcd-cluster.my-namespace:2379 + zones = example.com. + + - `etcd-endpoints` is the endpoint to access etcd. + - `zones` is the federation domain for which CoreDNS is authoritative and is same as --dns-zone-name flag of `kubefed init`. + +*Note: middleware.etcd.zones in CoreDNS configuration and --dns-zone-name +flag to kubefed init should match.* + + +## Setup CoreDNS server in nameserver resolv.conf chain + +Once the federation control plane is deployed and federated clusters +are joined to the federation, you need to add the CoreDNS server to the +pod's nameserver resolv.conf chain in all the federated clusters as this +self hosted CoreDNS server is not discoverable publicly. This can be +achieved by adding the below line to `dnsmasq` container's arg in +`kube-dns` deployment. + + --server=/example.com./ + +Replace `example.com` above with federation domain. + +*Note: Adding CoreDNS server to the pod's nameserver resolv.conf chain will be +automated in subsequent releases.* + + +Now the federated cluster is ready for cross-cluster service discovery! + +{% endcapture %} + +{% include templates/tutorial.md %}