From 44ad2dd262bcd1375da34513ed712e74bd419f5e Mon Sep 17 00:00:00 2001 From: Ole Markus With Date: Sun, 10 May 2020 20:38:25 +0200 Subject: [PATCH 1/3] Add documentation on gossip --- docs/bastion.md | 6 +++--- docs/getting_started/aws.md | 8 ++------ docs/gossip.md | 29 +++++++++++++++++++++++++++++ mkdocs.yml | 1 + 4 files changed, 35 insertions(+), 9 deletions(-) create mode 100644 docs/gossip.md diff --git a/docs/bastion.md b/docs/bastion.md index 0e6be8b103742..7e676e1875868 100644 --- a/docs/bastion.md +++ b/docs/bastion.md @@ -86,10 +86,10 @@ spec: - "sg-***" ``` -### Access when using gossip (k8s.local) +### Access when using gossip -When using gossip mode, there is no DNS zone where we can configure a -CNAME for the bastion. Because bastions are fronted with a load +When using [gossip mode](gossip.md), there is no DNS zone where we can configure a +CNAME for the bastion. Because bastions are fronted with a load balancer, you can instead use the endpoint of the load balancer to reach your bastion. diff --git a/docs/getting_started/aws.md b/docs/getting_started/aws.md index ef40745452cbf..20d08d5035d56 100644 --- a/docs/getting_started/aws.md +++ b/docs/getting_started/aws.md @@ -64,17 +64,13 @@ export AWS_SECRET_ACCESS_KEY=$(aws configure get aws_secret_access_key) ## Configure DNS -Note: If you are using Kops 1.6.2 or later, then DNS configuration is -optional. Instead, a gossip-based cluster can be easily created. The -only requirement to trigger this is to have the cluster name end with -`.k8s.local`. If a gossip-based cluster is created then you can skip -this section. - In order to build a Kubernetes cluster with `kops`, we need to prepare somewhere to build the required DNS records. There are three scenarios below and you should choose the one that most closely matches your AWS situation. +Note: if you want to use [gossip-based DNS](../gossip.md), you can skip this section. + ### Scenario 1a: A Domain purchased/hosted via AWS If you bought your domain with AWS, then you should already have a hosted zone diff --git a/docs/gossip.md b/docs/gossip.md new file mode 100644 index 0000000000000..8c7dc2d4933d8 --- /dev/null +++ b/docs/gossip.md @@ -0,0 +1,29 @@ +# Gossip DNS + +Gossip-based clusters uses a peer-to-peer network for propagating the K8s API address instead of normal DNS. +This means that no hosted zone is needed for the cluster. + +Gossip does not suffer potential disruptions due to the DNS TTL as the propagation is almost instant. + +Gossip is also the only option if you want to deploy a cluster in any of the China of GovCloud AWS regions as Route 53 is not available there. + +## Configuring a cluster to use Gossip + +The only thing you need to do in order to use gossip-based DNS is to use the `k8s.local` suffix for the cluster domain name. + +## Accessing the cluster + +### Kubernetes API + +When using gossip mode, you have to expose the kubernetes API using a loadbalancer. Since there is no hosted zone for gossip-based clusters, you simply use the load balancer address directly. The user experience is identical to standard clusters. Kops will add the ELB DNS name to the kops-generated kubernetes configuration. + +### Bastion + +If you are using [bastion hosts](bastion.md), it is a bit tricky to find the bastion address name. On AWS, you can run the following command: + +``` +kops toolbox dump -ojson | grep 'bastion.*elb.amazonaws.com' +``` + + + diff --git a/mkdocs.yml b/mkdocs.yml index c126307c2b236..5488c6a333401 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -81,6 +81,7 @@ nav: - Service Account Token Volume: "operations/service_account_token_volumes.md" - Moving from a Single Master to Multiple HA Masters: "single-to-multi-master.md" - Running kops in a CI environment: "continuous_integration.md" + - Gossip DNS: "gossip.md" - etcd: - etcd administration: "operations/etcd_administration.md" - etcd backup, restore and encryption: "operations/etcd_backup_restore_encryption.md" From c702f490180a3dac35819a6a607b47985ded7845 Mon Sep 17 00:00:00 2001 From: Ole Markus With Date: Sun, 10 May 2020 21:54:01 +0200 Subject: [PATCH 2/3] Apply suggestions from code review Co-authored-by: John Gardiner Myers --- docs/gossip.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/docs/gossip.md b/docs/gossip.md index 8c7dc2d4933d8..37de2aee05bff 100644 --- a/docs/gossip.md +++ b/docs/gossip.md @@ -1,15 +1,15 @@ # Gossip DNS -Gossip-based clusters uses a peer-to-peer network for propagating the K8s API address instead of normal DNS. -This means that no hosted zone is needed for the cluster. +Gossip-based clusters use a peer-to-peer network instead of externally hosted DNS for propagating the K8s API address. +This means that an externally hosted DNS service is not needed. -Gossip does not suffer potential disruptions due to the DNS TTL as the propagation is almost instant. +Gossip does not suffer potential disruptions due to out of date records in DNS caches as the propagation is almost instant. -Gossip is also the only option if you want to deploy a cluster in any of the China of GovCloud AWS regions as Route 53 is not available there. +Gossip is also the only option if you want to deploy a cluster in any of the AWS regions without Route 53, such as the China and GovCloud ones. ## Configuring a cluster to use Gossip -The only thing you need to do in order to use gossip-based DNS is to use the `k8s.local` suffix for the cluster domain name. +In order to use gossip-based DNS, configure the cluster domain name to end with `.k8s.local`. ## Accessing the cluster @@ -26,4 +26,3 @@ kops toolbox dump -ojson | grep 'bastion.*elb.amazonaws.com' ``` - From 8f50070a9aca599146df016290a776ef51a079c5 Mon Sep 17 00:00:00 2001 From: Ole Markus With Date: Sun, 10 May 2020 21:54:39 +0200 Subject: [PATCH 3/3] Remove trailing empty lines --- docs/gossip.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/gossip.md b/docs/gossip.md index 37de2aee05bff..110462e0d87dd 100644 --- a/docs/gossip.md +++ b/docs/gossip.md @@ -23,6 +23,4 @@ If you are using [bastion hosts](bastion.md), it is a bit tricky to find the bas ``` kops toolbox dump -ojson | grep 'bastion.*elb.amazonaws.com' -``` - - +``` \ No newline at end of file