cmueller/ansible
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Prompts chapter

Browse source
This commit is contained in:
Michael DeHaan 2013-09-29 18:44:46 -04:00
parent d494691398
commit c10904bcef
5 changed files with 138 additions and 4011 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
docsite/latest/rst/index.rst
View file

@ -61,7 +61,6 @@ ways to organize playbooks and the files they include, and we'll offer up some s
playbooks
playbooks_roles
playbooks_variables
playbooks_facts
playbooks_loops
playbooks_best_practices
Example Playbooks <https://github.com/ansible/ansible-examples>

247
docsite/latest/rst/intro_variables.rst
View file

@ -2,13 +2,11 @@ Variables
=========
All of your systems are likely not the same. On some systems you may want to set some behavior
that is different from others.
Some of the observed behavior of remote systems might need to influence how you configure those
systems.
or configuration that is slightly different from others. Also, some of the observed behavior or state
of remote systems might need to influence how you configure those systems.
You might have some templates for configuration files that are mostly the same, but slightly different
between those different systems.
based on those variables.
Variables in Ansible are how we manage with differences between systems. Once understanding variables you'll
also want to dig into `playbooks_conditionals` and `playbooks_loops`.
@ -27,25 +25,115 @@ See the `intro_inventory` document for multiple ways on how to define variables
Variables Defined in a Playbook
```````````````````````````````
TODO: explain 'vars'
In a playbook, it's possible to define variables directly inline like so::
- hosts: webservers
vars:
http_port: 80
This can be nice as it's right there when you are reading the playbook.
Variables defined from includes
-------------------------------
As described in `intro_roles`, variables can also be included in the playbook via include files, which may or may
not be part of an "Ansible Role". Usage of roles is preferred as it provides a nice organizational system.
Using Variables: About Jinja2
`````````````````````````````
TODO: some background and examples, move complex var section up here
We've referenced various ways to define variables above, but how do you reference them? Ansible allows you to
reference variables in your playbooks using the Jinja2 templating system. While you can do a lot of complex
things in Jinja, only the basics are things you really need to learn.
For instance, in a simple template, you can do something like
My amp goes to {{ max_amp_value }}
And that will provide the most basic form of variable substitution.
This is also valid directly in playbooks, and you'll occasionally want to do things like:
template: src=foo.cfg.j2 dest={{ remote_install_path}}/foo.cfg
.. note:: ansible allows Jinja2 loops and conditionals in templates, but in playbooks, we do not use them. Ansible
templates are pure machine-parseable YAML.
.. note:: YAML syntax requires that if you start a value with {{ foo }} you quote the whole line, since it wants to be
sure you aren't trying to start a YAML dictionary. This is covered on the `YAMLSyntax` page.
Information discovered from systems: Facts
``````````````````````````````````````````
TODO: some background and links
Facts are information derived from speaking with your remote systems.
An example of this might be the ip address of the remote host, or what the operating system is.
To see what information is available, try the following::
ansible hostname -m setup
The results of this can be used to create dynamic groups of hosts that match particular critera, see the :doc:`group_by` for details,
as well as in generalized conditional statements as discussed in the `playbook_conditionals` chapter.
Turning Off Facts
`````````````````
If you know you don't need any fact data about your hosts, and know everything about your systems centrally, you
can turn off fact gathering. This has advantages in scaling Ansible in push mode with very large numbers of
systems, mainly, or if you are using Ansible on experimental platforms. In any play, just do this::
- hosts: whatever
gather_facts: no
Local Facts (Facts.d)
`````````````````````
.. versionadded:: 1.3
As discussed in the playbooks chapter, Ansible facts are a way of getting data about remote systems for use in playbook variables.
Usually these are discovered automatically by the 'setup' module in Ansible. Users can also write custom facts modules, as described
in the API guide. However, what if you want to have a simple way to provide system or user
provided data for use in Ansible variables, without writing a fact module? For instance, what if you want users to be able to control some aspect about how their systems are managed? "Facts.d" is one such mechanism.
If a remotely managed system has an "/etc/ansible/facts.d" directory, any files in this directory
ending in ".fact", can be JSON, INI, or executable files returning JSON, and these can supply local facts in Ansible.
For instance assume a /etc/ansible/facts.d/preferences.fact::
[general]
asdf=1
bar=2
This will produce a hash variable fact named "general" with 'asdf' and 'bar' as members.
To validate this, run the following::
ansible <hostname> -m setup -a "filter=ansible_local"
And you will see the following fact added::
"ansible_local": {
"preferences": {
"general": {
"asdf" : "1",
"bar" : "2"
}
}
}
And this data can be accessed in a template/playbook as::
{{ ansible_local.preferences.general.asdf }}
The local namespace prevents any user supplied fact from overriding system facts
or variables defined elsewhere in the playbook.
TODO: move fact documentation up, also disabling facts, and fact modules and provide more background
Registered Variables
````````````````````
TODO: add a duplicate explanation here, though this is also covered in conditionals
The value of a task being executed in ansible can be saved in a variable and used later. See some examples of this in the
`playbooks_conditionals` chapter.
Accessing Complex Variable Data
```````````````````````````````
@ -306,142 +394,3 @@ from turning into arbitrary code with ugly nested ifs, conditionals, and so on -
in more streamlined & auditable configuration rules -- especially because there are a
minimum of decision points to track.
Lookup Plugins - Accessing Outside Data
```````````````````````````````````````
.. note:: This feature is very infrequently used in Ansible. You may wish to skip this section.
.. versionadded:: 0.8
Various *lookup plugins* allow additional ways to iterate over data. In `playbooks_loops` you will learn
how to use them to walk over collections of numerous types. However, they can also be used to pull in data
from remote sources, such as shell commands or even key value stores. This section will cover lookup
plugins in this capacity.
Here are some examples::
---
- hosts: all
tasks:
- debug: msg="{{ lookup('env','HOME') }} is an environment variable"
- debug: msg="{{ item }} is a line from the result of this command"
with_lines:
- cat /etc/motd
- debug: msg="{{ lookup('pipe','date') }} is the raw result of running this command"
- debug: msg="{{ lookup('redis_kv', 'redis://localhost:6379,somekey') }} is value in Redis for somekey"
- debug: msg="{{ lookup('dnstxt', 'example.com') }} is a DNS TXT record for example.com"
- debug: msg="{{ lookup('template', './some_template.j2') }} is a value from evaluation of this template"
As an alternative you can also assign lookup plugins to variables or use them
elsewhere. This macros are evaluated each time they are used in a task (or
template)::
vars:
motd_value: "{{ lookup('file', '/etc/motd') }}"
tasks:
- debug: msg="motd value is {{ motd_value }}"
.. versionadded:: 1.1
``password`` generates a random plaintext password and store it in
a file at a given filepath. Support for crypted save modes (as with vars_prompt) is pending. If the
file exists previously, it will retrieve its contents, behaving just like with_file. Usage of variables like "{{ inventory_hostname }}" in the filepath can be used to set
up random passwords per host (what simplifies password management in 'host_vars' variables).
Generated passwords contain a random mix of upper and lowercase ASCII letters, the
numbers 0-9 and punctuation (". , : - _"). The default length of a generated password is 30 characters.
This length can be changed by passing an extra parameter::
---
- hosts: all
tasks:
# create a mysql user with a random password:
- mysql_user: name={{ client }}
password="{{ lookup('password', 'credentials/' + client + '/' + tier + '/' + role + '/mysqlpassword length=15') }}"
priv={{ client }}_{{ tier }}_{{ role }}.*:ALL
(...)
Getting values from files
`````````````````````````
.. note:: this is technically a "lookup" plugin too, but it's used more frequently than a bit of the others. You probably won't need to learn about the other lookup plugins but it's a good idea to understand 'file'.
.. versionadded:: 0.8
Sometimes you'll want to include the content of a file directly into a playbook. You can do so using a macro.
This syntax will remain in future versions, though we will also will provide ways to do this via lookup plugins (see "More Loops") as well. What follows
is an example using the authorized_key module, which requires the actual text of the SSH key as a parameter::
tasks:
- name: enable key-based ssh access for users
authorized_key: user={{ item }} key="{{ lookup('file', '/keys/' + item ) }}"
with_items:
- pinky
- brain
- snowball
Turning Off Facts
`````````````````
If you know you don't need any fact data about your hosts, and know everything about your systems centrally, you
can turn off fact gathering. This has advantages in scaling Ansible in push mode with very large numbers of
systems, mainly, or if you are using Ansible on experimental platforms. In any play, just do this::
- hosts: whatever
gather_facts: no
Local Facts (Facts.d)
`````````````````````
.. versionadded:: 1.3
As discussed in the playbooks chapter, Ansible facts are a way of getting data about remote systems for use in playbook variables.
Usually these are discovered automatically by the 'setup' module in Ansible. Users can also write custom facts modules, as described
in the API guide. However, what if you want to have a simple way to provide system or user
provided data for use in Ansible variables, without writing a fact module? For instance, what if you want users to be able to control some aspect about how their systems are managed? "Facts.d" is one such mechanism.
If a remotely managed system has an "/etc/ansible/facts.d" directory, any files in this directory
ending in ".fact", can be JSON, INI, or executable files returning JSON, and these can supply local facts in Ansible.
For instance assume a /etc/ansible/facts.d/preferences.fact::
[general]
asdf=1
bar=2
This will produce a hash variable fact named "general" with 'asdf' and 'bar' as members.
To validate this, run the following::
ansible <hostname> -m setup -a "filter=ansible_local"
And you will see the following fact added::
"ansible_local": {
"preferences": {
"general": {
"asdf" : "1",
"bar" : "2"
}
}
}
And this data can be accessed in a template/playbook as::
{{ ansible_local.preferences.general.asdf }}
The local namespace prevents any user supplied fact from overriding system facts
or variables defined elsewhere in the playbook.

1330
docsite/latest/rst/playbooks_facts.rst
View file

File diff suppressed because it is too large Load diff

1306
docsite/latest/rst/playbooks_lookups.rst
View file

File diff suppressed because it is too large Load diff

1265
docsite/latest/rst/playbooks_prompts.rst
View file

File diff suppressed because it is too large Load diff