From: Sebastian Wagner <sebastian.wagner@suse.com>
Date: Fri, 5 Jun 2020 10:42:54 +0000 (+0200)
Subject: doc/cephadm: Add chapter about FQDNs
X-Git-Tag: wip-pdonnell-testing-20200918.022351~999^2
X-Git-Url: http://git.apps.os.sepia.ceph.com/?a=commitdiff_plain;h=55e608d796952881083f3620c91edb5596da8220;p=ceph-ci.git

doc/cephadm: Add chapter about FQDNs

Signed-off-by: Sebastian Wagner <sebastian.wagner@suse.com>
---

diff --git a/doc/cephadm/concepts.rst b/doc/cephadm/concepts.rst
index 8dd9b4a6b50..35cdf0ea0fd 100644
--- a/doc/cephadm/concepts.rst
+++ b/doc/cephadm/concepts.rst
@@ -1,5 +1,77 @@
+Cephadm Concepts
+================
+
+.. _cephadm-fqdn:
+
+Fully qualified domain names vs bare host names
+-----------------------------------------------
+
+cephadm has very minimal requirements when it comes to resolving host
+names etc. When cephadm initiates an ssh connection to a remote host,
+the host name  can be resolved in four different ways:
+
+-  a custom ssh config resolving the name to an IP
+-  via an externally maintained ``/etc/hosts``
+-  via explictly providing an IP address to cephadm: ``ceph orch host add <hostname> <IP>``
+-  automatic name resolution via DNS.
+
+Ceph itself uses the command ``hostname`` to determine the name of the
+current host.
+
+.. note::
+
+  cephadm demands that the name of the host given via ``ceph orch host add`` 
+  equals the output of ``hostname`` on remote hosts.
+
+Otherwise cephadm can't be sure, the host names returned by
+``ceph * metadata`` match the hosts known to cephadm. This might result
+in a :ref:`cephadm-stray-host` warning.
+
+When configuring new hosts, there are two **valid** ways to set the 
+``hostname`` of a host:
+
+1. Using the bare host name. In this case:
+
+-  ``hostname`` returns the bare host name.
+- ``hostname -f`` returns the FQDN.
+
+2. Using the fully qualified domain name as the host name. In this case:
+
+-  ``hostname`` returns the FQDN
+-  ``hostname -s`` return the bare host name
+
+Note that ``man hostname`` recommends ``hostname`` to return the bare
+host name:
+
+    The FQDN (Fully Qualified Domain Name) of the system is the
+    name that the resolver(3) returns for the host name, such as,
+    ursula.example.com. It is usually the hostname followed by the DNS
+    domain name (the part after the first dot). You can check the FQDN
+    using hostname --fqdn or the domain name using dnsdomainname.
+
+    ::
+
+          You cannot change the FQDN with hostname or dnsdomainname.
+
+          The recommended method of setting the FQDN is to make the hostname
+          be an alias for the fully qualified name using /etc/hosts, DNS, or
+          NIS. For example, if the hostname was "ursula", one might have
+          a line in /etc/hosts which reads
+
+                 127.0.1.1    ursula.example.com ursula
+
+Which means, ``man hostname`` recommends ``hostname`` to return the bare
+host name. This in turn means that Ceph will return the bare host names
+when executing ``ceph * metadata``. This in turn means cephadm also
+requires the bare host name when adding a host to the cluster: 
+``ceph orch host add <bare-name>``.
+
+..
+  TODO: This chapter needs to provide way for users to configure
+  Grafana in the dashboard, as this is right no very hard to do.
+  
 Cephadm Scheduler
-=================
+-----------------
 
 Cephadm uses a declarative state to define the layout of the cluster. This
 state consists of a list of service specificatins containing placement 
@@ -45,4 +117,4 @@ candidate hosts.
 However, there is a special cases that cephadm needs to consider.
 
 In case the are fewer hosts selected by the placement specification than 
-demanded by ``count``, cephadm will only deploy on selected hosts.
+demanded by ``count``, cephadm will only deploy on selected hosts.
\ No newline at end of file
diff --git a/doc/cephadm/operations.rst b/doc/cephadm/operations.rst
index 7768b1ff4a6..d7f5ee7128e 100644
--- a/doc/cephadm/operations.rst
+++ b/doc/cephadm/operations.rst
@@ -193,6 +193,8 @@ Resume cephadm work with::
 
   ceph orch resume
 
+.. _cephadm-stray-host:
+
 CEPHADM_STRAY_HOST
 ------------------
 
@@ -216,6 +218,9 @@ You can also disable this warning entirely with::
 
   ceph config set mgr mgr/cephadm/warn_on_stray_hosts false
 
+See :ref:`cephadm-fqdn` for more information about host names and
+domain names.
+
 CEPHADM_STRAY_DAEMON
 --------------------
 
diff --git a/doc/mgr/orchestrator.rst b/doc/mgr/orchestrator.rst
index 469dd97b0e1..b463c8d376b 100644
--- a/doc/mgr/orchestrator.rst
+++ b/doc/mgr/orchestrator.rst
@@ -73,6 +73,8 @@ Add and remove hosts::
     ceph orch host add <hostname> [<addr>] [<labels>...]
     ceph orch host rm <hostname>
 
+For cephadm, see also :ref:`cephadm-fqdn`.
+
 Host Specification
 ------------------