community.general.proxmox_pct_remote connection – Run tasks in Proxmox LXC container instances using pct CLI via SSH
Note
This connection plugin is part of the community.general collection (version 10.3.0).
You might already have this collection installed if you are using the ansible
package.
It is not included in ansible-core
.
To check whether it is installed, run ansible-galaxy collection list
.
To install it, use: ansible-galaxy collection install community.general
.
You need further requirements to be able to use this connection plugin,
see Requirements for details.
To use it in a playbook, specify: community.general.proxmox_pct_remote
.
New in community.general 10.3.0
Synopsis
Run commands or put/fetch files to an existing Proxmox LXC container using pct CLI via SSH.
Uses the Python SSH implementation (Paramiko) to connect to the Proxmox host.
Requirements
The below requirements are needed on the local controller node that executes this connection.
paramiko
Parameters
Parameter |
Comments |
---|---|
Configures, in seconds, the amount of time to wait for the SSH banner to be presented. This option is supported by paramiko version 1.15.0 or newer. Default: Configuration:
|
|
Automatically add host keys to Choices:
Configuration:
|
|
Set this to Choices:
Configuration:
|
|
Number of seconds until the plugin gives up on trying to write a lock file when writing SSH known host keys. Default: Configuration:
|
|
Set to Choices:
Configuration:
|
|
Secret used to either login the SSH server or as a passphrase for SSH keys that require it. Can be set from the CLI via the Configuration:
|
|
Remote port to connect to. Default: Configuration:
|
|
Path to private key file to use for authentication. Configuration:
|
|
Become command used in proxmox Default: Configuration:
|
|
Proxy information for running the connection via a jumphost. Default: Configuration:
|
|
Choices:
Configuration:
|
|
Save the host keys to a file. Choices:
Configuration:
|
|
Address of the remote target. Default: Configuration:
|
|
User to login/authenticate as. Can be set from the CLI via the Configuration:
|
|
Number of seconds until the plugin gives up on failing to establish a TCP connection. Default: Configuration:
|
|
Toggles the use of persistence for connections. Choices:
Configuration:
|
|
Whether or not to enable RSA SHA2 algorithms for pubkeys and hostkeys. On paramiko versions older than 2.9, this only affects hostkeys. For behavior matching paramiko<2.9 set this to Choices:
Configuration:
|
|
LXC Container ID Configuration:
|
Notes
Note
When NOT using this plugin as root, you need to have a become mechanism, e.g.
sudo
, installed on Proxmox and setup so we can run it without prompting for the password. Inside the container, we need a shell, for examplesh
and thecat
command to be available in thePATH
for this plugin to work.
Examples
# --------------------------------------------------------------
# Setup sudo with password less access to pct for user 'ansible':
# --------------------------------------------------------------
#
# Open a Proxmox root shell and execute:
# $ useradd -d /opt/ansible-pct -r -m -s /bin/sh ansible
# $ mkdir -p /opt/ansible-pct/.ssh
# $ ssh-keygen -t ed25519 -C 'ansible' -N "" -f /opt/ansible-pct/.ssh/ansible <<< y > /dev/null
# $ cat /opt/ansible-pct/.ssh/ansible
# $ mv /opt/ansible-pct/.ssh/ansible.pub /opt/ansible-pct/.ssh/authorized-keys
# $ rm /opt/ansible-pct/.ssh/ansible*
# $ chown -R ansible:ansible /opt/ansible-pct/.ssh
# $ chmod 700 /opt/ansible-pct/.ssh
# $ chmod 600 /opt/ansible-pct/.ssh/authorized-keys
# $ echo 'ansible ALL = (root) NOPASSWD: /usr/sbin/pct' > /etc/sudoers.d/ansible_pct
#
# Save the displayed private key and add it to your ssh-agent
#
# Or use ansible:
# ---
# - name: Setup ansible-pct user and configure environment on Proxmox host
# hosts: proxmox
# become: true
# gather_facts: false
#
# tasks:
# - name: Create ansible user
# ansible.builtin.user:
# name: ansible
# comment: Ansible User
# home: /opt/ansible-pct
# shell: /bin/sh
# create_home: true
# system: true
#
# - name: Create .ssh directory
# ansible.builtin.file:
# path: /opt/ansible-pct/.ssh
# state: directory
# owner: ansible
# group: ansible
# mode: '0700'
#
# - name: Generate SSH key for ansible user
# community.crypto.openssh_keypair:
# path: /opt/ansible-pct/.ssh/ansible
# type: ed25519
# comment: 'ansible'
# force: true
# mode: '0600'
# owner: ansible
# group: ansible
#
# - name: Set public key as authorized key
# ansible.builtin.copy:
# src: /opt/ansible-pct/.ssh/ansible.pub
# dest: /opt/ansible-pct/.ssh/authorized-keys
# remote_src: yes
# owner: ansible
# group: ansible
# mode: '0600'
#
# - name: Add sudoers entry for ansible user
# ansible.builtin.copy:
# content: 'ansible ALL = (root) NOPASSWD: /usr/sbin/pct'
# dest: /etc/sudoers.d/ansible_pct
# owner: root
# group: root
# mode: '0440'
#
# - name: Fetch private SSH key to localhost
# ansible.builtin.fetch:
# src: /opt/ansible-pct/.ssh/ansible
# dest: ~/.ssh/proxmox_ansible_private_key
# flat: yes
# fail_on_missing: true
#
# - name: Clean up generated SSH keys
# ansible.builtin.file:
# path: /opt/ansible-pct/.ssh/ansible*
# state: absent
#
# - name: Configure private key permissions on localhost
# hosts: localhost
# tasks:
# - name: Set permissions for fetched private key
# ansible.builtin.file:
# path: ~/.ssh/proxmox_ansible_private_key
# mode: '0600'
#
# --------------------------------
# Static inventory file: hosts.yml
# --------------------------------
# all:
# children:
# lxc:
# hosts:
# container-1:
# ansible_host: 10.0.0.10
# proxmox_vmid: 100
# ansible_connection: community.general.proxmox_pct_remote
# ansible_user: ansible
# container-2:
# ansible_host: 10.0.0.10
# proxmox_vmid: 200
# ansible_connection: community.general.proxmox_pct_remote
# ansible_user: ansible
# proxmox:
# hosts:
# proxmox-1:
# ansible_host: 10.0.0.10
#
#
# ---------------------------------------------
# Dynamic inventory file: inventory.proxmox.yml
# ---------------------------------------------
# plugin: community.general.proxmox
# url: https://10.0.0.10:8006
# validate_certs: false
# user: ansible@pam
# token_id: ansible
# token_secret: !vault |
# $ANSIBLE_VAULT;1.1;AES256
# ...
# want_facts: true
# exclude_nodes: true
# filters:
# - proxmox_vmtype == "lxc"
# want_proxmox_nodes_ansible_host: false
# compose:
# ansible_host: "'10.0.0.10'"
# ansible_connection: "'community.general.proxmox_pct_remote'"
# ansible_user: "'ansible'"
#
#
# ----------------------
# Playbook: playbook.yml
# ----------------------
---
- hosts: lxc
# On nodes with many containers you might want to deactivate the devices facts
# or set `gather_facts: false` if you don't need them.
# More info on gathering fact subsets:
# https://docs.ansible.com/ansible/latest/collections/ansible/builtin/setup_module.html
#
# gather_facts: true
# gather_subset:
# - "!devices"
tasks:
- name: Ping LXC container
ansible.builtin.ping: