Module ansible

The ansible module allows you to run Ansible playbooks against Deckhouse Virtualization Platform virtual machines, as well as against hosts that are named by address and are not resources of the cluster.

A run is described by the AnsibleRun custom resource. The playbook is executed in a temporary Pod created by the module, and the result of the execution is stored in the status of that same resource. A separate control node with Ansible installed and an inventory file of your own are not required.

Main features

The module provides the following capabilities:

• Configuring a virtual machine right after it is created. The playbook runs as soon as the machine starts answering SSH, so the configuration does not have to be baked into the image.
• Running one playbook against a group of machines selected by labels. The platform resolves the group at the moment the run starts, so the list of machines does not have to be maintained manually.
• Keeping configuration in the desired state on a schedule, the way a CronJob resource does. A regular execution of the playbook brings the machines back to the state described in it.
• Running a playbook from a ConfigMap resource or from a Git repository, together with its roles and Galaxy dependencies. A project with roles is executed unchanged, and a commit reference pins the version of the playbook.
• Configuring hosts that are not resources of the cluster, such as a physical server, a network appliance or a machine whose address is known only to its owner. Such hosts are named by address in the manifest of the run, and this capability is available in commercial editions only.
• Running the listed scenarios inside an isolated network, such as a dedicated management network or an infrastructure network of your own. The run receives an interface in the specified network, and this capability is also available in commercial editions only.

How the module works

A run is executed in the following steps:

1. A Secret with SSH credentials and an AnsibleRun resource are created in the namespace. The resource states which machines to configure, how to connect to them and which playbook to run.
2. The controller of the module resolves the targets of the run, obtains their addresses and builds the Ansible inventory file. Host groups and variables are taken by the controller from the annotations of the virtual machines and from the fields of the run.
3. The controller creates a temporary Pod with the ansible-playbook utility and, if an additional network is specified in the run, gives that Pod an interface in such a network.
4. The result of the execution is written into the status of the AnsibleRun resource. The status holds the number of completed tasks per host, the list of skipped machines and the tasks that failed. The Pod of a successful run is deleted, while the Pod of a failed run is kept together with its logs.

System requirements and recommendations

Before using the module, make sure that the following requirements are met:

• Deckhouse Kubernetes Platform 1.68 or later is deployed in the cluster. Earlier versions of the platform do not support the module.
• The virtualization module is enabled if the targets of the run are virtual machines. A run in an additional network also requires the sdn module with an address pool on that network.
• The target machine answers SSH and has an address the platform knows about. Such an address is either the status.ipAddress of the virtual machine or an address from an additional network that has an address pool configured. This is the address the run connects to.

Addresses configured inside a guest OS by hand or handed out by an external DHCP server are invisible to the platform. Machines with such addresses are configured as hosts named by address.

Availability in editions

The module is available in every edition of the platform, but some of its capabilities work in commercial editions only. In the Community Edition a run works with virtual machines of the platform and is executed in the main network of the cluster.

In the Community Edition a manifest that uses an unavailable capability is refused when it is created. A run created before the cluster moved to that edition ends in the Error phase with the EditionNotSupported reason.

Limits

Keep the following limits in mind when planning work with the module:

• A run is executed once, and its spec cannot be changed after creation. To run the playbook again or with different parameters, create another AnsibleRun resource, and for regular runs use the AnsibleRunSchedule resource.
• One run works with targets of a single kind and is executed in a single network. If both virtual machines and hosts named by address, or machines from different networks, have to be configured, split the work into several runs.
• SSH is the only supported transport, so an SSH server has to be running on the target machine. The credentials are read by the module from a Secret in the namespace where the run is created, so a single Secret cannot serve runs from different namespaces.
• The module is at the Experimental stage. This means that the API of the module may change in later releases, so it is recommended to check how runs behave in a test environment before upgrading the platform.

The numeric ceilings of a single run are listed in the table below.

Further reading

Detailed information on working with the module is provided in the following sections:

• The user guide describes every field of a run, the result format and the troubleshooting steps.
• The examples hold ready-made scenarios, from a first connectivity check to scheduled runs and runs in an isolated network.