Add documentation on gossip

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.
 

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

docs/gossip.md

@@ -0,0 +1,26 @@
+# Gossip DNS
+
+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 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 AWS regions without Route 53, such as the China and GovCloud ones.
+
+## Configuring a cluster to use Gossip
+
+In order to use gossip-based DNS,  configure the cluster domain name to end with `.k8s.local`.
+
+## 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'
+```

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"