10000 Merge pull request #8770 from techhat/troubleshooting · linuxme/salt@b597de5 · GitHub
[go: up one dir, main page]
Skip to content

Commit b597de5

Browse files
techhattechhat
committed
Merge pull request saltstack#8770 from techhat/troubleshooting
Initial commit of troubleshooting doc for Salt Cloud
2 parents f5b8734 + fb40e36 commit b597de5

File tree

1 file changed

+151
-0
lines changed

1 file changed

+151
-0
lines changed

‎doc/topics/cloud/troubleshooting.rst

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
==========================
2+
Troubleshooting Salt Cloud
3+
==========================
4+
5+
This page describes various steps for troubleshooting problems that may arise
6+
while using Salt Cloud.
7+
8+
Generic Troubleshooting Steps
9+
=============================
10+
This section describes a set of instructions that are useful to a large number
11+
of situations, and are likely to solve most issues that arise.
12+
13+
Debug Mode
14+
----------
15+
Frequently, running Salt Cloud in debug mode will reveal information about a
16+
deployment which would otherwise not be obvious:
17+
18+
.. code-block:: bash
19+
20+
salt-cloud -p myprofile myinstance -l debug
21+
22+
Keep in mind that a number of messages will appear that look at first like
23+
errors, but are in fact intended to give developers factual information to
24+
assist in debugging. A number of messages that appear will be for cloud
25+
providers that you do not have configured; in these cases, the message usually
26+
is intended to confirm that they are not configured.
27+
28+
29+
Salt Bootstrap
30+
--------------
31+
By default, Salt Cloud uses the Salt Bootstrap script to provision instances:
32+
33+
.. _`Salt Bootstrap`: https://github.com/saltstack/salt-bootstrap
34+
35+
This script is packaged with Salt Cloud, but may be updated without updating
36+
the Salt package:
37+
38+
.. code-block:: bash
39+
40+
salt-cloud -u
41+
42+
43+
The Bootstrap Log
44+
-----------------
45+
If the default deploy script was used, there should be a file in the ``/tmp/``
46+
directory called ``bootstrap-salt.log``. This file contains the full output from
47+
the deployment, including any errors that may have occurred.
48+
49+
50+
Keeping Temp Files
51+
------------------
52+
Salt Cloud uploads minion-specific files to instances once they are available
53+
via SSH, and then executes a deploy script to put them into the correct place
54+
and install Salt. The ``--keep-tmp`` option will instruct Salt Cloud not to
55+
remove those files when finished with them, so that the user may inspect them
56+
for problems:
57+
58+
.. code-block:: bash
59+
60+
salt-cloud -p myprofile myinstance --keep-tmp
61+
62+
By default, Salt Cloud will create a directory on the target instance called
63+
``/tmp/.saltcloud/``. This directory should be owned by the user that is to
64+
execute the deploy script, and should have permissions of ``0700``.
65+
66+
Most cloud providers are configured to use ``root`` as the default initial user
67+
for deployment, and as such, this directory and all files in it should be owned
68+
by the ``root`` user.
69+
70+
The ``/tmp/.saltcloud/`` directory should the following files:
71+
72+
- A ``deploy.sh`` script. This script should have permissions of ``0755``.
73+
- A ``.pem`` and ``.pub`` key named after the minion. The ``.pem`` file should
74+
have permissions of ``0600``. Ensure that the ``.pem`` and ``.pub`` files have
75+
been properly copied to the ``/etc/salt/pki/minion/`` directory.
76+
- A file called ``minion``. This file should have been copied to the
77+
``/etc/salt/`` directory.
78+
- Optionally, a file called ``grains``. This file, if present, should have been
79+
copied to the ``/etc/salt/`` directory.
80+
81+
82+
Unprivileged Primary Users
83+
--------------------------
84+
Some providers, most notably EC2, are configured with a different primary user.
85+
Some common examples are ``ec2-user``, ``ubuntu``, ``fedora`` and ``bitnami``.
86+
In these cases, the ``/tmp/.saltcloud/`` directory and all files in it should
87+
be owned by this user.
88+
89+
Some providers, such as EC2, are configured to not require these users to
90+
provide a password when using the ``sudo`` command. Because it is more secure
91+
to require ``sudo`` users to provide a password, other providers are configured
92+
that way.
93+
94+
If this instance is required to provide a password, it needs to be configured
95+
in Salt Cloud. A password for sudo to use may be added to either the provider
96+
configuration or the profile configuration:
97+
98+
.. code-block:: yaml
99+
100+
sudo_password: mypassword
101+
102+
103+
``/tmp/`` is Mounted as ``noexec``
104+
----------------------------------
105+
It is more secure to mount the ``/tmp/`` directory with a ``noexec`` option.
106+
This is uncommon on most cloud providers, but very common in private
107+
environments. To see if the ``/tmp/`` directory is mounted this way, run the
108+
following command:
109+
110+
.. code-block:: bash
111+
112+
mount | grep tmp
113+
114+
The if the output of this command includes a line that looks like this, then
115+
the ``/tmp/`` directory is mounted as ``noexec``:
116+
117+
.. code-block:: bash
118+
119+
tmpfs on /tmp type tmpfs (rw,noexec)
120+
121+
If this is the case, then the ``deploy_command`` will need to be changed
122+
in order to run the deploy script through the ``sh`` command, rather than trying
123+
to execute it directly. This may be specified in either the provider or the
124+
profile config:
125+
126+
.. code-block:: yaml
127+
128+
deploy_command: sh /tmp/.saltcloud/deploy.sh
129+
130+
Please note that by default, Salt Cloud will place its files in a directory
131+
called ``/tmp/.saltcloud/``. This may be also be changed in the provider or
132+
profile configuration:
133+
134+
.. code-block:: yaml
135+
136+
tmp_dir: /tmp/.saltcloud/
137+
138+
If this directory is changed, then the ``deploy_command`` need to be changed
139+
in order to reflect the ``tmp_dir`` configuration.
140+
141+
142+
Executing the Deploy Script Manually
143+
------------------------------------
144+
If all of the files needed for deployment were successfully uploaded to the
145+
correct locations, and contain the correct permissions and ownerships, the
146+
deploy script may be executed manually in order to check for other issues:
147+
148+
.. code-block:: bash
149+
150+
cd /tmp/.saltcloud/
151+
./deploy.sh

0 commit comments

Comments
 (0)
0