github.com/rvaralda/deis@v1.4.1/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  Deis runs on CoreOS, so connecting is as simple as using ``ssh``.
    22  
    23  CoreOS's default username is ``core``. Use the SSH key you provisioned the cluster with.
    24  
    25  Connect to the public IP address of one of your nodes (or use "convenience" DNS records if you've set them up).
    26  
    27  .. code-block:: console
    28  
    29      $ ssh core@deis-1.example.com -i ~/.ssh/deis.pub
    30  
    31  
    32  Troubleshooting etcd
    33  --------------------
    34  
    35  Sometimes issues with Deis are caused by latency between CoreOS hosts. A telltale sign of this is
    36  if all of the Deis components on a single machine crash. To aid in debugging etcd, we've created
    37  a system service that is installed but not started when you deploy CoreOS using our provision scripts.
    38  
    39  To start this service, run ``sudo systemctl start debug-etcd`` on a CoreOS machine in your cluster.
    40  This starts a service which queries etcd's state once per second. Watching this output with
    41  ``journalctl -fu debug-etcd`` makes it easy to spot heartbeat timeouts or other abnormalities
    42  which will lead to issues running Deis successfully.
    43  
    44  A deis-store component fails to start
    45  -------------------------------------
    46  
    47  For information on troubleshooting a ``deis-store`` component, see :ref:`troubleshooting-store`.
    48  
    49  Any component fails to start
    50  ----------------------------
    51  
    52  Use ``deisctl status <component>`` to view the status of the component.
    53  You can also use ``deisctl journal <component>`` to tail logs for a component, or ``deisctl list``
    54  to list all components.
    55  
    56  Failed initializing SSH client
    57  ------------------------------
    58  
    59  A ``deisctl`` command fails with: 'Failed initializing SSH client: ssh: handshake failed: ssh: unable to authenticate'.
    60  Did you remember to add your SSH key to the ssh-agent? ``ssh-add -L`` should list the key you used
    61  to provision the servers. If it's not there, ``ssh-add -K /path/to/your/key``.
    62  
    63  All the given peers are not reachable
    64  -------------------------------------
    65  
    66  A ``deisctl`` command fails with: 'All the given peers are not reachable (Tried to connect to each peer twice and failed)'.
    67  The most common cause of this issue is that a new discovery URL wasn't generated and updated in
    68  ``contrib/coreos/user-data`` before the cluster was launched. Each Deis cluster must have a unique
    69  discovery URL, or else ``etcd`` will try and fail to connect to old hosts. Try destroying the cluster
    70  and relaunching the cluster with a fresh discovery URL.
    71  
    72  You can use ``make discovery-url`` to automatically fetch a new discovery URL.
    73  
    74  Could not find unit template...
    75  -------------------------------
    76  
    77  If you built ``deisctl`` locally or didn't use its installer, you may see an error like this:
    78  
    79      .. code-block:: console
    80  
    81          $ deisctl install platform
    82  
    83          Storage subsystem...
    84          Could not find unit template for store-daemon
    85  
    86  This is because ``deisctl`` could not find unit files for Deis locally. Run
    87  ``deisctl help refresh-units`` to see where ``deisctl`` searches, and then run a command such as
    88  ``deisctl refresh-units --tag=v1.4.1``, or set the ``$DEISCTL_UNITS`` environment variable to a directory
    89  containing the unit files.
    90  
    91  Other issues
    92  ------------
    93  
    94  Running into something not detailed here? Please `open an issue`_ or hop into #deis on Freenode IRC and we'll help!
    95  
    96  .. _`open an issue`: https://github.com/deis/deis/issues/new