diff --git a/DC-Ansible b/DC-Ansible new file mode 100644 index 000000000..0e6717697 --- /dev/null +++ b/DC-Ansible @@ -0,0 +1,16 @@ +# This file originates from the project https://github.com/openSUSE/doc-kit +# This file can be edited downstream. + +MAIN="ansible.asm.xml" +# Point to the ID of the of your assembly +SRC_DIR="articles" +IMG_SRC_DIR="images" + +PROFOS="sles" +PROFCONDITION="16.0" +STRUCTID="ansible" +#PROFCONDITION="suse-product;beta" +#PROFCONDITION="community-project" + +STYLEROOT="/usr/share/xml/docbook/stylesheet/suse2022-ns" +FALLBACK_STYLEROOT="/usr/share/xml/docbook/stylesheet/suse-ns" \ No newline at end of file diff --git a/articles/ansible.asm.xml b/articles/ansible.asm.xml new file mode 100644 index 000000000..845812b83 --- /dev/null +++ b/articles/ansible.asm.xml @@ -0,0 +1,152 @@ + + + + %entities; +]> + + + + + + + + + + + + + + + + Ansible core + + 2025-06-19 + + + Initial version + + + + + + + + + + Smart Docs + + + + Administration + Configuration + Security + + + + + + https://bugzilla.suse.com/enter_bug.cgi + Documentation + SUSE Linux Enterprise Server 16.0 + amrita.sakthivel@suse.com + + yes + + + + + &x86-64; + &power; + &zseries; + &aarch64; + + + + + &sles; + + + + Ansible automation platform + Learn how to automate IT tasks using Ansible + + + Save time by using Ansible automation platform. + + + + + WHAT? + + +This article gives an introduction to Ansible and guides you on how to automate repetitive IT tasks. +Ansible is an IT automation tool that simplifies configuration management,application deployment and +task orchestration by enabling you to define infrastructure as code in a simple way. + + + + + WHY? + + +Learn how to automate IT infrastructure with Ansible;how to install and configure, create +an inventory file and a playbook. + + + + + EFFORT + + +The average reading time of this article is approximately 40 minutes. + + + + + REQUIREMENTS + + + + +Linux fundamentals:Understanding basic Linux commands,file permissions, directory structures +and usage of the command line. + + + + +Networking:Ansible connects to remote machines via SSH so knowledge of IP addresses,SSH,host names and pots is required. + + + + +YAML:Ansible playbooks are written in YAML so knowing how to structure a YAML file is essential. + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/concepts/ansible-intro.xml b/concepts/ansible-intro.xml new file mode 100644 index 000000000..425520ebc --- /dev/null +++ b/concepts/ansible-intro.xml @@ -0,0 +1,63 @@ + + + + + %entities; +]> + + + Introduction to Ansible core + + + + Ansible is an open-source IT automation engine that automates provisioning, configuration management, application deployment and other IT processes. + It is simple and has agent less architecture, which means it does not require any special software installed on the machines it manages. + It operates on the following concepts: + + + + + + Control node: The machine where Ansible is installed and executed. + + + + Managed Nodes: The target servers or devices that Ansible manages. + + + + + Inventory: A file that defines and groups your managed nodes. + + + + + Modules: Small programs that Ansible pushes to managed nodes to perform specific tasks. + + + + + Tasks: A single action executed by a module. + + + + + Playbooks: YAML files that contain an ordered list of tasks and define the desired state of your systems. + + + + + Roles: Structured ways to organize playbooks and other related files for reusability. + + + + + \ No newline at end of file diff --git a/concepts/ansible-inventory-file.xml b/concepts/ansible-inventory-file.xml new file mode 100644 index 000000000..f99252ae8 --- /dev/null +++ b/concepts/ansible-inventory-file.xml @@ -0,0 +1,154 @@ + + + %entities; +]> + + + + + + + Structure of an inventory file + + + + An &ansible; inventory file defines the hosts or servers on which &ansible; commands and playbooks will run. + It can be in either INI or YAML format and is a fundamental component of an Ansible project. + + + + Ansible uses several built-in variables to connect to and manage hosts, which are often defined in the inventory file. + The most common ones are: + + ansible_host:Specifies the IP address or DNS name of the host. + + ansible_userThe user account to use for SSH connections. + + ansible_port:The path to the private key file for authentication. + + ansible_private_key_file:Specifies the IP address or DNS name of the host. + + ansible_python_interpreter:Specifies the path to the Python interpreter on the remote host if it is not the default. + + +
+ <literal>INI</literal>format + The INI format is the more traditional and widely used format for inventory files. + Hosts can be listed individually or grouped together. + + + Individual hosts + + You can either list the IP addresses or host names. For example: + host1.example.com + 192.168.1.50 + + + + Groups + + Groups are defined using [] brackets. You can apply tasks to multiple hosts simultaneously. + A host can belong to multiple groups. For example: + [webservers] + web1.example.com + web2.example.com + + [databases] + db1.example.com + + + + Group variables + + Variables can be assigned to all hosts within a specific group. + These are defined under the group name using a :vars suffix. For example: + [webservers:vars] + ansible_user=test + http_port=80 + + + + Child groups + + You can create a group of groups, known as a parent group, using the :children suffix. + This is useful for combining different host types for a single task. For example: + [all_servers:children] + webservers + databases + + + +
+
+ <literal>YAML</literal>format + YAML offers a structured and hierarchical way to represent the inventory. + It is often preferred for its readability and ability to handle complex data structures. + + + Host and group structure: + + The inventory is defined under the all keyword, which contains + hosts and children. For example, + all: + hosts: + host1.example.com: + 192.168.1.50: + children: + webservers: + hosts: + web1.example.com: + web2.example.com: + databases: + hosts: + db1.example.com: + + + + Group and host variables + + Variables are defined under a vars dictionary within the host or group. + For example: + [webservers] + web1.example.com + web2.example.com + + [databases] + db1.example.com + + + + Group variables + + Variables can be assigned to all hosts within a specific group. + These are defined under the group name using a :vars suffix. For example: + [webservers:vars] + ansible_user=test + http_port=80 + + + + Child groups + + You can create a group of groups, known as a parent group, using the :children suffix. + This is useful for combining different host types for a single task. For example: + all: + children: + webservers: + hosts: + web1.example.com: + ansible_user: test + vars: + http_port: 80 + + + +
+ diff --git a/references/ansible-basic-usage.xml b/references/ansible-basic-usage.xml new file mode 100644 index 000000000..96be2dfec --- /dev/null +++ b/references/ansible-basic-usage.xml @@ -0,0 +1,263 @@ + + + + + %entities; +]> + + + Basic usage of Ansible + + + + Ansible provides ad-hoc commands and several utilities to perform various operation and automation + tasks. Ad-hoc commands in Ansible are useful for performing quick and one-off tasks that do not need to be saved for future use. + They are single line commands executed directly from the command line. Ad-hoc commands use the ansible CLI tool. + + In contrast, playbooks are a more powerful and scalable solution for defining complex, multi-step IT automation tasks. + They are written in YAML and contain a list of plays, with each play associating a group of hosts with a series of tasks. + The ansible-playbook CLI tool is used to execute these playbooks. This approach promotes reusability, version control, + and collaboration, making it the preferred method for managing and deploying applications at scale. + You can use either ad-hoc commands or create a playbook to automate your IT infrastructure based on your use case. + + + +
+ Ad-hoc commands + Ad-hoc commands are a quick way to run a single task on one or more managed hosts directly from the command. + Ideal for simple operations like checking system uptime or rebooting a server. + They are useful for quickly managing servers by performing actions like rebooting, copying files and managing packages and users. + You can use any of the available Ansible modules in an ad-hoc task. Like playbooks, ad-hoc tasks use a declarative + model, where you define the desired final state. Ansible then automatically calculates and executes the necessary steps to achieve that state. + This approach ensures the task can be run multiple times without causing unintended changes, as Ansible first checks the + current state of the host and only performs an action if it differs from the specified final state. +
+
+ Ansible command-line tools + + Ansible provides the following command-line tools: + + + ansible + + + A simple tool or framework for remote tasks; this command-line tool allows you to define and run a single task + playbook against a set of hosts. + &prompt.user;ansible -h + usage: ansible [-h] [--version] [-v] [-b] [--become-method BECOME_METHOD] [--become-user BECOME_USER] [-K | --become-password-file BECOME_PASSWORD_FILE] [-i INVENTORY] [--list-hosts] + [-l SUBSET] [-P POLL_INTERVAL] [-B SECONDS] [-o] [-t TREE] [--private-key PRIVATE_KEY_FILE] [-u REMOTE_USER] [-c CONNECTION] [-T TIMEOUT] + [--ssh-common-args SSH_COMMON_ARGS] [--sftp-extra-args SFTP_EXTRA_ARGS] [--scp-extra-args SCP_EXTRA_ARGS] [--ssh-extra-args SSH_EXTRA_ARGS] [-k | + --connection-password-file CONNECTION_PASSWORD_FILE] [-C] [-D] [-e EXTRA_VARS] [--vault-id VAULT_IDS] [-J | --vault-password-file VAULT_PASSWORD_FILES] [-f FORKS] + [-M MODULE_PATH] [--playbook-dir BASEDIR] [--task-timeout TASK_TIMEOUT] [-a MODULE_ARGS] [-m MODULE_NAME] + pattern + Define and run a single task 'playbook' against a set of hosts + [...] + + + + + ansible-config + + + Used to manage and view Ansible's configuration settings. + &prompt.user;ansible-config -h + usage: ansible-config [-h] [--version] [-v] {list,dump,view,init,validate} ... + +View ansible configuration. + +positional arguments: + {list,dump,view,init,validate} + list Print all config options + dump Dump configuration + view View configuration file + init Create initial configuration + validate Validate the configuration file and environment variables. By default it only checks the base settings without accounting for plugins (see -t). + +options: + --version show program's version number, config file location, configured module search path, module location, executable location and exit + -h, --help show this help message and exit + -v, --verbose Causes Ansible to print more debug messages. Adding multiple -v will increase the verbosity, the builtin plugins currently evaluate up to -vvvvvv. A + reasonable level to start is -vvv, connection debugging might require -vvvv. This argument may be specified multiple times. + + + + ansible-console + + + An interactive command-line tool or Read-Eval-Print Loop (REPL), that lets you run Ansible ad-hoc commands in a persistent real-time shell environment. + It is a great tool for quickly testing modules, exploring your inventory and debugging issues without having to run a new command for every action. + + &prompt.user;ansible-console -h + usage: ansible-console [-h] [--version] [-v] [-b] [--become-method BECOME_METHOD] [--become-user BECOME_USER] [-K | --become-password-file BECOME_PASSWORD_FILE] [-i INVENTORY] + [--list-hosts] [-l SUBSET] [--private-key PRIVATE_KEY_FILE] [-u REMOTE_USER] [-c CONNECTION] [-T TIMEOUT] [--ssh-common-args SSH_COMMON_ARGS] + [--sftp-extra-args SFTP_EXTRA_ARGS] [--scp-extra-args SCP_EXTRA_ARGS] [--ssh-extra-args SSH_EXTRA_ARGS] [-k | + --connection-password-file CONNECTION_PASSWORD_FILE] [-C] [-D] [--vault-id VAULT_IDS] [-J | --vault-password-file VAULT_PASSWORD_FILES] [-f FORKS] + [-M MODULE_PATH] [--playbook-dir BASEDIR] [-e EXTRA_VARS] [--task-timeout TASK_TIMEOUT] [--step] + [pattern] + +REPL console for executing Ansible tasks. + [...] + + + + + ansible-doc + + + A command-line tool that provides documentation for all Ansible's installed modules and plugins. + It is an essential utility for anyone writing playbooks or ad-hoc commands. You can look up a module's purpose, parameters, return , and even usage examples directly from your terminal. + + &prompt.user;ansible-doc -h + usage: ansible-doc [-h] [--version] [-v] [-M MODULE_PATH] [--playbook-dir BASEDIR] + [-t {become,cache,callback,cliconf,connection,httpapi,inventory,lookup,netconf,shell,vars,module,strategy,test,filter,role,keyword}] [-j] [-r ROLES_PATH] + [-e ENTRY_POINT | -s | -F | -l | --metadata-dump] [--no-fail-on-errors] + [plugin ...] + +plugin documentation tool + [...] + + + + + ansible-galaxy + + + A command-line tool that comes with Ansible and is used for managing and sharing roles. + &prompt.user;ansible-galaxy -h + Perform various Role and Collection related operations. + +positional arguments: + TYPE + collection Manage an Ansible Galaxy collection. + role Manage an Ansible Galaxy role. + +options: + --version show program's version number, config file location, configured module search path, module location, executable location and exit + -h, --help show this help message and exit + -v, --verbose Causes Ansible to print more debug messages. Adding multiple -v will increase the verbosity, the builtin plugins currently evaluate up to -vvvvvv. A reasonable level + to start is -vvv, connection debugging might require -vvvv. This argument may be specified multiple times. + + + + + ansible-inventory + + +Is a command-line tool that helps you inspect, validate and understand your inventory. + &prompt.user;ansible-inventory -h + usage: ansible-inventory [-h] [--version] [-v] [-i INVENTORY] [-l SUBSET] [--vault-id VAULT_IDS] [-J | --vault-password-file VAULT_PASSWORD_FILES] [--playbook-dir BASEDIR] + [-e EXTRA_VARS] [--list] [--host HOST] [--graph] [-y] [--toml] [--vars] [--export] [--output OUTPUT_FILE] + [group] + +Show Ansible inventory information, by default it uses the inventory script JSON format +[...] + + + + + ansible-playbook + + +Is a command-line tool that helps you inspect, validate and understand your inventory. + &prompt.user;ansible-playbook -h + usage: ansible-playbook [-h] [--version] [-v] [--private-key PRIVATE_KEY_FILE] [-u REMOTE_USER] [-c CONNECTION] [-T TIMEOUT] [--ssh-common-args SSH_COMMON_ARGS] + [--sftp-extra-args SFTP_EXTRA_ARGS] [--scp-extra-args SCP_EXTRA_ARGS] [--ssh-extra-args SSH_EXTRA_ARGS] [-k | + --connection-password-file CONNECTION_PASSWORD_FILE] [--force-handlers] [--flush-cache] [-b] [--become-method BECOME_METHOD] [--become-user BECOME_USER] [-K | + --become-password-file BECOME_PASSWORD_FILE] [-t TAGS] [--skip-tags SKIP_TAGS] [-C] [-D] [-i INVENTORY] [--list-hosts] [-l SUBSET] [-e EXTRA_VARS] + [--vault-id VAULT_IDS] [-J | --vault-password-file VAULT_PASSWORD_FILES] [-f FORKS] [-M MODULE_PATH] [--syntax-check] [--list-tasks] [--list-tags] [--step] + [--start-at-task START_AT_TASK] + playbook [playbook ...] + +Runs Ansible playbooks, executing the defined tasks on the targeted hosts. +[...] + + + + + ansible-pull + + + Is a command-line tool that inverts Ansible's default push-based architecture into a pull-based one. + Instead of a central control machine pushing configurations out to all the managed nodes, ansible-pullansible-pull is a command + that you run on each managed node. It tells that node to pull a playbook from a remote and then execute it. + + + &prompt.user;ansible-pull -h + ansible-pull -h + usage: ansible-pull [-h] [--version] [-v] [--private-key PRIVATE_KEY_FILE] [-u REMOTE_USER] [-c CONNECTION] [-T TIMEOUT] [--ssh-common-args SSH_COMMON_ARGS] + [--sftp-extra-args SFTP_EXTRA_ARGS] [--scp-extra-args SCP_EXTRA_ARGS] [--ssh-extra-args SSH_EXTRA_ARGS] [-k | --connection-password-file CONNECTION_PASSWORD_FILE] + [--vault-id VAULT_IDS] [-J | --vault-password-file VAULT_PASSWORD_FILES] [-e EXTRA_VARS] [-t TAGS] [--skip-tags SKIP_TAGS] [-i INVENTORY] [--list-hosts] + [-l SUBSET] [-M MODULE_PATH] [-K | --become-password-file BECOME_PASSWORD_FILE] [--purge] [-o] [-s SLEEP] [-f] [-d DEST] [-U URL] [--full] [-C CHECKOUT] + [--accept-host-key] [-m MODULE_NAME] [--verify-commit] [--clean] [--track-subs] [--check] [--diff] + [playbook.yml ...] + + pulls playbooks from a VCS repo and executes them on target host +[...] + + + + + ansible-vault + + Is a command-line tool that allows you to encrypt sensitive data, such as passwords, API keys and other secrets + and store them securely within your playbooks and other configuration files. + &prompt.user;ansible-vault -h + usage: ansible-vault [-h] [--version] [-v] {create,decrypt,edit,view,encrypt,encrypt_string,rekey} ... + +encryption/decryption utility for Ansible data files + +[...] + + + + +
+
+ Creating a playbook + + An Ansible playbook is a YAML file that defines a series of tasks to be executed on one or more hosts. + This topic covers creating a simple playbook. + + + Set up SSH key-based authentication from the control node to each managed node. + Generate a key pair on the control node. + It is recommended to use a dedicated SSH key and clearly defined in the variable ansible_ssh_private_key_file. + + Copy the public key to the managed node. + + This one-time setup allows Ansible to connect securely without prompting for credentials during automation. + + Define an inventory file. For example: + + Although Ansible uses etc/ansible/hosts/ by default, it is a + best practice to maintain a separate inventory file and specify it using the-i flag. + + Verify your inventory file, for example: + &prompt.user;ansible-inventory -i test.ini --list + + + Test the connection between the control node and managed nodes with the Ansible ad-hoc command: + &prompt.user;ansible all -i test.ini -m ping + If the configuration is correct, the following message is displayed: + + This confirms Ansible can reach the managed nodes securely via SSH. + + Playbooks are YAML files that define the tasks Ansible should perform. + For example, create a file named install.yml to define a task to install common packages on all managed &suse; systems: + + + Run the playbook: + ansible-playbook -i hosts.ini install.yml + Ansible connects to each host in your inventory and executes the defined tasks using the system’s package manager. + + +
+ \ No newline at end of file diff --git a/references/ansible-best-practices.xml b/references/ansible-best-practices.xml new file mode 100644 index 000000000..a086c3bf5 --- /dev/null +++ b/references/ansible-best-practices.xml @@ -0,0 +1,27 @@ + + + %entities; +]> + + + + + + + &ansible; best practices + + + xxxx + + + + xxxx + diff --git a/references/ansible-configure.xml b/references/ansible-configure.xml new file mode 100644 index 000000000..866020e84 --- /dev/null +++ b/references/ansible-configure.xml @@ -0,0 +1,55 @@ + + + + + %entities; +]> + + + Understanding Ansible configuration + + + +Use the ansible.cfg file to adjust certain settings. The standard configuration is usually sufficient +for most users. Ansible's behavior can also be configured in environment variables, command-line options and playbook keywords. + + + + The ansible-config utility provides users with a comprehensive view of all available configuration settings, including their default values, + instructions on how to set them, and the origin of their current values. Ansible processes the following list and uses the first file found, all others are ignored. + + + + + ANSIBLE_CONFIG environment variable if set. + + + + + ansible.cfg located in the current directory. + + + + + ~/.ansible.cfg located in the home directory. + + + + + /etc/ansible/ansible.cfg + + + + You can generate a sample ansible.cfg file either with a fully commented out file or + more complete file that includes existing plugin. For example: + &prompt.user; ansible-config init --disabled > ansible.cfg + &prompt.user; ansible-config init --disabled -t all > ansible.cfg + \ No newline at end of file diff --git a/tasks/ansible-install.xml b/tasks/ansible-install.xml new file mode 100644 index 000000000..5359cda26 --- /dev/null +++ b/tasks/ansible-install.xml @@ -0,0 +1,49 @@ + + + + + %entities; +]> + + + Installing Ansible + + + +&ansible; is part of the base system on &productnameshort; &productnumber;. Additional modules are not required. + + + + + + + Refresh the repository and install &ansible; + &prompt.sudo;zypper refresh + &prompt.sudo;zypper install ansible + + + + To verify: + + &prompt.user;ansible --version + ansible [core 2.18.3] + config file = None + configured module search path = ['/root/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules'] + ansible python module location = /usr/lib/python3.13/site-packages/ansible + ansible collection location = /root/.ansible/collections:/usr/share/ansible/collections + executable location = /bin/ansible + python version = 3.13.2 (main, Feb 09 2025, 18:58:59) [GCC] (/usr/bin/python3.13) + jinja version = 3.1.6 + libyaml = True + + + + \ No newline at end of file