Module ansible

The ansible module runs Ansible playbooks against Deckhouse Platform (DP) virtual machines (VMs) and against hosts that you specify by address and that are not cluster resources.

The AnsibleRun custom resource describes a run. DP executes the playbook in a temporary Pod and records the result in the status of the same resource, so you need neither a separate control node with Ansible nor an inventory file of your own.

Main features

The module provides the following capabilities:

• Configuring a VM after it is created. A run applies the required configuration to a running VM that answers SSH, so the configuration does not have to be baked into the image.
• Executing one playbook against a group of VMs selected by labels. DP resolves the group at the moment the run starts, so you do not have to maintain the list of VMs manually.
• Keeping configuration in the desired state. A schedule executes the playbook regularly, and every run brings the VMs back to the state described in it.
• Executing 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 cluster resources, for example, a physical server, a network appliance or a host whose address only its owner knows. Such hosts are listed by address in the manifest of the run, and this capability is available in commercial DP editions only.
• Executing the listed scenarios inside an isolated network, such as a dedicated management network or an infrastructure network of your organization. The run receives an interface in the specified network, and this capability is also available in commercial DP editions only.

How the module works

DP executes a run in the following steps:

1. The user creates a Secret with SSH credentials and an AnsibleRun resource in the namespace. The resource states which VMs to configure, how to connect to them and which playbook to execute.
2. DP resolves the targets of the run, obtains their addresses and builds the Ansible inventory file. DP takes host groups and variables from the annotations of the VMs and from the fields of the run.
3. DP creates a temporary Pod with the ansible-playbook utility and, if the run specifies an additional network, attaches the Pod to it.
4. DP writes the result of the execution into the status of the AnsibleRun resource. The status holds the number of completed tasks per host, the list of skipped VMs and the failed tasks. DP deletes the Pod of a successful run and keeps the Pod of a failed run together with its logs.

System requirements and recommendations

Before using the module, make sure that the following requirements for the cluster and VMs are met:

• The cluster runs DP 1.68 or later.
• The virtualization module is enabled to work with VMs. A run in an additional network also requires the sdn module and an address pool configured on that network.
• The target VM answers SSH at an address DP knows about. This is the address from the status.ipAddress field of the VM or an address in an additional network with an address pool configured.

DP does not see addresses configured inside a guest OS by hand or handed out by an external DHCP server. Configure VMs with such addresses as hosts specified by address.

Availability in editions

The module is available in every DP edition, but some of its capabilities work in commercial editions only. In DP Open a run works only with DP VMs and only in the main network of the cluster.

In DP Open the API server rejects a manifest that uses these capabilities. If such a manifest still ends up in the cluster, the run ends in the Error phase with the EditionNotSupported reason. This happens when the run was created before the cluster moved to DP Open or when the cluster runs Kubernetes older than 1.30.

Limits

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

• A run is executed only once, and its spec cannot be changed after creation. To execute 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 only in a single network. To configure both VMs and hosts specified by address, or VMs from different networks, split the work into several runs.
• A run connects to its targets over SSH only, so an SSH server has to be running on the target VM. DP reads the credentials from a Secret in the namespace of the run, so a single Secret cannot serve runs from different namespaces.
• The module is at the Experimental stage, and its API may change in later releases. Check how runs behave in a test environment before upgrading.

The table below lists the numeric limits of a single run.

Further reading

The fields of a run, the result format and the troubleshooting steps are described in the user guide. Ready-made scenarios, from a first connectivity check to scheduled runs and runs in an isolated network, are collected on the Examples page.