Docs updates

This commit brings our docs up to date with the current state of the project. Fixes #171, #229, #239, #264
mesosphere · Sep 21, 2015 · 1576d38 · 1576d38
1 parent c1b2823
commit 1576d38
Show file tree

Hide file tree

Showing 9 changed files with 28 additions and 124 deletions.
diff --git a/docs/_layouts/docs.html b/docs/_layouts/docs.html
@@ -4,22 +4,13 @@
 
 <div class="row">
   <div class="col-sm-3">
-    <h5>Welcome</h5>
+    <h5>Documentation</h5>
     <ul class="list-unstyled">
       <li>
         <a href="{{ site.baseurl }}/docs/">
-          Getting Started
+          Installing and running
         </a>
       </li>
-      <li>
-        <a href="{{ site.baseurl }}/docs/contributing.html">
-          Contributing
-        </a>
-      </li>
-    </ul>
-    <hr>
-    <h5>Reference</h5>
-    <ul class="list-unstyled">
        <li>
         <a href="{{ site.baseurl }}/docs/configuration-parameters.html">
         Configuration</a>
@@ -38,11 +29,6 @@ <h5>Reference</h5>
         <a href="{{ site.baseurl }}/docs/performance-tuning.html">
           Performance Tuning
         </a>
-      </li>
-      <li>
-        <a href="{{ site.baseurl }}/docs/packaging.html">
-          Packaging
-        </a>
       </li>
        <li>
         <a href="{{ site.baseurl }}/docs/faq.html">

diff --git a/docs/docs/configuration-parameters.md b/docs/docs/configuration-parameters.md
@@ -29,7 +29,7 @@ The configuration file should include the following fields:
   "SOARetry":   600,
   "SOAExpire":  86400,
   "SOAMinttl": 60,
-  "IPSources": ["mesos", "host"]
+  "IPSources": ["netinfo", "mesos", "host"]
 }
 ```
 
@@ -74,3 +74,11 @@ It is sufficient to specify just one of the `zk` or `masters` field. If both are
 `recurseon` controls if the DNS replies for names in the Mesos domain will indicate that recursion is available. The default value is `true`. 
 
 `enforceRFC952` will enforce an older, more strict set of rules for DNS labels. For details, see the [RFC-952](https://tools.ietf.org/html/rfc952). The default value is `false`.
+
+`IPSources` defines a fallback list of IP sources for task records,
+sorted by priority. The default value is: `["netinfo", "mesos", "host"]`
+
+- `host`: Host IP of the Mesos slave where a task is running.
+- `mesos`: Mesos containerizer IP. **DEPRECATED**
+- `docker`: Docker containerizer IP. **DEPRECATED**
+- `netinfo`: Mesos 0.25 NetworkInfo.
diff --git a/docs/docs/contributing.md b/docs/docs/contributing.md
diff --git a/docs/docs/index.md b/docs/docs/index.md
@@ -1,34 +1,11 @@
 ---
-title: Building and Running Mesos-DNS
+title: Installing and running Mesos-DNS
 ---
 
-## Building And Running Mesos-DNS
+## Installing and running Mesos-DNS
 
-### Building Mesos-DNS
-
-To build Mesos-DNS, you need to install [`go`](https://golang.org/doc/install) and [`godep`](https://github.com/tools/godep) on your computer. You **must** set the `GOPATH` environment variable to point to the directory where outside `go` packages will be installed. You **must** also add `$GOPATH/bin` to the `PATH` environment variable. If you install go to a custom location, you may need to set the `GOROOT` environment properly and add `$GOROOT/bin` to the `PATH` environment variable. For instance, you may need to do the following:
-
-```
-export GOPATH=$HOME/go
-export PATH=$PATH:$GOPATH/bin
-export GOROOT=/usr/local/go      # assuming go is installed at /usr/local/go
-export PATH=$PATH:$GOROOT/bin
-```   
-
-To build Mesos-DNS using `godep`: 
-
-```
-go get github.com/mesosphere/mesos-dns
-cd $GOPATH/src/github.com/mesosphere/mesos-dns
-make all
-``` 
-
-This generates `mesos-dns`, a statically-linked binary that can be installed anywhere. You will find a sample configuration file `config.json` in the same directory. 
-
-We have built and tested Mesos-DNS with `go` versions 1.3.3 and 1.4. Newer versions of `go` should work as well. 
-
-
-### Running Mesos-DNS
+The official distribution and installation channel is pre-compiled
+binaries available in [Github releases](https://github.com/mesosphere/mesos-dns/releases).
 
 To run Mesos-DNS, you first need to install the `mesos-dns` binary somewhere on a selected server. The server can be the same machine as one of the Mesos masters, one of the slaves, or a dedicated machine on the same network. Next, follow [these instructions](configuration-parameters.html) to create a configuration file for your cluster. You can launch Mesos-DNS with: 
 
@@ -66,4 +43,4 @@ If multiple instances of Mesos-DNS are launched, add a nameserver line for each
 
 All other nameserver settings in `/etc/resolv.conf` should remain unchanged. The `/etc/resolv.conf` file in the masters should only change if the master machines are also used as slaves. 
 
-You can also use Mesos-DNS to serve just a *forward lookup zone* from your primary DNS server (see [this tutorial](tutorial-forward.html)). In this case, you do not need to make any changes to the slaves in the cluster. 
+You can also use Mesos-DNS to serve just a *forward lookup zone* from your primary DNS server (see [this tutorial](tutorial-forward.html)). In this case, you do not need to make any changes to the slaves in the cluster.
diff --git a/docs/docs/naming.md b/docs/docs/naming.md
@@ -103,6 +103,7 @@ The following table illustrates the rules that govern SRV generation:
 
 Mesos-DNS generates a few special records:
 - for the leading master: A record (`leader.domain`) and SRV records (`_leader._tcp.domain` and `_leader._udp.domain`); and
+- for all framework schedulers: A records (`{framework}.domain`) and SRV records (`_framework._tcp.{framework}.domain`)
 - for every known Mesos master: A records (`master.domain`) and SRV records (`_master._tcp.domain` and `_master._udp.domain`); and
 - for every known Mesos slave: A records (`slave.domain`) and SRV records (`_slave._tcp.domain`).
 

diff --git a/docs/docs/packaging.md b/docs/docs/packaging.md
diff --git a/docs/docs/tutorial-systemd.md b/docs/docs/tutorial-systemd.md
@@ -21,35 +21,13 @@ This tutorial assumes the following cluster topology:
 
 For this tutorial we will assume the master IP address is `10.14.245.208`.
 
-### Step 2: Build and install Mesos-DNS
+### Step 2: Install Mesos-DNS
 
-We will build and install Mesos-DNS on node `10.14.245.208`.  Access the node through ssh.
+We will install Mesos-DNS on node `10.14.245.208`.  Access the node through ssh.
 
-You will need git for this process.   For SUSE this means `sudo zypper install git-core`
-
-The build process includes installing `go`:
-
-```
-wget https://storage.googleapis.com/golang/go1.4.linux-amd64.tar.gz
-tar xzf go*
-sudo mv go /usr/local/.
-export PATH=$PATH:/usr/local/go/bin
-export GOROOT=/usr/local/go
-export PATH=$PATH:$GOROOT/bin
-export GOPATH=$HOME/go
-go get github.com/tools/godep
-export PATH=$PATH:$GOPATH/bin
-```
-
-Now, we are ready to compile Mesos-DNS:
-
-```
-go get github.com/mesosphere/mesos-dns
-cd $GOPATH/src/github.com/mesosphere/mesos-dns
-make all
-cd
-sudo mv ~/go/bin/mesos-dns /usr/bin/mesos-dns
-```
+After downloading a [release](https://github.com/mesosphere/mesos-dns/releases) and
+extracting it, place the executable in well known location such as
+`/usr/bin/mesos-dns`.
 
 In the `/etc/mesos-dns/` directory lets create a file named `config.json` with the following contents: 
 

diff --git a/docs/index.md b/docs/index.md
@@ -8,20 +8,11 @@ title: DNS-based service discovery for Mesos
     DNS-based service discovery for Mesos
   </p>
   <p>
-    <a href="https://github.com/mesosphere/mesos-dns"
+    <a href="https://github.com/mesosphere/mesos-dns/releases"
         class="btn btn-lg btn-primary">
-      Mesos-DNS repository (alpha)
+      Mesos-DNS releases
     </a>
   </p>
-<!--  <a class="btn btn-link"
-      href="http://downloads.mesosphere.com/mesos-dns/v0.1.0/mesos-dns-0.1.0.tgz.sha256">
-    v0.1.0 SHA-256 Checksum
-  </a> &middot;
-  <a class="btn btn-link"
-      href="https://github.com/mesosphere/mesos-dns/releases/tag/v0.1.0">
-    v0.1.0 Release Notes
-  </a>
--->
 </div>
 
 
@@ -37,6 +28,3 @@ Mesos-DNS is designed to be a minimal, stateless service that is easy to deploy
 Mesos-DNS periodically queries the Mesos master(s), retrieves the state of all running tasks from all running frameworks, and generates DNS records for these tasks (A and SRV records). As tasks start, finish, fail, or restart on the Mesos cluster, Mesos-DNS updates the DNS records to reflect the latest state. The configuration of Mesos-DNS is minimal. You simply point it to the Mesos masters at launch. Frameworks do not need to communicate with Mesos-DNS at all. Applications and services running on Mesos slaves can discover the IP addresses and ports of other applications they depend upon by issuing DNS lookup requests or by issuing HTTP request through a REST API. Mesos-DNS replies directly to requests for tasks launched by Mesos. For DNS requests for other hostnames or services, Mesos-DNS uses an external nameserver to derive replies. Alternatively, you can configure your existing DNS server to forward only the requests for Mesos tasks to Mesos-DNS. 
 
 Mesos-DNS is simple and stateless. It does not require consensus mechanisms, persistent storage, or a replicated log. This is possible because Mesos-DNS does not implement heartbeats, health monitoring, or lifetime management for applications. This functionality is already available by the Mesos master, slaves, and frameworks. Mesos-DNS can be made fault-tolerant by launching with a framework like [Marathon](https://github.com/mesosphere/marathon), that can monitor application health and re-launch it on failures. On restart after a failure, Mesos-DNS retrieves the latest state from the Mesos master(s) and serves DNS requests without further coordination. It can be easily replicated to improve availability or to load balance DNS requests in clusters with large numbers of slaves. 
-
-The current **alpha** version of Mesos-DNS (0.1.2) has been tested with Mesos version v0.21.0. It has no dependencies to any frameworks. 
-
diff --git a/docs/support.md b/docs/support.md
@@ -13,6 +13,10 @@ an eye on issues and questions in a few places.
 
 You can report issues and bugs at the [Mesos-DNS github repository](https://github.com/mesosphere/mesos-dns). 
 
+### Mailing list
+
+For any discussion that isn't well suited for Github [issues](https://github.com/mesosphere/mesos-dns/issues), please use our [mailing list](https://groups.google.com/forum/#!forum/mesos-dns).
+
 ### Mesos Community
 
 You can get advice on Mesos and Mesos-related projects from the [Apache Mesos IRC channel and mailing lists](http://mesos.apache.org/community/).