ch02-playbooks-a-beginning.html

<section data-type="chapter" id="playbooks_a_beginning">
<h1>Playbooks: A Beginning</h1>


<p>Most of your time in Ansible will be spent writing playbooks. A <em>playbook</em> is
the term that Ansible uses for a configuration management script. <a data-type="indexterm" id="ix_playbk" data-primary="playbooks"/>Let&#8217;s look at
an example: installing the Nginx web server and configuring it for secure
communication.</p>

<p>If you&#8217;re following along in this chapter, you should end up with the files listed here:</p>

<ul>
<li>
<p><em>playbooks/ansible.cfg</em></p>
</li>
<li>
<p><em>playbooks/hosts</em></p>
</li>
<li>
<p><em>playbooks/Vagrantfile</em></p>
</li>
<li>
<p><em>playbooks/web-notls.yml</em></p>
</li>
<li>
<p><em>playbooks/web-tls.yml</em></p>
</li>
<li>
<p><em>playbooks/files/nginx.key</em></p>
</li>
<li>
<p><em>playbooks/files/nginx.crt</em></p>
</li>
<li>
<p><em>playbooks/files/nginx.conf</em></p>
</li>
<li>
<p><em>playbooks/templates/index.html.j2</em></p>
</li>
<li>
<p><em>playbooks/templates/nginx.conf.j2</em></p>
</li>
</ul>






<section data-type="sect1">
<h1>Some Preliminaries</h1>

<p>Before we can run this playbook against our Vagrant machine, we need
to expose ports 80 and 443, so we can access them. <a data-type="indexterm" data-primary="Nginx" data-secondary="configuring host to run" data-tertiary="exposing ports on Vagrant machine"/><a data-type="indexterm" data-primary="Vagrant" data-secondary="exposing ports on"/>As shown in
<a data-type="xref" href="#vagrant_ports_figure"/>, we are going to configure Vagrant so that requests to
ports 8080 and 8443 on our local machine are forwarded to ports 80 and 443 on
the Vagrant machine. This will allow us to access the web server running inside Vagrant at
<a href="http://localhost:8080"><em class="hyperlink">http://localhost:8080</em></a> and <a href="https://localhost:8443"><em class="hyperlink">https://localhost:8443</em></a>.</p>

<figure id="vagrant_ports_figure">
<img src="images/aur2_0201.png" alt="Vagrant port forwarding"/>
<figcaption>Exposing ports on Vagrant machine</figcaption>
</figure>

<p>Modify your <em>Vagrantfile</em> so it looks like this:</p>

<pre data-type="programlisting" data-code-language="ruby">VAGRANTFILE_API_VERSION = "2"

Vagrant.configure(VAGRANTFILE_API_VERSION) do |config|
  config.vm.box = "ubuntu/trusty64"
  config.vm.network "forwarded_port", guest: 80, host: 8080
  config.vm.network "forwarded_port", guest: 443, host: 8443
end</pre>

<p>This maps port 8080 on your local machine to port 80 of the Vagrant machine, and
port 8443 on your local machine to port 443 on the Vagrant machine. After you
make the changes, tell Vagrant to have them go into effect by running this command:</p>

<pre data-type="programlisting" data-code-language="console">$ vagrant reload</pre>

<p>You should see output that includes the following:</p>

<pre data-type="programlisting">==&gt; default: Forwarding ports...
    default: 80 =&gt; 8080 (adapter 1)
    default: 443 =&gt; 8443 (adapter 1)
    default: 22 =&gt; 2222 (adapter 1)</pre>
</section>













<section data-type="sect1">
<h1>A Very Simple Playbook</h1>

<p>For our first example playbook, we&#8217;ll configure a host to run an Nginx web
server.<a data-type="indexterm" id="ix_Nginxconf" data-primary="Nginx" data-secondary="configuring host to run"/><a data-type="indexterm" id="ix_playbksimex" data-primary="playbooks" data-secondary="simple example, configuring host to run Nginx"/> For this example, we won&#8217;t configure the web server to support TLS encryption. This will make setting up
the web server simpler. However, a proper website should have Transport Layer Security (TLS) encryption
enabled, and we&#8217;ll cover how to do that later in this chapter.</p>
<aside data-type="sidebar" class="pagebreak-before less_space">
<h5>TLS versus SSL</h5>
<p>You might be familiar with the term <em>SSL</em> rather than <em>TLS</em> in the context of secure web servers.<a data-type="indexterm" data-primary="SSL (Secure Sockets Layer)" data-seealso="TLS"/><a data-type="indexterm" data-primary="TLS (Transport Layer Security)"/> SSL is an older protocol that was used to secure communications between browsers and web servers, and it has been superseded by a newer protocol named TLS. Although many continue to use the term <em>SSL</em> to refer to the current secure protocol, in this book, I use the more accurate <em>TLS</em>.</p>
</aside>

<p>First, we&#8217;ll see what happens when we run the playbook in <a data-type="xref" href="#WEB_NOTLS_PLAYBOOK"/>, and then we&#8217;ll go over the contents of the playbook in detail.</p>
<div id="WEB_NOTLS_PLAYBOOK" data-type="example">
<h5>web-notls.yml</h5>

<pre data-type="programlisting"></pre></div>
<aside id="YAML_TRUTHY" data-type="sidebar">
<h5>Why Do You Use <em>True</em> in One Place and <em>Yes</em> in Another?</h5>
<p>Sharp-eyed readers might have noticed that <a data-type="xref" href="#WEB_NOTLS_PLAYBOOK"/> uses <code>True</code> in
one spot in the playbook (to enable <code>sudo</code>) and <code>yes</code> in another spot in the
playbook (to update the apt cache).</p>

<p>Ansible is pretty flexible in how you represent truthy and falsey values in
playbooks.<a data-type="indexterm" data-primary="truthy and falsey values in playbooks"/> Strictly speaking, module arguments (for example, <code>update_cache=yes</code>) are treated
differently from values elsewhere in playbooks (for example, <code>sudo: True</code>). Values elsewhere
are handled by the YAML parser and so use the YAML conventions of truthiness:</p>
<dl>
<dt>YAML truthy</dt>
<dd>
<p><code>true</code>, <code>True</code>, <code>TRUE</code>, <code>yes</code>, <code>Yes</code>, <code>YES</code>, <code>on</code>, <code>On</code>, <code>ON</code>, <code>y</code>, <code>Y</code></p>
</dd>
<dt>YAML falsey</dt>
<dd>
<p><code>false</code>, <code>False</code>, <code>FALSE</code>, <code>no</code>, <code>No</code>, <code>NO</code>, <code>off</code>, <code>Off</code>, <code>OFF</code>, <code>n</code>, <code>N</code></p>
</dd>
</dl>

<p>Module arguments are passed as strings and use Ansible&#8217;s internal
conventions:</p>
<dl>
<dt>module arg truthy</dt>
<dd>
<p><code>yes</code>, <code>on</code>, <code>1</code>, <code>true</code></p>
</dd>
<dt>module arg falsey</dt>
<dd>
<p><code>no</code>, <code>off</code>, <code>0</code>, <code>false</code></p>
</dd>
</dl>

<p>I tend to follow the examples in the official Ansible documentation. These
typically use <code>yes</code> and <code>no</code> when passing arguments to modules (since that&#8217;s
consistent with the module documentation), and <code>True</code> and <code>False</code> elsewhere in
playbooks.</p>
</aside>








<section data-type="sect2">
<h2>Specifying an Nginx Config File</h2>

<p>This playbook requires two additional files before we can run it. First, we need
to define an Nginx configuration file.<a data-type="indexterm" data-primary="playbooks" data-secondary="simple example, configuring host to run Nginx" data-tertiary="specifying Nginx config file"/><a data-type="indexterm" data-primary="Nginx" data-secondary="configuring host to run" data-tertiary="specifying config file"/></p>

<p>Nginx ships with a configuration file that works out of the box if you just want
to serve static files. But you&#8217;ll almost always need to customize this, so we&#8217;ll
overwrite the default configuration file with our own as part
of this playbook. As you&#8217;ll see later, we&#8217;ll need to modify this configuration
file to support TLS. <a data-type="xref" href="#NGINX_CONF_NOTLS"/> shows a basic Nginx config file.  Put it in
<em>playbooks/files/nginx.conf</em>.<span data-type="footnote">Note that while we call this file <em>nginx.conf</em>, it replaces the <em>sites-enabled/default</em> Nginx server block config file, not the main <em>/etc/nginx.conf</em> config file.</span></p>
<div data-type="note">
<p>An Ansible convention is to keep files in a subdirectory named <em>files</em>, and
Jinja2 templates in a subdirectory named <em>templates</em>. I follow this
convention throughout the book.<a data-type="indexterm" data-primary="templates subdirectory"/><a data-type="indexterm" data-primary="files subdirectory"/></p>
</div>
<div id="NGINX_CONF_NOTLS" data-type="example">
<h5>files/nginx.conf</h5>

<pre data-type="programlisting" data-code-language="nginx"></pre></div>
</section>













<section data-type="sect2">
<h2>Creating a Custom Home Page</h2>

<p>Let&#8217;s add a custom home page. We&#8217;re going to use Ansible&#8217;s template functionality
so that Ansible will generate the file from a template.<a data-type="indexterm" data-primary="templates" data-secondary="home page"/><a data-type="indexterm" data-primary="playbooks" data-secondary="simple example, configuring host to run Nginx" data-tertiary="creating custom home page"/> Put the content shown in
<a data-type="xref" href="#HOME_PAGE_TEMPLATE"/> in <em>playbooks/templates/index.html.j2</em>.</p>
<div id="HOME_PAGE_TEMPLATE" data-type="example">
<h5>playbooks/templates/index.html.j2</h5>

<pre data-type="programlisting" data-code-language="html">&lt;html&gt;
  &lt;head&gt;
    &lt;title&gt;Welcome to ansible&lt;/title&gt;
  &lt;/head&gt;
  &lt;body&gt;
  &lt;h1&gt;nginx, configured by Ansible&lt;/h1&gt;
  &lt;p&gt;If you can see this, Ansible successfully installed nginx.&lt;/p&gt;

  &lt;p&gt;{{ ansible_managed }}&lt;/p&gt;
  &lt;/body&gt;
&lt;/html&gt;</pre></div>

<p>This template references a special Ansible variable named <code>ansible_managed</code>.
When Ansible renders this template,<a data-type="indexterm" data-primary="ansible_managed variable"/> it will replace this variable with
information about when the template file was generated.
<a data-type="xref" href="#web_page_screenshot"/> shows a web browser displaying the
generated HTML.</p>

<figure id="web_page_screenshot">
<img src="images/aur2_0202.png" alt="Welcome page"/>
<figcaption>Rendered HTML</figcaption>
</figure>
</section>













<section data-type="sect2">
<h2>Creating a Webservers Group</h2>

<p>Let&#8217;s create a <code>webservers</code> group in our inventory file so that we can refer to
this group in our playbook. <a data-type="indexterm" data-primary="webservers group, creating"/><a data-type="indexterm" data-primary="Nginx" data-secondary="configuring host to run" data-tertiary="creating webservers group"/><a data-type="indexterm" data-primary="playbooks" data-secondary="simple example, configuring host to run Nginx" data-tertiary="creating webservers group"/>For now, this group will contain our test server.</p>

<p>Inventory files are in the <em>.ini</em> file format. We&#8217;ll go into this format in detail later in the book. Edit your <em>playbooks/hosts</em> file to put a <code>[webservers]</code> line above the <code>testserver</code> line, as shown in <a data-type="xref" href="#example-2-5"/>. This indicates that <code>testserver</code> is in the <code>webservers</code> group.</p>
<div id="example-2-5" data-type="example">
<h5>playbooks/hosts</h5>

<pre data-type="programlisting">[webservers]
testserver ansible_host=127.0.0.1 ansible_port=2222</pre></div>

<p>You should now be able to ping the <code>webservers</code> group<a data-type="indexterm" data-primary="ping module, invoking" data-secondary="pinging webservers group"/> by using the <code>ansible</code>
command-line tool:</p>

<pre data-type="programlisting" data-code-language="console">$ ansible webservers -m ping</pre>

<p>The output should look like this:</p>

<pre data-type="programlisting">testserver | success &gt;&gt; {
    "changed": false,
    "ping": "pong"
}</pre>
</section>





</section>













<section data-type="sect1">
<h1>Running the Playbook</h1>

<p>The <code>ansible-playbook</code> command executes playbooks.<a data-type="indexterm" data-primary="playbooks" data-secondary="simple example, configuring host to run Nginx" data-tertiary="running the playbook" data-startref="ix_playbkrun"/><a data-type="indexterm" data-primary="ansible-playbook command"/> To run the playbook, use this command:</p>

<pre data-type="programlisting" data-code-language="console">$ ansible-playbook web-notls.yml</pre>

<p><a data-type="xref" href="#output_ansible_playbook"/> shows what the output should look like.</p>
<div id="output_ansible_playbook" data-type="example">
<h5>Output of ansible-playbook</h5>

<pre data-type="programlisting">PLAY [Configure webserver with nginx] *********************************

GATHERING FACTS ***************************************************************
ok: [testserver]

TASK: [install nginx] *********************************************************
changed: [testserver]

TASK: [copy nginx config file] ************************************************
changed: [testserver]

TASK: [enable configuration] **************************************************
ok: [testserver]

TASK: [copy index.html] *******************************************************
changed: [testserver]

TASK: [restart nginx] *********************************************************
changed: [testserver]

PLAY RECAP ********************************************************************
testserver                 : ok=6    changed=4    unreachable=0    failed=0</pre></div>
<aside data-type="sidebar">
<h5>Cowsay</h5>
<p>If you have the <em>cowsay</em> program installed on your local machine, <a data-type="indexterm" data-primary="cowsay program, disabling"/>Ansible output will look like this instead:</p>

<pre data-type="programlisting"> _______________________________________
&lt; PLAY [Configure webserver with nginx] &gt;
 ---------------------------------------
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||</pre>

<p>If you<a data-type="indexterm" data-primary="ANSIBLE_NOCOWS environment variable"/> don&#8217;t want to see the cows, you can disable cowsay by
setting the <span class="keep-together"><code>ANSIBLE_NOCOWS</code></span> environment variable like this:</p>

<pre data-type="programlisting" data-code-language="console">$ export ANSIBLE_NOCOWS=1</pre>

<p>You can also disable cowsay by adding the following to your <em>ansible.cfg</em> file:</p>

<pre data-type="programlisting">[defaults]
nocows = 1</pre>
</aside>

<p>If you didn&#8217;t get any errors,<span data-type="footnote">If you encountered an error, you might want to skip to <a data-type="xref" href="#DEBUGGING"/> for assistance on debugging.</span> you should be able to point
your browser to <a href="http://localhost:8080"><em class="hyperlink">http://localhost:8080</em></a> and see the custom HTML page, as shown in
<a data-type="xref" href="#web_page_screenshot"/>.</p>
<div data-type="tip">
<p>If your playbook file is marked as executable<a data-type="indexterm" data-primary="shebangs"/><a data-type="indexterm" data-primary="#! (shebang), lines beginning with"/> and starts with a line that looks like
this:<span data-type="footnote">Colloquially referred to as a <em>shebang</em>.</span></p>

<pre data-type="programlisting">#!/usr/bin/env ansible-playbook</pre>

<p>then you can execute it by invoking it directly, like this:</p>

<pre data-type="programlisting" data-code-language="console">$ ./web-notls.yml</pre>
</div>
</section>













<section data-type="sect1">
<h1>Playbooks Are YAML</h1>

<p>Ansible playbooks are written in YAML syntax. <em>YAML</em> is a file format similar in<a data-type="indexterm" data-primary="playbooks" data-secondary="simple example, configuring host to run Nginx" data-tertiary="running the playbook" data-startref="ix_playbkrun"/><a data-type="indexterm" data-primary="Nginx" data-secondary="configuring host to run" data-startref="ix_Nginxconf"/><a data-type="indexterm" data-primary="playbooks" data-secondary="simple example, configuring host to run Nginx" data-startref="ix_playbksimex"/>
intent to JSON, but generally easier for humans to read and write. Before we go
over the playbook, let&#8217;s cover the concepts of YAML that are
most important for writing playbooks.<a data-type="indexterm" id="ix_YAML" data-primary="YAML"/><a data-type="indexterm" id="ix_playbkYAML" data-primary="playbooks" data-secondary="YAML syntax"/></p>








<section data-type="sect2">
<h2>Start of File</h2>

<p>YAML files are supposed to start with three dashes to <a data-type="indexterm" data-primary="YAML" data-secondary="start of file"/><a data-type="indexterm" data-primary="start of file (YAML)"/>indicate the beginning of
the document:</p>

<pre data-type="programlisting" data-code-language="yaml"></pre>

<p>However, if you forget to put those three dashes at the top of your playbook
files, Ansible won&#8217;t complain.</p>
</section>













<section data-type="sect2">
<h2>Comments</h2>

<p>Comments start with a number sign and apply to the end of the line, the same as in<a data-type="indexterm" data-primary="comments in YAML"/><a data-type="indexterm" data-primary="YAML" data-secondary="comments"/>
shell scripts, Python, and Ruby:</p>

<pre data-type="programlisting" data-code-language="yaml+jinja"># This is a YAML comment</pre>
</section>













<section data-type="sect2">
<h2>Strings</h2>

<p>In general, YAML strings don&#8217;t have to be quoted, although you can quote them if
you prefer.<a data-type="indexterm" data-primary="strings" data-secondary="in YAML"/><a data-type="indexterm" data-primary="YAML" data-secondary="strings"/> Even if there are spaces, you don&#8217;t need to quote them. For example,
this is a string in YAML:</p>

<pre data-type="programlisting" data-code-language="yaml+jinja">this is a lovely sentence</pre>

<p>The JSON equivalent is as follows:</p>

<pre data-type="programlisting" data-code-language="yaml+jinja">"this is a lovely sentence"</pre>

<p>In some scenarios in Ansible, you will need to quote strings. These typically involve the use of <code>{{ braces }}</code> for variable substitution. We&#8217;ll get to those later.<a data-type="indexterm" data-primary="{{ }} (braces notation)" data-secondary="variable substitution"/></p>
</section>













<section data-type="sect2">
<h2>Booleans</h2>

<p>YAML has a native Boolean type, and provides you with a wide variety of strings<a data-type="indexterm" data-primary="Boolean type in YAML"/><a data-type="indexterm" data-primary="YAML" data-secondary="Boolean type"/>
that can be interpreted as true or false, which we covered in <a data-type="xref" href="#YAML_TRUTHY"/>. Personally, I always use <code>True</code> and <code>False</code> in my Ansible playbooks.</p>

<p>For example, this is a Boolean in YAML:</p>

<pre data-type="programlisting" data-code-language="yaml+jinja">True</pre>

<p>The JSON equivalent is this:</p>

<pre data-type="programlisting" data-code-language="json">true</pre>
</section>













<section data-type="sect2">
<h2>Lists</h2>

<p>YAML lists are like arrays in JSON and Ruby, or lists in Python.<a data-type="indexterm" data-primary="YAML" data-secondary="lists (or sequences)"/><a data-type="indexterm" data-primary="sequences in YAML"/><a data-type="indexterm" data-primary="lists" data-secondary="in YAML"/> Technically,
these are called <em>sequences</em> in YAML, but I call them <em>lists</em> here to be
consistent with the official Ansible documentation.</p>

<p>They are delimited with hyphens, like this:</p>

<pre data-type="programlisting" data-code-language="yaml+jinja">- My Fair Lady
- Oklahoma
- The Pirates of Penzance</pre>

<p>The JSON equivalent is shown here:</p>

<pre data-type="programlisting" data-code-language="json">[
  "My Fair Lady",
  "Oklahoma",
  "The Pirates of Penzance"
]</pre>

<p>(Note again that we don&#8217;t have to quote the strings in YAML, even though they have spaces in them.)</p>

<p>YAML also supports an<a data-type="indexterm" data-primary="inline lists format (YAML)"/> inline format for lists, which looks like this:</p>

<pre data-type="programlisting">[My Fair Lady, Oklahoma, The Pirates of Penzance]</pre>
</section>













<section data-type="sect2">
<h2>Dictionaries</h2>

<p>YAML <em>dictionaries</em> are like objects in JSON, dictionaries in Python, or hashes in
Ruby.<a data-type="indexterm" data-primary="dictionaries" data-secondary="YAML"/><a data-type="indexterm" data-primary="YAML" data-secondary="dictionaries"/> Technically, these are called <em>mappings</em> in YAML, but I call them
<em>dictionaries</em> here to be consistent with the official Ansible documentation.</p>

<p>They look like this:</p>

<pre data-type="programlisting" data-code-language="yaml+jinja">address: 742 Evergreen Terrace
city: Springfield
state: North Takoma</pre>

<p>The JSON equivalent is shown here:</p>

<pre data-type="programlisting" data-code-language="json">{
  "address": "742 Evergreen Terrace",
  "city": "Springfield",
  "state": "North Takoma"
}</pre>

<p>YAML also supports an inline format for dictionaries, which looks like this:</p>

<pre data-type="programlisting">{address: 742 Evergreen Terrace, city: Springfield, state: North Takoma}</pre>
</section>













<section data-type="sect2" id="line_folding">
<h2>Line Folding</h2>

<p>When writing playbooks, you&#8217;ll often encounter situations where you&#8217;re passing
many arguments to a module.<a data-type="indexterm" data-primary="YAML" data-secondary="line folding"/> For aesthetics, you might want to break this up across
multiple lines in your file, but you want Ansible to treat the string as if it
were a single line.</p>

<p>You can do this with YAML by using line folding with the greater than (<code>&gt;</code>)
character.<a data-type="indexterm" data-primary="&gt;, line folding in YAML"/><a data-type="indexterm" data-primary="line folding in YAML"/> The YAML parser will replace line breaks with spaces. For example:</p>

<pre data-type="programlisting" data-code-language="yaml+jinja">address: &gt;
    Department of Computer Science,
    A.V. Williams Building,
    University of Maryland
city: College Park
state: Maryland</pre>

<p>The JSON equivalent is as follows:</p>

<pre data-type="programlisting" data-code-language="json">{
  "address": "Department of Computer Science, A.V. Williams Building,
              University of Maryland",
  "city": "College Park",
  "state": "Maryland"
}</pre>
</section>





</section>













<section data-type="sect1">
<h1>Anatomy of a Playbook</h1>

<p>Let&#8217;s take a look at our playbook from the perspective of a YAML file.<a data-type="indexterm" data-primary="YAML" data-startref="ix_YAML"/><a data-type="indexterm" data-primary="playbooks" data-secondary="YAML syntax" data-startref="ix_playbkYAML"/><a data-type="indexterm" id="ix_playbkanat" data-primary="playbooks" data-secondary="anatomy of"/> Here it is again, in <a data-type="xref" href="#example2-7"/>.</p>
<div id="example2-7" data-type="example">
<h5>web-notls.yml</h5>

<pre data-type="programlisting" data-code-language="yaml+jinja"></pre></div>

<p>In <a data-type="xref" href="#example2-8"/>, we see the JSON equivalent of this file.</p>
<div id="example2-8" data-type="example">
<h5>JSON equivalent of web-notls.yml</h5>

<pre data-type="programlisting" data-code-language="json"></pre></div>
<div data-type="note">
<p>A valid JSON file is also a valid YAML file.<a data-type="indexterm" data-primary="JSON" data-secondary="valid file"/><a data-type="indexterm" data-primary="YAML" data-secondary="valid file, JSON and"/> This is because YAML allows strings to be quoted, considers <code>true</code> and <code>false</code> to be valid Booleans, and has inline lists and dictionary syntaxes that are the same as JSON arrays and objects. But don&#8217;t write your playbooks as JSON—the whole point of YAML is that it&#8217;s easier for people to read.</p>
</div>








<section data-type="sect2">
<h2>Plays</h2>

<p>Looking at either the YAML or JSON representation, it should be clear that a
playbook is a list of dictionaries.<a data-type="indexterm" data-primary="playbooks" data-secondary="anatomy of" data-tertiary="plays"/> Specifically, a playbook is a list of
<em>plays</em>.<a data-type="indexterm" data-primary="plays"/></p>

<p>Here&#8217;s the play<span data-type="footnote">Actually, it&#8217;s a list that contains a single play.</span> from our example:</p>

<pre data-type="programlisting" data-code-language="yaml+jinja">- name: Configure webserver with nginx
  hosts: webservers
  become: True
  tasks:
    - name: install nginx
      apt: name=nginx update_cache=yes

    - name: copy nginx config file
      copy: src=files/nginx.conf dest=/etc/nginx/sites-available/default

    - name: enable configuration
      file: &gt;
        dest=/etc/nginx/sites-enabled/default
        src=/etc/nginx/sites-available/default
        state=link

    - name: copy index.html
      template: src=templates/index.html.j2
               dest=/usr/share/nginx/html/index.html mode=0644


    - name: restart nginx
      service: name=nginx state=restarted</pre>

<p>Every play must contain the following:</p>

<ul>
<li>
<p>A set of <em>hosts</em> to configure</p>
</li>
<li>
<p>A list of <em>tasks</em> to be executed on those hosts</p>
</li>
</ul>

<p>Think of a play as the thing that connects hosts to tasks.<a data-type="indexterm" data-primary="hosts" data-secondary="in plays"/><a data-type="indexterm" data-primary="tasks" data-secondary="in plays"/></p>

<p>In addition to specifying hosts and tasks, plays also support optional settings. We&#8217;ll get into those later, but here are three common ones:</p>
<dl>
<dt><code>name</code></dt>
<dd>
<p>    A comment that describes what the play is about. Ansible prints this out
when the play starts to run.<a data-type="indexterm" data-primary="name setting (in plays)"/></p>
</dd>
<dt><code>become</code></dt>
<dd>
<p>    If true, Ansible will run every task by becoming (by default) the root
user.<a data-type="indexterm" data-primary="become setting (in plays)"/><a data-type="indexterm" data-primary="root user"/> This is useful when managing Ubuntu servers, since by default you cannot SSH as the root user.</p>
</dd>
<dt><code>vars</code></dt>
<dd>
<p>    A list of variables and values.<a data-type="indexterm" data-primary="variables" data-secondary="vars setting in plays"/> You&#8217;ll see this in action later in this
chapter.</p>
</dd>
</dl>
</section>













<section data-type="sect2">
<h2>Tasks</h2>

<p>Our example playbook contains one play that has five tasks.<a data-type="indexterm" data-primary="tasks" data-secondary="in example playbook"/><a data-type="indexterm" data-primary="playbooks" data-secondary="anatomy of" data-tertiary="tasks"/> Here&#8217;s the first
task of that play:</p>

<pre data-type="programlisting" data-code-language="yaml+jinja">- name: install nginx
  apt: name=nginx update_cache=yes</pre>

<p>The <code>name</code> is optional, so it&#8217;s perfectly <a data-type="indexterm" data-primary="names" data-secondary="name setting for tasks"/>valid to write a task like this:</p>

<pre data-type="programlisting" data-code-language="yaml+jinja">- apt: name=nginx update_cache=yes</pre>

<p>Even though names are optional, I recommend you use them because they serve as good reminders for the intent of the task. (Names will be very useful when somebody else is trying to understand your playbook, including yourself in six months.) As you&#8217;ve seen, Ansible will print out the name of a task when it runs. Finally, as you&#8217;ll see in
<a data-type="xref" href="#DEBUGGING"/>, you can use the <code>--start-at-task &lt;task name&gt;</code> flag to tell <code>ansible-playbook</code> to start a playbook in the middle of a play, but you need to reference the task by name.</p>

<p>Every task must contain a key with the name of a module and a value with the
arguments to that module.<a data-type="indexterm" data-primary="modules" data-secondary="name and arguments in tasks"/><a data-type="indexterm" data-primary="apt module" data-secondary="and arguments in a task"/> In the preceding example, the module name is <code>apt</code> and the
arguments are <code>name=nginx update_cache=yes</code>.</p>

<p>These arguments tell the <code>apt</code> module to install the package named <em>nginx</em> and to
update the package cache (the equivalent of doing an <code>apt-get update</code>) before
installing the package.</p>

<p>It&#8217;s important to understand that, from the point of the view of the YAML parser used by the Ansible frontend, the arguments are treated as a string, not as a dictionary.<a data-type="indexterm" data-primary="YAML" data-secondary="line folding" data-tertiary="for module name and arguments in playbook tasks"/> This means that if you want to break arguments into multiple lines, you need to use the YAML folding syntax, like this:</p>

<pre data-type="programlisting" data-code-language="yaml+jinja">- name: install nginx
  apt: &gt;
      name=nginx
      update_cache=yes</pre>

<p>Ansible also supports a task syntax that will let you specify module arguments as
a YAML dictionary, which is helpful when using modules that support complex
<span class="keep-together">arguments</span>. We&#8217;ll cover that in <a data-type="xref" href="#COMPLEX_ARGS"/>.</p>

<p>Ansible also supports an older syntax that uses <code>action</code> as the key and puts the name of the module in the value. The preceding example also can be written as follows:</p>

<pre data-type="programlisting" data-code-language="yaml+jinja">- name: install nginx
  action: apt name=nginx update_cache=yes</pre>
</section>













<section data-type="sect2">
<h2>Modules</h2>

<p><em>Modules</em> are scripts that come packaged with Ansible and perform some kind of action on a host.<span data-type="footnote">The modules that ship with Ansible all are written in Python, but modules can be written in any language.</span> Admittedly, that&#8217;s a pretty generic description, but there&#8217;s enormous variety across Ansible modules.<a data-type="indexterm" data-primary="modules"/><a data-type="indexterm" data-primary="playbooks" data-secondary="anatomy of" data-tertiary="modules"/> The modules we use in this chapter are as follows:</p>
<dl>
<dt><code>apt</code></dt>
<dd>
<p>Installs or removes packages by using the apt package manager</p>
</dd>
<dt><code>copy</code></dt>
<dd>
<p>Copies a file from local machine to the hosts</p>
</dd>
<dt><code>file</code></dt>
<dd>
<p>Sets the attribute of a file, symlink, or directory</p>
</dd>
<dt><code>service</code></dt>
<dd>
<p>Starts, stops, or restarts a service</p>
</dd>
<dt><code>template</code></dt>
<dd>
<p>Generates a file from a template and copies it to the hosts</p>
</dd>
</dl>
<aside data-type="sidebar">
<h5>Viewing Ansible Module Documentation</h5>
<p>Ansible ships with the <code>ansible-doc</code> command-line tool, which shows documentation about modules.<a data-type="indexterm" data-primary="modules" data-secondary="documentation for"/><a data-type="indexterm" data-primary="documentation" data-secondary="for Ansible modules"/><a data-type="indexterm" data-primary="ansible-doc command-line tool"/> Think of it as man pages for Ansible modules. For example, to show the documentation for the <code>service</code> module, run this:</p>

<pre data-type="programlisting" data-code-language="console">$ ansible-doc service</pre>

<p>If you use macOS, there&#8217;s a wonderful documentation viewer called
<a href="http://kapeli.com/dash">Dash</a> that has support for Ansible. Dash indexes all of the Ansible module documentation.<a data-type="indexterm" data-primary="Dash"/><a data-type="indexterm" data-primary="macOS" data-secondary="Dash documentation viewer"/> It&#8217;s a commercial tool ($24.99 as of this writing), but I find it invaluable.</p>
</aside>

<p>Recall from the first chapter that Ansible executes a task on a host by
generating a custom script based on the module name and arguments, and then copies this script to the host and runs it.</p>

<p>More than 200 modules ship with Ansible, and this number grows with every release. You can also find third-party Ansible modules out there, or write your own.</p>
</section>













<section data-type="sect2">
<h2>Putting It All Together</h2>

<p>To sum up, a playbook contains one or more plays. A play associates an unordered set of hosts with an ordered list of tasks. Each task is associated with exactly one module.<a data-type="indexterm" data-primary="playbooks" data-secondary="anatomy of" data-tertiary="summary of contents"/></p>

<p><a data-type="xref" href="#erd_figure"/> is an entity-relationship diagram that depicts this
relationship between playbooks, plays, hosts, tasks, and modules.</p>

<figure id="erd_figure">
<img src="images/aur2_0203.png" alt="Ansible entities"/>
<figcaption>Entity-relationship diagram</figcaption>
</figure>
</section>





</section>













<section data-type="sect1">
<h1>Did Anything Change? Tracking Host State</h1>

<p>When you run <code>ansible-playbook</code>, Ansible outputs status information for each task it executes in the play.<a data-type="indexterm" data-primary="playbooks" data-secondary="tracking host state"/><a data-type="indexterm" data-primary="hosts" data-secondary="tracking host state"/></p>

<p>Looking back at <a data-type="xref" href="#output_ansible_playbook"/>, notice that the status for some of the tasks is <code>changed</code>, and the status for some others is <code>ok</code>. For example, the <code>install nginx</code> task <a data-type="indexterm" data-primary="tasks" data-secondary="changed status"/>has status <code>changed</code>, which appears as yellow on my terminal:</p>

<pre data-type="programlisting">TASK: [install nginx] *********************************************************
changed: [testserver]</pre>

<p>The <code>enable configuration</code>, on the other hand,<a data-type="indexterm" data-primary="tasks" data-secondary="ok status"/> has status <code>ok</code>, which appears as green on my terminal:</p>

<pre data-type="programlisting">TASK: [enable configuration] **************************************************
ok: [testserver]</pre>

<p>Any Ansible task that runs has the potential to change the state of the host in
some way. Ansible modules will first check to see whether the state of the host needs
to be changed before taking any action. If the state of the host matches the
arguments of the module, Ansible takes no action on the host and responds
with a state of <code>ok</code>.</p>

<p>On the other hand, if there is a difference between the state of the host and
the arguments to the module, Ansible will change the state of the host and
return <code>changed</code>.</p>

<p>In the example output just shown, the <code>install nginx</code> task was changed,
which meant that before I ran the playbook, the <em>nginx</em> package had not
previously been installed on the host.  The <code>enable configuration</code> task was
unchanged, which meant that there was already a configuration file on the
server that was identical to the file I was copying over. The reason for this is
that the <em>nginx.conf</em> file I used in my playbook is the same as the <em>nginx.conf</em>
file that gets installed by the <em>nginx</em> package on Ubuntu.</p>

<p>As you&#8217;ll see later in this chapter, Ansible&#8217;s detection of state change can
be used to trigger additional actions through the use of <em>handlers</em>.<a data-type="indexterm" data-primary="handlers"/> But, even
without using handlers, it is still a useful form of feedback to see whether
your hosts are changing state as the playbook runs.<a data-type="indexterm" data-primary="playbooks" data-secondary="anatomy of" data-startref="ix_playbkanat"/></p>
</section>













<section data-type="sect1">
<h1>Getting Fancier: TLS Support</h1>

<p>Let&#8217;s move on to a more complex example: we&#8217;re going to modify the previous playbook so that our web servers support TLS.<a data-type="indexterm" id="ix_TLS" data-primary="TLS (Transport Layer Security)"/><a data-type="indexterm" id="ix_playbkTLS" data-primary="playbooks" data-secondary="modifying simple example to add TLS support"/> The new features here are as follows:</p>

<ul>
<li>
<p>Variables</p>
</li>
<li>
<p>Handlers</p>
</li>
</ul>

<p><a data-type="xref" href="#WEB_TLS_PLAYBOOK"/> shows what our playbook looks like with TLS support.</p>
<div id="WEB_TLS_PLAYBOOK" data-type="example">
<h5>web-tls.yml</h5>

<pre data-type="programlisting" data-code-language="yaml+jinja"></pre></div>








<section data-type="sect2">
<h2>Generating a TLS Certificate</h2>

<p>We need to manually generate a TLS certificate. <a data-type="indexterm" data-primary="TLS (Transport Layer Security)" data-secondary="generating a TLS certificate"/><a data-type="indexterm" data-primary="certificates" data-secondary="generating a TLS certificate"/>In a
production environment, you&#8217;d purchase your TLS certificate from a certificate
authority, or use a free service such as Let&#8217;s Encrypt, which Ansible supports via
the <code>letsencrypt</code> module. We&#8217;ll use a self-signed certificate, since we can generate those for
free.</p>

<p>Create a <em>files</em> subdirectory of your <em>playbooks</em> directory, and then generate the TLS certificate and key:</p>

<pre data-type="programlisting" data-code-language="console">$ mkdir files
$ openssl req -x509 -nodes -days 3650 -newkey rsa:2048 \
    -subj /CN=localhost \
    -keyout files/nginx.key -out files/nginx.crt</pre>

<p>This should generate the files <em>nginx.key</em> and <em>nginx.crt</em> in the <em>files</em>
directory. The certificate has an expiration date of 10 years (3,650 days) from the day you created it.</p>
</section>













<section data-type="sect2">
<h2>Variables</h2>

<p>The play in our playbook now has a section called <code>vars</code>:</p>

<pre data-type="programlisting" data-code-language="yaml+jinja">vars:
  key_file: /etc/nginx/ssl/nginx.key
  cert_file: /etc/nginx/ssl/nginx.crt
  conf_file: /etc/nginx/sites-available/default
  server_name: localhost</pre>

<p>This section defines four <a data-type="indexterm" data-primary="variables" data-secondary="in playbook with TLS support"/>variables and assigns a value to each variable.</p>

<p>In our example, each value is a string (e.g., <code>/etc/nginx/ssl/nginx.key</code>),
but any valid YAML can be used as the value of a variable. You can use lists
and dictionaries in addition to strings and Booleans.</p>

<p>Variables can be used in tasks, as well as in template files.<a data-type="indexterm" data-primary="tasks" data-secondary="variables in"/> You reference
variables by using the <code>{{ braces }}</code> notation. <a data-type="indexterm" data-primary="{{ }} (braces notation)" data-secondary="referencing variables"/>Ansible replaces these braces
with the value of the variable.</p>

<p>Consider this task in the playbook:</p>

<pre data-type="programlisting" data-code-language="yaml+jinja">- name: copy TLS key
  copy: src=files/nginx.key dest={{ key_file }} owner=root mode=0600</pre>

<p>Ansible will substitute <code>{{ key_file }}</code> with <code>/etc/nginx/ssl/nginx.key</code> when it
executes this task.</p>
<aside data-type="sidebar">
<h5>When Quoting Is Necessary</h5>
<p>If you reference a variable right after specifying the module, the YAML parser will misinterpret the variable reference as the beginning of an inline dictionary.<a data-type="indexterm" data-primary="strings" data-secondary="quoting in arguments"/> Consider the following example:</p>

<pre data-type="programlisting" data-code-language="yaml+jinja">- name: perform some task
  command: {{ myapp }} -a foo</pre>

<p>Ansible will try to parse the first part of <code>{{ myapp }} -a foo</code> as a dictionary
instead of a string, and will return an error. In this case, you must quote the
arguments:</p>

<pre data-type="programlisting" data-code-language="yaml+jinja">- name: perform some task
  command: "{{ myapp }} -a foo"</pre>

<p>A similar problem arises if your argument contains a colon. For example:</p>

<pre data-type="programlisting" data-code-language="yaml+jinja">- name: show a debug message
  debug: msg="The debug module will print a message: neat, eh?"</pre>

<p>The colon in the <code>msg</code> argument trips up the YAML parser. To get around this, you need to quote the entire argument string.</p>

<p>Unfortunately, just quoting the argument string won&#8217;t resolve the problem, either:</p>

<pre data-type="programlisting" data-code-language="yaml+jinja">- name: show a debug message
  debug: "msg=The debug module will print a message: neat, eh?"</pre>

<p>This will make the YAML parser happy, but the output isn&#8217;t what you expect:</p>

<pre data-type="programlisting">TASK: [show a debug message] ************************************************
ok: [localhost] =&gt; {
    "msg": "The"
}</pre>

<p>The <code>debug</code> module&#8217;s <code>msg</code> argument requires a quoted string to capture the
spaces.<a data-type="indexterm" data-primary="debug module" data-secondary="msg argument, requiring quoted string"/> In this particular case, we need to quote both the whole argument string
and the <code>msg</code> argument. Ansible supports alternating single and double quotes,
so you can do this:</p>

<pre data-type="programlisting" data-code-language="yaml+jinja">- name: show a debug message
  debug: "msg='The debug module will print a message: neat, eh?'"</pre>

<p>This yields the expected output:</p>

<pre data-type="programlisting">TASK: [show a debug message] ************************************************
ok: [localhost] =&gt; {
    "msg": "The debug module will print a message: neat, eh?"
}</pre>

<p>Ansible is pretty good at generating meaningful error messages if you forget to
put quotes in the right places and end up with invalid YAML.</p>
</aside>
</section>













<section data-type="sect2">
<h2>Generating the Nginx Configuration Template</h2>

<p>If you&#8217;ve done web programming, you&#8217;ve likely used a template system to generate
HTML.<a data-type="indexterm" data-primary="configuration files" data-secondary="generating template for Nginx configuration"/><a data-type="indexterm" data-primary="templates" data-secondary="generating for Nginx configuration"/> In case you haven&#8217;t, a <em>template</em> is just a text file that has special
syntax for specifying variables that should be replaced by values. If you&#8217;ve
ever received an automated email from a company, it&#8217;s probably using an email
template, as shown in <a data-type="xref" href="#example2-10"/>.</p>
<div id="example2-10" data-type="example">
<h5>An email template</h5>

<pre data-type="programlisting" data-code-language="jinja">Dear {{ name }},

You have {{ num_comments }} new comments on your blog: {{ blog_name }}.</pre></div>

<p>Ansible&#8217;s use case isn&#8217;t HTML pages or emails—it&#8217;s configuration files. You
don&#8217;t want to hand-edit configuration files if you can avoid it. This is
especially true if you have to reuse the same bits of configuration data (say,
the IP address of your queue server or your database credentials) across
multiple configuration files. It&#8217;s much better to take the info that&#8217;s
specific to your deployment, record it in one location, and then
generate all of the files that need this information from templates.</p>

<p>Ansible uses the Jinja2 template engine to implement templating. If you&#8217;ve ever
used a templating library such as Mustache, ERB, or the Django template system, Jinja2 will
feel very familiar.<a data-type="indexterm" data-primary="Jinja2 template engine" data-secondary="generating template for Nginx configuration"/></p>

<p>Nginx&#8217;s configuration file needs information about where to find the TLS
key and certificate. We&#8217;re going to use Ansible&#8217;s templating functionality to
define this configuration file so that we can avoid hardcoding values that
might change.</p>

<p>In your <em>playbooks</em> directory, create a <em>templates</em> subdirectory and create the
file <em>templates/nginx.conf.j2</em>, as shown in <a data-type="xref" href="#NGINX_CONF_TEMPLATE"/>.</p>
<div id="NGINX_CONF_TEMPLATE" data-type="example">
<h5>templates/nginx.conf.j2</h5>

<pre data-type="programlisting" data-code-language="nginx"></pre></div>

<p>We use the <code>.j2</code> extension to indicate that the file is a Jinja2 template.<a data-type="indexterm" data-primary=".j2 file extension" data-primary-sortas="j2 file extension"/>
However, you can use a different extension if you like; Ansible doesn&#8217;t care.</p>

<p>In our template, we reference three variables:</p>
<dl>
<dt><code>server_name</code></dt>
<dd>
<p>The hostname of the web server (e.g., <code>www.example.com</code>)</p>
</dd>
<dt><code>cert_file</code></dt>
<dd>
<p>The path to the TLS certificate</p>
</dd>
<dt><code>key_file</code></dt>
<dd>
<p>The path to the TLS private key</p>
</dd>
</dl>

<p>We define these variables in the playbook.</p>

<p>Ansible also uses the Jinja2 template engine to evaluate variables in playbooks.<a data-type="indexterm" data-primary="variables" data-secondary="evaluating in playbooks with Jinja2"/>
Recall that we saw the <code>{{ conf_file }}</code> syntax in the playbook itself.</p>
<div data-type="note">
<p>Early versions of Ansible used a dollar sign (<code>$</code>) to do variable interpolation in
playbooks instead of the braces. You used to dereference the variable <em>foo</em> by
writing <code>$foo</code>, whereas now you write <code>{{ foo }}</code>. The dollar sign syntax has been
deprecated; if you encounter it in an example playbook you find on the internet,
then you&#8217;re looking at older Ansible code.</p>
</div>

<p>You can use all of the Jinja2 features in your templates, but we won&#8217;t cover them in detail here. Check out the <a href="http://jinja.pocoo.org/docs/dev/templates/">Jinja2 Template Designer Documentation</a> for more details.<a data-type="indexterm" data-primary="Jinja2 template engine" data-secondary="Template Designer Documentation"/> You probably won&#8217;t need to use those advanced templating features, though. One Jinja2 feature you probably will use with Ansible is filters; we&#8217;ll cover those in a later
chapter.</p>
</section>













<section data-type="sect2">
<h2>Handlers</h2>

<p>Looking back at our <em>web-tls.yml</em> playbook, note that there are two new playbook elements we haven&#8217;t
discussed yet.<a data-type="indexterm" data-primary="handlers" data-secondary="in playbook for Nginx TLS support"/> There&#8217;s a <code>handlers</code> section that looks like this:</p>

<pre data-type="programlisting" data-code-language="yaml+jinja">handlers:
- name: restart nginx
  service: name=nginx state=restarted</pre>

<p>In addition, several of the tasks contain a <code>notify</code> key. <a data-type="indexterm" data-primary="tasks" data-secondary="notify key"/><a data-type="indexterm" data-primary="notify key in tasks"/>For example:</p>

<pre data-type="programlisting" data-code-language="yaml+jinja">- name: copy TLS key
  copy: src=files/nginx.key dest={{ key_file }} owner=root mode=0600
  notify: restart nginx</pre>

<p>Handlers are one of the conditional forms that Ansible supports. A handler is
similar to a task, but it runs only if it has been notified by a task. A task
will fire the notification if Ansible recognizes that the task has changed the
state of the system.</p>

<p>A task notifies a handler by passing the handler&#8217;s name as the argument. In the preceding example, the handler&#8217;s name is <code>restart nginx</code>. For an Nginx server, we&#8217;d need to
restart it if any of the following happens:<span data-type="footnote">Alternatively, we could reload the configuration file by using <code>state=reloaded</code> instead of restarting the service.</span></p>

<ul>
<li>
<p>The TLS key changes.</p>
</li>
<li>
<p>The TLS certificate changes.</p>
</li>
<li>
<p>The configuration file changes.</p>
</li>
<li>
<p>The contents of the <em>sites-enabled</em> directory change.</p>
</li>
</ul>

<p>We put a <code>notify</code> statement on each of the tasks to ensure that Ansible restarts
Nginx if any of these conditions are met.</p>










<section data-type="sect3">
<h3>A few things to keep in mind about handlers</h3>

<p>Handlers usually run after all of the tasks are run at the end of the play. They run only once, even
if they are notified multiple times. If a play contains multiple handlers, the
handlers always run in the order that they are defined in the <code>handlers</code> section,
not the notification order.</p>

<p>The official Ansible docs mention that the only common uses for handlers are
for restarting services and for reboots. Personally, I&#8217;ve always used them only for restarting services.<a data-type="indexterm" data-primary="handlers" data-secondary="uses for"/> Even then, it&#8217;s a pretty small optimization, since we
can always just unconditionally restart the service at the end of the playbook
instead of notifying it on change, and restarting a service doesn&#8217;t usually take
very long.</p>

<p>Another pitfall with handlers that I&#8217;ve encountered is that they can be troublesome when debugging a playbook. It goes something like this:</p>
<ol>
<li>
<p>I run a playbook.</p>
</li>
<li>
<p>One of my tasks with a <code>notify</code> on it changes state.</p>
</li>
<li>
<p>An error occurs on a subsequent task, stopping Ansible.</p>
</li>
<li>
<p>I fix the error in my playbook.</p>
</li>
<li>
<p>I run Ansible again.</p>
</li>
<li>
<p>None of the tasks report a state change the second time around, so Ansible doesn&#8217;t run the handler.</p>
</li>

</ol>

<p>Read more about advanced handler usages and applications in <a data-type="xref" href="#handlers_advanced"/>.</p>
</section>



</section>













<section data-type="sect2">
<h2>Running the Playbook</h2>

<p>As before, we use the <code>ansible-playbook</code> command to run <a data-type="indexterm" data-primary="TLS (Transport Layer Security)" data-secondary="playbook with TLS support for Nginx, running"/>the playbook:</p>

<pre data-type="programlisting" data-code-language="console">$ ansible-playbook web-tls.yml</pre>

<p>The output should look something like this:</p>

<pre data-type="programlisting">PLAY [Configure webserver with nginx and tls] *********************************

GATHERING FACTS ***************************************************************
ok: [testserver]

TASK: [Install nginx] *********************************************************
changed: [testserver]

TASK: [create directories for tls certificates] *******************************
changed: [testserver]

TASK: [copy TLS key] **********************************************************
changed: [testserver]

TASK: [copy TLS certificate] **************************************************
changed: [testserver]

TASK: [copy nginx config file] ************************************************
changed: [testserver]

TASK: [enable configuration] **************************************************
ok: [testserver]

NOTIFIED: [restart nginx] *****************************************************
changed: [testserver]

PLAY RECAP ********************************************************************
testserver                 : ok=8    changed=6    unreachable=0    failed=0</pre>

<p>Point your browser to <em>https://localhost:8443</em> (don&#8217;t forget the <em>s</em> on <em>https</em>). If you&#8217;re using Chrome, as I am, you&#8217;ll get a ghastly message that says something like, "Your connection is not private" (see <a data-type="xref" href="#chrome_error"/>).<a data-type="indexterm" data-primary="Chrome, and self-signed TLS certificates"/></p>

<figure id="chrome_error">
<img src="images/aur2_0204.png" alt="Scary error message"/>
<figcaption>Browsers such as Chrome don&#8217;t trust self-signed TLS certificates</figcaption>
</figure>

<p>Don&#8217;t worry, though; that error is expected, as we generated a self-signed TLS certificate, and web
browsers such as Chrome trust only certificates that have been issued from a proper
authority.</p>

<p>We covered a lot of the <em>what</em> of Ansible in this chapter, describing what
Ansible will do to your hosts. The handlers we discussed here are just one form
of control flow that Ansible supports. In a later chapter, we&#8217;ll see iteration
and conditionally running tasks based on the values of variables. In the next chapter, we&#8217;ll talk about the <em>who</em>; in other words, how to describe the hosts that
your playbooks will run against.<a data-type="indexterm" data-primary="TLS (Transport Layer Security)" data-startref="ix_TLS"/><a data-type="indexterm" data-primary="playbooks" data-secondary="modifying simple example to add TLS support" data-startref="ix_playbkTLS"/><a data-type="indexterm" data-primary="playbooks" data-startref="ix_playbk"/></p>
</section>





</section>







</section>