Ansible: Difference between revisions

Latest revision as of 04:11, 2 November 2023

This material needs expanding ...

Please feel free to help us complete it.

Ansible is a simple configuration management, deployment, task-execution, and multinode orchestration framework.

It uses SSH for the communication between the involved systems, no server or client daemons are needed, and no additional software beside Python on managed nodes is required.

Installation

On the control node (master host), you can install the ansible-core package and/or the ansible package, which is a "batteries included" package that brings in ansible-core along with a set of curated collections. Both are available from the community repository:

Tip: If you don't know you need ansible-core, I would recommend installing ansible.

# apk add ansible

Create a SSH key

Generate a SSH key for the managed node. It's recommended to use a key which is protected with a password.

$ ssh-keygen -t ed25519

Managed nodes

There are only minimal requirements for the clients. For every system you want to manage, you need to have the client's SSH key in the authorized_keys file of the management system and Python.

Install the Python package:

# apk add python3

Transfer the SSH key

There are two ways to do it. From a default Alpine installation you can use ssh and cat to do it.

ssh root@[IP of the management system] 'cat ~/.ssh/id_ed25519.pub' | cat - >> ~/.ssh/authorized_keys

If you are planning to use additional features of SSH. ssh-copy-id, which is provided by the openssh-client package, can help you with the key setup.

ssh-copy-id -i ~/.ssh/id_ed25519.pub root@[IP of the management system]

Usage

Configuration

Todo: https://docs.ansible.com/ansible/latest/reference_appendices/config.html

Inventory

The inventory is the list of managed nodes or "hosts". The default location is /etc/ansible/hosts. You can specify a different inventory file using -i PATH on the command line. See How to build your inventory for more information.

Contents of /etc/ansible/hosts

[control]
10.0.0.5

[managed]
10.0.1.5
10.0.1.50

Ping

Check that you can reach all nodes:

$ ansible all -m ping

Playbooks

When writing playbooks for Alpine Linux there are some things to keep in mind:

There is support for OpenRC, the Init System, in the service module.

- name: Make "lighttpd" start on boot and start now, if not started.
  ansible.builtin.service:
    name: lighttpd
    enabled: true
    state: started

There is support for APK as of Ansible 2.0, in the apk module.

- name: Ensure lighttpd is installed, update cache and install if not.
  community.general.apk:
    name: lighttpd
    state: present
    update_cache: yes

There is support for the Awall firewall as of Ansible 2.4, in the awall module.

- name: Enable "foobar" policy
  community.general.awall:
    name: foobar
    state: enabled
    activate: true

If you are going to re-use playbooks from other Linux distributions, please keep in mind that Alpine Linux uses different paths for the binaries. For example rm is /bin/rm.

Vault

Todo: https://docs.ansible.com/ansible/latest/vault_guide/index.html

ansible-lint

You can check if you're using "proven practices", by installing the ansible-lint package and running:

$ ansible-lint -s ./PATH

@@ Line 1: / Line 1: @@
-{{Draft|At the moment Alpine Linux can't be used }}
+{{Expand}}
+{{TOC right}}
-[http://ansible.cc/ ansible] is a simple configuration management, deployment, task-execution, and multinode orchestration framework. It uses SSH for the communication between the involved systems, no server or client daemons are needed, and no additional software beside Python on client boxes is required.
+[https://www.ansible.com/ Ansible] is a simple configuration management, deployment, task-execution, and multinode orchestration framework.
-= Installation of ansible =
+It uses SSH for the communication between the involved systems, no server or client daemons are needed, and no additional software beside Python on managed nodes is required.
-ansible is available in ''testing''. The latest package is broken, sorry.
-{{Cmd|apk add ansible -U -X http://dl-3.alpinelinux.org/alpine/edge/testing/ --allow-untrusted}}
+== Installation ==
+On the control node (master host), you can install the {{Pkg|ansible-core}} package and/or the {{Pkg|ansible}} package, which is a "batteries included" package that brings in {{Pkg|ansible-core}} along with a set of curated [https://docs.ansible.com/collections.html collections].  Both are available from the [[Repositories#Community|community]] repository:
+{{Tip|If you don't know you need {{Pkg|ansible-core}}, I would recommend installing {{Pkg|ansible}}.}}
+{{Cmd|# apk add ansible}}
+=== Create a SSH key ===
-== Create a SSH key ==
 Generate a SSH key for the managed node. It's recommended to use a key which is protected with a password.
-{{Cmd|ssh-keygen -t rsa}}
+{{Cmd|$ ssh-keygen -t ed25519}}
-= Managed nodes =
+== Managed nodes ==
 There are only minimal requirements for the clients. For every system you want to manage, you need to have the client's SSH key in the <code>authorized_keys</code> file of the management system and Python.
-Install the Python package.
+Install the Python package:
-{{Cmd|apk add python}}
+{{Cmd|# apk add python3}}
-== Transfer the SSH key ==
+=== Transfer the SSH key ===
 There are two ways to do it. From a default Alpine installation you can use ssh and cat to do it.
-{{Cmd|ssh root@[IP of the management system] 'cat ~/.ssh/id_rsa.pub' | cat - >> ~/.ssh/authorized_keys}}
+{{Cmd|<nowiki>ssh root@[IP of the management system] 'cat ~/.ssh/id_ed25519.pub' | cat - >> ~/.ssh/authorized_keys</nowiki>}}
 If you are planning to use additional features of SSH. <code>ssh-copy-id</code>, which is provided by the <code>openssh-client</code> package, can help you with the key setup.
-{{Cmd|ssh-copy-id -i ~/.ssh/id_rsa.pub root@[IP of the management system]}}
+{{Cmd|ssh-copy-id -i ~/.ssh/id_ed25519.pub root@[IP of the management system]}}
+== Usage ==
+=== Configuration ===
+{{Todo|https://docs.ansible.com/ansible/latest/reference_appendices/config.html}}
+=== Inventory ===
+The inventory is the list of managed nodes or "hosts".  The default location is <code>/etc/ansible/hosts</code>.  You can specify a different inventory file using <code>-i PATH</code> on the command line.
+See [https://docs.ansible.com/ansible/latest/inventory_guide/intro_inventory.html How to build your inventory] for more information.
+{{Cat|/etc/ansible/hosts|[control]
+.0.0.5
+[managed]
+.0.1.5
+.0.1.50}}
+=== Ping ===
+Check that you can reach all nodes:
+{{Cmd|$ ansible all -m ping}}
+=== Playbooks ===
+When writing playbooks for Alpine Linux there are some things to keep in mind:
+<ol>
+<li>There is support for OpenRC, the [[OpenRC|Init System]], in the [https://docs.ansible.com/ansible/latest/collections/ansible/builtin/service_module.html service] module.
+<pre>
+- name: Make "lighttpd" start on boot and start now, if not started.
+  ansible.builtin.service:
+    name: lighttpd
+    enabled: true
+    state: started
+</pre>
+<li>There is support for [[Alpine_Package_Keeper|APK]] as of Ansible 2.0, in the [https://docs.ansible.com/ansible/latest/collections/community/general/apk_module.html apk] module.
+<pre>
+- name: Ensure lighttpd is installed, update cache and install if not.
+  community.general.apk:
+    name: lighttpd
+    state: present
+    update_cache: yes
+</pre>
+<li>There is support for the [[Alpine_Wall|Awall]] firewall as of Ansible 2.4, in the [https://docs.ansible.com/ansible/latest/collections/community/general/awall_module.html awall] module.
+<pre>
+- name: Enable "foobar" policy
+  community.general.awall:
+    name: foobar
+    state: enabled
+    activate: true
+</pre>
+<li>
+If you are going to re-use playbooks from other Linux distributions, please keep in mind that Alpine Linux uses different paths for the binaries.  For example <code>rm</code> is <code>/bin/rm</code>.
+</ol>
-= Setup hosts =
+=== Vault ===
-Add all your remote systems to <code>/etc/ansible/hosts</code>. For details, please refer to [http://ansible.cc/docs/patterns.html#hosts-and-groups Hosts and Groups] in the ansible documentation.
-{{Cat|/etc/ansible/hosts|
+{{Todo|https://docs.ansible.com/ansible/latest/vault_guide/index.html}}
-.168.1.50
-.0.0.12
-webserver.example.org
-mail.example.org}}
-= First test =
+=== ansible-lint ===
-{{Cmd|$ ansible all -m ping -u you --sudo}}
+You can check if you're using "[https://ansible-lint.readthedocs.io/ proven practices]",
+by installing the {{Pkg|ansible-lint}} package and running:
-Another test is check all variables.
+{{Cmd|$ ansible-lint -s ./PATH}}
-{{Cmd|# ansible [IP of your Alpine Linux box] -m setup}}
+== See Also ==
-= Playbooks =
+* https://docs.ansible.com/ansible/latest/collections/community/general/apk_module.html - Official documentation for the apk module.
-When writing playbooks for Alpine Linux there are some issues:
+* [https://wiki.archlinux.org/title/Ansible ArchWiki: Ansible]
-# At the moment APK is not supported natively by Ansible. But the following will work {{Cmd|action: command /sbin/apk add lighttpd}}
+[[Category:Installation]]
-# Same with the OpenRC, the [[Alpine_Linux_Init_System|Init System]] {{Cmd|action: command /etc/init.d/lighttpd start}}
+[[Category:System_Administration]]
-# If you are going to re-use playbooks from other Linux distribution, please keep in mind that Alpine Linux uses different paths for the binaries. <code>/bin/rm</code>