mirror of
https://github.com/ansible-collections/community.general.git
synced 2025-10-21 11:34:15 -07:00
Rename 'yamlscripts' to 'yamlsyntax', add some extra crosslinking to make sure folks find the
interesting docs pages, some misc editing here and there.
This commit is contained in:
parent
02549869b1
commit
d3fe5f617a
22 changed files with 219 additions and 165 deletions
|
@ -1,83 +0,0 @@
|
|||
YAML Format
|
||||
===========
|
||||
|
||||
This page provides a basic overview of correct YAML syntax, which is how Ansible
|
||||
playbooks (our configuration management language) are expressed.
|
||||
You may also wish to read playbook examples and will quickly pick this up from those.
|
||||
|
||||
YAML Basics
|
||||
-----------
|
||||
|
||||
For `ansible`, every YAML file must be a list at it's root-most
|
||||
element. Each item in the list is a dictionary. These dictionaries
|
||||
represent all the options you can use to write an `ansible` file. In
|
||||
addition, all YAML files (regardless of their association with
|
||||
`ansible` or not) should start with ``---``.
|
||||
|
||||
In YAML a list can be represented in two ways. In one way all members
|
||||
of a list are lines beginning at the same indentation level starting
|
||||
with a ``-`` character::
|
||||
|
||||
---
|
||||
# A list of tasty fruits
|
||||
- Apple
|
||||
- Orange
|
||||
- Strawberry
|
||||
- Mango
|
||||
|
||||
In the second way a list is represented as comma separated elements
|
||||
surrounded by square brackets. Newlines are permitted between
|
||||
elements::
|
||||
|
||||
---
|
||||
# A list of tasty fruits
|
||||
[apple, orange, banana, mango]
|
||||
|
||||
A dictionary is represented in a simple ``key:`` and ``value`` form::
|
||||
|
||||
---
|
||||
# An employee record
|
||||
name: John Eckersberg
|
||||
job: Developer
|
||||
skill: Elite
|
||||
|
||||
Like lists, dictionaries can be represented in an abbreviated form::
|
||||
|
||||
---
|
||||
# An employee record
|
||||
{name: John Eckersberg, job: Developer, skill: Elite}
|
||||
|
||||
.. _truthiness:
|
||||
|
||||
You can specify a boolean value (true/false) in several forms::
|
||||
|
||||
---
|
||||
knows_oop: True
|
||||
likes_emacs: TRUE
|
||||
uses_cvs: false
|
||||
|
||||
Finally, you can combine these data structures::
|
||||
|
||||
---
|
||||
# An employee record
|
||||
name: John Eckersberg
|
||||
job: Developer
|
||||
skill: Elite
|
||||
employed: True
|
||||
foods:
|
||||
- Apple
|
||||
- Orange
|
||||
- Strawberry
|
||||
- Mango
|
||||
languages:
|
||||
ruby: Elite
|
||||
python: Elite
|
||||
dotnet: Lame
|
||||
|
||||
That's all you really need to know about YAML to get started writing
|
||||
`Ansible` playbooks.
|
||||
|
||||
.. seealso::
|
||||
|
||||
`YAMLLint <http://yamllint.com/>`_
|
||||
YAML Lint gets the lint out of your YAML
|
94
rst/YAMLSyntax.rst
Normal file
94
rst/YAMLSyntax.rst
Normal file
|
@ -0,0 +1,94 @@
|
|||
YAML Syntax
|
||||
===========
|
||||
|
||||
This page provides a basic overview of correct YAML syntax, which is how Ansible
|
||||
playbooks (our configuration management language) are expressed.
|
||||
|
||||
We use YAML because it is easier to read and write for humans than other common
|
||||
data formats like XML or JSON. Further, there are libraries available for reading
|
||||
and writing YAML in most programming languages.
|
||||
|
||||
You may also wish to read playbook examples at the same time to see how this
|
||||
is used in practice.
|
||||
|
||||
.. seealso::
|
||||
|
||||
:doc:`playbooks`
|
||||
See YAML examples in practice in playbooks
|
||||
|
||||
|
||||
YAML Basics
|
||||
-----------
|
||||
|
||||
For `ansible`, every YAML file starts with a list of things
|
||||
to do. Each item in the list is a list of key/value pairs, commonly
|
||||
called a "hash" or a "dictionary". So, we need to know how
|
||||
to write lists and dictionaries in YAML.
|
||||
|
||||
There's another small quirk to YAML. All YAML files (regardless of their association with
|
||||
`ansible` or not) should start with ``---``. This is just a YAML
|
||||
format thing that means "this is the start of a document".
|
||||
|
||||
All members of a list are lines beginning at the same indentation level starting
|
||||
with a ``-`` (dash) character::
|
||||
|
||||
---
|
||||
# A list of tasty fruits
|
||||
- Apple
|
||||
- Orange
|
||||
- Strawberry
|
||||
- Mango
|
||||
|
||||
A dictionary is represented in a simple ``key:`` and ``value`` form::
|
||||
|
||||
---
|
||||
# An employee record
|
||||
name: John Eckersberg
|
||||
job: Developer
|
||||
skill: Elite
|
||||
|
||||
Dictionaries can also be represented in an abbreviated form if you really want to::
|
||||
|
||||
---
|
||||
# An employee record
|
||||
{name: John Eckersberg, job: Developer, skill: Elite}
|
||||
|
||||
.. _truthiness:
|
||||
|
||||
Ansible doesn't really use these too much, but you can also specify a
|
||||
boolean value (true/false) in several forms::
|
||||
|
||||
---
|
||||
knows_oop: True
|
||||
likes_emacs: TRUE
|
||||
uses_cvs: false
|
||||
|
||||
Let's combine what we learned so far in an arbitary YAML example. This really
|
||||
has nothing to do with Ansible, but will give you a feel for the format::
|
||||
|
||||
---
|
||||
# An employee record
|
||||
name: John Eckersberg
|
||||
job: Developer
|
||||
skill: Elite
|
||||
employed: True
|
||||
foods:
|
||||
- Apple
|
||||
- Orange
|
||||
- Strawberry
|
||||
- Mango
|
||||
languages:
|
||||
ruby: Elite
|
||||
python: Elite
|
||||
dotnet: Lame
|
||||
|
||||
That's all you really need to know about YAML to get started writing
|
||||
`Ansible` playbooks.
|
||||
|
||||
.. seealso::
|
||||
|
||||
:doc:`playbooks`
|
||||
Learn what playbooks can do and how to write/run them.
|
||||
`YAMLLint <http://yamllint.com/>`_
|
||||
YAML Lint (online) helps you debug YAML syntax if you are having problems
|
||||
|
|
@ -181,3 +181,10 @@ It also excels for writing distributed
|
|||
scripts and ad-hoc applications that need to gather data or perform arbitrary
|
||||
tasks -- whether for a QA sytem, build system, or anything you can think of.
|
||||
|
||||
.. seealso::
|
||||
|
||||
:doc:`examples`
|
||||
Examples of basic commands
|
||||
:doc:`playbooks`
|
||||
Learning ansible's configuration management language
|
||||
|
||||
|
|
|
@ -99,13 +99,16 @@ Now run a live command on all of your nodes::
|
|||
ansible all /bin/echo hello
|
||||
|
||||
Congratulations. You've just contacted your nodes with Ansible. It's
|
||||
now time to read some of the more real-world examples, and explore
|
||||
now time to read some of the more real-world :doc:`examples`, and explore
|
||||
what you can do with different modules, as well as the Ansible
|
||||
playbooks language. Ansible is not just about running commands, but
|
||||
:doc:`playbooks` language. Ansible is not just about running commands, but
|
||||
you already have a working infrastructure!
|
||||
|
||||
|
||||
.. seealso::
|
||||
|
||||
:ref:`Inventory <inventoryformat>`
|
||||
Complete documentation on the inventory file format
|
||||
:doc:`examples`
|
||||
Examples of basic commands
|
||||
:doc:`playbooks`
|
||||
Learning ansible's configuration management language
|
||||
|
||||
|
|
|
@ -88,7 +88,7 @@ Contents
|
|||
patterns
|
||||
examples
|
||||
modules
|
||||
YAMLScripts
|
||||
YAMLSyntax
|
||||
playbooks
|
||||
api
|
||||
faq
|
||||
|
|
|
@ -34,6 +34,8 @@ looks like this::
|
|||
two.example.com
|
||||
three.example.com
|
||||
|
||||
The things in brackets are group names, you don't have to have them,
|
||||
but they are useful.
|
||||
|
||||
Selecting Targets
|
||||
+++++++++++++++++
|
||||
|
@ -43,19 +45,20 @@ These patterns target all hosts in the inventory file::
|
|||
all
|
||||
*
|
||||
|
||||
It is also possible to address specific hosts::
|
||||
Basically 'all' is an alias for '*'. It is also possible to address a specific host or hosts::
|
||||
|
||||
one.example.com
|
||||
one.example.com:two.example.com
|
||||
192.168.1.50
|
||||
192.168.1.*
|
||||
|
||||
|
||||
The following patterns address one or more groups, which are denoted
|
||||
with the bracket headers in the inventory file::
|
||||
with the aforementioned bracket headers in the inventory file::
|
||||
|
||||
webservers
|
||||
webservers:dbservers
|
||||
|
||||
Individual hosts, but not groups, can also be referenced using
|
||||
Individual host names (or IPs), but not groups, can also be referenced using
|
||||
wildcards::
|
||||
|
||||
*.example.com
|
||||
|
@ -66,4 +69,8 @@ It's also ok to mix wildcard patterns and groups at the same time::
|
|||
one*.com:dbservers
|
||||
|
||||
.. note::
|
||||
It is not possible to target a host not in the inventory file.
|
||||
It is not possible to target a host not in the inventory file. This is a safety feature.
|
||||
|
||||
Easy enough. Now see :doc:`examples` and then :doc:`playbooks` for how to do things to selected hosts.
|
||||
|
||||
|
||||
|
|
|
@ -3,7 +3,7 @@ Playbooks
|
|||
|
||||
.. seealso::
|
||||
|
||||
:doc:`YAMLScripts`
|
||||
:doc:`YAMLSyntax`
|
||||
Learn about YAML syntax
|
||||
:doc:`modules`
|
||||
Learn about available modules and writing your own
|
||||
|
|
Loading…
Add table
Add a link
Reference in a new issue