Table of Contents

Open all
Close all
Preface
21
About This Book
23
Formatting
23
Ansible Versions
25
Platforms and Linux Distributions
25
1 Introduction and Installation
27
1.1 What Is Ansible?
27
1.1.1 Basic Features
27
1.1.2 Core Components
28
1.1.3 Declarative or Imperative?
28
1.2 What Is Ansible Not?
29
1.3 History and Versions
30
1.3.1 Versions
30
1.3.2 Supported Python Versions
31
1.4 Setup/Lab Environment
31
1.5 Ansible Installation on the Control Host
36
1.6 Installation via PIP (plus virtualenv)
38
1.7 Authentication and Authorization on Target Hosts
39
1.8 Setting Up SSH Public Key Authentication
41
1.9 An Ad Hoc Test without Any Configuration
42
1.10 Another Note on Migrating from Older Versions
43
2 Basic Setup and Initial Inventory Management
45
2.1 Setting Up the Directory Structure
45
2.2 Basic Configuration (ansible.cfg)
46
2.3 Creating and Managing a Static Inventory
48
2.4 Configuration Settings versus Parameters versus …?
50
2.5 Inventory Aliases and Namespaces
51
2.6 Beyond Ping
53
2.7 A Somewhat More Complex Example
55
2.8 Alternative or Multiple Inventories
56
3 Ad Hoc Commands and Patterns
59
3.1 Ad Hoc Commands
59
3.1.1 The “command” Module
59
3.1.2 The “shell” Module
60
3.2 Use Cases Beyond “command” and “shell”
61
3.3 Idempotency
61
3.4 Internal Workings
63
3.4.1 Parallel Execution
63
3.4.2 Persistent Connections
63
3.4.3 What Happens When a Module Is Called?
65
3.5 The Ansible Console
66
3.6 Patterns for Addressing Hosts
67
4 YAML: The Configuration and Serialization Language
69
4.1 Syntax and Structure
69
4.2 Editing YAML Files
70
4.2.1 vim
70
4.2.2 nano
71
4.2.3 Emacs
72
4.2.4 Notepad++
72
4.3 Syntactic Checks
72
4.4 Lists and Maps
73
4.5 Nested Structures
73
4.6 Text Passages and Block Expressions
75
4.6.1 Variations
75
4.6.2 Long Texts without Line Breaks
76
4.7 Nothingness in YAML
76
4.8 Anchors and References
77
5 Playbooks and Tasks: The Basics
79
5.1 Hello Ansible: The Very First Playbook
79
5.1.1 Relative Paths in Playbook Calls
81
5.1.2 Addressing the Actual Target Hosts
82
5.2 Formulation of Tasks
83
5.3 Ending Plays
85
5.4 The Problematic Colon
85
5.5 Error Handling and Retrying Files
86
5.6 Tags
88
5.7 The “ansible-playbook” Command
90
5.8 An Example of an Apache Installation
91
5.8.1 Step by Step
91
5.8.2 The Complete Playbook
93
5.8.3 “–start-at-task, “–check,” and “–diff”
94
5.9 Handler: Executing Tasks Only on Changes
95
5.9.1 Step by Step Execution
95
5.9.2 Handlers
97
5.9.3 The Complete Playbook up to This Point
100
6 Playbooks and Tasks: Advanced Methods
103
6.1 Variables
103
6.1.1 Play Vars
103
6.1.2 Extra Vars
104
6.1.3 Precedence
104
6.1.4 “set_fact”
105
6.1.5 “group_vars”
106
6.1.6 “host_vars”
108
6.1.7 “vars_files”: Variables in Any External Files
109
6.1.8 Prompting
109
6.1.9 Accessing Complex Structures
110
6.1.10 “assert” Tests
111
6.2 Registered Variables
112
6.3 Facts and Implicit Variables
115
6.3.1 Facts
115
6.3.2 Caching of Facts
117
6.3.3 Implicit Variables
118
6.3.4 Example
119
6.3.5 External Information Gatherers: “facter” and “ohai”
120
6.3.6 Not Enough Facts Yet? Try “/etc/ansible/facts.d”!
120
6.4 Conditional Execution with “when”
121
6.5 Handling System Differences: What’s the Deal Now?
122
6.5.1 The Clumsy Method
123
6.5.2 The Solid Method
124
6.5.3 The Tricky Method
126
6.5.4 The Modular Method
127
6.5.5 The Complete Playbook up to This Point
129
6.6 Jinja and Templates
131
6.6.1 Definition: Templates and Template Engines
131
6.6.2 An Individual Homepage for Our Apache Servers
132
6.6.3 Quick Testing of Jinja Templates
134
6.6.4 Jinja Syntax: Output Expressions, Statements, and Comments
136
6.6.5 Filter
137
6.6.6 Whitespace Control
138
6.6.7 Macros
140
6.7 Variable Tests
141
6.8 Lookup Plug-ins
143
6.9 Loops
145
6.9.1 “with_*” Loops Are Lookups
145
6.9.2 Iteration Over a List with “with_items” or “with_list”
146
6.9.3 Iteration Over a Map with “with_dict”
149
6.9.4 Iteration Over a Generated Sequence with “with_sequence”
149
6.9.5 Looping Over the Combination of Two Lists with “with_nested”
150
6.9.6 Looping Over Two Parallel Lists with “with_together”
151
6.9.7 Nested Loops with “with_subelements”
151
6.9.8 Repeating Tasks with “until”
152
6.9.9 More Control with “loop_control”
154
6.9.10 “register” plus Loop
157
6.10 Error Handling with “failed_when” and “ignore_errors”
158
6.11 Blocks
159
6.12 Timeouts and Asynchronous Execution
161
6.13 Local Tasks
163
6.13.1 “local_action”
165
6.13.2 Using Other Hosts
165
6.14 Environment Variables
166
6.14.1 Setting Environment Variables with the “environment” Parameter
166
6.14.2 Reading Environment Variables
167
6.14.3 Environment Variables in “path” or “dest” Attributes
168
7 Using Modules and Collections
169
7.1 Collections
169
7.1.1 A Minimal Environment with “ansible-core”
169
7.1.2 Managing Collections
170
7.1.3 The Fully Qualified Collection Name
172
7.1.4 Interim Conclusion
173
7.2 Module
173
7.3 Modules for Command Execution
174
7.3.1 “command”: Executing Commands
174
7.3.2 “shell”: Executing Commands via a Shell
174
7.3.3 “raw”: Executing Commands without the Python Subsystem
174
7.3.4 “script”: Transferring and Executing Local Scripts
175
7.4 Modules for Package Management
175
7.4.1 “apt”: Package Management on Debian/Ubuntu Systems
175
7.4.2 “dnf” and “yum”: Package Management on Rocky, CentOS, Red Hat, and Fedora Systems
176
7.4.3 “community.general.zypper”: Package Management on SUSE Systems
176
7.4.4 “package”: Generic Package Management
176
7.4.5 “package_facts”: Representing Package Information as Facts
176
7.4.6 Some Other (Not Further Described) Modules
177
7.5 Modules for Managing Files and File Contents
177
7.5.1 “copy”: Copying and Uploading Files
177
7.5.2 “template”: Processing Files with Jinja and Uploading
178
7.5.3 “file”: Managing Files and File Attributes
178
7.5.4 “stat”: Obtaining Information about Files
179
7.5.5 “lineinfile”: Managing Lines in Text Files
180
7.5.6 “blockinfile”: Managing Text Passages in Files
180
7.5.7 “replace”: Searching and Replacing in Text Files
181
7.5.8 “unarchive”: Uploading and Extracting Archives
181
7.5.9 Some Other (Not Further Described) Modules
181
7.6 Modules for Other Typical Administrative Tasks
182
7.6.1 “service”: Starting, Stopping, and Restarting Services, Etc.
182
7.6.2 “service_facts”: Presenting Service Information as Facts
182
7.6.3 “cron”: Managing Cron Jobs
183
7.6.4 “hostname”: Changing the Hostname
183
7.6.5 “user” and “group”: User and Group Management
183
7.6.6 “ansible.posix.firewalld”: Managing firewalld-Based Firewalls
184
7.6.7 “reboot”: Rebooting Machines
184
7.6.8 Some Other (Not Further Described) Modules
184
7.7 Modules for Interacting with Network Services
185
7.7.1 “get_url”: Downloading Resources
185
7.7.2 “uri”: Communicating with Web Services
185
7.7.3 “git”: Interacting with Git Servers
185
7.8 Special Modules (Control Flow Management, Etc.)
186
7.8.1 “meta”: Triggering Various Ansible Actions
186
7.8.2 “debug”: Generating Output during Playbook Runs
187
7.8.3 “fail”: Triggering a Failure
187
7.8.4 “pause”: Pausing and Optionally Reading Input
187
7.8.5 “wait_for”: Waiting for Certain Events
188
7.8.6 “wait_for_connection”: Waiting Until a Target Host Is Reachable
188
7.8.7 “assert”: Ensuring that Certain Conditions Are Met
189
7.8.8 “set_fact”: Setting Variables during Runtime
189
8 Modularization with Roles and Includes
191
8.1 Creating and Using Roles
191
8.1.1 The Concept of Roles in Ansible
191
8.1.2 A Simple Example of a Role
193
8.1.3 Using Roles in a Playbook
193
8.1.4 Plays with Roles and Tasks, “pre_tasks” and “post_tasks”
195
8.1.5 Dependencies between Roles
195
8.1.6 Choosing Other Startup Files
196
8.1.7 Creating New Roles with “ansible-galaxy”
197
8.2 The Online Ansible Galaxy Repository
198
8.3 Using Imports and Includes
198
8.3.1 “import_tasks” and “include_tasks”
198
8.3.2 “include_tasks” and Tags
199
8.3.3 Dynamic Loading of Variables with “include_vars”
201
8.3.4 “import_playbook”
201
8.4 Apache Once Again
202
8.5 Documentation (and Conventions)
206
8.5.1 “defaults/main.yml” as a Convention
207
8.5.2 “README.md”
208
8.6 Reusing Roles
209
8.6.1 Extending the Directory Structure
210
8.6.2 The Developer’s Situation
212
9 Web Interfaces: AWX and More
213
9.1 Installation of Python Packages on Current Debian and Ubuntu Systems
213
9.2 Ansible Configuration Management Database (“ansible-cmdb”)
214
9.2.1 Usage
215
9.2.2 Deploying the Page
215
9.3 Preparations for Operating More Demanding Applications
216
9.4 The Gitea Git Server
219
9.4.1 Commissioning and Logging In for the First Time
219
9.4.2 Checking In on Our Initial Project
220
9.4.3 Adding »README.md« and Useful Git Commands
222
9.5 AWX
223
9.5.1 Commissioning and First Login
223
9.5.2 Example Usage
224
9.5.3 Execution Environments
225
9.5.4 Conclusion
228
9.6 ARA
229
9.6.1 Test Setup
229
9.6.2 Further Possibilities
230
9.7 Other Applications Not Considered in Detail Here
230
9.7.1 Semaphore
231
9.7.2 Polemarch
231
9.7.3 Jenkins
232
9.7.4 Rundeck
232
9.8 Terminating or Deleting Applications That Are No Longer Needed
233
10 Additional Tools and Techniques
235
10.1 Ansible Vault
235
10.1.1 Before All Technology
235
10.1.2 Getting Started
236
10.1.3 Meaning of the Vault ID
238
10.1.4 Further Vault Commands
239
10.1.5 A Trick for Finding Variables Again
239
10.1.6 Encrypting Individual Variables
240
10.1.7 More Convenience or Automation
241
10.1.8 Convenience and Relative Security with a Password Client Script
242
10.1.9 Convenient and (Preferably) Secure with GNU Privacy Guard plus Pass
243
10.2 Debugging and Troubleshooting
244
10.2.1 Debug Mode and Verbosity Level
244
10.2.2 Improving the Readability of Outputs
245
10.2.3 Gathering Facts Takes Too Long
247
10.2.4 The Playbook Debugger
248
10.2.5 Static Code Analysis with “ansible-lint”
251
10.2.6 Check Mode and Diff Mode
254
10.2.7 Last but Not Least: The “debug” Module
256
10.3 Accelerating Playbooks with Pipelining
257
10.4 The Talking Cow
258
10.5 Ansible in Pull Mode
259
10.5.1 “ansible-pull”: Technique and Requirements
259
10.5.2 Getting Started
260
10.5.3 The Full Solution
261
10.5.4 What Might Still Be Missing?
263
11 Ansible and Docker
265
11.1 Installing Docker
265
11.2 Docker Modules
267
11.2.1 Preparations and Preliminary Considerations
267
11.2.2 A First Simple Example
268
11.2.3 Overview
269
11.3 An Example Application
274
11.4 Ansible and Docker Compose
278
11.4.1 Version Issues
281
11.4.2 Inline Specification with “definition”
281
11.5 The “docker” Connection Plug-in
282
11.6 Creating Images
283
11.6.1 Creating Images with “docker build”
283
11.6.2 “ansible-bender”
285
11.6.3 Creating Images with “ansible-bender”
286
11.6.4 Conclusion
288
12 Inventory Management: Advanced Methods
289
12.1 The “ansible-inventory” Command
289
12.2 Nested Groups
290
12.3 Static Inventories in YAML format
291
12.4 Creating on-the-Fly Inventories with “add_host”
293
12.5 Dynamic Groups with “group_by”
295
12.6 Dynamic and External Inventories
298
12.6.1 Inventory Scripts
298
12.6.2 Using Inventory Plug-ins
301
13 Ansible and the Cloud
303
13.1 Version Issues and virtualenv
304
13.2 Where to Store Keys, Tokens, Secrets, Etc.
304
13.3 Hetzner Cloud
305
13.3.1 Preparations on the Control Host
305
13.3.2 Preparations in the Cloud
306
13.3.3 Using Cloud Modules
306
13.3.4 Provisioning Cloud ervers
308
13.3.5 Inventorying Cloud Servers
309
13.3.6 Further Possibilities of the Inventory Plug-in
310
13.4 Amazon Web Services Elastic Compute Cloud
311
13.4.1 Preparations on the Control Host
311
13.4.2 Preparations in the Cloud
312
13.4.3 Using Cloud Modules
313
13.4.4 Provisioning Cloud Servers
314
13.4.5 Inventorying Cloud Servers
315
13.4.6 Further Possibilities of the Inventory Plug-in
316
13.5 Proxmox Virtual Environment
318
13.5.1 Preparations on the Control Host
318
13.5.2 Preparations in the Proxmox Virtual Environment
318
13.5.3 An Initial Test
319
13.5.4 Provisioning of Virtual Machines
320
13.5.5 Outlook
323
14 Ansible as an Orchestration Tool
325
14.1 Many Target Hosts for Testing
325
14.2 Altering the Sequence of Execution
326
14.2.1 “throttle” and “order”
328
14.2.2 “serial”
329
14.2.3 Faulty Hosts in “serial” Mode
330
14.2.4 Strategy Plug-ins
332
14.3 Delegation
335
15 Ansible and Windows
339
15.1 A Control Host Based on Windows
339
15.1.1 The Windows Subsystem for Linux
339
15.1.2 Cygwin
341
15.2 Windows Targets and Windows Remote Management
343
15.3 Preparations on the Control Host
343
15.4 Prerequisites on the Windows Side and Windows Remote Management Setup
344
15.5 Windows Remote Management Troubleshooting
345
15.6 Setup with an Active Directory and Kerberos
346
15.7 Windows Modules
348
15.7.1 “chocolatey.chocolatey.win_chocolatey”: Package Management with Chocolatey
349
15.7.2 “win_domain_user”: Managing Domain Accounts
349
15.7.3 “win_environment”: Managing Environment Variables
350
15.7.4 “win_regedit”: Managing Registry Entries
350
15.7.5 “win_updates”: Applying Updates
350
16 Callback Plug-ins
351
16.1 Stdout Callback Plug-ins
351
16.2 Aggregate and Notification Callback Plug-ins
353
17 Creating Your Own Collections and Modules
355
17.1 Namespaces, Names, and Setting Up a Collection Project
355
17.1.1 Ansible Project for Manually Testing the Collection
356
17.1.2 Where Is Work Currently Being Done?
357
17.2 Playbooks in Collections
357
17.3 Roles in Collections
358
17.4 Modules in Collections
359
17.4.1 Getting Started
359
17.4.2 Module Parameters
361
17.4.3 Modules with Python: Example Problem Statement
364
17.4.4 An Example Solution
365
17.4.5 Explanations and Further Possibilities
367
17.4.6 Embedded Documentation
369
17.4.7 Outlook
371
17.5 Plug-ins in Collections
371
17.5.1 An Example Callback Plug-in
371
17.5.2 Outlook
373
17.6 Deploying and Installing Collections
373
18 Developing and Testing with Molecule
377
18.1 Preparations and Setup
377
18.2 Getting Started
379
18.3 Develop
380
18.4 Testing with the Ansible Verifier
383
18.5 Testing with the Testinfra Verifier
385
18.6 The Complete Test Cycle
386
18.7 Outlook and Conclusion
387
19 Recipes, How-Tos, and Best Practices
389
19.1 New Projects
389
19.1.1 A Recommended “ansible.cfg”
389
19.1.2 A Template for a New Project
390
19.2 Administration
391
19.2.1 Building Simple Installers
391
19.2.2 Determining the IP Address of a Target Host
393
19.2.3 Managing “firewalld”
395
19.2.4 Applying Linux Software Updates
397
19.2.5 Initial Distribution of SSH keys
399
19.2.6 Passing Passwords on the Command Line
400
19.2.7 Ansible via a Gateway or Jump Host
401
19.3 Jinja Magic
401
19.3.1 Extending Maps or Lists during Runtime
401
19.3.2 Modifying and Combining the Elements of a List
403
19.3.3 Searching in a List of Maps
404
19.3.4 Filtering an Attribute from a List of Maps
405
19.3.5 Generating a Report from Target System Facts
406
19.3.6 Generating Passwords and Password Hashes
407
19.4 Tasks and Control Flow
408
19.4.1 Executing a Task Depending on a Previous Task
408
19.4.2 Executing a Task if the Host Is in a Specific Group
410
19.4.3 Avoiding Redundant Module Parameters with “module_defaults”
410
19.4.4 Dynamically Set Play Hosts
412
19.4.5 Reading Configuration Files
413
19.5 Miscellaneous
415
19.5.1 Simulating Functions
416
19.5.2 Managing Host-Specific Resources
417
20 What Could Be Better, and What Is Still Missing?
421
20.1 Tracking Long-Running Tasks
421
20.2 Finishing the Processing of a Role
422
20.3 Loops over Blocks
424
20.4 Locking with Concurrent Playbook Calls
425
20.5 Conclusion
426
Appendices
427
A Project-Specific Environment Variables with “direnv”
429
A.1 Installation and Shell Integration
429
A.2 Usage
430
A.3 Aliases and Functions
431
A.4 Command Execution Upon Entry
432
B The “pass” Password Manager
433
B.1 Installation and Preparations
433
B.2 Usage
434
B.3 Configuring GNU Privacy Guard Agent Cache Times
435
C Secure Shell
437
C.1 Server-Side Requirements for Using Secure Shell
437
C.2 Secure Shell Client Programs
438
C.3 Public Key Authentication
439
C.4 SSH Agents (Linux Client)
443
C.5 PuTTY, PuTTYgen, and Pageant
444
C.6 Windows Secure Copy
446
C.7 Advanced Configuration and Usage
447
C.8 “pssh” or “parallel-ssh”
452
D Regular Expressions
455
D.1 Motivation
455
D.2 Dialects
456
D.3 Basics
456
D.4 Regular Expressions: Extended Capabilities (Perl Compatible Regular Expressions)
458
D.5 Extended Capabilities (Portable Operating System Interface Extended Regular Expressions)
460
E “vim” and “nano” Tips and Tricks
463
E.1 “vim”
463
E.2 “nano”
464
The Author
467
Index
469