valitydev/salt
14
0
Fork 0
mirror of https://github.com/valitydev/salt.git synced 2024-11-06 16:45:27 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity
ead856ee93
salt/doc/topics/tutorials/esxi_proxy_minion.rst
Alan Cugler 0b1eb00dc4
Replaced test.ping with test.version 
Result of issue #52277

Any where `test.ping` still exists in the docs was left
because of the context in those docs.
2019-03-25 12:09:48 -05:00

529 lines
18 KiB
ReStructuredText
Raw Blame History

.. _tutorial-esxi-proxy:
=================
ESXi Proxy Minion
=================
.. versionadded:: 2015.8.4
.. note::
This tutorial assumes basic knowledge of Salt. To get up to speed, check
out the :ref:`Salt Walkthrough <tutorial-salt-walk-through>`.
This tutorial also assumes a basic understanding of Salt Proxy Minions. If
you're unfamiliar with Salt's Proxy Minion system, please read the
:ref:`Salt Proxy Minion <proxy-minion>` documentation and the
:ref:`Salt Proxy Minion End-to-End Example <proxy-minion-end-to-end-example>`
tutorial.
The third assumption that this tutorial makes is that you also have a
basic understanding of ESXi hosts. You can learn more about ESXi hosts on
`VMware's various resources`_.
.. _VMware's various resources: https://www.vmware.com/products/esxi-and-esx/overview
Salt's ESXi Proxy Minion allows a VMware ESXi host to be treated as an individual
Salt Minion, without installing a Salt Minion on the ESXi host.
Since an ESXi host may not necessarily run on an OS capable of hosting a Python
stack, the ESXi host can't run a regular Salt Minion directly. Therefore, Salt's
Proxy Minion functionality enables you to designate another machine to host a
proxy process that "proxies" communication from the Salt Master to the ESXi host.
The master does not know or care that the ESXi target is not a "real" Salt Minion.
More in-depth conceptual reading on Proxy Minions can be found in the
:ref:`Proxy Minion <proxy-minion>` section of Salt's documentation.
Salt's ESXi Proxy Minion was added in the 2015.8.4 release of Salt.
.. note::
Be aware that some functionality for the ESXi Proxy Minion may depend on the
type of license attached the ESXi host(s).
For example, certain services are only available to manipulate service state
or policies with a VMware vSphere Enterprise or Enterprise Plus license, while
others are available with a Standard license. The ``ntpd`` service is restricted
to an Enterprise Plus license, while ``ssh`` is available via the Standard
license.
Please see the `vSphere Comparison`_ page for more information.
.. _vSphere Comparison: https://www.vmware.com/products/vsphere/compare
Dependencies
============
Manipulation of the ESXi host via a Proxy Minion requires the machine running
the Proxy Minion process to have the ESXCLI package (and all of it's dependencies)
and the pyVmomi Python Library to be installed.
ESXi Password
-------------
The ESXi Proxy Minion uses VMware's API to perform tasks on the host as if it was
a regular Salt Minion. In order to access the API that is already running on the
ESXi host, the ESXi host must have a username and password that is used to log
into the host. The username is usually ``root``. Before Salt can access the ESXi
host via VMware's API, a default password *must* be set on the host.
pyVmomi
-------
The pyVmomi Python library must be installed on the machine that is running the
proxy process. pyVmomi can be installed via pip:
.. code-block:: bash
pip install pyVmomi
.. note::
Version 6.0 of pyVmomi has some problems with SSL error handling on certain
versions of Python. If using version 6.0 of pyVmomi, the machine that you
are running the proxy minion process from must have either Python 2.6,
Python 2.7.9, or newer. This is due to an upstream dependency in pyVmomi 6.0
that is not supported in Python version 2.7 to 2.7.8. If the
version of Python running the proxy process is not in the supported range, you
will need to install an earlier version of pyVmomi. See `Issue #29537`_ for
more information.
.. _Issue #29537: https://github.com/saltstack/salt/issues/29537
Based on the note above, to install an earlier version of pyVmomi than the
version currently listed in PyPi, run the following:
.. code-block:: bash
pip install pyVmomi==5.5.0.2014.1.1
The 5.5.0.2014.1.1 is a known stable version that the original ESXi Proxy Minion
was developed against.
ESXCLI
------
Currently, about a third of the functions used for the ESXi Proxy Minion require
the ESXCLI package be installed on the machine running the Proxy Minion process.
The ESXCLI package is also referred to as the VMware vSphere CLI, or vCLI. VMware
provides vCLI package installation instructions for `vSphere 5.5`_ and
`vSphere 6.0`_.
.. _vSphere 5.5: http://pubs.vmware.com/vsphere-55/index.jsp#com.vmware.vcli.getstart.doc/cli_install.4.2.html
.. _vSphere 6.0: http://pubs.vmware.com/vsphere-60/index.jsp#com.vmware.vcli.getstart.doc/cli_install.4.2.html
Once all of the required dependencies are in place and the vCLI package is
installed, you can check to see if you can connect to your ESXi host by running
the following command:
.. code-block:: bash
esxcli -s <host-location> -u <username> -p <password> system syslog config get
If the connection was successful, ESXCLI was successfully installed on your system.
You should see output related to the ESXi host's syslog configuration.
Configuration
=============
There are several places where various configuration values need to be set in
order for the ESXi Proxy Minion to run and connect properly.
Proxy Config File
-----------------
On the machine that will be running the Proxy Minon process(es), a proxy config
file must be in place. This file should be located in the ``/etc/salt/`` directory
and should be named ``proxy``. If the file is not there by default, create it.
This file should contain the location of your Salt Master that the Salt Proxy
will connect to.
Example Proxy Config File:
.. code-block:: yaml
# /etc/salt/proxy
master: <salt-master-location>
Pillar Profiles
---------------
Proxy minions get their configuration from Salt's Pillar. Every proxy must
have a stanza in Pillar and a reference in the Pillar top-file that matches
the Proxy ID. At a minimum for communication with the ESXi host, the pillar
should look like this:
.. code-block:: yaml
proxy:
proxytype: esxi
host: <ip or dns name of esxi host>
username: <ESXi username>
passwords:
- first_password
- second_password
- third_password
Some other optional settings are ``protocol`` and ``port``. These can be added
to the pillar configuration.
proxytype
^^^^^^^^^
The ``proxytype`` key and value pair is critical, as it tells Salt which
interface to load from the ``proxy`` directory in Salt's install hierarchy,
or from ``/srv/salt/_proxy`` on the Salt Master (if you have created your
own proxy module, for example). To use this ESXi Proxy Module, set this to
``esxi``.
host
^^^^
The location, or ip/dns, of the ESXi host. Required.
username
^^^^^^^^
The username used to login to the ESXi host, such as ``root``. Required.
passwords
^^^^^^^^^
A list of passwords to be used to try and login to the ESXi host. At least
one password in this list is required.
The proxy integration will try the passwords listed in order. It is
configured this way so you can have a regular password and the password you
may be updating for an ESXi host either via the
:mod:`vsphere.update_host_password <salt.modules.vsphere.update_host_password>`
execution module function or via the
:mod:`esxi.password_present <salt.states.esxi.password_present>` state
function. This way, after the password is changed, you should not need to
restart the proxy minion--it should just pick up the new password
provided in the list. You can then change pillar at will to move that
password to the front and retire the unused ones.
Use-case/reasoning for using a list of passwords: You are setting up an
ESXi host for the first time, and the host comes with a default password.
You know that you'll be changing this password during your initial setup
from the default to a new password. If you only have one password option,
and if you have a state changing the password, any remote execution commands
or states that run after the password change will not be able to run on the
host until the password is updated in Pillar and the Proxy Minion process is
restarted.
This allows you to use any number of potential fallback passwords.
.. note::
When a password is changed on the host to one in the list of possible
passwords, the further down on the list the password is, the longer
individual commands will take to return. This is due to the nature of
pyVmomi's login system. We have to wait for the first attempt to fail
before trying the next password on the list.
This scenario is especially true, and even slower, when the proxy
minion first starts. If the correct password is not the first password
on the list, it may take up to a minute for ``test.version`` to respond
with salt's version installed (Example: ``2018.3.4``. Once the initial
authorization is complete, the responses for commands will be a little
faster.
To avoid these longer waiting periods, SaltStack recommends moving the
correct password to the top of the list and restarting the proxy minion
at your earliest convenience.
protocol
^^^^^^^^
If the ESXi host is not using the default protocol, set this value to an
alternate protocol. Default is ``https``. For example:
port
^^^^
If the ESXi host is not using the default port, set this value to an
alternate port. Default is ``443``.
Example Configuration Files
---------------------------
An example of all of the basic configurations that need to be in place before
starting the Proxy Minion processes includes the Proxy Config File, Pillar
Top File, and any individual Proxy Minion Pillar files.
In this example, we'll assuming there are two ESXi hosts to connect to. Therefore,
we'll be creating two Proxy Minion config files, one config for each ESXi host.
Proxy Config File:
.. code-block:: yaml
# /etc/salt/proxy
master: <salt-master-location>
Pillar Top File:
.. code-block:: yaml
# /srv/pillar/top.sls
base:
'esxi-1':
- esxi-1
'esxi-2':
- esxi-2
Pillar Config File for the first ESXi host, esxi-1:
.. code-block:: yaml
# /srv/pillar/esxi-1.sls
proxy:
proxytype: esxi
host: esxi-1.example.com
username: 'root'
passwords:
- bad-password-1
- backup-bad-password-1
Pillar Config File for the second ESXi host, esxi-2:
.. code-block:: yaml
# /srv/pillar/esxi-2.sls
proxy:
proxytype: esxi
host: esxi-2.example.com
username: 'root'
passwords:
- bad-password-2
- backup-bad-password-2
Starting the Proxy Minion
=========================
Once all of the correct configuration files are in place, it is time to start the
proxy processes!
#. First, make sure your Salt Master is running.
#. Start the first Salt Proxy, in debug mode, by giving the Proxy Minion process
and ID that matches the config file name created in the `Configuration`_ section.
.. code-block:: bash
salt-proxy --proxyid='esxi-1' -l debug
#. Accept the ``esxi-1`` Proxy Minion's key on the Salt Master:
.. code-block:: bash
# salt-key -L
Accepted Keys:
Denied Keys:
Unaccepted Keys:
esxi-1
Rejected Keys:
#
# salt-key -a esxi-1
The following keys are going to be accepted:
Unaccepted Keys:
esxi-1
Proceed? [n/Y] y
Key for minion esxi-1 accepted.
#. Repeat for the second Salt Proxy, this time we'll run the proxy process as a
daemon, as an example.
.. code-block:: bash
salt-proxy --proxyid='esxi-2' -d
#. Accept the ``esxi-2`` Proxy Minion's key on the Salt Master:
.. code-block:: bash
# salt-key -L
Accepted Keys:
esxi-1
Denied Keys:
Unaccepted Keys:
esxi-2
Rejected Keys:
#
# salt-key -a esxi-1
The following keys are going to be accepted:
Unaccepted Keys:
esxi-2
Proceed? [n/Y] y
Key for minion esxi-1 accepted.
#. Check and see if your Proxy Minions are responding:
.. code-block:: bash
# salt 'esxi-*' test.version
esxi-1:
True
esxi-3:
True
Executing Commands
==================
Now that you've configured your Proxy Minions and have them responding successfully
to a ``test.version``, we can start executing commands against the ESXi hosts via Salt.
It's important to understand how this particular proxy works, and there are a couple
of important pieces to be aware of in order to start running remote execution and
state commands against the ESXi host via a Proxy Minion: the
`vSphere Execution Module`_, the `ESXi Execution Module`_, and the `ESXi State Module`_.
vSphere Execution Module
------------------------
The :mod:`Salt.modules.vsphere <salt.modules.vsphere>` is a
standard Salt execution module that does the bulk of the work for the ESXi Proxy
Minion. If you pull up the docs for it you'll see that almost every function in
the module takes credentials (``username`` and ``password``) and a target ``host``
argument. When credentials and a host aren't passed, Salt runs commands
through ``pyVmomi`` or ``ESXCLI`` against the local machine. If you wanted,
you could run functions from this module on any machine where an appropriate
version of ``pyVmomi`` and ``ESXCLI`` are installed, and that machine would reach
out over the network and communicate with the ESXi host.
You'll notice that most of the functions in the vSphere module require a ``host``,
``username``, and ``password``. These parameters are contained in the Pillar files and
passed through to the function via the proxy process that is already running. You don't
need to provide these parameters when you execute the commands. See the
`Running Remote Execution Commands`_ section below for an example.
ESXi Execution Module
---------------------
In order for the Pillar information set up in the `Configuration`_ section above to
be passed to the function call in the vSphere Execution Module, the
:mod:`salt.modules.esxi <salt.modules.esxi>` execution module acts
as a "shim" between the vSphere execution module functions and the proxy process.
The "shim" takes the authentication credentials specified in the Pillar files and
passes them through to the ``host``, ``username``, ``password``, and optional
``protocol`` and ``port`` options required by the vSphere Execution Module functions.
If the function takes more positional, or keyword, arguments you can append them
to the call. It's this shim that speaks to the ESXi host through the proxy, arranging
for the credentials and hostname to be pulled from the Pillar section for the ESXi
Proxy Minion.
Because of the presence of the shim, to lookup documentation for what
functions you can use to interface with the ESXi host, you'll want to
look in :mod:`salt.modules.vsphere <salt.modules.vsphere>`
instead of :mod:`salt.modules.esxi <salt.modules.esxi>`.
Running Remote Execution Commands
---------------------------------
To run commands from the Salt Master to execute, via the ESXi Proxy Minion, against
the ESXi host, you use the ``esxi.cmd <vsphere-function-name>`` syntax to call
functions located in the vSphere Execution Module. Both args and kwargs needed
for various vsphere execution module functions must be passed through in a kwarg-
type manor. For example:
.. code-block:: bash
salt 'esxi-*' esxi.cmd system_info
salt 'exsi-*' esxi.cmd get_service_running service_name='ssh'
ESXi State Module
-----------------
The ESXi State Module functions similarly to other state modules. The "shim" provided
by the `ESXi Execution Module`_ passes the necessary ``host``, ``username``, and
``password`` credentials through, so those options don't need to be provided in the
state. Other than that, state files are written and executed just like any other
Salt state. See the :mod:`salt.modules.esxi <salt.states.esxi>` state
for ESXi state functions.
The follow state file is an example of how to configure various pieces of an ESXi host
including enabling SSH, uploading and SSH key, configuring a coredump network config,
syslog, ntp, enabling VMotion, resetting a host password, and more.
.. code-block:: yaml
# /srv/salt/configure-esxi.sls
configure-host-ssh:
esxi.ssh_configured:
- service_running: True
- ssh_key_file: /etc/salt/ssh_keys/my_key.pub
- service_policy: 'automatic'
- service_restart: True
- certificate_verify: True
configure-host-coredump:
esxi.coredump_configured:
- enabled: True
- dump_ip: 'my-coredump-ip.example.com'
configure-host-syslog:
esxi.syslog_configured:
- syslog_configs:
loghost: ssl://localhost:5432,tcp://10.1.0.1:1514
default-timeout: 120
- firewall: True
- reset_service: True
- reset_syslog_config: True
- reset_configs: loghost,default-timeout
configure-host-ntp:
esxi.ntp_configured:
- service_running: True
- ntp_servers:
- 192.174.1.100
- 192.174.1.200
- service_policy: 'automatic'
- service_restart: True
configure-vmotion:
esxi.vmotion_configured:
- enabled: True
configure-host-vsan:
esxi.vsan_configured:
- enabled: True
- add_disks_to_vsan: True
configure-host-password:
esxi.password_present:
- password: 'new-bad-password'
States are called via the ESXi Proxy Minion just as they would on a regular minion.
For example:
.. code-block:: bash
salt 'esxi-*' state.sls configure-esxi test=true
salt 'esxi-*' state.sls configure-esxi
Relevant Salt Files and Resources
=================================
- :mod:`ESXi Proxy Minion <salt.proxy.esxi>`
- :mod:`ESXi Execution Module <salt.modules.esxi>`
- :mod:`ESXi State Module <salt.states.esxi>`
- :ref:`Salt Proxy Minion Docs <proxy-minion>`
- :ref:`Salt Proxy Minion End-to-End Example <proxy-minion-end-to-end-example>`
- :mod:`vSphere Execution Module <salt.modules.vsphere>`
Reference in New Issue View Git Blame Copy Permalink