github.com/chasestarr/deis@v1.13.5-0.20170519182049-1d9e59fbdbfc/docs/troubleshooting_deis/index.rst (about)

     1  :title: Troubleshooting Deis
     2  :description: Resolutions for common issues encountered when running Deis.
     3  
     4  .. _troubleshooting_deis:
     5  
     6  Troubleshooting Deis
     7  ====================
     8  
     9  :Release: |version|
    10  :Date: |today|
    11  
    12  .. toctree::
    13  
    14      troubleshooting-store
    15  
    16  Common issues that users have run into when provisioning Deis are detailed below.
    17  
    18  Logging in to the cluster
    19  -------------------------
    20  
    21  To open a interactive shell on a machine in your cluster:
    22  
    23  .. code-block:: console
    24  
    25      $ deisctl ssh <unit>
    26  
    27  For example, to open a shell session on the machine that is running Controller,
    28  you can run this:
    29  
    30  .. code-block:: console
    31  
    32      $ deisctl ssh controller
    33  
    34  You can execute just a single command instead of opening a shell:
    35  
    36  .. code-block:: console
    37  
    38      $ deisctl ssh <unit> <command>
    39  
    40  You can also connect directly to the Docker instance of that unit:
    41  
    42  .. code-block:: console
    43  
    44      $ deisctl dock <unit> <command>
    45  
    46  For example, to start a Bash session on the Builder Docker container, you can
    47  run the following command:
    48  
    49  .. code-block:: console
    50  
    51      $ deisctl dock builder bash`
    52  
    53  
    54  Troubleshooting etcd
    55  --------------------
    56  
    57  Sometimes issues with Deis are caused by latency between CoreOS hosts. A telltale sign of this is
    58  if all of the Deis components on a single machine crash. To aid in debugging etcd, we've created
    59  a system service that is installed but not started when you deploy CoreOS using our provision scripts.
    60  
    61  To start this service, run ``sudo systemctl start debug-etcd`` on a CoreOS machine in your cluster.
    62  This starts a service which queries etcd's state once per second. Watching this output with
    63  ``journalctl -fu debug-etcd`` makes it easy to spot heartbeat timeouts or other abnormalities
    64  which will lead to issues running Deis successfully.
    65  
    66  A deis-store component fails to start
    67  -------------------------------------
    68  
    69  For information on troubleshooting a ``deis-store`` component, see :ref:`troubleshooting-store`.
    70  
    71  Any component fails to start
    72  ----------------------------
    73  
    74  Use ``deisctl status <component>`` to view the status of the component.
    75  You can also use ``deisctl journal <component>`` to tail logs for a component, or ``deisctl list``
    76  to list all components.
    77  
    78  Failed initializing SSH client
    79  ------------------------------
    80  
    81  A ``deisctl`` command fails with: 'Failed initializing SSH client: ssh: handshake failed: ssh: unable to authenticate'.
    82  Did you remember to add your SSH key to the ssh-agent? ``ssh-add -L`` should list the key you used
    83  to provision the servers. If it's not there, ``ssh-add -K /path/to/your/key``.
    84  
    85  All the given peers are not reachable
    86  -------------------------------------
    87  
    88  A ``deisctl`` command fails with: 'All the given peers are not reachable (Tried to connect to each peer twice and failed)'.
    89  The most common cause of this issue is that a new discovery URL wasn't generated and updated in
    90  ``contrib/coreos/user-data`` before the cluster was launched. Each Deis cluster must have a unique
    91  discovery URL, or else ``etcd`` will try and fail to connect to old hosts. Try destroying the cluster
    92  and relaunching the cluster with a fresh discovery URL.
    93  
    94  You can use ``make discovery-url`` to automatically fetch a new discovery URL.
    95  
    96  Could not find unit template...
    97  -------------------------------
    98  
    99  If you built ``deisctl`` locally or didn't use its installer, you may see an error like this:
   100  
   101      .. code-block:: console
   102  
   103          $ deisctl install platform
   104  
   105          Storage subsystem...
   106          Could not find unit template for store-daemon
   107  
   108  This is because ``deisctl`` could not find unit files for Deis locally. Run
   109  ``deisctl help refresh-units`` to see where ``deisctl`` searches, and then run a command such as
   110  ``deisctl refresh-units --tag=v1.13.4``, or set the ``$DEISCTL_UNITS`` environment variable to a directory
   111  containing the unit files.
   112  
   113  Other issues
   114  ------------
   115  
   116  Running into something not detailed here? Please `open an issue`_ or hop into #deis on Freenode IRC and we'll help!
   117  
   118  .. _`open an issue`: https://github.com/deis/deis/issues/new