Core Docs Refactor and Redesign (#36067)

* Docs refactor as outlined in https://github.com/ansible/proposals/issues/79. Moves content into 'guides'; refactors TOC; fixes CSS; design tweaks to layout and CSS; fixes generated plugin, CLI and module docs to fix links accodingly; more.

* Adding extra blank line for shippable
This commit is contained in:
scottb 2018-02-13 07:23:55 -08:00 committed by GitHub
parent 480a9c10c9
commit 373b1dcf59
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
157 changed files with 13167 additions and 178 deletions

View file

@ -74,22 +74,22 @@ clean:
# TODO: make generate_man output dir cli option
cli: $(GENERATE_CLI)
PYTHONPATH=../../lib $(GENERATE_CLI) --template-file=../templates/cli_rst.j2 --output-dir=rst/ --output-format rst ../../lib/ansible/cli/*.py
PYTHONPATH=../../lib $(GENERATE_CLI) --template-file=../templates/cli_rst.j2 --output-dir=rst/cli/ --output-format rst ../../lib/ansible/cli/*.py
keywords: $(FORMATTER) ../templates/playbooks_keywords.rst.j2
PYTHONPATH=../../lib $(DUMPER) --template-dir=../templates --output-dir=rst/ -d ./keyword_desc.yml
PYTHONPATH=../../lib $(DUMPER) --template-dir=../templates --output-dir=rst/reference_appendices/ -d ./keyword_desc.yml
config:
PYTHONPATH=../../lib $(CONFIG_DUMPER) --template-file=../templates/config.rst.j2 --output-dir=rst/ -d ../../lib/ansible/config/base.yml
PYTHONPATH=../../lib $(CONFIG_DUMPER) --template-file=../templates/config.rst.j2 --output-dir=rst/reference_appendices/ -d ../../lib/ansible/config/base.yml
modules: $(FORMATTER) ../templates/plugin.rst.j2
PYTHONPATH=../../lib $(FORMATTER) -t rst --template-dir=../templates --module-dir=../../lib/ansible/modules -o rst/module_docs/ $(MODULE_ARGS)
PYTHONPATH=../../lib $(FORMATTER) -t rst --template-dir=../templates --module-dir=../../lib/ansible/modules -o rst/modules/ $(MODULE_ARGS)
plugins: $(FORMATTER) ../templates/plugin.rst.j2
@echo "looping over doc plugins"
for plugin in $(DOC_PLUGINS); \
do \
PYTHONPATH=../../lib $(FORMATTER) -t rst --plugin-type $$plugin --template-dir=../templates --module-dir=../../lib/ansible/plugins/$$plugin -o rst/ $(PLUGIN_ARGS); \
PYTHONPATH=../../lib $(FORMATTER) -t rst --plugin-type $$plugin --template-dir=../templates --module-dir=../../lib/ansible/plugins/$$plugin -o rst $(PLUGIN_ARGS); \
done
testing:

Binary file not shown.

Before

Width:  |  Height:  |  Size: 318 B

After

Width:  |  Height:  |  Size: 6.4 KiB

View file

@ -0,0 +1,20 @@
"""Sphinx ReadTheDocs theme.
From https://github.com/ryan-roemer/sphinx-bootstrap-theme.
"""
from os import path
__version__ = '0.2.5b2'
__version_full__ = __version__
def get_html_theme_path():
"""Return list of HTML theme paths."""
cur_dir = path.abspath(path.dirname(path.dirname(__file__)))
return cur_dir
# See http://www.sphinx-doc.org/en/stable/theming.html#distribute-your-theme-as-a-python-package
def setup(app):
app.add_html_theme('sphinx_rtd_theme', path.abspath(path.dirname(__file__)))

View file

@ -0,0 +1,11 @@
<ul class="wy-breadcrumbs">
<li><a href="{{ pathto(master_doc) }}">Docs</a> &raquo;</li>
<li><a href="">{{ title }}</a></li>
{% if not pagename.endswith('_module') and (not 'list_of' in pagename) and (not 'category' in pagename) %}
<li class="wy-breadcrumbs-aside">
<a href="https://github.com/ansible/ansible/blob/devel/docs/docsite/rst/{{ pagename }}.rst" class="icon icon-github"> Edit on GitHub</a>
</li>
{% endif %}
</ul>
<hr/>

View file

@ -0,0 +1,35 @@
<footer>
{% if next or prev %}
<div class="rst-footer-buttons">
{% if next %}
<a href="{{ next.link|e }}" class="btn btn-neutral float-right" title="{{ next.title|striptags|e }}"/>Next <span class="icon icon-circle-arrow-right"></span></a>
{% endif %}
{% if prev %}
<a href="{{ prev.link|e }}" class="btn btn-neutral" title="{{ prev.title|striptags|e }}"><span class="icon icon-circle-arrow-left"></span> Previous</a>
{% endif %}
</div>
{% endif %}
<hr/>
<script type="text/javascript">
(function(w,d,t,u,n,s,e){w['SwiftypeObject']=n;w[n]=w[n]||function(){
(w[n].q=w[n].q||[]).push(arguments);};s=d.createElement(t);
e=d.getElementsByTagName(t)[0];s.async=1;s.src=u;e.parentNode.insertBefore(s,e);
})(window,document,'script','//s.swiftypecdn.com/install/v2/st.js','_st');
_st('install','yABGvz2N8PwcwBxyfzUc','2.0.0');
</script>
<p>
Copyright © 2017 Red Hat, Inc.
<br>
{%- if last_updated %}
{% trans last_updated=last_updated|e %}Last updated on {{ last_updated }}.{% endtrans %}
{%- endif %}
</p>
<p>
Ansible docs are generated from <a href="https://github.com/ansible/ansible">GitHub sources</a> using <a href="http://sphinx-doc.org/">Sphinx</a> using a theme provided by <a href="http://readthedocs.org">Read the Docs</a>. {% if pagename.endswith("_module") %}Module documentation is not edited directly, but is generated from the source code for the modules. To submit an update to module docs, edit the 'DOCUMENTATION' metadata in the <a href="https://github.com/ansible/ansible/tree/devel/lib/ansible/modules">modules directory</a> of the <a href="https://github.com/ansible/ansible/">core source code repository</a>. {% endif %}
</p>
</footer>

View file

@ -0,0 +1,318 @@
{# TEMPLATE VAR SETTINGS #}
{%- set url_root = pathto('', 1) %}
{%- if url_root == '#' %}{% set url_root = '' %}{% endif %}
{%- if not embedded and docstitle %}
{%- set titlesuffix = " &mdash; "|safe + docstitle|e %}
{%- else %}
{%- set titlesuffix = "" %}
{%- endif %}
{%- set lang_attr = 'en' if language == None else (language | replace('_', '-')) %}
<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="{{ lang_attr }}" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="{{ lang_attr }}" > <!--<![endif]-->
<head>
<meta charset="utf-8">
{{ metatags }}
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<script type="text/javascript" src="//www.redhat.com/dtm.js"></script>
<meta class="swiftype" name="published_at" data-type="date" content="2017-12-13" />
<meta class="swiftype" name="version" data-type="string" content="3.2.2">
<!-- Google Tag Manager Data Layer -->
<script>
dataLayer = [];
</script>
<!-- End Google Tag Manager Data Layer -->
{% block htmltitle %}
<title>{{ title|striptags|e }}{{ titlesuffix }}</title>
{% endblock %}
{# FAVICON #}
{% if favicon %}
<link rel="shortcut icon" href="{{ pathto('_static/' + favicon, 1) }}"/>
{% endif %}
{# CANONICAL URL #}
{% if theme_canonical_url %}
<link rel="canonical" href="{{ theme_canonical_url }}{{ pagename }}.html"/>
{% endif %}
{# CSS #}
<link href='https://fonts.googleapis.com/css?family=Lato:400,700|Roboto+Slab:400,700|Inconsolata:400,700' rel='stylesheet' type='text/css'>
<link href='https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.0.3/css/font-awesome.min.css' rel='stylesheet' type='text/css'>
{# OPENSEARCH #}
{% if not embedded %}
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT:'{{ url_root }}',
VERSION:'{{ release|e }}',
COLLAPSE_INDEX:false,
FILE_SUFFIX:'{{ '' if no_search_suffix else file_suffix }}',
HAS_SOURCE: {{ has_source|lower }}
};
</script>
{%- for scriptfile in script_files %}
<script type="text/javascript" src="{{ pathto(scriptfile, 1) }}"></script>
{%- endfor %}
{% if use_opensearch %}
<link rel="search" type="application/opensearchdescription+xml"
title="{% trans docstitle=docstitle|e %}Search within {{ docstitle }}{% endtrans %}"
href="{{ pathto('_static/opensearch.xml', 1) }}"/>
{% endif %}
{% endif %}
{# RTD hosts this file, so just load on non RTD builds #}
{%- if not READTHEDOCS %}
<link rel="stylesheet" href="{{ pathto('_static/' + style, 1) }}" type="text/css" />
{%- endif %}
<link rel="stylesheet" href="{{ pathto('_static/pygments.css', 1) }}" type="text/css" />
{%- for css in css_files %}
{%- if css|attr("rel") %}
<link rel="{{ css.rel }}" href="{{ pathto(css.filename, 1) }}" type="text/css"{% if css.title is not none %} title="{{ css.title }}"{% endif %} />
{%- else %}
<link rel="stylesheet" href="{{ pathto(css, 1) }}" type="text/css" />
{%- endif %}
{%- endfor %}
{%- for cssfile in extra_css_files %}
<link rel="stylesheet" href="{{ pathto(cssfile, 1) }}" type="text/css" />
{%- endfor %}
{%- block linktags %}
{%- if hasdoc('about') %}
<link rel="author" title="{{ _('About these documents') }}" href="{{ pathto('about') }}" />
{%- endif %}
{%- if hasdoc('genindex') %}
<link rel="index" title="{{ _('Index') }}" href="{{ pathto('genindex') }}" />
{%- endif %}
{%- if hasdoc('search') %}
<link rel="search" title="{{ _('Search') }}" href="{{ pathto('search') }}" />
{%- endif %}
{%- if hasdoc('copyright') %}
<link rel="copyright" title="{{ _('Copyright') }}" href="{{ pathto('copyright') }}" />
{%- endif %}
{%- if next %}
<link rel="next" title="{{ next.title|striptags|e }}" href="{{ next.link|e }}" />
{%- endif %}
{%- if prev %}
<link rel="prev" title="{{ prev.title|striptags|e }}" href="{{ prev.link|e }}" />
{%- endif %}
{%- endblock %}
{%- block extrahead %} {% endblock %}
<script src="//cdnjs.cloudflare.com/ajax/libs/modernizr/2.6.2/modernizr.min.js"></script>
{# Keep modernizr in head - http://modernizr.com/docs/#installing #}
<script src="{{ pathto('_static/js/modernizr.min.js', 1) }}"></script>
</head>
<body class="wy-body-for-nav">
<!-- Google Tag Manager -->
<noscript><iframe src="//www.googletagmanager.com/ns.html?id=GTM-PSB293" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
<script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start': new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0], j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src='//www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f); })(window,document,'script','dataLayer','GTM-PSB293');</script>
<!-- End Google Tag Manager -->
<div class="DocSite-globalNav ansibleNav">
<ul>
<li><a href="https://www.ansible.com/ansiblefest" target="_blank">AnsibleFest</a></li>
<li><a href="https://www.ansible.com/tower" target="_blank">Products</a></li>
<li><a href="https://www.ansible.com/community" target="_blank">Community</a></li>
<li><a href="https://www.ansible.com/webinars-training" target="_blank">Webinars & Training</a></li>
<li><a href="https://www.ansible.com/blog" target="_blank">Blog</a></li>
</ul>
</div>
<a class="DocSite-nav" href="/">
<img class="DocSiteNav-logo"
src="{{ pathto('_static/', 1) }}images/logo_invert.png"
alt="Ansible Logo">
<div class="DocSiteNav-title">
Documentation
</div>
</a>
<div class="wy-grid-for-nav">
{# SIDE NAV, TOGGLES ON MOBILE #}
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search">
{% block sidebartitle %}
<div style="background-color:#5bbdbf;height=80px;margin:'auto auto auto auto'">
<a class="DocSiteProduct-header DocSiteProduct-header--core" href="/">
<div class="DocSiteProduct-productName">
<div class="DocSiteProduct-logoText">
Ansible
<div class="DocSiteProduct-CurrentVersion" align="right">
devel
</div>
</div>
</div>
</a>
<div class="DocSiteProduct-CheckVersionPara">For previous versions, see the <a class="DocSiteProduct-versionheader" href="/#coreversionselect">documentation archive.</a></div>
</div>
<div class="wy-side-nav-search" style="background-color#5bbdbf;height=80px;margin:'auto auto auto auto'">
<!-- <a href="{{ pathto(master_doc) }}" class="icon icon-home"> {{ project }}</a> -->
{% include "searchbox.html" %}
</div>
{% endblock %}
</div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
{% block menu %}
{#
The singlehtml builder doesn't handle this toctree call when the
toctree is empty. Skip building this for now.
#}
{% if 'singlehtml' not in builder %}
{% set global_toc = toctree(maxdepth=theme_navigation_depth|int,
collapse=theme_collapse_navigation|tobool,
includehidden=theme_includehidden|tobool,
titles_only=theme_titles_only|tobool) %}
{% endif %}
{% if global_toc %}
{{ global_toc }}
{% else %}
<!-- Local TOC -->
<div class="local-toc">{{ toc }}</div>
{% endif %}
{% endblock %}
</div>
<!-- changeable widget -->
<div id="sideBanner">
<br/>
<a href="https://www.ansible.com/docs-left?utm_source=docs">
<img style="border-width:0px;" src="https://cdn2.hubspot.net/hubfs/330046/docs-graphics/ASB-docs-left-rail.png" />
</a>
</div>
</div>
&nbsp;
</nav>
</div>
<div class="DocSite-sideNav ansibleNav">
<ul class="">
<li><a href="https://www.ansible.com/ansiblefest" target="_blank">AnsibleFest</a></li>
<li><a href="https://www.ansible.com/tower" target="_blank">Products</a></li>
<li><a href="https://www.ansible.com/community" target="_blank">Community</a></li>
<li><a href="https://www.ansible.com/webinars-training" target="_blank">Webinars & Training</a></li>
<li><a href="https://www.ansible.com/blog" target="_blank">Blog</a></li>
</ul>
</div>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
{# MOBILE NAV, TRIGGLES SIDE NAV ON TOGGLE #}
<nav class="wy-nav-top" aria-label="top navigation">
{% block mobile_nav %}
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="{{ pathto(master_doc) }}">{{ project }}</a>
{% endblock %}
</nav>
{# PAGE CONTENT #}
<div class="wy-nav-content">
<div class="rst-content">
<!-- Banner ads
<div class="DocSiteBanner">
<a class="DocSiteBanner-imgWrapper"
href="https://www.ansible.com/docs-top?utm_source=docs">
<img src="https://cdn2.hubspot.net/hubfs/330046/docs-graphics/ASB-docs-top-left.png">
</a>
<a class="DocSiteBanner-imgWrapper"
href="https://www.ansible.com/docs-top?utm_source=docs">
<img src="https://cdn2.hubspot.net/hubfs/330046/docs-graphics/ASB-docs-top-right.png">
</a>
</div> -->
{% include "breadcrumbs.html" %}
<div id="page-content">
{% block body %}{% endblock %}
</div>
<div id="search-results"><gcse:searchresults-only></div>
{% include "footer.html" %}
</div>
</div>
</section>
</div>
{% include "versions.html" %}
{% if not embedded %}
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT:'{{ url_root }}',
VERSION:'{{ release|e }}',
LANGUAGE:'{{ language }}',
COLLAPSE_INDEX:false,
FILE_SUFFIX:'{{ '' if no_search_suffix else file_suffix }}',
HAS_SOURCE: {{ has_source|lower }},
SOURCELINK_SUFFIX: '{{ sourcelink_suffix }}'
};
</script>
{%- for scriptfile in script_files %}
<script type="text/javascript" src="{{ pathto(scriptfile, 1) }}"></script>
{%- endfor %}
{% endif %}
{# RTD hosts this file, so just load on non RTD builds #}
{% if not READTHEDOCS %}
<script type="text/javascript" src="{{ pathto('_static/js/theme.js', 1) }}"></script>
{% endif %}
<script type="text/javascript">
jQuery(function () {
{% if theme_sticky_navigation|tobool %}
SphinxRtdTheme.Navigation.enableSticky();
{% else %}
SphinxRtdTheme.Navigation.enable();
{% endif %}
});
</script>
{%- block footer %} {% endblock %}
<!-- begin analytics -->
<script type="text/javascript">
var _hsq = _hsq || [];
_hsq.push(["setContentType", "standard-page"]);
(function(d,s,i,r) {
if (d.getElementById(i)){return;}
var n = d.createElement(s),e = document.getElementsByTagName(s)[0];
n.id=i;n.src = '//js.hs-analytics.net/analytics/'+(Math.ceil(new Date()/r)*r)+'/330046.js';
e.parentNode.insertBefore(n, e);
})(document, "script", "hs-analytics",300000);
</script>
<!-- end analytics -->
<script type="text/javascript">
if (("undefined" !== typeof _satellite) && ("function" === typeof _satellite.pageBottom)) {
_satellite.pageBottom();
}
</script>
</body>
</html>

View file

@ -0,0 +1,50 @@
{#
basic/search.html
~~~~~~~~~~~~~~~~~
Template for the search page.
:copyright: Copyright 2007-2013 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
#}
{%- extends "layout.html" %}
{% set title = _('Search') %}
{% set script_files = script_files + ['_static/searchtools.js'] %}
{% block footer %}
<script type="text/javascript">
jQuery(function() { Search.loadIndex("{{ pathto('searchindex.js', 1) }}"); });
</script>
{# this is used when loading the search index using $.ajax fails,
such as on Chrome for documents on localhost #}
<script type="text/javascript" id="searchindexloader"></script>
{{ super() }}
{% endblock %}
{% block body %}
<noscript>
<div id="fallback" class="admonition warning">
<p class="last">
{% trans %}Please activate JavaScript to enable the search
functionality.{% endtrans %}
</p>
</div>
</noscript>
{% if search_performed %}
<h2>{{ _('Search Results') }}</h2>
{% if not search_results %}
<p>{{ _('Your search did not match any documents. Please make sure that all words are spelled correctly and that you\'ve selected enough categories.') }}</p>
{% endif %}
{% endif %}
<div id="search-results">
{% if search_results %}
<ul>
{% for href, caption, context in search_results %}
<li>
<a href="{{ pathto(item.href) }}">{{ caption }}</a>
<p class="context">{{ context|e }}</p>
</li>
{% endfor %}
</ul>
{% endif %}
</div>
{% endblock %}

View file

@ -0,0 +1,9 @@
{%- if builder != 'singlehtml' %}
<div role="search">
<form id="rtd-search-form" class="wy-form" action="{{ pathto('search') }}" method="get">
<input type="text" name="q" placeholder="{{ _('Search docs') }}" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
{%- endif %}

View file

@ -0,0 +1 @@
.fa:before{-webkit-font-smoothing:antialiased}.clearfix{*zoom:1}.clearfix:before,.clearfix:after{display:table;content:""}.clearfix:after{clear:both}@font-face{font-family:FontAwesome;font-weight:normal;font-style:normal;src:url("../fonts/fontawesome-webfont.eot");src:url("../fonts/fontawesome-webfont.eot?#iefix") format("embedded-opentype"),url("../fonts/fontawesome-webfont.woff") format("woff"),url("../fonts/fontawesome-webfont.ttf") format("truetype"),url("../fonts/fontawesome-webfont.svg#FontAwesome") format("svg")}.fa:before{display:inline-block;font-family:FontAwesome;font-style:normal;font-weight:normal;line-height:1;text-decoration:inherit}a .fa{display:inline-block;text-decoration:inherit}li .fa{display:inline-block}li .fa-large:before,li .fa-large:before{width:1.875em}ul.fas{list-style-type:none;margin-left:2em;text-indent:-0.8em}ul.fas li .fa{width:0.8em}ul.fas li .fa-large:before,ul.fas li .fa-large:before{vertical-align:baseline}.fa-book:before{content:""}.icon-book:before{content:""}.fa-caret-down:before{content:""}.icon-caret-down:before{content:""}.fa-caret-up:before{content:""}.icon-caret-up:before{content:""}.fa-caret-left:before{content:""}.icon-caret-left:before{content:""}.fa-caret-right:before{content:""}.icon-caret-right:before{content:""}.rst-versions{position:fixed;bottom:0;left:0;width:300px;color:#fcfcfc;background:#1f1d1d;border-top:solid 10px #343131;font-family:"Lato","proxima-nova","Helvetica Neue",Arial,sans-serif;z-index:400}.rst-versions a{color:#2980B9;text-decoration:none}.rst-versions .rst-badge-small{display:none}.rst-versions .rst-current-version{padding:12px;background-color:#272525;display:block;text-align:right;font-size:90%;cursor:pointer;color:#27AE60;*zoom:1}.rst-versions .rst-current-version:before,.rst-versions .rst-current-version:after{display:table;content:""}.rst-versions .rst-current-version:after{clear:both}.rst-versions .rst-current-version .fa{color:#fcfcfc}.rst-versions .rst-current-version .fa-book{float:left}.rst-versions .rst-current-version .icon-book{float:left}.rst-versions .rst-current-version.rst-out-of-date{background-color:#E74C3C;color:#fff}.rst-versions .rst-current-version.rst-active-old-version{background-color:#F1C40F;color:#000}.rst-versions.shift-up .rst-other-versions{display:block}.rst-versions .rst-other-versions{font-size:90%;padding:12px;color:gray;display:none}.rst-versions .rst-other-versions hr{display:block;height:1px;border:0;margin:20px 0;padding:0;border-top:solid 1px #413d3d}.rst-versions .rst-other-versions dd{display:inline-block;margin:0}.rst-versions .rst-other-versions dd a{display:inline-block;padding:6px;color:#fcfcfc}.rst-versions.rst-badge{width:auto;bottom:20px;right:20px;left:auto;border:none;max-width:300px}.rst-versions.rst-badge .icon-book{float:none}.rst-versions.rst-badge .fa-book{float:none}.rst-versions.rst-badge.shift-up .rst-current-version{text-align:right}.rst-versions.rst-badge.shift-up .rst-current-version .fa-book{float:left}.rst-versions.rst-badge.shift-up .rst-current-version .icon-book{float:left}.rst-versions.rst-badge .rst-current-version{width:auto;height:30px;line-height:30px;padding:0 6px;display:block;text-align:center}@media screen and (max-width: 768px){.rst-versions{width:85%;display:none}.rst-versions.shift{display:block}}

File diff suppressed because it is too large Load diff

File diff suppressed because it is too large Load diff

After

Width:  |  Height:  |  Size: 434 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 8.1 KiB

File diff suppressed because one or more lines are too long

View file

@ -0,0 +1 @@
require=function n(e,t,i){function o(s,a){if(!t[s]){if(!e[s]){var l="function"==typeof require&&require;if(!a&&l)return l(s,!0);if(r)return r(s,!0);var c=new Error("Cannot find module '"+s+"'");throw c.code="MODULE_NOT_FOUND",c}var u=t[s]={exports:{}};e[s][0].call(u.exports,function(n){var t=e[s][1][n];return o(t||n)},u,u.exports,n,e,t,i)}return t[s].exports}for(var r="function"==typeof require&&require,s=0;s<i.length;s++)o(i[s]);return o}({"sphinx-rtd-theme":[function(n,e,t){var jQuery="undefined"!=typeof window?window.jQuery:n("jquery");e.exports.ThemeNav=function(){var n={navBar:null,win:null,winScroll:!1,winResize:!1,linkScroll:!1,winPosition:0,winHeight:null,docHeight:null,isRunning:!1};return n.enable=function(n){var e=this;e.isRunning||(e.isRunning=!0,jQuery(function(t){e.init(t),e.reset(),e.win.on("hashchange",e.reset),n&&e.win.on("scroll",function(){e.linkScroll||e.winScroll||(e.winScroll=!0,requestAnimationFrame(function(){e.onScroll()}))}),e.win.on("resize",function(){e.winResize||(e.winResize=!0,requestAnimationFrame(function(){e.onResize()}))}),e.onResize()}))},n.enableSticky=function(){this.enable(!0)},n.init=function(n){n(document);var e=this;this.navBar=n("div.wy-side-scroll:first"),this.win=n(window),n(document).on("click","[data-toggle='wy-nav-top']",function(){n("[data-toggle='wy-nav-shift']").toggleClass("shift"),n("[data-toggle='rst-versions']").toggleClass("shift")}).on("click",".wy-menu-vertical .current ul li a",function(){var t=n(this);n("[data-toggle='wy-nav-shift']").removeClass("shift"),n("[data-toggle='rst-versions']").toggleClass("shift"),e.toggleCurrent(t),e.hashChange()}).on("click","[data-toggle='rst-current-version']",function(){n("[data-toggle='rst-versions']").toggleClass("shift-up")}),n("table.docutils:not(.field-list,.footnote,.citation)").wrap("<div class='wy-table-responsive'></div>"),n("table.docutils.footnote").wrap("<div class='wy-table-responsive footnote'></div>"),n("table.docutils.citation").wrap("<div class='wy-table-responsive citation'></div>"),n(".wy-menu-vertical ul").not(".simple").siblings("a").each(function(){var t=n(this);expand=n('<span class="toctree-expand"></span>'),expand.on("click",function(n){return e.toggleCurrent(t),n.stopPropagation(),!1}),t.prepend(expand)})},n.reset=function(){var n=encodeURI(window.location.hash)||"#";try{var e=$(".wy-menu-vertical").find('[href="'+n+'"]');if(0===e.length){var t=$('.document a[href="'+n+'"]').closest("div.section");e=$(".wy-menu-vertical").find('[href="#'+t.attr("id")+'"]')}e.length>0&&($(".wy-menu-vertical .current").removeClass("current"),e.addClass("current"),e.closest("li.toctree-l1").addClass("current"),e.closest("li.toctree-l1").parent().addClass("current"),e.closest("li.toctree-l1").addClass("current"),e.closest("li.toctree-l2").addClass("current"),e.closest("li.toctree-l3").addClass("current"),e.closest("li.toctree-l4").addClass("current"))}catch(i){console.log("Error expanding nav for anchor",i)}},n.onScroll=function(){this.winScroll=!1;var n=this.win.scrollTop(),e=n+this.winHeight,t=this.navBar.scrollTop()+(n-this.winPosition);n<0||e>this.docHeight||(this.navBar.scrollTop(t),this.winPosition=n)},n.onResize=function(){this.winResize=!1,this.winHeight=this.win.height(),this.docHeight=$(document).height()},n.hashChange=function(){this.linkScroll=!0,this.win.one("hashchange",function(){this.linkScroll=!1})},n.toggleCurrent=function(n){var e=n.closest("li");e.siblings("li.current").removeClass("current"),e.siblings().find("li.current").removeClass("current"),e.find("> ul li.current").removeClass("current"),e.toggleClass("current")},n}(),"undefined"!=typeof window&&(window.SphinxRtdTheme={Navigation:e.exports.ThemeNav}),function(){for(var n=0,e=["ms","moz","webkit","o"],t=0;t<e.length&&!window.requestAnimationFrame;++t)window.requestAnimationFrame=window[e[t]+"RequestAnimationFrame"],window.cancelAnimationFrame=window[e[t]+"CancelAnimationFrame"]||window[e[t]+"CancelRequestAnimationFrame"];window.requestAnimationFrame||(window.requestAnimationFrame=function(e,t){var i=(new Date).getTime(),o=Math.max(0,16-(i-n)),r=window.setTimeout(function(){e(i+o)},o);return n=i+o,r}),window.cancelAnimationFrame||(window.cancelAnimationFrame=function(n){clearTimeout(n)})}()},{jquery:"jquery"}]},{},["sphinx-rtd-theme"]);

View file

@ -0,0 +1,18 @@
[theme]
inherit = basic
stylesheet = css/theme.css
pygments_style = default
[options]
canonical_url =
analytics_id =
collapse_navigation = False
sticky_navigation = True
navigation_depth = 4
includehidden = True
titles_only =
logo_only =
display_version = True
prev_next_buttons_location = bottom
style_external_links = False
vcs_pageview_mode =

View file

@ -0,0 +1,37 @@
{% if READTHEDOCS %}
{# Add rst-badge after rst-versions for small badge style. #}
<div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="versions">
<span class="rst-current-version" data-toggle="rst-current-version">
<span class="fa fa-book"> Read the Docs</span>
v: {{ current_version }}
<span class="fa fa-caret-down"></span>
</span>
<div class="rst-other-versions">
<dl>
<dt>{{ _('Versions') }}</dt>
{% for slug, url in versions %}
<dd><a href="{{ url }}">{{ slug }}</a></dd>
{% endfor %}
</dl>
<dl>
<dt>{{ _('Downloads') }}</dt>
{% for type, url in downloads %}
<dd><a href="{{ url }}">{{ type }}</a></dd>
{% endfor %}
</dl>
<dl>
<dt>{{ _('On Read the Docs') }}</dt>
<dd>
<a href="//{{ PRODUCTION_DOMAIN }}/projects/{{ slug }}/?fromdocs={{ slug }}">{{ _('Project Home') }}</a>
</dd>
<dd>
<a href="//{{ PRODUCTION_DOMAIN }}/builds/{{ slug }}/?fromdocs={{ slug }}">{{ _('Builds') }}</a>
</dd>
</dl>
<hr/>
{% trans %}Free document hosting provided by <a href="http://www.readthedocs.org">Read the Docs</a>.{% endtrans %}
</div>
</div>
{% endif %}

View file

@ -171,7 +171,7 @@
</div>
<div id="menu-id" class="wy-menu wy-menu-vertical" data-spy="affix">
{% set toctree = toctree(maxdepth=2, collapse=False) %}
{% set toctree = toctree(maxdepth=4, collapse=True) %}
{% if toctree %}
{{ toctree }}
{% else %}

File diff suppressed because one or more lines are too long

View file

@ -1,3 +1,4 @@
* {
-webkit-box-sizing: border-box;
-moz-box-sizing: border-box;
@ -3084,7 +3085,7 @@ li.wy-form-gallery-edit .arrow {
}
.wy-table caption, .rst-content table.docutils caption, .rst-content table.field-list caption {
color: #000;
color: #fff;
font: italic 85%/1 arial, sans-serif;
padding: 1em 0;
text-align: center;
@ -4004,6 +4005,7 @@ pre.literal-block {
background-image: url(data:image/png;
base64, iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWFnZVJlYWR5ccllPAAAAyRpVFh0WE1MOmNvbS5hZG9iZS54bXAAAAAAADw/eHBhY2tldCBiZWdpbj0i77u/IiBpZD0iVzVNME1wQ2VoaUh6cmVTek5UY3prYzlkIj8+IDx4OnhtcG1ldGEgeG1sbnM6eD0iYWRvYmU6bnM6bWV0YS8iIHg6eG1wdGs9IkFkb2JlIFhNUCBDb3JlIDUuMy1jMDExIDY2LjE0NTY2MSwgMjAxMi8wMi8wNi0xNDo1NjoyNyAgICAgICAgIj4gPHJkZjpSREYgeG1sbnM6cmRmPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5LzAyLzIyLXJkZi1zeW50YXgtbnMjIj4gPHJkZjpEZXNjcmlwdGlvbiByZGY6YWJvdXQ9IiIgeG1sbnM6eG1wPSJodHRwOi8vbnMuYWRvYmUuY29tL3hhcC8xLjAvIiB4bWxuczp4bXBNTT0iaHR0cDovL25zLmFkb2JlLmNvbS94YXAvMS4wL21tLyIgeG1sbnM6c3RSZWY9Imh0dHA6Ly9ucy5hZG9iZS5jb20veGFwLzEuMC9zVHlwZS9SZXNvdXJjZVJlZiMiIHhtcDpDcmVhdG9yVG9vbD0iQWRvYmUgUGhvdG9zaG9wIENTNiAoTWFjaW50b3NoKSIgeG1wTU06SW5zdGFuY2VJRD0ieG1wLmlpZDoxOERBMTRGRDBFMUUxMUUzODUwMkJCOThDMEVFNURFMCIgeG1wTU06RG9jdW1lbnRJRD0ieG1wLmRpZDoxOERBMTRGRTBFMUUxMUUzODUwMkJCOThDMEVFNURFMCI+IDx4bXBNTTpEZXJpdmVkRnJvbSBzdFJlZjppbnN0YW5jZUlEPSJ4bXAuaWlkOjE4REExNEZCMEUxRTExRTM4NTAyQkI5OEMwRUU1REUwIiBzdFJlZjpkb2N1bWVudElEPSJ4bXAuZGlkOjE4REExNEZDMEUxRTExRTM4NTAyQkI5OEMwRUU1REUwIi8+IDwvcmRmOkRlc2NyaXB0aW9uPiA8L3JkZjpSREY+IDwveDp4bXBtZXRhPiA8P3hwYWNrZXQgZW5kPSJyIj8+EwrlwAAAAA5JREFUeNpiMDU0BAgwAAE2AJgB9BnaAAAAAElFTkSuQmCC);
background-size: 300px 1px;
color: #lightgrey;
}
.wy-grid-for-nav {
@ -4914,4 +4916,24 @@ table {
.documentation-table {
border-right: 1px solid #000;
border-bottom: 1px solid #000;
}
}
.caption {
line-height: 24px;
margin: 0;
font-size: 16px;
margin-bottom: 0px;
margin-left: 4px;
color: cornflowerblue;
}
.toctree-l2 {
margin-left: 16px;
}
.toctree-l3 {
margin-left: 24px;
}
@import "sphinxrtd.css";

Binary file not shown.

Before

Width:  |  Height:  |  Size: 6.4 KiB

View file

@ -0,0 +1,152 @@
.. _ansible-config:
==============
ansible-config
==============
:strong:`View, edit, and manage ansible configuration.`
.. contents::
:local:
:depth: 2
.. program:: ansible-config
Synopsis
========
.. code-block:: bash
ansible-config [view|dump|list] [--help] [options] [ansible.cfg]
Description
===========
Config command line class
Common Options
==============
.. option:: --version
show program's version number and exit
.. option:: -c <CONFIG_FILE>, --config <CONFIG_FILE>
path to configuration file, defaults to first file found in precedence.
.. option:: -h, --help
show this help message and exit
.. option:: -v, --verbose
verbose mode (-vvv for more, -vvvv to enable connection debugging)
Actions
=======
.. program:: ansible-config list
.. _ansible_config_list:
list
----
list all current configs reading lib/constants.py and shows env and config file setting names
.. program:: ansible-config dump
.. _ansible_config_dump:
dump
----
Shows the current settings, merges ansible.cfg if specified
.. option:: --only-changed
Only show configurations that have changed from the default
.. program:: ansible-config view
.. _ansible_config_view:
view
----
Displays the current config file
.. program:: ansible-config
Environment
===========
The following environment variables may be specified.
:envvar:`ANSIBLE_CONFIG` -- Override the default ansible config file
Many more are available for most options in ansible.cfg
Files
=====
:file:`/etc/ansible/ansible.cfg` -- Config file, used if present
:file:`~/.ansible.cfg` -- User config file, overrides the default config if present
Author
======
Ansible was originally written by Michael DeHaan.
See the `AUTHORS` file for a complete list of contributors.
Copyright
=========
Copyright © 2017 Red Hat, Inc | Ansible.
Ansible is released under the terms of the GPLv3 License.
See also
========
:manpage:`ansible(1)`, :manpage:`ansible-config(1)`, :manpage:`ansible-console(1)`, :manpage:`ansible-doc(1)`, :manpage:`ansible-galaxy(1)`, :manpage:`ansible-inventory(1)`, :manpage:`ansible-playbook(1)`, :manpage:`ansible-pull(1)`, :manpage:`ansible-vault(1)`,

View file

@ -0,0 +1,257 @@
.. _ansible-console:
===============
ansible-console
===============
:strong:`REPL console for executing Ansible tasks.`
.. contents::
:local:
:depth: 2
.. program:: ansible-console
Synopsis
========
.. code-block:: bash
ansible-console [<host-pattern>] [options]
Description
===========
a REPL that allows for running ad-hoc tasks against a chosen inventory (based on dominis' ansible-shell).
Common Options
==============
.. option:: --ask-su-pass
ask for su password (deprecated, use become)
.. option:: --ask-sudo-pass
ask for sudo password (deprecated, use become)
.. option:: --ask-vault-pass
ask for vault password
.. option:: --become-method <BECOME_METHOD>
privilege escalation method to use (default=sudo), valid choices: [ sudo | su | pbrun | pfexec | doas | dzdo | ksu | runas | pmrun | enable ]
.. option:: --become-user <BECOME_USER>
run operations as this user (default=root)
.. option:: --list-hosts
outputs a list of matching hosts; does not execute anything else
.. option:: --playbook-dir <BASEDIR>
Since this tool does not use playbooks, use this as a subsitute playbook directory.This sets the relative path for many features including roles/ group_vars/ etc.
.. option:: --private-key, --key-file
use this file to authenticate the connection
.. option:: --scp-extra-args <SCP_EXTRA_ARGS>
specify extra arguments to pass to scp only (e.g. -l)
.. option:: --sftp-extra-args <SFTP_EXTRA_ARGS>
specify extra arguments to pass to sftp only (e.g. -f, -l)
.. option:: --ssh-common-args <SSH_COMMON_ARGS>
specify common arguments to pass to sftp/scp/ssh (e.g. ProxyCommand)
.. option:: --ssh-extra-args <SSH_EXTRA_ARGS>
specify extra arguments to pass to ssh only (e.g. -R)
.. option:: --step
one-step-at-a-time: confirm each task before running
.. option:: --syntax-check
perform a syntax check on the playbook, but do not execute it
.. option:: --vault-id
the vault identity to use
.. option:: --vault-password-file
vault password file
.. option:: --version
show program's version number and exit
.. option:: -C, --check
don't make any changes; instead, try to predict some of the changes that may occur
.. option:: -D, --diff
when changing (small) files and templates, show the differences in those files; works great with --check
.. option:: -K, --ask-become-pass
ask for privilege escalation password
.. option:: -M, --module-path
prepend colon-separated path(s) to module library (default=[u'/Users/sbutler/.ansible/plugins/modules', u'/usr/share/ansible/plugins/modules'])
.. option:: -R <SU_USER>, --su-user <SU_USER>
run operations with su as this user (default=None) (deprecated, use become)
.. option:: -S, --su
run operations with su (deprecated, use become)
.. option:: -T <TIMEOUT>, --timeout <TIMEOUT>
override the connection timeout in seconds (default=10)
.. option:: -U <SUDO_USER>, --sudo-user <SUDO_USER>
desired sudo user (default=root) (deprecated, use become)
.. option:: -b, --become
run operations with become (does not imply password prompting)
.. option:: -c <CONNECTION>, --connection <CONNECTION>
connection type to use (default=smart)
.. option:: -f <FORKS>, --forks <FORKS>
specify number of parallel processes to use (default=5)
.. option:: -h, --help
show this help message and exit
.. option:: -i, --inventory, --inventory-file
specify inventory host path or comma separated host list. --inventory-file is deprecated
.. option:: -k, --ask-pass
ask for connection password
.. option:: -l <SUBSET>, --limit <SUBSET>
further limit selected hosts to an additional pattern
.. option:: -s, --sudo
run operations with sudo (nopasswd) (deprecated, use become)
.. option:: -u <REMOTE_USER>, --user <REMOTE_USER>
connect as this user (default=None)
.. option:: -v, --verbose
verbose mode (-vvv for more, -vvvv to enable connection debugging)
Environment
===========
The following environment variables may be specified.
:envvar:`ANSIBLE_CONFIG` -- Override the default ansible config file
Many more are available for most options in ansible.cfg
Files
=====
:file:`/etc/ansible/ansible.cfg` -- Config file, used if present
:file:`~/.ansible.cfg` -- User config file, overrides the default config if present
Author
======
Ansible was originally written by Michael DeHaan.
See the `AUTHORS` file for a complete list of contributors.
Copyright
=========
Copyright © 2017 Red Hat, Inc | Ansible.
Ansible is released under the terms of the GPLv3 License.
See also
========
:manpage:`ansible(1)`, :manpage:`ansible-config(1)`, :manpage:`ansible-console(1)`, :manpage:`ansible-doc(1)`, :manpage:`ansible-galaxy(1)`, :manpage:`ansible-inventory(1)`, :manpage:`ansible-playbook(1)`, :manpage:`ansible-pull(1)`, :manpage:`ansible-vault(1)`,

View file

@ -0,0 +1,130 @@
.. _ansible-doc:
===========
ansible-doc
===========
:strong:`plugin documentation tool`
.. contents::
:local:
:depth: 2
.. program:: ansible-doc
Synopsis
========
.. code-block:: bash
ansible-doc [-l|-F|-s] [options] [-t <plugin type> ] [plugin]
Description
===========
displays information on modules installed in Ansible libraries.
It displays a terse listing of plugins and their short descriptions,
provides a printout of their DOCUMENTATION strings,
and it can create a short "snippet" which can be pasted into a playbook.
Common Options
==============
.. option:: --version
show program's version number and exit
.. option:: -F, --list_files
Show plugin names and their source files without summaries (implies --list)
.. option:: -M, --module-path
prepend colon-separated path(s) to module library (default=[u'/Users/sbutler/.ansible/plugins/modules', u'/usr/share/ansible/plugins/modules'])
.. option:: -a, --all
**For internal testing only** Show documentation for all plugins.
.. option:: -h, --help
show this help message and exit
.. option:: -l, --list
List available plugins
.. option:: -s, --snippet
Show playbook snippet for specified plugin(s)
.. option:: -t <TYPE>, --type <TYPE>
Choose which plugin type (defaults to "module")
.. option:: -v, --verbose
verbose mode (-vvv for more, -vvvv to enable connection debugging)
Environment
===========
The following environment variables may be specified.
:envvar:`ANSIBLE_CONFIG` -- Override the default ansible config file
Many more are available for most options in ansible.cfg
Files
=====
:file:`/etc/ansible/ansible.cfg` -- Config file, used if present
:file:`~/.ansible.cfg` -- User config file, overrides the default config if present
Author
======
Ansible was originally written by Michael DeHaan.
See the `AUTHORS` file for a complete list of contributors.
Copyright
=========
Copyright © 2017 Red Hat, Inc | Ansible.
Ansible is released under the terms of the GPLv3 License.
See also
========
:manpage:`ansible(1)`, :manpage:`ansible-config(1)`, :manpage:`ansible-console(1)`, :manpage:`ansible-doc(1)`, :manpage:`ansible-galaxy(1)`, :manpage:`ansible-inventory(1)`, :manpage:`ansible-playbook(1)`, :manpage:`ansible-pull(1)`, :manpage:`ansible-vault(1)`,

View file

@ -0,0 +1,380 @@
.. _ansible-galaxy:
==============
ansible-galaxy
==============
:strong:`None`
.. contents::
:local:
:depth: 2
.. program:: ansible-galaxy
Synopsis
========
.. code-block:: bash
ansible-galaxy [delete|import|info|init|install|list|login|remove|search|setup] [--help] [options] ...
Description
===========
command to manage Ansible roles in shared repostories, the default of which is Ansible Galaxy *https://galaxy.ansible.com*.
Common Options
==============
.. option:: --list
List all of your integrations.
.. option:: --remove <REMOVE_ID>
Remove the integration matching the provided ID value. Use --list to see ID values.
.. option:: --version
show program's version number and exit
.. option:: -c, --ignore-certs
Ignore SSL certificate validation errors.
.. option:: -h, --help
show this help message and exit
.. option:: -s <API_SERVER>, --server <API_SERVER>
The API server destination
.. option:: -v, --verbose
verbose mode (-vvv for more, -vvvv to enable connection debugging)
Actions
=======
.. program:: ansible-galaxy info
.. _ansible_galaxy_info:
info
----
prints out detailed information about an installed role as well as info available from the galaxy API.
.. option:: --offline
Don't query the galaxy API when creating roles
.. option:: -p , --roles-path
The path to the directory containing your roles. The default is the roles_path configured in your ansible.cfgfile (/etc/ansible/roles if not configured)
.. program:: ansible-galaxy search
.. _ansible_galaxy_search:
search
------
searches for roles on the Ansible Galaxy server
.. option:: --author <AUTHOR>
GitHub username
.. option:: --galaxy-tags <GALAXY_TAGS>
list of galaxy tags to filter by
.. option:: --platforms <PLATFORMS>
list of OS platforms to filter by
.. option:: -p , --roles-path
The path to the directory containing your roles. The default is the roles_path configured in your ansible.cfgfile (/etc/ansible/roles if not configured)
.. program:: ansible-galaxy setup
.. _ansible_galaxy_setup:
setup
-----
Setup an integration from Github or Travis for Ansible Galaxy roles
.. option:: --list
List all of your integrations.
.. option:: --remove <REMOVE_ID>
Remove the integration matching the provided ID value. Use --list to see ID values.
.. program:: ansible-galaxy list
.. _ansible_galaxy_list:
list
----
lists the roles installed on the local system or matches a single role passed as an argument.
.. option:: -p , --roles-path
The path to the directory containing your roles. The default is the roles_path configured in your ansible.cfgfile (/etc/ansible/roles if not configured)
.. program:: ansible-galaxy remove
.. _ansible_galaxy_remove:
remove
------
removes the list of roles passed as arguments from the local system.
.. option:: -p , --roles-path
The path to the directory containing your roles. The default is the roles_path configured in your ansible.cfgfile (/etc/ansible/roles if not configured)
.. program:: ansible-galaxy init
.. _ansible_galaxy_init:
init
----
creates the skeleton framework of a role that complies with the galaxy metadata format.
.. option:: --container-enabled
Initialize the skeleton role with default contents for a Container Enabled role.
.. option:: --init-path <INIT_PATH>
The path in which the skeleton role will be created. The default is the current working directory.
.. option:: --offline
Don't query the galaxy API when creating roles
.. option:: --role-skeleton <ROLE_SKELETON>
The path to a role skeleton that the new role should be based upon.
.. option:: -f , --force
Force overwriting an existing role
.. program:: ansible-galaxy install
.. _ansible_galaxy_install:
install
-------
uses the args list of roles to be installed, unless -f was specified. The list of roles
can be a name (which will be downloaded via the galaxy API and github), or it can be a local .tar.gz file.
.. option:: -f , --force
Force overwriting an existing role
.. option:: -i , --ignore-errors
Ignore errors and continue with the next specified role.
.. option:: -n , --no-deps
Don't download roles listed as dependencies
.. option:: -p , --roles-path
The path to the directory containing your roles. The default is the roles_path configured in your ansible.cfgfile (/etc/ansible/roles if not configured)
.. option:: -r <ROLE_FILE>, --role-file <ROLE_FILE>
A file containing a list of roles to be imported
.. program:: ansible-galaxy import
.. _ansible_galaxy_import:
import
------
used to import a role into Ansible Galaxy
.. option:: --branch <REFERENCE>
The name of a branch to import. Defaults to the repository's default branch (usually master)
.. option:: --no-wait
Don't wait for import results.
.. option:: --role-name <ROLE_NAME>
The name the role should have, if different than the repo name
.. option:: --status
Check the status of the most recent import request for given github_user/github_repo.
.. program:: ansible-galaxy login
.. _ansible_galaxy_login:
login
-----
verify user's identify via Github and retrieve an auth token from Ansible Galaxy.
.. option:: --github-token <TOKEN>
Identify with github token rather than username and password.
.. program:: ansible-galaxy delete
.. _ansible_galaxy_delete:
delete
------
Delete a role from Ansible Galaxy.
.. program:: ansible-galaxy
Environment
===========
The following environment variables may be specified.
:envvar:`ANSIBLE_CONFIG` -- Override the default ansible config file
Many more are available for most options in ansible.cfg
Files
=====
:file:`/etc/ansible/ansible.cfg` -- Config file, used if present
:file:`~/.ansible.cfg` -- User config file, overrides the default config if present
Author
======
Ansible was originally written by Michael DeHaan.
See the `AUTHORS` file for a complete list of contributors.
Copyright
=========
Copyright © 2017 Red Hat, Inc | Ansible.
Ansible is released under the terms of the GPLv3 License.
See also
========
:manpage:`ansible(1)`, :manpage:`ansible-config(1)`, :manpage:`ansible-console(1)`, :manpage:`ansible-doc(1)`, :manpage:`ansible-galaxy(1)`, :manpage:`ansible-inventory(1)`, :manpage:`ansible-playbook(1)`, :manpage:`ansible-pull(1)`, :manpage:`ansible-vault(1)`,

View file

@ -0,0 +1,157 @@
.. _ansible-inventory:
=================
ansible-inventory
=================
:strong:`None`
.. contents::
:local:
:depth: 2
.. program:: ansible-inventory
Synopsis
========
.. code-block:: bash
ansible-inventory [options] [host|group]
Description
===========
used to display or dump the configured inventory as Ansible sees it
Common Options
==============
.. option:: --ask-vault-pass
ask for vault password
.. option:: --graph
create inventory graph, if supplying pattern it must be a valid group name
.. option:: --host <HOST>
Output specific host info, works as inventory script
.. option:: --list
Output all hosts info, works as inventory script
.. option:: --list-hosts
outputs a list of matching hosts; does not execute anything else
.. option:: --playbook-dir <BASEDIR>
Since this tool does not use playbooks, use this as a subsitute playbook directory.This sets the relative path for many features including roles/ group_vars/ etc.
.. option:: --vars
Add vars to graph display, ignored unless used with --graph
.. option:: --vault-id
the vault identity to use
.. option:: --vault-password-file
vault password file
.. option:: --version
show program's version number and exit
.. option:: -h, --help
show this help message and exit
.. option:: -i, --inventory, --inventory-file
specify inventory host path or comma separated host list. --inventory-file is deprecated
.. option:: -l <SUBSET>, --limit <SUBSET>
further limit selected hosts to an additional pattern
.. option:: -v, --verbose
verbose mode (-vvv for more, -vvvv to enable connection debugging)
.. option:: -y, --yaml
Use YAML format instead of default JSON, ignored for --graph
Environment
===========
The following environment variables may be specified.
:envvar:`ANSIBLE_CONFIG` -- Override the default ansible config file
Many more are available for most options in ansible.cfg
Files
=====
:file:`/etc/ansible/ansible.cfg` -- Config file, used if present
:file:`~/.ansible.cfg` -- User config file, overrides the default config if present
Author
======
Ansible was originally written by Michael DeHaan.
See the `AUTHORS` file for a complete list of contributors.
Copyright
=========
Copyright © 2017 Red Hat, Inc | Ansible.
Ansible is released under the terms of the GPLv3 License.
See also
========
:manpage:`ansible(1)`, :manpage:`ansible-config(1)`, :manpage:`ansible-console(1)`, :manpage:`ansible-doc(1)`, :manpage:`ansible-galaxy(1)`, :manpage:`ansible-inventory(1)`, :manpage:`ansible-playbook(1)`, :manpage:`ansible-pull(1)`, :manpage:`ansible-vault(1)`,

View file

@ -0,0 +1,293 @@
.. _ansible-playbook:
================
ansible-playbook
================
:strong:`Runs Ansible playbooks, executing the defined tasks on the targeted hosts.`
.. contents::
:local:
:depth: 2
.. program:: ansible-playbook
Synopsis
========
.. code-block:: bash
ansible-playbook [options] playbook.yml [playbook2 ...]
Description
===========
the tool to run *Ansible playbooks*, which are a configuration and multinode deployment system.
See the project home page (https://docs.ansible.com) for more information.
Common Options
==============
.. option:: --ask-su-pass
ask for su password (deprecated, use become)
.. option:: --ask-sudo-pass
ask for sudo password (deprecated, use become)
.. option:: --ask-vault-pass
ask for vault password
.. option:: --become-method <BECOME_METHOD>
privilege escalation method to use (default=sudo), valid choices: [ sudo | su | pbrun | pfexec | doas | dzdo | ksu | runas | pmrun | enable ]
.. option:: --become-user <BECOME_USER>
run operations as this user (default=root)
.. option:: --flush-cache
clear the fact cache for every host in inventory
.. option:: --force-handlers
run handlers even if a task fails
.. option:: --list-hosts
outputs a list of matching hosts; does not execute anything else
.. option:: --list-tags
list all available tags
.. option:: --list-tasks
list all tasks that would be executed
.. option:: --private-key, --key-file
use this file to authenticate the connection
.. option:: --scp-extra-args <SCP_EXTRA_ARGS>
specify extra arguments to pass to scp only (e.g. -l)
.. option:: --sftp-extra-args <SFTP_EXTRA_ARGS>
specify extra arguments to pass to sftp only (e.g. -f, -l)
.. option:: --skip-tags
only run plays and tasks whose tags do not match these values
.. option:: --ssh-common-args <SSH_COMMON_ARGS>
specify common arguments to pass to sftp/scp/ssh (e.g. ProxyCommand)
.. option:: --ssh-extra-args <SSH_EXTRA_ARGS>
specify extra arguments to pass to ssh only (e.g. -R)
.. option:: --start-at-task <START_AT_TASK>
start the playbook at the task matching this name
.. option:: --step
one-step-at-a-time: confirm each task before running
.. option:: --syntax-check
perform a syntax check on the playbook, but do not execute it
.. option:: --vault-id
the vault identity to use
.. option:: --vault-password-file
vault password file
.. option:: --version
show program's version number and exit
.. option:: -C, --check
don't make any changes; instead, try to predict some of the changes that may occur
.. option:: -D, --diff
when changing (small) files and templates, show the differences in those files; works great with --check
.. option:: -K, --ask-become-pass
ask for privilege escalation password
.. option:: -M, --module-path
prepend colon-separated path(s) to module library (default=[u'/Users/sbutler/.ansible/plugins/modules', u'/usr/share/ansible/plugins/modules'])
.. option:: -R <SU_USER>, --su-user <SU_USER>
run operations with su as this user (default=None) (deprecated, use become)
.. option:: -S, --su
run operations with su (deprecated, use become)
.. option:: -T <TIMEOUT>, --timeout <TIMEOUT>
override the connection timeout in seconds (default=10)
.. option:: -U <SUDO_USER>, --sudo-user <SUDO_USER>
desired sudo user (default=root) (deprecated, use become)
.. option:: -b, --become
run operations with become (does not imply password prompting)
.. option:: -c <CONNECTION>, --connection <CONNECTION>
connection type to use (default=smart)
.. option:: -e, --extra-vars
set additional variables as key=value or YAML/JSON, if filename prepend with @
.. option:: -f <FORKS>, --forks <FORKS>
specify number of parallel processes to use (default=5)
.. option:: -h, --help
show this help message and exit
.. option:: -i, --inventory, --inventory-file
specify inventory host path or comma separated host list. --inventory-file is deprecated
.. option:: -k, --ask-pass
ask for connection password
.. option:: -l <SUBSET>, --limit <SUBSET>
further limit selected hosts to an additional pattern
.. option:: -s, --sudo
run operations with sudo (nopasswd) (deprecated, use become)
.. option:: -t, --tags
only run plays and tasks tagged with these values
.. option:: -u <REMOTE_USER>, --user <REMOTE_USER>
connect as this user (default=None)
.. option:: -v, --verbose
verbose mode (-vvv for more, -vvvv to enable connection debugging)
Environment
===========
The following environment variables may be specified.
:envvar:`ANSIBLE_CONFIG` -- Override the default ansible config file
Many more are available for most options in ansible.cfg
Files
=====
:file:`/etc/ansible/ansible.cfg` -- Config file, used if present
:file:`~/.ansible.cfg` -- User config file, overrides the default config if present
Author
======
Ansible was originally written by Michael DeHaan.
See the `AUTHORS` file for a complete list of contributors.
Copyright
=========
Copyright © 2017 Red Hat, Inc | Ansible.
Ansible is released under the terms of the GPLv3 License.
See also
========
:manpage:`ansible(1)`, :manpage:`ansible-config(1)`, :manpage:`ansible-console(1)`, :manpage:`ansible-doc(1)`, :manpage:`ansible-galaxy(1)`, :manpage:`ansible-inventory(1)`, :manpage:`ansible-playbook(1)`, :manpage:`ansible-pull(1)`, :manpage:`ansible-vault(1)`,

View file

@ -0,0 +1,285 @@
.. _ansible-pull:
============
ansible-pull
============
:strong:`pulls playbooks from a VCS repo and executes them for the local host`
.. contents::
:local:
:depth: 2
.. program:: ansible-pull
Synopsis
========
.. code-block:: bash
ansible-pull -U <repository> [options] [<playbook.yml>]
Description
===========
is used to up a remote copy of ansible on each managed node,
each set to run via cron and update playbook source via a source repository.
This inverts the default *push* architecture of ansible into a *pull* architecture,
which has near-limitless scaling potential.
The setup playbook can be tuned to change the cron frequency, logging locations, and parameters to ansible-pull.
This is useful both for extreme scale-out as well as periodic remediation.
Usage of the 'fetch' module to retrieve logs from ansible-pull runs would be an
excellent way to gather and analyze remote logs from ansible-pull.
Common Options
==============
.. option:: --accept-host-key
adds the hostkey for the repo url if not already added
.. option:: --ask-su-pass
ask for su password (deprecated, use become)
.. option:: --ask-sudo-pass
ask for sudo password (deprecated, use become)
.. option:: --ask-vault-pass
ask for vault password
.. option:: --check
don't make any changes; instead, try to predict some of the changes that may occur
.. option:: --clean
modified files in the working repository will be discarded
.. option:: --full
Do a full clone, instead of a shallow one.
.. option:: --list-hosts
outputs a list of matching hosts; does not execute anything else
.. option:: --private-key, --key-file
use this file to authenticate the connection
.. option:: --purge
purge checkout after playbook run
.. option:: --scp-extra-args <SCP_EXTRA_ARGS>
specify extra arguments to pass to scp only (e.g. -l)
.. option:: --sftp-extra-args <SFTP_EXTRA_ARGS>
specify extra arguments to pass to sftp only (e.g. -f, -l)
.. option:: --skip-tags
only run plays and tasks whose tags do not match these values
.. option:: --ssh-common-args <SSH_COMMON_ARGS>
specify common arguments to pass to sftp/scp/ssh (e.g. ProxyCommand)
.. option:: --ssh-extra-args <SSH_EXTRA_ARGS>
specify extra arguments to pass to ssh only (e.g. -R)
.. option:: --track-subs
submodules will track the latest changes. This is equivalent to specifying the --remote flag to git submodule update
.. option:: --vault-id
the vault identity to use
.. option:: --vault-password-file
vault password file
.. option:: --verify-commit
verify GPG signature of checked out commit, if it fails abort running the playbook. This needs the corresponding VCS module to support such an operation
.. option:: --version
show program's version number and exit
.. option:: -C <CHECKOUT>, --checkout <CHECKOUT>
branch/tag/commit to checkout. Defaults to behavior of repository module.
.. option:: -K, --ask-become-pass
ask for privilege escalation password
.. option:: -M, --module-path
prepend colon-separated path(s) to module library (default=[u'/Users/sbutler/.ansible/plugins/modules', u'/usr/share/ansible/plugins/modules'])
.. option:: -T <TIMEOUT>, --timeout <TIMEOUT>
override the connection timeout in seconds (default=10)
.. option:: -U <URL>, --url <URL>
URL of the playbook repository
.. option:: -c <CONNECTION>, --connection <CONNECTION>
connection type to use (default=smart)
.. option:: -d <DEST>, --directory <DEST>
directory to checkout repository to
.. option:: -e, --extra-vars
set additional variables as key=value or YAML/JSON, if filename prepend with @
.. option:: -f, --force
run the playbook even if the repository could not be updated
.. option:: -h, --help
show this help message and exit
.. option:: -i, --inventory, --inventory-file
specify inventory host path or comma separated host list. --inventory-file is deprecated
.. option:: -k, --ask-pass
ask for connection password
.. option:: -l <SUBSET>, --limit <SUBSET>
further limit selected hosts to an additional pattern
.. option:: -m <MODULE_NAME>, --module-name <MODULE_NAME>
Repository module name, which ansible will use to check out the repo. Choices are ('git', 'subversion', 'hg', 'bzr'). Default is git.
.. option:: -o, --only-if-changed
only run the playbook if the repository has been updated
.. option:: -s <SLEEP>, --sleep <SLEEP>
sleep for random interval (between 0 and n number of seconds) before starting. This is a useful way to disperse git requests
.. option:: -t, --tags
only run plays and tasks tagged with these values
.. option:: -u <REMOTE_USER>, --user <REMOTE_USER>
connect as this user (default=None)
.. option:: -v, --verbose
verbose mode (-vvv for more, -vvvv to enable connection debugging)
Environment
===========
The following environment variables may be specified.
:envvar:`ANSIBLE_CONFIG` -- Override the default ansible config file
Many more are available for most options in ansible.cfg
Files
=====
:file:`/etc/ansible/ansible.cfg` -- Config file, used if present
:file:`~/.ansible.cfg` -- User config file, overrides the default config if present
Author
======
Ansible was originally written by Michael DeHaan.
See the `AUTHORS` file for a complete list of contributors.
Copyright
=========
Copyright © 2017 Red Hat, Inc | Ansible.
Ansible is released under the terms of the GPLv3 License.
See also
========
:manpage:`ansible(1)`, :manpage:`ansible-config(1)`, :manpage:`ansible-console(1)`, :manpage:`ansible-doc(1)`, :manpage:`ansible-galaxy(1)`, :manpage:`ansible-inventory(1)`, :manpage:`ansible-playbook(1)`, :manpage:`ansible-pull(1)`, :manpage:`ansible-vault(1)`,

View file

@ -0,0 +1,281 @@
.. _ansible-vault:
=============
ansible-vault
=============
:strong:`encryption/decryption utility for Ansible data files`
.. contents::
:local:
:depth: 2
.. program:: ansible-vault
Synopsis
========
.. code-block:: bash
ansible-vault [create|decrypt|edit|encrypt|encrypt_string|rekey|view] [options] [vaultfile.yml]
Description
===========
can encrypt any structured data file used by Ansible.
This can include *group_vars/* or *host_vars/* inventory variables,
variables loaded by *include_vars* or *vars_files*, or variable files
passed on the ansible-playbook command line with *-e @file.yml* or *-e @file.json*.
Role variables and defaults are also included!
Because Ansible tasks, handlers, and other objects are data, these can also be encrypted with vault.
If you'd like to not expose what variables you are using, you can keep an individual task file entirely encrypted.
The password used with vault currently must be the same for all files you wish to use together at the same time.
Common Options
==============
.. option:: --ask-vault-pass
ask for vault password
.. option:: --new-vault-id <NEW_VAULT_ID>
the new vault identity to use for rekey
.. option:: --new-vault-password-file
new vault password file for rekey
.. option:: --vault-id
the vault identity to use
.. option:: --vault-password-file
vault password file
.. option:: --version
show program's version number and exit
.. option:: -h, --help
show this help message and exit
.. option:: -v, --verbose
verbose mode (-vvv for more, -vvvv to enable connection debugging)
Actions
=======
.. program:: ansible-vault encrypt
.. _ansible_vault_encrypt:
encrypt
-------
encrypt the supplied file using the provided vault secret
.. option:: --encrypt-vault-id <ENCRYPT_VAULT_ID>
the vault id used to encrypt (required if more than vault-id is provided)
.. option:: --output
output file name for encrypt or decrypt; use - for stdout
.. program:: ansible-vault rekey
.. _ansible_vault_rekey:
rekey
-----
re-encrypt a vaulted file with a new secret, the previous secret is required
.. option:: --encrypt-vault-id <ENCRYPT_VAULT_ID>
the vault id used to encrypt (required if more than vault-id is provided)
.. program:: ansible-vault encrypt_string
.. _ansible_vault_encrypt_string:
encrypt_string
--------------
encrypt the supplied string using the provided vault secret
.. option:: --encrypt-vault-id <ENCRYPT_VAULT_ID>
the vault id used to encrypt (required if more than vault-id is provided)
.. option:: --output
output file name for encrypt or decrypt; use - for stdout
.. option:: --stdin-name <ENCRYPT_STRING_STDIN_NAME>
Specify the variable name for stdin
.. option:: -n , --name
Specify the variable name
.. option:: -p , --prompt
Prompt for the string to encrypt
.. program:: ansible-vault edit
.. _ansible_vault_edit:
edit
----
open and decrypt an existing vaulted file in an editor, that will be encryped again when closed
.. program:: ansible-vault create
.. _ansible_vault_create:
create
------
create and open a file in an editor that will be encryped with the provided vault secret when closed
.. option:: --encrypt-vault-id <ENCRYPT_VAULT_ID>
the vault id used to encrypt (required if more than vault-id is provided)
.. program:: ansible-vault decrypt
.. _ansible_vault_decrypt:
decrypt
-------
decrypt the supplied file using the provided vault secret
.. option:: --output
output file name for encrypt or decrypt; use - for stdout
.. program:: ansible-vault view
.. _ansible_vault_view:
view
----
open, decrypt and view an existing vaulted file using a pager using the supplied vault secret
.. program:: ansible-vault
Environment
===========
The following environment variables may be specified.
:envvar:`ANSIBLE_CONFIG` -- Override the default ansible config file
Many more are available for most options in ansible.cfg
Files
=====
:file:`/etc/ansible/ansible.cfg` -- Config file, used if present
:file:`~/.ansible.cfg` -- User config file, overrides the default config if present
Author
======
Ansible was originally written by Michael DeHaan.
See the `AUTHORS` file for a complete list of contributors.
Copyright
=========
Copyright © 2017 Red Hat, Inc | Ansible.
Ansible is released under the terms of the GPLv3 License.
See also
========
:manpage:`ansible(1)`, :manpage:`ansible-config(1)`, :manpage:`ansible-console(1)`, :manpage:`ansible-doc(1)`, :manpage:`ansible-galaxy(1)`, :manpage:`ansible-inventory(1)`, :manpage:`ansible-playbook(1)`, :manpage:`ansible-pull(1)`, :manpage:`ansible-vault(1)`,

View file

@ -0,0 +1,288 @@
.. _ansible:
=======
ansible
=======
:strong:`Define and run a single task 'playbook' against a set of hosts`
.. contents::
:local:
:depth: 2
.. program:: ansible
Synopsis
========
.. code-block:: bash
ansible <host-pattern> [options]
Description
===========
is an extra-simple tool/framework/API for doing 'remote things'.
this command allows you to define and run a single task 'playbook' against a set of hosts
Common Options
==============
.. option:: --ask-su-pass
ask for su password (deprecated, use become)
.. option:: --ask-sudo-pass
ask for sudo password (deprecated, use become)
.. option:: --ask-vault-pass
ask for vault password
.. option:: --become-method <BECOME_METHOD>
privilege escalation method to use (default=sudo), valid choices: [ sudo | su | pbrun | pfexec | doas | dzdo | ksu | runas | pmrun | enable ]
.. option:: --become-user <BECOME_USER>
run operations as this user (default=root)
.. option:: --list-hosts
outputs a list of matching hosts; does not execute anything else
.. option:: --playbook-dir <BASEDIR>
Since this tool does not use playbooks, use this as a subsitute playbook directory.This sets the relative path for many features including roles/ group_vars/ etc.
.. option:: --private-key, --key-file
use this file to authenticate the connection
.. option:: --scp-extra-args <SCP_EXTRA_ARGS>
specify extra arguments to pass to scp only (e.g. -l)
.. option:: --sftp-extra-args <SFTP_EXTRA_ARGS>
specify extra arguments to pass to sftp only (e.g. -f, -l)
.. option:: --ssh-common-args <SSH_COMMON_ARGS>
specify common arguments to pass to sftp/scp/ssh (e.g. ProxyCommand)
.. option:: --ssh-extra-args <SSH_EXTRA_ARGS>
specify extra arguments to pass to ssh only (e.g. -R)
.. option:: --syntax-check
perform a syntax check on the playbook, but do not execute it
.. option:: --vault-id
the vault identity to use
.. option:: --vault-password-file
vault password file
.. option:: --version
show program's version number and exit
.. option:: -B <SECONDS>, --background <SECONDS>
run asynchronously, failing after X seconds (default=N/A)
.. option:: -C, --check
don't make any changes; instead, try to predict some of the changes that may occur
.. option:: -D, --diff
when changing (small) files and templates, show the differences in those files; works great with --check
.. option:: -K, --ask-become-pass
ask for privilege escalation password
.. option:: -M, --module-path
prepend colon-separated path(s) to module library (default=[u'/Users/sbutler/.ansible/plugins/modules', u'/usr/share/ansible/plugins/modules'])
.. option:: -P <POLL_INTERVAL>, --poll <POLL_INTERVAL>
set the poll interval if using -B (default=15)
.. option:: -R <SU_USER>, --su-user <SU_USER>
run operations with su as this user (default=None) (deprecated, use become)
.. option:: -S, --su
run operations with su (deprecated, use become)
.. option:: -T <TIMEOUT>, --timeout <TIMEOUT>
override the connection timeout in seconds (default=10)
.. option:: -U <SUDO_USER>, --sudo-user <SUDO_USER>
desired sudo user (default=root) (deprecated, use become)
.. option:: -a <MODULE_ARGS>, --args <MODULE_ARGS>
module arguments
.. option:: -b, --become
run operations with become (does not imply password prompting)
.. option:: -c <CONNECTION>, --connection <CONNECTION>
connection type to use (default=smart)
.. option:: -e, --extra-vars
set additional variables as key=value or YAML/JSON, if filename prepend with @
.. option:: -f <FORKS>, --forks <FORKS>
specify number of parallel processes to use (default=5)
.. option:: -h, --help
show this help message and exit
.. option:: -i, --inventory, --inventory-file
specify inventory host path or comma separated host list. --inventory-file is deprecated
.. option:: -k, --ask-pass
ask for connection password
.. option:: -l <SUBSET>, --limit <SUBSET>
further limit selected hosts to an additional pattern
.. option:: -m <MODULE_NAME>, --module-name <MODULE_NAME>
module name to execute (default=command)
.. option:: -o, --one-line
condense output
.. option:: -s, --sudo
run operations with sudo (nopasswd) (deprecated, use become)
.. option:: -t <TREE>, --tree <TREE>
log output to this directory
.. option:: -u <REMOTE_USER>, --user <REMOTE_USER>
connect as this user (default=None)
.. option:: -v, --verbose
verbose mode (-vvv for more, -vvvv to enable connection debugging)
Environment
===========
The following environment variables may be specified.
:envvar:`ANSIBLE_CONFIG` -- Override the default ansible config file
Many more are available for most options in ansible.cfg
Files
=====
:file:`/etc/ansible/ansible.cfg` -- Config file, used if present
:file:`~/.ansible.cfg` -- User config file, overrides the default config if present
Author
======
Ansible was originally written by Michael DeHaan.
See the `AUTHORS` file for a complete list of contributors.
Copyright
=========
Copyright © 2017 Red Hat, Inc | Ansible.
Ansible is released under the terms of the GPLv3 License.
See also
========
:manpage:`ansible(1)`, :manpage:`ansible-config(1)`, :manpage:`ansible-console(1)`, :manpage:`ansible-doc(1)`, :manpage:`ansible-galaxy(1)`, :manpage:`ansible-inventory(1)`, :manpage:`ansible-playbook(1)`, :manpage:`ansible-pull(1)`, :manpage:`ansible-vault(1)`,

View file

@ -1,11 +0,0 @@
Command Line Tools
==================
Most users are familiar with `ansible` and `ansible-playbook`, but those are not the only utilities Ansible provides.
Below you is a complete list of Ansible utilities. Each page contains a description of the utility and a listing of supported parameters.
.. toctree:: :maxdepth: 1
:glob:
ansible
ansible-*

View file

@ -1,9 +1,6 @@
*********************
Community Information
*********************
***********************
Ansible Community Guide
=======================
***********************
Welcome to the Ansible Community Guide!
@ -13,7 +10,7 @@ To get started, select one of the following topics.
.. toctree::
:maxdepth: 1
:maxdepth: 2
development_process
reporting_bugs_and_features

View file

@ -38,6 +38,7 @@ AUTHOR = 'Ansible, Inc'
# Add any Sphinx extension module names here, as strings.
# They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
# TEST: 'sphinxcontrib.fulltoc'
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx']
# Later on, add 'sphinx.ext.viewcode' to the list if you want to have
@ -55,7 +56,7 @@ master_doc = 'index'
# General substitutions.
project = 'Ansible Documentation'
copyright = "2013-2017 Ansible, Inc"
copyright = "2013-2018 Ansible, Inc"
# The default replacements for |version| and |release|, also used in various
# other places throughout the built documents.
@ -80,7 +81,8 @@ today_fmt = '%B %d, %Y'
# A list of glob-style patterns that should be excluded when looking
# for source files.
exclude_patterns = ['modules']
# OBSOLETE - removing this - dharmabumstead 2018-02-06
# exclude_patterns = ['modules']
# The reST default role (used for this markup: `text`) to use for all
# documents.
@ -122,7 +124,7 @@ rst_epilog = """
# -----------------------
html_theme_path = ['../_themes']
html_theme = 'srtd'
html_theme = 'sphinx_rtd_theme'
html_short_title = 'Ansible Documentation'
# The style sheet to use for HTML and HTML Help pages. A file of that name

View file

@ -71,6 +71,8 @@ How To Develop A Module
The following topics will discuss how to develop and work with modules:
:doc:`developing_program_flow_modules`
A description of Ansible's module architecture.
:doc:`developing_modules_general`
A general overview of how to develop, debug, and test modules.
:doc:`developing_modules_general_windows`

View file

@ -1,8 +1,8 @@
.. _flow_modules:
=======
Modules
=======
===========================
Ansible Module Architecture
===========================
This in-depth dive helps you understand Ansible's program flow to execute
modules. It is written for people working on the portions of the Core Ansible

View file

@ -1,9 +1,6 @@
*********************
Developer Information
*********************
Ansible Developer Guide
=======================
***************
Developer Guide
***************
Welcome to the Ansible Developer Guide!
@ -13,16 +10,10 @@ To get started, select one of the following topics.
.. toctree::
:maxdepth: 1
:maxdepth: 2
overview_architecture
developing_modules
developing_modules_general
developing_modules_general_windows
developing_modules_documenting
developing_modules_best_practices
developing_modules_checklist
developing_modules_in_groups
developing_program_flow_modules
developing_module_utilities
developing_plugins

View file

@ -1,13 +1,12 @@
:tocdepth: 3
Ansible Documentation
=====================
About Ansible
`````````````
Welcome to the Ansible documentation!
Ansible is an IT automation tool. It can configure systems, deploy software, and orchestrate more advanced IT tasks
such as continuous deployments or zero downtime rolling updates.
Ansible is an IT automation tool. It can configure systems, deploy software, and orchestrate more advanced IT tasks such as continuous deployments or zero downtime rolling updates.
Ansible's main goals are simplicity and ease-of-use. It also has a strong focus on security and reliability, featuring a minimum of moving parts, usage of OpenSSH for transport (with other transports and pull modes as alternatives), and a language that is designed around auditability by humans--even those not familiar with the program.
@ -20,32 +19,76 @@ This documentation covers the current released version of Ansible (2.3) and also
Ansible, Inc. releases a new major release of Ansible approximately every two months. The core application evolves somewhat conservatively, valuing simplicity in language design and setup. However, the community around new modules and plugins being developed and contributed moves very quickly, typically adding 20 or so new modules in each release.
.. _an_introduction:
.. toctree::
:maxdepth: 2
:caption: Installation, Upgrade & Configuration
installation_guide/index
porting_guides/porting_guides
.. toctree::
:maxdepth: 3
:caption: Using Ansible
user_guide/index
.. toctree::
:maxdepth: 3
:caption: Contributing to Ansible
intro
quickstart
playbooks
playbooks_special_topics
modules
module_docs/modules_by_category
vault
command_line_tools
plugins_by_category
guides
dev_guide/index
tower
community/index
network
galaxy
test_strategies
faq
config
glossary
YAMLSyntax
porting_guides
python_3_support
release_and_maintenance
windows
.. toctree::
:maxdepth: 3
:caption: Extending Ansible
dev_guide/index
.. toctree::
:maxdepth: 2
:caption: Scenario Guides
networking_guide/network
..scenario_guides/guides
scenario_guides/guide_aws
scenario_guides/guide_azure
scenario_guides/guide_rax
scenario_guides/guide_gce
scenario_guides/guide_cloudstack
scenario_guides/guide_vagrant
scenario_guides/guide_docker
scenario_guides/guide_packet
scenario_guides/guide_rolling_upgrade
.. toctree::
:maxdepth: 2
:caption: Reference & Appendices
reference_appendices/modules_by_category
reference_appendices/playbooks_keywords
reference_appendices/galaxy
reference_appendices/common_return_values
reference_appendices/config
reference_appendices/YAMLSyntax
reference_appendices/python_3_support
reference_appendices/release_and_maintenance
reference_appendices/test_strategies
reference_appendices/faq
reference_appendices/glossary
reference_appendices/tower
.. toctree::
:maxdepth: 2
:caption: Release Notes
.. toctree::
:maxdepth: 2
:caption: Roadmaps
roadmap/ROADMAP_2_1.rst
roadmap/ROADMAP_2_2.rst
roadmap/ROADMAP_2_3.rst
roadmap/ROADMAP_2_4.rst
roadmap/ROADMAP_2_5.rst

View file

@ -0,0 +1,3 @@
.. This is a hack to allow doc references to files in other subdirectories.
.. include:: ../reference_appendices/config.rst

View file

@ -0,0 +1,10 @@
Welcome to the Ansible Installation Guide!
Introductory install guide text here.
.. toctree::
:maxdepth: 2
intro_installation
intro_configuration

View file

@ -1,5 +1,6 @@
Configuration
-------------
*******************
Configuring Ansible
*******************
.. contents:: Topics
@ -10,7 +11,7 @@ This topic describes how to control Ansible settings.
.. _the_configuration_file:
Configuration file
++++++++++++++++++
==================
Certain settings in Ansible are adjustable via a configuration file (ansible.cfg).
The stock configuration should be sufficient for most users, but there may be reasons you would want to change them.
@ -18,7 +19,7 @@ The stock configuration should be sufficient for most users, but there may be re
.. _getting_the_latest_configuration:
Getting the latest configuration
````````````````````````````````
================================
If installing Ansible from a package manager, the latest ansible.cfg file should be present in /etc/ansible, possibly
as a ".rpmnew" file (or other) as appropriate in the case of updates.
@ -28,43 +29,27 @@ default settings in Ansible.
An `example file is available on Github <https://raw.github.com/ansible/ansible/devel/examples/ansible.cfg>`_.
For more details and a full listing of available configurations go to :doc:configuration. Starting with Ansible version 2.4, you can use the :doc:`ansible-config` command line utility to list your available options and inspect the current values.
For more details and a full listing of available configurations go to :ref:`configuration_settings`. Starting with Ansible version 2.4, you can use the :doc:`ansible-config` command line utility to list your available options and inspect the current values.
For in depth details you check out :doc:`config`.
For in-depth details, see :doc:`_config`.
Environmental configuration
+++++++++++++++++++++++++++
===========================
Ansible also allows configuration of settings using environment variables.
If these environment variables are set, they will override any setting loaded from the configuration file.
You can get a full listing of available environment variables from :doc:`config`.
You can get a full listing of available environment variables from :doc:`_config`.
.. _command_line_configuration:
Command line options
++++++++++++++++++++
====================
Not all configuration options are present in the command line, just the ones deemed most useful or common.
Settings in the command line will override those passed through the configuration file and the environment.
The full list of options available is in :doc:`ansible-playbook` and :doc:`ansible`.
The full list of options available is in :ref:`ansible-playbook` and :ref:`ansible`.
.. seealso::
:doc:`intro_dynamic_inventory`
Pulling inventory from dynamic sources, such as cloud providers
:doc:`intro_adhoc`
Examples of basic commands
:doc:`playbooks`
Learning Ansible's configuration, deployment, and orchestration language.
:doc:`config`
Ansible's configuration file and environment settings in detail
:doc:`command_line_tools`
Ansible's command line tools documentation and detailed options
`Mailing List <http://groups.google.com/group/ansible-project>`_
Questions? Help? Ideas? Stop by the list on Google Groups
`irc.freenode.net <http://irc.freenode.net>`_
#ansible IRC chat channel

View file

@ -1,8 +1,9 @@
Installation
============
Installation Guide
==================
.. contents:: Topics
Welcome to the Ansible Installation Guide!
.. _what_will_be_installed:

View file

@ -1,15 +1,21 @@
Ansible Network
=====================
************************
Ansible Networking Guide
************************
Introduction
============
Ansible Network extends the benefits of simple, powerful, agentless automation to network administrators and teams. Ansible Network modules can configure your network stack, test and validate existing network state, and discover and correct network configuration drift.
If you're new to Ansible, or new to using Ansible for network management, start with the Getting Started Guide (under development).
For documentation on using a particular network module, consult the :doc:`list of all network modules<module_docs/list_of_network_modules>`. Some network modules are maintained by the Ansible community - here's a list of :doc:`network modules maintained by the Ansible Network Team<module_docs/network_maintained>`.
.. toctree::
:maxdepth: 1
:maxdepth: 3
network_best_practices_2.5
network_debug_troubleshooting
network_working_with_command_output
For documentation on using a particular network module, consult the :doc:`list of all network modules<module_docs/list_of_network_modules>`. Some network modules are maintained by the Ansible community - here's a list of :doc:`network modules maintained by the Ansible Network Team<module_docs/network_maintained>`.

View file

@ -4,8 +4,6 @@
Network Best Practices for Ansible 2.5
**************************************
.. contents:: Topics
Overview
========

View file

@ -4,7 +4,6 @@
Network Debug and Troubleshooting Guide
***************************************
.. contents:: Topics
Introduction
============

View file

@ -1,5 +1,9 @@
Action Plugins
---------------
==============
.. contents::
:local:
:depth: 2
Action plugins act in conjunction with :doc:`modules <../modules>` to execute the actions required by playbook tasks.
They usually execute automatically in the background doing prerequisite work before modules execute.
@ -9,17 +13,28 @@ The 'normal' action plugin is used for modules that do not already have an actio
.. _enabling_action:
Enabling Action Plugins
+++++++++++++++++++++++
-----------------------
You can enable a custom action plugin by either dropping it into the ``action_plugins`` directory adjacent to your play, inside a role, or by putting it in one of the action plugin directory sources configured in :doc:`ansible.cfg <../config>`.
.. _using_action:
Using Action Plugins
+++++++++++++++++++++
--------------------
Action plugin are executed by default when an associated module is used; no action is required.
Plugin List
-----------
You can use ``ansible-doc -t cache -l`` to see the list of available plugins.
Use ``ansible-doc -t cache <plugin name>`` to see specific documentation and examples.
.. toctree:: :maxdepth: 1
:glob:
action/*
.. seealso::
:doc:`cache`

View file

@ -1,19 +1,28 @@
Plugins
=======
********************
Working With Plugins
********************
Plugins are pieces of code that augment Ansible's core functionality. Ansible uses a plugin architecture to enable a rich, flexible and expandible feature set.
Plugins are pieces of code that augment Ansible's core functionality. Ansible uses a plugin architecture to enable a rich, flexible and expandable feature set.
Ansible ships with a number of handy plugins, and you can easily write your own.
This section covers the various types of plugins that are included with Ansible:
.. toctree:: :maxdepth: 1
:glob:
plugins/*
playbooks_filters
playbooks_tests
.. toctree::
:maxdepth: 1
action
cache
callback
connection
inventory
lookup
shell
strategy
vars
playbooks_filters
playbooks_tests
../user_guide/plugin_filtering_config
.. seealso::

View file

@ -25,17 +25,17 @@ In this case, you will also want to update the :ref:`ansible_executable` to matc
.. seealso::
:doc:`../playbooks`
:doc:`../user_guide/playbooks`
An introduction to playbooks
:doc:`inventory`
Ansible inventory plugins
:doc:`callback`
Ansible callback plugins
:doc:`../playbooks_filters`
:doc:`../user_guide/playbooks_filters`
Jinja2 filter plugins
:doc:`../playbooks_tests`
:doc:`../user_guide/playbooks_tests`
Jinja2 test plugins
:doc:`../playbooks_lookups`
:doc:`../user_guide/playbooks_lookups`
Jinja2 lookup plugins
`User Mailing List <http://groups.google.com/group/ansible-devel>`_
Have a question? Stop by the google group!

View file

@ -6,8 +6,10 @@ Ansible Porting Guides
This section lists porting guides that can help you playbooks, plugins and other parts of your Ansible infrastructure from one version of Ansible to the next. Please note that this is not a complete list. If you believe any extra information would be useful in these pages, you can edit by clicking `Edit on GitHub` on the top right, or raising an issue.
* :ref:`Ansible 1.x to 2.0 porting guide <porting_2.0_guide>`
* :ref:`Ansible 2.2 to 2.3 porting guide <porting_2.3_guide>`
* :ref:`Ansible 2.3 to 2.4 porting guide <porting_2.4_guide>`
* :ref:`Ansible 2.4 to 2.5 porting guide <porting_2.5_guide>`
.. toctree::
:maxdepth: 2
porting_guide_2.0
porting_guide_2.3
porting_guide_2.4
porting_guide_2.5

File diff suppressed because it is too large Load diff

View file

@ -141,7 +141,7 @@ Where does the configuration file live and what can I configure in it?
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
See :doc:`intro_configuration`.
See :doc:`../installation_guide/intro_configuration`.
.. _who_would_ever_want_to_disable_cowsay_but_ok_here_is_how:
@ -229,7 +229,7 @@ How do I access a variable of the first host in a group?
What happens if we want the ip address of the first webserver in the webservers group? Well, we can do that too. Note that if we
are using dynamic inventory, which host is the 'first' may not be consistent, so you wouldn't want to do this unless your inventory
is static and predictable. (If you are using :doc:`tower`, it will use database order, so this isn't a problem even if you are using cloud
is static and predictable. (If you are using :doc:`../reference_appendices/tower`, it will use database order, so this isn't a problem even if you are using cloud
based inventory scripts).
Anyway, here's the trick:
@ -301,7 +301,7 @@ Once the library is ready, SHA512 password values can then be generated as follo
python -c "from passlib.hash import sha512_crypt; import getpass; print(sha512_crypt.using(rounds=5000).hash(getpass.getpass()))"
Use the integrated :ref:`hash_filters` to generate a hashed version of a password.
You shouldn't put plaintext passwords in your playbook or host_vars; instead, use :doc:`playbooks_vault` to encrypt sensitive data.
You shouldn't put plaintext passwords in your playbook or host_vars; instead, use :doc:`../user_guide/playbooks_vault` to encrypt sensitive data.
.. _commercial_support:
@ -332,7 +332,7 @@ Is there a web interface / REST API / etc?
++++++++++++++++++++++++++++++++++++++++++
Yes! Ansible, Inc makes a great product that makes Ansible even more powerful
and easy to use. See :doc:`tower`.
and easy to use. See :doc:`../reference_appendices/tower`.
.. _docs_contributions:
@ -346,7 +346,7 @@ Great question! Documentation for Ansible is kept in the main project git repos
How do I keep secret data in my playbook?
+++++++++++++++++++++++++++++++++++++++++
If you would like to keep secret data in your Ansible content and still share it publicly or keep things in source control, see :doc:`playbooks_vault`.
If you would like to keep secret data in your Ansible content and still share it publicly or keep things in source control, see :doc:`../user_guide/playbooks_vault`.
If you have a task that you don't want to show the results or command given to it when using -v (verbose) mode, the following task or playbook attribute can be useful::
@ -408,11 +408,9 @@ Please see the section below for a link to IRC and the Google Group, where you c
.. seealso::
:doc:`index`
The documentation index
:doc:`playbooks`
:doc:`../user_guide/playbooks`
An introduction to playbooks
:doc:`playbooks_best_practices`
:doc:`../user_guide/playbooks_best_practices`
Best practices advice
`User Mailing List <http://groups.google.com/group/ansible-project>`_
Have a question? Stop by the google group!

View file

@ -0,0 +1,7 @@
Module Index
============
.. toctree:: :maxdepth: 1
../modules/modules_by_category

View file

@ -0,0 +1,424 @@
Playbook Keywords
=================
These are the keywords available on common playbook objects.
.. note:: Please note:
* Aliases for the directives are not reflected here, nor are mutable one. For example,
:term:`action` in task can be substituted by the name of any Ansible module.
* The keywords do not have ``version_added`` information at this time
* Some keywords set defaults for the objects inside of them rather than for the objects
themselves
.. contents::
:local:
:depth: 1
Play
----
.. glossary::
always_run
*DEPRECATED*, forces a task to run even in check mode. Use :term:`check_mode` directive instead.
any_errors_fatal
Force any un-handled task errors on any host to propagate to all hosts and end the play.
become
Boolean that controls if privilege escalation is used or not on :term:`Task` execution.
become_flags
A string of flag(s) to pass to the privilege escalation program when :term:`become` is True.
become_method
Which method of privilege escalation to use (such as sudo or su).
become_user
User that you 'become' after using privilege escalation. The remote/login user must have permissions to become this user.
check_mode
A boolean that controls if a task is executed in 'check' mode
.. seealso:: :ref:`check_mode_dry`
connection
Allows you to change the connection plugin used for tasks to execute on the target.
.. seealso:: :ref:`using_connection`
debugger
UNDOCUMENTED!!
diff
Toggle to make tasks return 'diff' information or not.
environment
A dictionary that gets converted into environment vars to be provided for the task upon execution.
fact_path
Set the fact path option for the fact gathering plugin controlled by :term:`gather_facts`.
force_handlers
Will force notified handler execution for hosts even if they failed during the play. Will not trigger if the play itself fails.
gather_facts
A boolean that controls if the play will automatically run the 'setup' task to gather facts for the hosts.
gather_subset
Allows you to pass subset options to the fact gathering plugin controlled by :term:`gather_facts`.
gather_timeout
Allows you to set the timeout for the fact gathering plugin controlled by :term:`gather_facts`.
handlers
A section with tasks that are treated as handlers, these won't get executed normally, only when notified after each section of tasks is complete.
hosts
A list of groups, hosts or host pattern that translates into a list of hosts that are the play's target.
ignore_errors
Boolean that allows you to ignore task failures and continue with play. It does not affect connection errors.
max_fail_percentage
can be used to abort the run after a given percentage of hosts in the current batch has failed.
name
Identifier. Can be used for documentation, in or tasks/handlers.
no_log
Boolean that controls information disclosure.
order
Controls the sorting of hosts as they are used for executing the play. Possible values are inventory (default), sorted, reverse_sorted, reverse_inventory and shuffle.
port
Used to override the default port used in a connection.
post_tasks
A list of tasks to execute after the :term:`tasks` section.
pre_tasks
A list of tasks to execute before :term:`roles`.
remote_user
User used to log into the target via the connection plugin.
roles
List of roles to be imported into the play
run_once
Boolean that will bypass the host loop, forcing the task to execute on the first host available and will also apply any facts to all active hosts.
serial
Explicitly define how Ansible batches the execution of the current play on the play's target
.. seealso:: :ref:`rolling_update_batch_size`
strategy
Allows you to choose the connection plugin to use for the play.
tags
Tags applied to the task or included tasks, this allows selecting subsets of tasks from the command line.
tasks
Main list of tasks to execute in the play, they run after :term:`roles` and before :term:`post_tasks`.
vars
Dictionary/map of variables
vars_files
List of files that contain vars to include in the play.
vars_prompt
list of variables to prompt for.
vault_password
Secret used to decrypt vaulted files or variables.
Role
----
.. glossary::
always_run
*DEPRECATED*, forces a task to run even in check mode. Use :term:`check_mode` directive instead.
any_errors_fatal
Force any un-handled task errors on any host to propagate to all hosts and end the play.
become
Boolean that controls if privilege escalation is used or not on :term:`Task` execution.
become_flags
A string of flag(s) to pass to the privilege escalation program when :term:`become` is True.
become_method
Which method of privilege escalation to use (such as sudo or su).
become_user
User that you 'become' after using privilege escalation. The remote/login user must have permissions to become this user.
check_mode
A boolean that controls if a task is executed in 'check' mode
.. seealso:: :ref:`check_mode_dry`
connection
Allows you to change the connection plugin used for tasks to execute on the target.
.. seealso:: :ref:`using_connection`
debugger
UNDOCUMENTED!!
delegate_facts
Boolean that allows you to apply facts to a delegated host instead of inventory_hostname.
delegate_to
Host to execute task instead of the target (inventory_hostname). Connection vars from the delegated host will also be used for the task.
diff
Toggle to make tasks return 'diff' information or not.
environment
A dictionary that gets converted into environment vars to be provided for the task upon execution.
ignore_errors
Boolean that allows you to ignore task failures and continue with play. It does not affect connection errors.
name
Identifier. Can be used for documentation, in or tasks/handlers.
no_log
Boolean that controls information disclosure.
port
Used to override the default port used in a connection.
remote_user
User used to log into the target via the connection plugin.
run_once
Boolean that will bypass the host loop, forcing the task to execute on the first host available and will also apply any facts to all active hosts.
tags
Tags applied to the task or included tasks, this allows selecting subsets of tasks from the command line.
vars
Dictionary/map of variables
when
Conditional expression, determines if an iteration of a task is run or not.
Block
-----
.. glossary::
always
List of tasks, in a block, that execute no matter if there is an error in the block or not.
always_run
*DEPRECATED*, forces a task to run even in check mode. Use :term:`check_mode` directive instead.
any_errors_fatal
Force any un-handled task errors on any host to propagate to all hosts and end the play.
become
Boolean that controls if privilege escalation is used or not on :term:`Task` execution.
become_flags
A string of flag(s) to pass to the privilege escalation program when :term:`become` is True.
become_method
Which method of privilege escalation to use (such as sudo or su).
become_user
User that you 'become' after using privilege escalation. The remote/login user must have permissions to become this user.
block
List of tasks in a block.
check_mode
A boolean that controls if a task is executed in 'check' mode
.. seealso:: :ref:`check_mode_dry`
connection
Allows you to change the connection plugin used for tasks to execute on the target.
.. seealso:: :ref:`using_connection`
debugger
UNDOCUMENTED!!
delegate_facts
Boolean that allows you to apply facts to a delegated host instead of inventory_hostname.
delegate_to
Host to execute task instead of the target (inventory_hostname). Connection vars from the delegated host will also be used for the task.
diff
Toggle to make tasks return 'diff' information or not.
environment
A dictionary that gets converted into environment vars to be provided for the task upon execution.
ignore_errors
Boolean that allows you to ignore task failures and continue with play. It does not affect connection errors.
name
Identifier. Can be used for documentation, in or tasks/handlers.
no_log
Boolean that controls information disclosure.
port
Used to override the default port used in a connection.
remote_user
User used to log into the target via the connection plugin.
rescue
List of tasks in a :term:`block` that run if there is a task error in the main :term:`block` list.
run_once
Boolean that will bypass the host loop, forcing the task to execute on the first host available and will also apply any facts to all active hosts.
tags
Tags applied to the task or included tasks, this allows selecting subsets of tasks from the command line.
vars
Dictionary/map of variables
when
Conditional expression, determines if an iteration of a task is run or not.
Task
----
.. glossary::
action
The 'action' to execute for a task, it normally translates into a C(module) or action plugin.
always_run
*DEPRECATED*, forces a task to run even in check mode. Use :term:`check_mode` directive instead.
any_errors_fatal
Force any un-handled task errors on any host to propagate to all hosts and end the play.
args
*DEPRECATED*, A secondary way to add arguments into a task. Takes a dictionary in which keys map to options and values.
async_val
UNDOCUMENTED!!
become
Boolean that controls if privilege escalation is used or not on :term:`Task` execution.
become_flags
A string of flag(s) to pass to the privilege escalation program when :term:`become` is True.
become_method
Which method of privilege escalation to use (such as sudo or su).
become_user
User that you 'become' after using privilege escalation. The remote/login user must have permissions to become this user.
changed_when
Conditional expression that overrides the task's normal 'changed' status.
check_mode
A boolean that controls if a task is executed in 'check' mode
.. seealso:: :ref:`check_mode_dry`
connection
Allows you to change the connection plugin used for tasks to execute on the target.
.. seealso:: :ref:`using_connection`
debugger
UNDOCUMENTED!!
delay
Number of seconds to delay between retries. This setting is only used in combination with :term:`until`.
delegate_facts
Boolean that allows you to apply facts to a delegated host instead of inventory_hostname.
delegate_to
Host to execute task instead of the target (inventory_hostname). Connection vars from the delegated host will also be used for the task.
diff
Toggle to make tasks return 'diff' information or not.
environment
A dictionary that gets converted into environment vars to be provided for the task upon execution.
failed_when
Conditional expression that overrides the task's normal 'failed' status.
ignore_errors
Boolean that allows you to ignore task failures and continue with play. It does not affect connection errors.
local_action
Same as action but also implies ``delegate_to: localhost``
loop
Takes a list for the task to iterate over, saving each list element into the ``item`` variable (configurable via loop_control)
loop_control
Several keys here allow you to modify/set loop behaviour in a task.
.. seealso:: :ref:`loop_control`
loop_with
UNDOCUMENTED!!
name
Identifier. Can be used for documentation, in or tasks/handlers.
no_log
Boolean that controls information disclosure.
notify
List of handlers to notify when the task returns a 'changed=True' status.
poll
Sets the polling interval in seconds for async tasks (default 10s).
port
Used to override the default port used in a connection.
register
Name of variable that will contain task status and module return data.
remote_user
User used to log into the target via the connection plugin.
retries
Number of retries before giving up in a :term:`until` loop. This setting is only used in combination with :term:`until`.
run_once
Boolean that will bypass the host loop, forcing the task to execute on the first host available and will also apply any facts to all active hosts.
tags
Tags applied to the task or included tasks, this allows selecting subsets of tasks from the command line.
until
This keyword implies a ':term:`retries` loop' that will go on until the condition supplied here is met or we hit the :term:`retries` limit.
vars
Dictionary/map of variables
when
Conditional expression, determines if an iteration of a task is run or not.
with_<lookup_plugin>
DEPRECATED: use ``loop`` instead, ``with_`` used to be how loops were defined,

View file

@ -1,5 +1,5 @@
Ansible Tower
`````````````
=============
`Ansible Tower <https://ansible.com/tower>`_ (formerly 'AWX') is a web-based solution that makes Ansible even more easy to use for IT teams of all kinds. It's designed to be the hub for all of your automation tasks.

View file

@ -0,0 +1,152 @@
.. _ansible-config:
==============
ansible-config
==============
:strong:`View, edit, and manage ansible configuration.`
.. contents::
:local:
:depth: 2
.. program:: ansible-config
Synopsis
========
.. code-block:: bash
ansible-config [view|dump|list] [--help] [options] [ansible.cfg]
Description
===========
Config command line class
Common Options
==============
.. option:: --version
show program's version number and exit
.. option:: -c <CONFIG_FILE>, --config <CONFIG_FILE>
path to configuration file, defaults to first file found in precedence.
.. option:: -h, --help
show this help message and exit
.. option:: -v, --verbose
verbose mode (-vvv for more, -vvvv to enable connection debugging)
Actions
=======
.. program:: ansible-config list
.. _ansible_config_list:
list
----
list all current configs reading lib/constants.py and shows env and config file setting names
.. program:: ansible-config dump
.. _ansible_config_dump:
dump
----
Shows the current settings, merges ansible.cfg if specified
.. option:: --only-changed
Only show configurations that have changed from the default
.. program:: ansible-config view
.. _ansible_config_view:
view
----
Displays the current config file
.. program:: ansible-config
Environment
===========
The following environment variables may be specified.
:envvar:`ANSIBLE_CONFIG` -- Override the default ansible config file
Many more are available for most options in ansible.cfg
Files
=====
:file:`/etc/ansible/ansible.cfg` -- Config file, used if present
:file:`~/.ansible.cfg` -- User config file, overrides the default config if present
Author
======
Ansible was originally written by Michael DeHaan.
See the `AUTHORS` file for a complete list of contributors.
Copyright
=========
Copyright © 2017 Red Hat, Inc | Ansible.
Ansible is released under the terms of the GPLv3 License.
See also
========
:manpage:`ansible(1)`, :manpage:`ansible-config(1)`, :manpage:`ansible-console(1)`, :manpage:`ansible-doc(1)`, :manpage:`ansible-galaxy(1)`, :manpage:`ansible-inventory(1)`, :manpage:`ansible-playbook(1)`, :manpage:`ansible-pull(1)`, :manpage:`ansible-vault(1)`,

View file

@ -0,0 +1,257 @@
.. _ansible-console:
===============
ansible-console
===============
:strong:`REPL console for executing Ansible tasks.`
.. contents::
:local:
:depth: 2
.. program:: ansible-console
Synopsis
========
.. code-block:: bash
ansible-console [<host-pattern>] [options]
Description
===========
a REPL that allows for running ad-hoc tasks against a chosen inventory (based on dominis' ansible-shell).
Common Options
==============
.. option:: --ask-su-pass
ask for su password (deprecated, use become)
.. option:: --ask-sudo-pass
ask for sudo password (deprecated, use become)
.. option:: --ask-vault-pass
ask for vault password
.. option:: --become-method <BECOME_METHOD>
privilege escalation method to use (default=sudo), valid choices: [ sudo | su | pbrun | pfexec | doas | dzdo | ksu | runas | pmrun | enable ]
.. option:: --become-user <BECOME_USER>
run operations as this user (default=root)
.. option:: --list-hosts
outputs a list of matching hosts; does not execute anything else
.. option:: --playbook-dir <BASEDIR>
Since this tool does not use playbooks, use this as a subsitute playbook directory.This sets the relative path for many features including roles/ group_vars/ etc.
.. option:: --private-key, --key-file
use this file to authenticate the connection
.. option:: --scp-extra-args <SCP_EXTRA_ARGS>
specify extra arguments to pass to scp only (e.g. -l)
.. option:: --sftp-extra-args <SFTP_EXTRA_ARGS>
specify extra arguments to pass to sftp only (e.g. -f, -l)
.. option:: --ssh-common-args <SSH_COMMON_ARGS>
specify common arguments to pass to sftp/scp/ssh (e.g. ProxyCommand)
.. option:: --ssh-extra-args <SSH_EXTRA_ARGS>
specify extra arguments to pass to ssh only (e.g. -R)
.. option:: --step
one-step-at-a-time: confirm each task before running
.. option:: --syntax-check
perform a syntax check on the playbook, but do not execute it
.. option:: --vault-id
the vault identity to use
.. option:: --vault-password-file
vault password file
.. option:: --version
show program's version number and exit
.. option:: -C, --check
don't make any changes; instead, try to predict some of the changes that may occur
.. option:: -D, --diff
when changing (small) files and templates, show the differences in those files; works great with --check
.. option:: -K, --ask-become-pass
ask for privilege escalation password
.. option:: -M, --module-path
prepend colon-separated path(s) to module library (default=[u'/Users/sbutler/.ansible/plugins/modules', u'/usr/share/ansible/plugins/modules'])
.. option:: -R <SU_USER>, --su-user <SU_USER>
run operations with su as this user (default=None) (deprecated, use become)
.. option:: -S, --su
run operations with su (deprecated, use become)
.. option:: -T <TIMEOUT>, --timeout <TIMEOUT>
override the connection timeout in seconds (default=10)
.. option:: -U <SUDO_USER>, --sudo-user <SUDO_USER>
desired sudo user (default=root) (deprecated, use become)
.. option:: -b, --become
run operations with become (does not imply password prompting)
.. option:: -c <CONNECTION>, --connection <CONNECTION>
connection type to use (default=smart)
.. option:: -f <FORKS>, --forks <FORKS>
specify number of parallel processes to use (default=5)
.. option:: -h, --help
show this help message and exit
.. option:: -i, --inventory, --inventory-file
specify inventory host path or comma separated host list. --inventory-file is deprecated
.. option:: -k, --ask-pass
ask for connection password
.. option:: -l <SUBSET>, --limit <SUBSET>
further limit selected hosts to an additional pattern
.. option:: -s, --sudo
run operations with sudo (nopasswd) (deprecated, use become)
.. option:: -u <REMOTE_USER>, --user <REMOTE_USER>
connect as this user (default=None)
.. option:: -v, --verbose
verbose mode (-vvv for more, -vvvv to enable connection debugging)
Environment
===========
The following environment variables may be specified.
:envvar:`ANSIBLE_CONFIG` -- Override the default ansible config file
Many more are available for most options in ansible.cfg
Files
=====
:file:`/etc/ansible/ansible.cfg` -- Config file, used if present
:file:`~/.ansible.cfg` -- User config file, overrides the default config if present
Author
======
Ansible was originally written by Michael DeHaan.
See the `AUTHORS` file for a complete list of contributors.
Copyright
=========
Copyright © 2017 Red Hat, Inc | Ansible.
Ansible is released under the terms of the GPLv3 License.
See also
========
:manpage:`ansible(1)`, :manpage:`ansible-config(1)`, :manpage:`ansible-console(1)`, :manpage:`ansible-doc(1)`, :manpage:`ansible-galaxy(1)`, :manpage:`ansible-inventory(1)`, :manpage:`ansible-playbook(1)`, :manpage:`ansible-pull(1)`, :manpage:`ansible-vault(1)`,

View file

@ -0,0 +1,130 @@
.. _ansible-doc:
===========
ansible-doc
===========
:strong:`plugin documentation tool`
.. contents::
:local:
:depth: 2
.. program:: ansible-doc
Synopsis
========
.. code-block:: bash
ansible-doc [-l|-F|-s] [options] [-t <plugin type> ] [plugin]
Description
===========
displays information on modules installed in Ansible libraries.
It displays a terse listing of plugins and their short descriptions,
provides a printout of their DOCUMENTATION strings,
and it can create a short "snippet" which can be pasted into a playbook.
Common Options
==============
.. option:: --version
show program's version number and exit
.. option:: -F, --list_files
Show plugin names and their source files without summaries (implies --list)
.. option:: -M, --module-path
prepend colon-separated path(s) to module library (default=[u'/Users/sbutler/.ansible/plugins/modules', u'/usr/share/ansible/plugins/modules'])
.. option:: -a, --all
**For internal testing only** Show documentation for all plugins.
.. option:: -h, --help
show this help message and exit
.. option:: -l, --list
List available plugins
.. option:: -s, --snippet
Show playbook snippet for specified plugin(s)
.. option:: -t <TYPE>, --type <TYPE>
Choose which plugin type (defaults to "module")
.. option:: -v, --verbose
verbose mode (-vvv for more, -vvvv to enable connection debugging)
Environment
===========
The following environment variables may be specified.
:envvar:`ANSIBLE_CONFIG` -- Override the default ansible config file
Many more are available for most options in ansible.cfg
Files
=====
:file:`/etc/ansible/ansible.cfg` -- Config file, used if present
:file:`~/.ansible.cfg` -- User config file, overrides the default config if present
Author
======
Ansible was originally written by Michael DeHaan.
See the `AUTHORS` file for a complete list of contributors.
Copyright
=========
Copyright © 2017 Red Hat, Inc | Ansible.
Ansible is released under the terms of the GPLv3 License.
See also
========
:manpage:`ansible(1)`, :manpage:`ansible-config(1)`, :manpage:`ansible-console(1)`, :manpage:`ansible-doc(1)`, :manpage:`ansible-galaxy(1)`, :manpage:`ansible-inventory(1)`, :manpage:`ansible-playbook(1)`, :manpage:`ansible-pull(1)`, :manpage:`ansible-vault(1)`,

View file

@ -0,0 +1,380 @@
.. _ansible-galaxy:
==============
ansible-galaxy
==============
:strong:`None`
.. contents::
:local:
:depth: 2
.. program:: ansible-galaxy
Synopsis
========
.. code-block:: bash
ansible-galaxy [delete|import|info|init|install|list|login|remove|search|setup] [--help] [options] ...
Description
===========
command to manage Ansible roles in shared repostories, the default of which is Ansible Galaxy *https://galaxy.ansible.com*.
Common Options
==============
.. option:: --list
List all of your integrations.
.. option:: --remove <REMOVE_ID>
Remove the integration matching the provided ID value. Use --list to see ID values.
.. option:: --version
show program's version number and exit
.. option:: -c, --ignore-certs
Ignore SSL certificate validation errors.
.. option:: -h, --help
show this help message and exit
.. option:: -s <API_SERVER>, --server <API_SERVER>
The API server destination
.. option:: -v, --verbose
verbose mode (-vvv for more, -vvvv to enable connection debugging)
Actions
=======
.. program:: ansible-galaxy info
.. _ansible_galaxy_info:
info
----
prints out detailed information about an installed role as well as info available from the galaxy API.
.. option:: --offline
Don't query the galaxy API when creating roles
.. option:: -p , --roles-path
The path to the directory containing your roles. The default is the roles_path configured in your ansible.cfgfile (/etc/ansible/roles if not configured)
.. program:: ansible-galaxy search
.. _ansible_galaxy_search:
search
------
searches for roles on the Ansible Galaxy server
.. option:: --author <AUTHOR>
GitHub username
.. option:: --galaxy-tags <GALAXY_TAGS>
list of galaxy tags to filter by
.. option:: --platforms <PLATFORMS>
list of OS platforms to filter by
.. option:: -p , --roles-path
The path to the directory containing your roles. The default is the roles_path configured in your ansible.cfgfile (/etc/ansible/roles if not configured)
.. program:: ansible-galaxy setup
.. _ansible_galaxy_setup:
setup
-----
Setup an integration from Github or Travis for Ansible Galaxy roles
.. option:: --list
List all of your integrations.
.. option:: --remove <REMOVE_ID>
Remove the integration matching the provided ID value. Use --list to see ID values.
.. program:: ansible-galaxy list
.. _ansible_galaxy_list:
list
----
lists the roles installed on the local system or matches a single role passed as an argument.
.. option:: -p , --roles-path
The path to the directory containing your roles. The default is the roles_path configured in your ansible.cfgfile (/etc/ansible/roles if not configured)
.. program:: ansible-galaxy remove
.. _ansible_galaxy_remove:
remove
------
removes the list of roles passed as arguments from the local system.
.. option:: -p , --roles-path
The path to the directory containing your roles. The default is the roles_path configured in your ansible.cfgfile (/etc/ansible/roles if not configured)
.. program:: ansible-galaxy init
.. _ansible_galaxy_init:
init
----
creates the skeleton framework of a role that complies with the galaxy metadata format.
.. option:: --container-enabled
Initialize the skeleton role with default contents for a Container Enabled role.
.. option:: --init-path <INIT_PATH>
The path in which the skeleton role will be created. The default is the current working directory.
.. option:: --offline
Don't query the galaxy API when creating roles
.. option:: --role-skeleton <ROLE_SKELETON>
The path to a role skeleton that the new role should be based upon.
.. option:: -f , --force
Force overwriting an existing role
.. program:: ansible-galaxy install
.. _ansible_galaxy_install:
install
-------
uses the args list of roles to be installed, unless -f was specified. The list of roles
can be a name (which will be downloaded via the galaxy API and github), or it can be a local .tar.gz file.
.. option:: -f , --force
Force overwriting an existing role
.. option:: -i , --ignore-errors
Ignore errors and continue with the next specified role.
.. option:: -n , --no-deps
Don't download roles listed as dependencies
.. option:: -p , --roles-path
The path to the directory containing your roles. The default is the roles_path configured in your ansible.cfgfile (/etc/ansible/roles if not configured)
.. option:: -r <ROLE_FILE>, --role-file <ROLE_FILE>
A file containing a list of roles to be imported
.. program:: ansible-galaxy import
.. _ansible_galaxy_import:
import
------
used to import a role into Ansible Galaxy
.. option:: --branch <REFERENCE>
The name of a branch to import. Defaults to the repository's default branch (usually master)
.. option:: --no-wait
Don't wait for import results.
.. option:: --role-name <ROLE_NAME>
The name the role should have, if different than the repo name
.. option:: --status
Check the status of the most recent import request for given github_user/github_repo.
.. program:: ansible-galaxy login
.. _ansible_galaxy_login:
login
-----
verify user's identify via Github and retrieve an auth token from Ansible Galaxy.
.. option:: --github-token <TOKEN>
Identify with github token rather than username and password.
.. program:: ansible-galaxy delete
.. _ansible_galaxy_delete:
delete
------
Delete a role from Ansible Galaxy.
.. program:: ansible-galaxy
Environment
===========
The following environment variables may be specified.
:envvar:`ANSIBLE_CONFIG` -- Override the default ansible config file
Many more are available for most options in ansible.cfg
Files
=====
:file:`/etc/ansible/ansible.cfg` -- Config file, used if present
:file:`~/.ansible.cfg` -- User config file, overrides the default config if present
Author
======
Ansible was originally written by Michael DeHaan.
See the `AUTHORS` file for a complete list of contributors.
Copyright
=========
Copyright © 2017 Red Hat, Inc | Ansible.
Ansible is released under the terms of the GPLv3 License.
See also
========
:manpage:`ansible(1)`, :manpage:`ansible-config(1)`, :manpage:`ansible-console(1)`, :manpage:`ansible-doc(1)`, :manpage:`ansible-galaxy(1)`, :manpage:`ansible-inventory(1)`, :manpage:`ansible-playbook(1)`, :manpage:`ansible-pull(1)`, :manpage:`ansible-vault(1)`,

View file

@ -0,0 +1,157 @@
.. _ansible-inventory:
=================
ansible-inventory
=================
:strong:`None`
.. contents::
:local:
:depth: 2
.. program:: ansible-inventory
Synopsis
========
.. code-block:: bash
ansible-inventory [options] [host|group]
Description
===========
used to display or dump the configured inventory as Ansible sees it
Common Options
==============
.. option:: --ask-vault-pass
ask for vault password
.. option:: --graph
create inventory graph, if supplying pattern it must be a valid group name
.. option:: --host <HOST>
Output specific host info, works as inventory script
.. option:: --list
Output all hosts info, works as inventory script
.. option:: --list-hosts
outputs a list of matching hosts; does not execute anything else
.. option:: --playbook-dir <BASEDIR>
Since this tool does not use playbooks, use this as a subsitute playbook directory.This sets the relative path for many features including roles/ group_vars/ etc.
.. option:: --vars
Add vars to graph display, ignored unless used with --graph
.. option:: --vault-id
the vault identity to use
.. option:: --vault-password-file
vault password file
.. option:: --version
show program's version number and exit
.. option:: -h, --help
show this help message and exit
.. option:: -i, --inventory, --inventory-file
specify inventory host path or comma separated host list. --inventory-file is deprecated
.. option:: -l <SUBSET>, --limit <SUBSET>
further limit selected hosts to an additional pattern
.. option:: -v, --verbose
verbose mode (-vvv for more, -vvvv to enable connection debugging)
.. option:: -y, --yaml
Use YAML format instead of default JSON, ignored for --graph
Environment
===========
The following environment variables may be specified.
:envvar:`ANSIBLE_CONFIG` -- Override the default ansible config file
Many more are available for most options in ansible.cfg
Files
=====
:file:`/etc/ansible/ansible.cfg` -- Config file, used if present
:file:`~/.ansible.cfg` -- User config file, overrides the default config if present
Author
======
Ansible was originally written by Michael DeHaan.
See the `AUTHORS` file for a complete list of contributors.
Copyright
=========
Copyright © 2017 Red Hat, Inc | Ansible.
Ansible is released under the terms of the GPLv3 License.
See also
========
:manpage:`ansible(1)`, :manpage:`ansible-config(1)`, :manpage:`ansible-console(1)`, :manpage:`ansible-doc(1)`, :manpage:`ansible-galaxy(1)`, :manpage:`ansible-inventory(1)`, :manpage:`ansible-playbook(1)`, :manpage:`ansible-pull(1)`, :manpage:`ansible-vault(1)`,

View file

@ -0,0 +1,293 @@
.. _ansible-playbook:
================
ansible-playbook
================
:strong:`Runs Ansible playbooks, executing the defined tasks on the targeted hosts.`
.. contents::
:local:
:depth: 2
.. program:: ansible-playbook
Synopsis
========
.. code-block:: bash
ansible-playbook [options] playbook.yml [playbook2 ...]
Description
===========
the tool to run *Ansible playbooks*, which are a configuration and multinode deployment system.
See the project home page (https://docs.ansible.com) for more information.
Common Options
==============
.. option:: --ask-su-pass
ask for su password (deprecated, use become)
.. option:: --ask-sudo-pass
ask for sudo password (deprecated, use become)
.. option:: --ask-vault-pass
ask for vault password
.. option:: --become-method <BECOME_METHOD>
privilege escalation method to use (default=sudo), valid choices: [ sudo | su | pbrun | pfexec | doas | dzdo | ksu | runas | pmrun | enable ]
.. option:: --become-user <BECOME_USER>
run operations as this user (default=root)
.. option:: --flush-cache
clear the fact cache for every host in inventory
.. option:: --force-handlers
run handlers even if a task fails
.. option:: --list-hosts
outputs a list of matching hosts; does not execute anything else
.. option:: --list-tags
list all available tags
.. option:: --list-tasks
list all tasks that would be executed
.. option:: --private-key, --key-file
use this file to authenticate the connection
.. option:: --scp-extra-args <SCP_EXTRA_ARGS>
specify extra arguments to pass to scp only (e.g. -l)
.. option:: --sftp-extra-args <SFTP_EXTRA_ARGS>
specify extra arguments to pass to sftp only (e.g. -f, -l)
.. option:: --skip-tags
only run plays and tasks whose tags do not match these values
.. option:: --ssh-common-args <SSH_COMMON_ARGS>
specify common arguments to pass to sftp/scp/ssh (e.g. ProxyCommand)
.. option:: --ssh-extra-args <SSH_EXTRA_ARGS>
specify extra arguments to pass to ssh only (e.g. -R)
.. option:: --start-at-task <START_AT_TASK>
start the playbook at the task matching this name
.. option:: --step
one-step-at-a-time: confirm each task before running
.. option:: --syntax-check
perform a syntax check on the playbook, but do not execute it
.. option:: --vault-id
the vault identity to use
.. option:: --vault-password-file
vault password file
.. option:: --version
show program's version number and exit
.. option:: -C, --check
don't make any changes; instead, try to predict some of the changes that may occur
.. option:: -D, --diff
when changing (small) files and templates, show the differences in those files; works great with --check
.. option:: -K, --ask-become-pass
ask for privilege escalation password
.. option:: -M, --module-path
prepend colon-separated path(s) to module library (default=[u'/Users/sbutler/.ansible/plugins/modules', u'/usr/share/ansible/plugins/modules'])
.. option:: -R <SU_USER>, --su-user <SU_USER>
run operations with su as this user (default=None) (deprecated, use become)
.. option:: -S, --su
run operations with su (deprecated, use become)
.. option:: -T <TIMEOUT>, --timeout <TIMEOUT>
override the connection timeout in seconds (default=10)
.. option:: -U <SUDO_USER>, --sudo-user <SUDO_USER>
desired sudo user (default=root) (deprecated, use become)
.. option:: -b, --become
run operations with become (does not imply password prompting)
.. option:: -c <CONNECTION>, --connection <CONNECTION>
connection type to use (default=smart)
.. option:: -e, --extra-vars
set additional variables as key=value or YAML/JSON, if filename prepend with @
.. option:: -f <FORKS>, --forks <FORKS>
specify number of parallel processes to use (default=5)
.. option:: -h, --help
show this help message and exit
.. option:: -i, --inventory, --inventory-file
specify inventory host path or comma separated host list. --inventory-file is deprecated
.. option:: -k, --ask-pass
ask for connection password
.. option:: -l <SUBSET>, --limit <SUBSET>
further limit selected hosts to an additional pattern
.. option:: -s, --sudo
run operations with sudo (nopasswd) (deprecated, use become)
.. option:: -t, --tags
only run plays and tasks tagged with these values
.. option:: -u <REMOTE_USER>, --user <REMOTE_USER>
connect as this user (default=None)
.. option:: -v, --verbose
verbose mode (-vvv for more, -vvvv to enable connection debugging)
Environment
===========
The following environment variables may be specified.
:envvar:`ANSIBLE_CONFIG` -- Override the default ansible config file
Many more are available for most options in ansible.cfg
Files
=====
:file:`/etc/ansible/ansible.cfg` -- Config file, used if present
:file:`~/.ansible.cfg` -- User config file, overrides the default config if present
Author
======
Ansible was originally written by Michael DeHaan.
See the `AUTHORS` file for a complete list of contributors.
Copyright
=========
Copyright © 2017 Red Hat, Inc | Ansible.
Ansible is released under the terms of the GPLv3 License.
See also
========
:manpage:`ansible(1)`, :manpage:`ansible-config(1)`, :manpage:`ansible-console(1)`, :manpage:`ansible-doc(1)`, :manpage:`ansible-galaxy(1)`, :manpage:`ansible-inventory(1)`, :manpage:`ansible-playbook(1)`, :manpage:`ansible-pull(1)`, :manpage:`ansible-vault(1)`,

View file

@ -0,0 +1,285 @@
.. _ansible-pull:
============
ansible-pull
============
:strong:`pulls playbooks from a VCS repo and executes them for the local host`
.. contents::
:local:
:depth: 2
.. program:: ansible-pull
Synopsis
========
.. code-block:: bash
ansible-pull -U <repository> [options] [<playbook.yml>]
Description
===========
is used to up a remote copy of ansible on each managed node,
each set to run via cron and update playbook source via a source repository.
This inverts the default *push* architecture of ansible into a *pull* architecture,
which has near-limitless scaling potential.
The setup playbook can be tuned to change the cron frequency, logging locations, and parameters to ansible-pull.
This is useful both for extreme scale-out as well as periodic remediation.
Usage of the 'fetch' module to retrieve logs from ansible-pull runs would be an
excellent way to gather and analyze remote logs from ansible-pull.
Common Options
==============
.. option:: --accept-host-key
adds the hostkey for the repo url if not already added
.. option:: --ask-su-pass
ask for su password (deprecated, use become)
.. option:: --ask-sudo-pass
ask for sudo password (deprecated, use become)
.. option:: --ask-vault-pass
ask for vault password
.. option:: --check
don't make any changes; instead, try to predict some of the changes that may occur
.. option:: --clean
modified files in the working repository will be discarded
.. option:: --full
Do a full clone, instead of a shallow one.
.. option:: --list-hosts
outputs a list of matching hosts; does not execute anything else
.. option:: --private-key, --key-file
use this file to authenticate the connection
.. option:: --purge
purge checkout after playbook run
.. option:: --scp-extra-args <SCP_EXTRA_ARGS>
specify extra arguments to pass to scp only (e.g. -l)
.. option:: --sftp-extra-args <SFTP_EXTRA_ARGS>
specify extra arguments to pass to sftp only (e.g. -f, -l)
.. option:: --skip-tags
only run plays and tasks whose tags do not match these values
.. option:: --ssh-common-args <SSH_COMMON_ARGS>
specify common arguments to pass to sftp/scp/ssh (e.g. ProxyCommand)
.. option:: --ssh-extra-args <SSH_EXTRA_ARGS>
specify extra arguments to pass to ssh only (e.g. -R)
.. option:: --track-subs
submodules will track the latest changes. This is equivalent to specifying the --remote flag to git submodule update
.. option:: --vault-id
the vault identity to use
.. option:: --vault-password-file
vault password file
.. option:: --verify-commit
verify GPG signature of checked out commit, if it fails abort running the playbook. This needs the corresponding VCS module to support such an operation
.. option:: --version
show program's version number and exit
.. option:: -C <CHECKOUT>, --checkout <CHECKOUT>
branch/tag/commit to checkout. Defaults to behavior of repository module.
.. option:: -K, --ask-become-pass
ask for privilege escalation password
.. option:: -M, --module-path
prepend colon-separated path(s) to module library (default=[u'/Users/sbutler/.ansible/plugins/modules', u'/usr/share/ansible/plugins/modules'])
.. option:: -T <TIMEOUT>, --timeout <TIMEOUT>
override the connection timeout in seconds (default=10)
.. option:: -U <URL>, --url <URL>
URL of the playbook repository
.. option:: -c <CONNECTION>, --connection <CONNECTION>
connection type to use (default=smart)
.. option:: -d <DEST>, --directory <DEST>
directory to checkout repository to
.. option:: -e, --extra-vars
set additional variables as key=value or YAML/JSON, if filename prepend with @
.. option:: -f, --force
run the playbook even if the repository could not be updated
.. option:: -h, --help
show this help message and exit
.. option:: -i, --inventory, --inventory-file
specify inventory host path or comma separated host list. --inventory-file is deprecated
.. option:: -k, --ask-pass
ask for connection password
.. option:: -l <SUBSET>, --limit <SUBSET>
further limit selected hosts to an additional pattern
.. option:: -m <MODULE_NAME>, --module-name <MODULE_NAME>
Repository module name, which ansible will use to check out the repo. Choices are ('git', 'subversion', 'hg', 'bzr'). Default is git.
.. option:: -o, --only-if-changed
only run the playbook if the repository has been updated
.. option:: -s <SLEEP>, --sleep <SLEEP>
sleep for random interval (between 0 and n number of seconds) before starting. This is a useful way to disperse git requests
.. option:: -t, --tags
only run plays and tasks tagged with these values
.. option:: -u <REMOTE_USER>, --user <REMOTE_USER>
connect as this user (default=None)
.. option:: -v, --verbose
verbose mode (-vvv for more, -vvvv to enable connection debugging)
Environment
===========
The following environment variables may be specified.
:envvar:`ANSIBLE_CONFIG` -- Override the default ansible config file
Many more are available for most options in ansible.cfg
Files
=====
:file:`/etc/ansible/ansible.cfg` -- Config file, used if present
:file:`~/.ansible.cfg` -- User config file, overrides the default config if present
Author
======
Ansible was originally written by Michael DeHaan.
See the `AUTHORS` file for a complete list of contributors.
Copyright
=========
Copyright © 2017 Red Hat, Inc | Ansible.
Ansible is released under the terms of the GPLv3 License.
See also
========
:manpage:`ansible(1)`, :manpage:`ansible-config(1)`, :manpage:`ansible-console(1)`, :manpage:`ansible-doc(1)`, :manpage:`ansible-galaxy(1)`, :manpage:`ansible-inventory(1)`, :manpage:`ansible-playbook(1)`, :manpage:`ansible-pull(1)`, :manpage:`ansible-vault(1)`,

View file

@ -0,0 +1,281 @@
.. _ansible-vault:
=============
ansible-vault
=============
:strong:`encryption/decryption utility for Ansible data files`
.. contents::
:local:
:depth: 2
.. program:: ansible-vault
Synopsis
========
.. code-block:: bash
ansible-vault [create|decrypt|edit|encrypt|encrypt_string|rekey|view] [options] [vaultfile.yml]
Description
===========
can encrypt any structured data file used by Ansible.
This can include *group_vars/* or *host_vars/* inventory variables,
variables loaded by *include_vars* or *vars_files*, or variable files
passed on the ansible-playbook command line with *-e @file.yml* or *-e @file.json*.
Role variables and defaults are also included!
Because Ansible tasks, handlers, and other objects are data, these can also be encrypted with vault.
If you'd like to not expose what variables you are using, you can keep an individual task file entirely encrypted.
The password used with vault currently must be the same for all files you wish to use together at the same time.
Common Options
==============
.. option:: --ask-vault-pass
ask for vault password
.. option:: --new-vault-id <NEW_VAULT_ID>
the new vault identity to use for rekey
.. option:: --new-vault-password-file
new vault password file for rekey
.. option:: --vault-id
the vault identity to use
.. option:: --vault-password-file
vault password file
.. option:: --version
show program's version number and exit
.. option:: -h, --help
show this help message and exit
.. option:: -v, --verbose
verbose mode (-vvv for more, -vvvv to enable connection debugging)
Actions
=======
.. program:: ansible-vault encrypt
.. _ansible_vault_encrypt:
encrypt
-------
encrypt the supplied file using the provided vault secret
.. option:: --encrypt-vault-id <ENCRYPT_VAULT_ID>
the vault id used to encrypt (required if more than vault-id is provided)
.. option:: --output
output file name for encrypt or decrypt; use - for stdout
.. program:: ansible-vault rekey
.. _ansible_vault_rekey:
rekey
-----
re-encrypt a vaulted file with a new secret, the previous secret is required
.. option:: --encrypt-vault-id <ENCRYPT_VAULT_ID>
the vault id used to encrypt (required if more than vault-id is provided)
.. program:: ansible-vault encrypt_string
.. _ansible_vault_encrypt_string:
encrypt_string
--------------
encrypt the supplied string using the provided vault secret
.. option:: --encrypt-vault-id <ENCRYPT_VAULT_ID>
the vault id used to encrypt (required if more than vault-id is provided)
.. option:: --output
output file name for encrypt or decrypt; use - for stdout
.. option:: --stdin-name <ENCRYPT_STRING_STDIN_NAME>
Specify the variable name for stdin
.. option:: -n , --name
Specify the variable name
.. option:: -p , --prompt
Prompt for the string to encrypt
.. program:: ansible-vault edit
.. _ansible_vault_edit:
edit
----
open and decrypt an existing vaulted file in an editor, that will be encryped again when closed
.. program:: ansible-vault create
.. _ansible_vault_create:
create
------
create and open a file in an editor that will be encryped with the provided vault secret when closed
.. option:: --encrypt-vault-id <ENCRYPT_VAULT_ID>
the vault id used to encrypt (required if more than vault-id is provided)
.. program:: ansible-vault decrypt
.. _ansible_vault_decrypt:
decrypt
-------
decrypt the supplied file using the provided vault secret
.. option:: --output
output file name for encrypt or decrypt; use - for stdout
.. program:: ansible-vault view
.. _ansible_vault_view:
view
----
open, decrypt and view an existing vaulted file using a pager using the supplied vault secret
.. program:: ansible-vault
Environment
===========
The following environment variables may be specified.
:envvar:`ANSIBLE_CONFIG` -- Override the default ansible config file
Many more are available for most options in ansible.cfg
Files
=====
:file:`/etc/ansible/ansible.cfg` -- Config file, used if present
:file:`~/.ansible.cfg` -- User config file, overrides the default config if present
Author
======
Ansible was originally written by Michael DeHaan.
See the `AUTHORS` file for a complete list of contributors.
Copyright
=========
Copyright © 2017 Red Hat, Inc | Ansible.
Ansible is released under the terms of the GPLv3 License.
See also
========
:manpage:`ansible(1)`, :manpage:`ansible-config(1)`, :manpage:`ansible-console(1)`, :manpage:`ansible-doc(1)`, :manpage:`ansible-galaxy(1)`, :manpage:`ansible-inventory(1)`, :manpage:`ansible-playbook(1)`, :manpage:`ansible-pull(1)`, :manpage:`ansible-vault(1)`,

Some files were not shown because too many files have changed in this diff Show more