From: Sage Weil Date: Tue, 17 Mar 2020 13:54:47 +0000 (-0500) Subject: doc/cephadm: more edits X-Git-Tag: v15.2.0~25^2~1 X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=3830b632e6a3a84c30305b6f34a7c1f8c089dcc3;p=ceph.git doc/cephadm: more edits Based on review by Alexandra Settle Signed-off-by: Sage Weil --- diff --git a/doc/cephadm/adoption.rst b/doc/cephadm/adoption.rst index 874802dce24f..f94e46325fde 100644 --- a/doc/cephadm/adoption.rst +++ b/doc/cephadm/adoption.rst @@ -1,3 +1,5 @@ +.. _cephadm-adoption: + Converting an existing cluster to cephadm ========================================= diff --git a/doc/cephadm/operations.rst b/doc/cephadm/operations.rst index 18072a3192d0..2e25874aabdf 100644 --- a/doc/cephadm/operations.rst +++ b/doc/cephadm/operations.rst @@ -5,7 +5,8 @@ Cephadm Operations Watching cephadm log messages ============================= -Cephadm logs to the ``cephadm`` cluster log channel, which means you can monitor progress in realtime with:: +Cephadm logs to the ``cephadm`` cluster log channel, meaning you can +monitor progress in realtime with:: # ceph -W cephadm @@ -22,7 +23,7 @@ You can see recent events with:: # ceph log last cephadm These events are also logged to the ``ceph.cephadm.log`` file on -monitor hosts and/or to the monitor-daemon stderr. +monitor hosts and to the monitor daemons' stderr. Ceph daemon logs @@ -31,14 +32,14 @@ Ceph daemon logs Logging to stdout ----------------- -Traditionally, Ceph daemons have logged to ``/var/log/ceph``. With -cephadm, by default, daemons instead log to stderr and the logs are +Traditionally, Ceph daemons have logged to ``/var/log/ceph``. By +default, cephadm daemons log to stderr and the logs are captured by the container runtime environment. For most systems, by default, these logs are sent to journald and accessible via ``journalctl``. For example, to view the logs for the daemon ``mon.foo`` for a cluster -with id ``5c5a50ae-272a-455d-99e9-32c6a013e694``, the command would be +with ID ``5c5a50ae-272a-455d-99e9-32c6a013e694``, the command would be something like:: journalctl -u ceph-5c5a50ae-272a-455d-99e9-32c6a013e694@mon.foo @@ -62,8 +63,8 @@ To enable logging to files:: ceph config set global log_to_file true ceph config set global mon_cluster_log_to_file true -You probably want to disable logging to stderr (see above) or else everything -will be logged twice!:: +We recommend disabling logging to stderr (see above) or else everything +will be logged twice:: ceph config set global log_to_stderr false ceph config set global mon_cluster_log_to_stderr false @@ -96,9 +97,9 @@ Disk usage ---------- Because a few Ceph daemons may store a significant amount of data in -``/var/lib/ceph`` (notably, the monitors and prometheus), you may want -to move this directory to its own disk, partition, or logical volume so -that you do not fill up the root file system. +``/var/lib/ceph`` (notably, the monitors and prometheus), we recommend +moving this directory to its own disk, partition, or logical volume so +that it does not fill up the root file system. @@ -112,9 +113,9 @@ with those hosts in a secure way. Default behavior ---------------- -Cephadm normally stores an SSH key in the monitor that is used to +Cephadm stores an SSH key in the monitor that is used to connect to remote hosts. When the cluster is bootstrapped, this SSH -key is generated automatically. Normally, no additional configuration +key is generated automatically and no additional configuration is necessary. A *new* SSH key can be generated with:: @@ -142,7 +143,7 @@ You will then need to restart the mgr daemon to reload the configuration with:: Customizing the SSH configuration --------------------------------- -Normally cephadm generates an appropriate ``ssh_config`` file that is +Cephadm generates an appropriate ``ssh_config`` file that is used for connecting to remote hosts. This configuration looks something like this:: @@ -153,20 +154,20 @@ something like this:: There are two ways to customize this configuration for your environment: -#. You can import a customized configuration file that will be stored +#. Import a customized configuration file that will be stored by the monitor with:: ceph cephadm set-ssh-config -i - To remove a customized ssh config and revert back to the default behavior:: + To remove a customized SSH config and revert back to the default behavior:: ceph cephadm clear-ssh-config -#. You can configure a file location for the ssh configuration file with:: +#. You can configure a file location for the SSH configuration file with:: ceph config set mgr mgr/cephadm/ssh_config_file - This approach is *not recommended*, however, as the path name must be + We do *not recommend* this approach. The path name must be visible to *any* mgr daemon, and cephadm runs all daemons as containers. That means that the file either need to be placed inside a customized container image for your deployment, or @@ -182,11 +183,11 @@ CEPHADM_PAUSED -------------- Cephadm background work has been paused with ``ceph orch pause``. Cephadm -will continue to perform passive monitoring activities (like checking +continues to perform passive monitoring activities (like checking host and daemon status), but it will not make any changes (like deploying or removing daemons). -You can resume cephadm work with:: +Resume cephadm work with:: ceph orch resume @@ -206,7 +207,7 @@ Note that you may need to configure SSH access to the remote host before this will work. Alternatively, you can manually connect to the host and ensure that -services on that host are removed and/or migrated to a host that is +services on that host are removed or migrated to a host that is managed by *cephadm*. You can also disable this warning entirely with:: @@ -217,14 +218,17 @@ CEPHADM_STRAY_DAEMON -------------------- One or more Ceph daemons are running but not are not managed by -*cephadm*, perhaps because they were deploy using a different tool, or -were started manually. This means that those services cannot -currently be managed by cephadm (e.g., restarted, upgraded, included -in `ceph orch ps`). +*cephadm*. This may be because they were deployed using a different +tool, or because they were started manually. Those +services cannot currently be managed by cephadm (e.g., restarted, +upgraded, or included in `ceph orch ps`). -**FIXME:** We need to implement and document an adopt procedure here. +If the daemon is a stateful one (monitor or OSD), it should be adopted +by cephadm; see :ref:`cephadm-adoption`. For stateless daemons, it is +usually easiest to provision a new daemon with the ``ceph orch apply`` +command and then stop the unmanaged daemon. -You can also disable this warning entirely with:: +This warning can be disabled entirely with:: ceph config set mgr mgr/cephadm/warn_on_stray_daemons false diff --git a/doc/cephadm/troubleshooting.rst b/doc/cephadm/troubleshooting.rst index 00752ff546d5..375420ad1828 100644 --- a/doc/cephadm/troubleshooting.rst +++ b/doc/cephadm/troubleshooting.rst @@ -25,7 +25,7 @@ get logs of a daemon running on a different host, give the ``--fsid`` option:: cephadm logs --fsid --name -Where the ```` corresponds to the cluster id printed by ``ceph status``. +where the ```` corresponds to the cluster ID printed by ``ceph status``. To fetch all log files of all daemons on a given host, run:: @@ -66,6 +66,6 @@ To list all container images that are downloaded on a host: Manually running containers --------------------------- -cephadm writes small wrappers that run a containers. Refer to -``/var/lib/ceph///unit.run`` for the container execution command. -to execute a container. +Cephadm writes small wrappers that run a containers. Refer to +``/var/lib/ceph///unit.run`` for the +container execution command. diff --git a/doc/cephadm/upgrade.rst b/doc/cephadm/upgrade.rst index def47ae38eb6..9ffa68f65df9 100644 --- a/doc/cephadm/upgrade.rst +++ b/doc/cephadm/upgrade.rst @@ -20,7 +20,7 @@ Starting the upgrade ==================== Before you start, you should verify that all hosts are currently online -and your cluster is generally healthy. +and your cluster is healthy. :: @@ -38,7 +38,8 @@ For example, to upgrade to v15.2.1:: Monitoring the upgrade ====================== -You can tell whether an upgrade is in progress with:: +Determine whether an upgrade is in process and what version the cluster is +upgrading to with:: # ceph upgrade status