Onboard Users to VMs with Ansible and the Kestra Assets Catalog

Grant server access as a workflow instead of a favor. An operator picks a VM from a dropdown backed by the Kestra Assets catalog, enters the new user's login and SSH public key, and an Ansible playbook connects to the machine, creates the account with sudo membership, and installs the authorized key. The execution is linked to the VM asset, so every machine carries a history of who was onboarded onto it and when.

How it works

1. The vmAssetId input uses a dynamic expression with the assets() function to list all io.kestra.plugin.ee.assets.VM assets, restricting onboarding to machines Kestra actually manages.
2. The vmMetadata task (io.kestra.plugin.core.output.OutputValues) fetches the selected asset's metadata, including its vmName.
3. The run_ansible task (io.kestra.plugin.ansible.cli.AnsibleCLI) builds everything inline: the SSH private key is written from a secret to id_rsa, and the inventory resolves the VM's external IP by looking up kv('externalIpAddressMapping')[vmName], a KV map maintained by your provisioning flow.
4. The inline playbook runs two modules as root with become: true: user creates the account with groups: sudo, shell: /bin/bash, and a home directory, and authorized_key installs the provided public key. The assets.inputs block records the VM as lineage input.
5. chmod 600 id_rsa satisfies SSH key permission requirements before ansible-playbook -i inventory.ini playbook.yml runs.

What you get

• Self-service, catalog-scoped user onboarding with no manual SSH sessions.
• Idempotent account management: rerunning is safe because both Ansible modules converge state.
• The connecting private key kept in Kestra secrets, never on operator laptops.
• Asset lineage connecting each VM to its onboarding executions.

Who it's for

• Platform teams handling frequent access requests for project VMs.
• IT operations formalizing joiner processes on Linux estates.
• Teams using Kestra Assets as the source of truth for managed machines.

Why orchestrate this with Kestra

Manually adding users means someone with root SSHes in, runs useradd, and pastes a key, with no record and no consistency. Here the target list is constrained to cataloged assets, the IP resolution is automatic via the KV store, the playbook is versioned with the flow, credentials come from the secret backend, and the audit trail is the execution history itself. Add a Pause task and manager approval becomes part of the same flow.

Prerequisites

• Kestra Enterprise Edition with the Assets feature enabled and VM assets registered by your provisioning flow.
• A KV entry externalIpAddressMapping mapping VM names to reachable IPs.
• Root SSH access from the Kestra worker to the target VMs.

Secrets

• SSH_PRIVATE_KEY: root private key used by Ansible to reach the target VM.

Quick start

1. Add the secret above to your Kestra namespace.
2. Ensure externalIpAddressMapping exists in the KV store with your VM name to IP mapping.
3. Execute the flow, pick a VM, and provide the username and public key.
4. Verify login: ssh <username>@<vm-ip> with the matching private key.

How to extend

• Add a io.kestra.plugin.core.flow.Pause approval gate before the playbook for privileged access requests.
• Build an offboarding twin that sets state: absent on the user and removes the key.
• Notify the user via io.kestra.plugin.email.MailSend once access is granted.
• Grant group membership based on an input SELECT (developers, dba, readonly) instead of always sudo.

Links

• Ansible plugin docs: https://kestra.io/plugins/plugin-ansible
• Kestra Assets docs: https://kestra.io/docs/enterprise/governance/assets
• KV store docs: https://kestra.io/docs/concepts/kv-store