1Glossary 2======== 3 4The following is a list (and re-explanation) of term definitions used elsewhere in the Ansible documentation. 5 6Consult the documentation home page for the full documentation and to see the terms in context, but this should be a good resource 7to check your knowledge of Ansible's components and understand how they fit together. It's something you might wish to read for review or 8when a term comes up on the mailing list. 9 10.. glossary:: 11 12 Action 13 An action is a part of a task that specifies which of the modules to 14 run and which arguments to pass to that module. Each task can have 15 only one action, but it may also have other parameters. 16 17 Ad Hoc 18 Refers to running Ansible to perform some quick command, using 19 :command:`/usr/bin/ansible`, rather than the :term:`orchestration` 20 language, which is :command:`/usr/bin/ansible-playbook`. An example 21 of an ad hoc command might be rebooting 50 machines in your 22 infrastructure. Anything you can do ad hoc can be accomplished by 23 writing a :term:`playbook <playbooks>` and playbooks can also glue 24 lots of other operations together. 25 26 Async 27 Refers to a task that is configured to run in the background rather 28 than waiting for completion. If you have a long process that would 29 run longer than the SSH timeout, it would make sense to launch that 30 task in async mode. Async modes can poll for completion every so many 31 seconds or can be configured to "fire and forget", in which case 32 Ansible will not even check on the task again; it will just kick it 33 off and proceed to future steps. Async modes work with both 34 :command:`/usr/bin/ansible` and :command:`/usr/bin/ansible-playbook`. 35 36 Callback Plugin 37 Refers to some user-written code that can intercept results from 38 Ansible and do something with them. Some supplied examples in the 39 GitHub project perform custom logging, send email, or even play sound 40 effects. 41 42 Check Mode 43 Refers to running Ansible with the ``--check`` option, which does not 44 make any changes on the remote systems, but only outputs the changes 45 that might occur if the command ran without this flag. This is 46 analogous to so-called "dry run" modes in other systems, though the 47 user should be warned that this does not take into account unexpected 48 command failures or cascade effects (which is true of similar modes in 49 other systems). Use this to get an idea of what might happen, but do 50 not substitute it for a good staging environment. 51 52 Connection Plugin 53 By default, Ansible talks to remote machines through pluggable 54 libraries. Ansible uses native OpenSSH (:term:`SSH (Native)`) or 55 a Python implementation called :term:`paramiko`. OpenSSH is preferred 56 if you are using a recent version, and also enables some features like 57 Kerberos and jump hosts. This is covered in the :ref:`getting 58 started section <remote_connection_information>`. There are also 59 other connection types like ``accelerate`` mode, which must be 60 bootstrapped over one of the SSH-based connection types but is very 61 fast, and local mode, which acts on the local system. Users can also 62 write their own connection plugins. 63 64 Conditionals 65 A conditional is an expression that evaluates to true or false that 66 decides whether a given task is executed on a given machine or not. 67 Ansible's conditionals are powered by the 'when' statement, which are 68 discussed in the :ref:`working_with_playbooks`. 69 70 Declarative 71 An approach to achieving a task that uses a description of the 72 final state rather than a description of the sequence of steps 73 necessary to achieve that state. For a real world example, a 74 declarative specification of a task would be: "put me in California". 75 Depending on your current location, the sequence of steps to get you to 76 California may vary, and if you are already in California, nothing 77 at all needs to be done. Ansible's Resources are declarative; it 78 figures out the steps needed to achieve the final state. It also lets 79 you know whether or not any steps needed to be taken to get to the 80 final state. 81 82 Diff Mode 83 A ``--diff`` flag can be passed to Ansible to show what changed on 84 modules that support it. You can combine it with ``--check`` to get a 85 good 'dry run'. File diffs are normally in unified diff format. 86 87 Executor 88 A core software component of Ansible that is the power behind 89 :command:`/usr/bin/ansible` directly -- and corresponds to the 90 invocation of each task in a :term:`playbook <playbooks>`. The 91 Executor is something Ansible developers may talk about, but it's not 92 really user land vocabulary. 93 94 Facts 95 Facts are simply things that are discovered about remote nodes. While 96 they can be used in :term:`playbooks` and templates just like 97 variables, facts are things that are inferred, rather than set. Facts 98 are automatically discovered by Ansible when running plays by 99 executing the internal :ref:`setup module <setup_module>` on the remote nodes. You 100 never have to call the setup module explicitly, it just runs, but it 101 can be disabled to save time if it is not needed or you can tell 102 ansible to collect only a subset of the full facts via the 103 ``gather_subset:`` option. For the convenience of users who are 104 switching from other configuration management systems, the fact module 105 will also pull in facts from the :program:`ohai` and :program:`facter` 106 tools if they are installed. These are fact libraries from Chef and 107 Puppet, respectively. (These may also be disabled via 108 ``gather_subset:``) 109 110 Filter Plugin 111 A filter plugin is something that most users will never need to 112 understand. These allow for the creation of new :term:`Jinja2` 113 filters, which are more or less only of use to people who know what 114 Jinja2 filters are. If you need them, you can learn how to write them 115 in the :ref:`API docs section <developing_filter_plugins>`. 116 117 Forks 118 Ansible talks to remote nodes in parallel and the level of parallelism 119 can be set either by passing ``--forks`` or editing the default in 120 a configuration file. The default is a very conservative five (5) 121 forks, though if you have a lot of RAM, you can easily set this to 122 a value like 50 for increased parallelism. 123 124 Gather Facts (Boolean) 125 :term:`Facts` are mentioned above. Sometimes when running a multi-play 126 :term:`playbook <playbooks>`, it is desirable to have some plays that 127 don't bother with fact computation if they aren't going to need to 128 utilize any of these values. Setting ``gather_facts: False`` on 129 a playbook allows this implicit fact gathering to be skipped. 130 131 Globbing 132 Globbing is a way to select lots of hosts based on wildcards, rather 133 than the name of the host specifically, or the name of the group they 134 are in. For instance, it is possible to select ``ww*`` to match all 135 hosts starting with ``www``. This concept is pulled directly from 136 :program:`Func`, one of Michael DeHaan's (an Ansible Founder) earlier 137 projects. In addition to basic globbing, various set operations are 138 also possible, such as 'hosts in this group and not in another group', 139 and so on. 140 141 Group 142 A group consists of several hosts assigned to a pool that can be 143 conveniently targeted together, as well as given variables that they 144 share in common. 145 146 Group Vars 147 The :file:`group_vars/` files are files that live in a directory 148 alongside an inventory file, with an optional filename named after 149 each group. This is a convenient place to put variables that are 150 provided to a given group, especially complex data structures, so that 151 these variables do not have to be embedded in the :term:`inventory` 152 file or :term:`playbook <playbooks>`. 153 154 Handlers 155 Handlers are just like regular tasks in an Ansible 156 :term:`playbook <playbooks>` (see :term:`Tasks`) but are only run if 157 the Task contains a ``notify`` directive and also indicates that it 158 changed something. For example, if a config file is changed, then the 159 task referencing the config file templating operation may notify 160 a service restart handler. This means services can be bounced only if 161 they need to be restarted. Handlers can be used for things other than 162 service restarts, but service restarts are the most common usage. 163 164 Host 165 A host is simply a remote machine that Ansible manages. They can have 166 individual variables assigned to them, and can also be organized in 167 groups. All hosts have a name they can be reached at (which is either 168 an IP address or a domain name) and, optionally, a port number, if they 169 are not to be accessed on the default SSH port. 170 171 Host Specifier 172 Each :term:`Play <plays>` in Ansible maps a series of :term:`tasks` (which define the role, 173 purpose, or orders of a system) to a set of systems. 174 175 This ``hosts:`` directive in each play is often called the hosts specifier. 176 177 It may select one system, many systems, one or more groups, or even 178 some hosts that are in one group and explicitly not in another. 179 180 Host Vars 181 Just like :term:`Group Vars`, a directory alongside the inventory file named 182 :file:`host_vars/` can contain a file named after each hostname in the 183 inventory file, in :term:`YAML` format. This provides a convenient place to 184 assign variables to the host without having to embed them in the 185 :term:`inventory` file. The Host Vars file can also be used to define complex 186 data structures that can't be represented in the inventory file. 187 188 Idempotency 189 An operation is idempotent if the result of performing it once is 190 exactly the same as the result of performing it repeatedly without 191 any intervening actions. 192 193 Includes 194 The idea that :term:`playbook <playbooks>` files (which are nothing 195 more than lists of :term:`plays`) can include other lists of plays, 196 and task lists can externalize lists of :term:`tasks` in other files, 197 and similarly with :term:`handlers`. Includes can be parameterized, 198 which means that the loaded file can pass variables. For instance, an 199 included play for setting up a WordPress blog may take a parameter 200 called ``user`` and that play could be included more than once to 201 create a blog for both ``alice`` and ``bob``. 202 203 Inventory 204 A file (by default, Ansible uses a simple INI format) that describes 205 :term:`Hosts <Host>` and :term:`Groups <Group>` in Ansible. Inventory 206 can also be provided via an :term:`Inventory Script` (sometimes called 207 an "External Inventory Script"). 208 209 Inventory Script 210 A very simple program (or a complicated one) that looks up 211 :term:`hosts <Host>`, :term:`group` membership for hosts, and variable 212 information from an external resource -- whether that be a SQL 213 database, a CMDB solution, or something like LDAP. This concept was 214 adapted from Puppet (where it is called an "External Nodes 215 Classifier") and works more or less exactly the same way. 216 217 Jinja2 218 Jinja2 is the preferred templating language of Ansible's template 219 module. It is a very simple Python template language that is 220 generally readable and easy to write. 221 222 JSON 223 Ansible uses JSON for return data from remote modules. This allows 224 modules to be written in any language, not just Python. 225 226 Lazy Evaluation 227 In general, Ansible evaluates any variables in 228 :term:`playbook <playbooks>` content at the last possible second, 229 which means that if you define a data structure that data structure 230 itself can define variable values within it, and everything "just 231 works" as you would expect. This also means variable strings can 232 include other variables inside of those strings. 233 234 Library 235 A collection of modules made available to :command:`/usr/bin/ansible` 236 or an Ansible :term:`playbook <playbooks>`. 237 238 Limit Groups 239 By passing ``--limit somegroup`` to :command:`ansible` or 240 :command:`ansible-playbook`, the commands can be limited to a subset 241 of :term:`hosts <Host>`. For instance, this can be used to run 242 a :term:`playbook <playbooks>` that normally targets an entire set of 243 servers to one particular server. 244 245 Local Action 246 A local_action directive in a :term:`playbook <playbooks>` targeting 247 remote machines means that the given step will actually occur on the 248 local machine, but that the variable ``{{ ansible_hostname }}`` can be 249 passed in to reference the remote hostname being referred to in that 250 step. This can be used to trigger, for example, an rsync operation. 251 252 Local Connection 253 By using ``connection: local`` in a :term:`playbook <playbooks>`, or 254 passing ``-c local`` to :command:`/usr/bin/ansible`, this indicates 255 that we are managing the local host and not a remote machine. 256 257 Lookup Plugin 258 A lookup plugin is a way to get data into Ansible from the outside world. 259 Lookup plugins are an extension of Jinja2 and can be accessed in templates, e.g., 260 ``{{ lookup('file','/path/to/file') }}``. 261 These are how such things as ``with_items``, are implemented. 262 There are also lookup plugins like ``file`` which loads data from 263 a file and ones for querying environment variables, DNS text records, 264 or key value stores. 265 266 Loops 267 Generally, Ansible is not a programming language. It prefers to be 268 more declarative, though various constructs like ``loop`` allow 269 a particular task to be repeated for multiple items in a list. 270 Certain modules, like :ref:`yum <yum_module>` and :ref:`apt <apt_module>`, actually take 271 lists directly, and can install all packages given in those lists 272 within a single transaction, dramatically speeding up total time to 273 configuration, so they can be used without loops. 274 275 Modules 276 Modules are the units of work that Ansible ships out to remote 277 machines. Modules are kicked off by either 278 :command:`/usr/bin/ansible` or :command:`/usr/bin/ansible-playbook` 279 (where multiple tasks use lots of different modules in conjunction). 280 Modules can be implemented in any language, including Perl, Bash, or 281 Ruby -- but can leverage some useful communal library code if written 282 in Python. Modules just have to return :term:`JSON`. Once modules are 283 executed on remote machines, they are removed, so no long running 284 daemons are used. Ansible refers to the collection of available 285 modules as a :term:`library`. 286 287 Multi-Tier 288 The concept that IT systems are not managed one system at a time, but 289 by interactions between multiple systems and groups of systems in 290 well defined orders. For instance, a web server may need to be 291 updated before a database server and pieces on the web server may 292 need to be updated after *THAT* database server and various load 293 balancers and monitoring servers may need to be contacted. Ansible 294 models entire IT topologies and workflows rather than looking at 295 configuration from a "one system at a time" perspective. 296 297 Notify 298 The act of a :term:`task <tasks>` registering a change event and 299 informing a :term:`handler <handlers>` task that another 300 :term:`action` needs to be run at the end of the :term:`play <plays>`. If 301 a handler is notified by multiple tasks, it will still be run only 302 once. Handlers are run in the order they are listed, not in the order 303 that they are notified. 304 305 Orchestration 306 Many software automation systems use this word to mean different 307 things. Ansible uses it as a conductor would conduct an orchestra. 308 A datacenter or cloud architecture is full of many systems, playing 309 many parts -- web servers, database servers, maybe load balancers, 310 monitoring systems, continuous integration systems, etc. In 311 performing any process, it is necessary to touch systems in particular 312 orders, often to simulate rolling updates or to deploy software 313 correctly. Some system may perform some steps, then others, then 314 previous systems already processed may need to perform more steps. 315 Along the way, emails may need to be sent or web services contacted. 316 Ansible orchestration is all about modeling that kind of process. 317 318 paramiko 319 By default, Ansible manages machines over SSH. The library that 320 Ansible uses by default to do this is a Python-powered library called 321 paramiko. The paramiko library is generally fast and easy to manage, 322 though users who want to use Kerberos or Jump Hosts may wish to switch 323 to a native SSH binary such as OpenSSH by specifying the connection 324 type in their :term:`playbooks`, or using the ``-c ssh`` flag. 325 326 Playbooks 327 Playbooks are the language by which Ansible orchestrates, configures, 328 administers, or deploys systems. They are called playbooks partially 329 because it's a sports analogy, and it's supposed to be fun using them. 330 They aren't workbooks :) 331 332 Plays 333 A :term:`playbook <playbooks>` is a list of plays. A play is 334 minimally a mapping between a set of :term:`hosts <Host>` selected by a host 335 specifier (usually chosen by :term:`groups <Group>` but sometimes by 336 hostname :term:`globs <Globbing>`) and the :term:`tasks` which run on those 337 hosts to define the role that those systems will perform. There can be 338 one or many plays in a playbook. 339 340 Pull Mode 341 By default, Ansible runs in :term:`push mode`, which allows it very 342 fine-grained control over when it talks to each system. Pull mode is 343 provided for when you would rather have nodes check in every N minutes 344 on a particular schedule. It uses a program called 345 :command:`ansible-pull` and can also be set up (or reconfigured) using 346 a push-mode :term:`playbook <playbooks>`. Most Ansible users use push 347 mode, but pull mode is included for variety and the sake of having 348 choices. 349 350 :command:`ansible-pull` works by checking configuration orders out of 351 git on a crontab and then managing the machine locally, using the 352 :term:`local connection` plugin. 353 354 Push Mode 355 Push mode is the default mode of Ansible. In fact, it's not really 356 a mode at all -- it's just how Ansible works when you aren't thinking 357 about it. Push mode allows Ansible to be fine-grained and conduct 358 nodes through complex orchestration processes without waiting for them 359 to check in. 360 361 Register Variable 362 The result of running any :term:`task <tasks>` in Ansible can be 363 stored in a variable for use in a template or a conditional statement. 364 The keyword used to define the variable is called ``register``, taking 365 its name from the idea of registers in assembly programming (though 366 Ansible will never feel like assembly programming). There are an 367 infinite number of variable names you can use for registration. 368 369 Resource Model 370 Ansible modules work in terms of resources. For instance, the 371 :ref:`file module <file_module>` will select a particular file and ensure 372 that the attributes of that resource match a particular model. As an 373 example, we might wish to change the owner of :file:`/etc/motd` to 374 ``root`` if it is not already set to ``root``, or set its mode to 375 ``0644`` if it is not already set to ``0644``. The resource models 376 are :term:`idempotent <idempotency>` meaning change commands are not 377 run unless needed, and Ansible will bring the system back to a desired 378 state regardless of the actual state -- rather than you having to tell 379 it how to get to the state. 380 381 Roles 382 Roles are units of organization in Ansible. Assigning a role to 383 a group of :term:`hosts <Host>` (or a set of :term:`groups <group>`, 384 or :term:`host patterns <Globbing>`, etc.) implies that they should 385 implement a specific behavior. A role may include applying certain 386 variable values, certain :term:`tasks`, and certain :term:`handlers` 387 -- or just one or more of these things. Because of the file structure 388 associated with a role, roles become redistributable units that allow 389 you to share behavior among :term:`playbooks` -- or even with other users. 390 391 Rolling Update 392 The act of addressing a number of nodes in a group N at a time to 393 avoid updating them all at once and bringing the system offline. For 394 instance, in a web topology of 500 nodes handling very large volume, 395 it may be reasonable to update 10 or 20 machines at a time, moving on 396 to the next 10 or 20 when done. The ``serial:`` keyword in an Ansible 397 :term:`playbooks` control the size of the rolling update pool. The 398 default is to address the batch size all at once, so this is something 399 that you must opt-in to. OS configuration (such as making sure config 400 files are correct) does not typically have to use the rolling update 401 model, but can do so if desired. 402 403 Serial 404 .. seealso:: 405 406 :term:`Rolling Update` 407 408 Sudo 409 Ansible does not require root logins, and since it's daemonless, 410 definitely does not require root level daemons (which can be 411 a security concern in sensitive environments). Ansible can log in and 412 perform many operations wrapped in a sudo command, and can work with 413 both password-less and password-based sudo. Some operations that 414 don't normally work with sudo (like scp file transfer) can be achieved 415 with Ansible's :ref:`copy <copy_module>`, :ref:`template <template_module>`, and 416 :ref:`fetch <fetch_module>` modules while running in sudo mode. 417 418 SSH (Native) 419 Native OpenSSH as an Ansible transport is specified with ``-c ssh`` 420 (or a config file, or a directive in the :term:`playbook <playbooks>`) 421 and can be useful if wanting to login via Kerberized SSH or using SSH 422 jump hosts, etc. In 1.2.1, ``ssh`` will be used by default if the 423 OpenSSH binary on the control machine is sufficiently new. 424 Previously, Ansible selected ``paramiko`` as a default. Using 425 a client that supports ``ControlMaster`` and ``ControlPersist`` is 426 recommended for maximum performance -- if you don't have that and 427 don't need Kerberos, jump hosts, or other features, ``paramiko`` is 428 a good choice. Ansible will warn you if it doesn't detect 429 ControlMaster/ControlPersist capability. 430 431 Tags 432 Ansible allows tagging resources in a :term:`playbook <playbooks>` 433 with arbitrary keywords, and then running only the parts of the 434 playbook that correspond to those keywords. For instance, it is 435 possible to have an entire OS configuration, and have certain steps 436 labeled ``ntp``, and then run just the ``ntp`` steps to reconfigure 437 the time server information on a remote host. 438 439 Task 440 :term:`Playbooks` exist to run tasks. Tasks combine an :term:`action` 441 (a module and its arguments) with a name and optionally some other 442 keywords (like :term:`looping directives <loops>`). :term:`Handlers` 443 are also tasks, but they are a special kind of task that do not run 444 unless they are notified by name when a task reports an underlying 445 change on a remote system. 446 447 Tasks 448 A list of :term:`Task`. 449 450 Templates 451 Ansible can easily transfer files to remote systems but often it is 452 desirable to substitute variables in other files. Variables may come 453 from the :term:`inventory` file, :term:`Host Vars`, :term:`Group 454 Vars`, or :term:`Facts`. Templates use the :term:`Jinja2` template 455 engine and can also include logical constructs like loops and if 456 statements. 457 458 Transport 459 Ansible uses :term:``Connection Plugins`` to define types of available 460 transports. These are simply how Ansible will reach out to managed 461 systems. Transports included are :term:`paramiko`, 462 :term:`ssh <SSH (Native)>` (using OpenSSH), and 463 :term:`local <Local Connection>`. 464 465 When 466 An optional conditional statement attached to a :term:`task <tasks>` that is used to 467 determine if the task should run or not. If the expression following 468 the ``when:`` keyword evaluates to false, the task will be ignored. 469 470 Vars (Variables) 471 As opposed to :term:`Facts`, variables are names of values (they can 472 be simple scalar values -- integers, booleans, strings) or complex 473 ones (dictionaries/hashes, lists) that can be used in templates and 474 :term:`playbooks`. They are declared things, not things that are 475 inferred from the remote system's current state or nature (which is 476 what Facts are). 477 478 YAML 479 Ansible does not want to force people to write programming language 480 code to automate infrastructure, so Ansible uses YAML to define 481 :term:`playbook <playbooks>` configuration languages and also variable 482 files. YAML is nice because it has a minimum of syntax and is very 483 clean and easy for people to skim. It is a good data format for 484 configuration files and humans, but also machine readable. Ansible's 485 usage of YAML stemmed from Michael DeHaan's first use of it inside of 486 Cobbler around 2006. YAML is fairly popular in the dynamic language 487 community and the format has libraries available for serialization in 488 many languages (Python, Perl, Ruby, etc.). 489 490.. seealso:: 491 492 :ref:`ansible_faq` 493 Frequently asked questions 494 :ref:`working_with_playbooks` 495 An introduction to playbooks 496 :ref:`playbooks_best_practices` 497 Best practices advice 498 `User Mailing List <https://groups.google.com/group/ansible-devel>`_ 499 Have a question? Stop by the google group! 500 `irc.libera.chat <https://libera.chat/>`_ 501 #ansible IRC chat channel 502