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

banner_timeout

float

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: 30.0

Configuration:

host_key_auto_add

boolean

Automatically add host keys to ~/.ssh/known_hosts.

Choices:

  • false

  • true

Configuration:

host_key_checking

boolean

Set this to false if you want to avoid host key checking by the underlying tools Ansible uses to connect to the host.

Choices:

  • false

  • true ← (default)

Configuration:

lock_file_timeout

integer

Number of seconds until the plugin gives up on trying to write a lock file when writing SSH known host keys.

Default: 60

Configuration:

look_for_keys

boolean

Set to false to disable searching for private key files in ~/.ssh/.

Choices:

  • false

  • true ← (default)

Configuration:

password

string

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 --ask-pass option.

Configuration:

  • Variable: ansible_password

  • Variable: ansible_ssh_pass

  • Variable: ansible_ssh_password

  • Variable: ansible_paramiko_pass

  • Variable: ansible_paramiko_password

port

integer

Remote port to connect to.

Default: 22

Configuration:

  • INI entries:

    [defaults]
    remote_port = 22
    
    [paramiko_connection]
    remote_port = 22
    
  • Environment variable: ANSIBLE_REMOTE_PORT

  • Environment variable: ANSIBLE_REMOTE_PARAMIKO_PORT

  • Variable: ansible_port

  • Variable: ansible_ssh_port

  • Variable: ansible_paramiko_port

  • Keyword: port

private_key_file

string

Path to private key file to use for authentication.

Configuration:

  • INI entries:

    [defaults]
    private_key_file = VALUE
    
    [paramiko_connection]
    private_key_file = VALUE
    
  • Environment variable: ANSIBLE_PRIVATE_KEY_FILE

  • Environment variable: ANSIBLE_PARAMIKO_PRIVATE_KEY_FILE

  • Variable: ansible_private_key_file

  • Variable: ansible_ssh_private_key_file

  • Variable: ansible_paramiko_private_key_file

  • CLI argument: –private-key

proxmox_become_method

string

Become command used in proxmox

Default: "sudo"

Configuration:

  • Variable: proxmox_become_method

proxy_command

string

Proxy information for running the connection via a jumphost.

Default: ""

Configuration:

  • INI entry:

    [paramiko_connection]
    proxy_command = ""
    
  • Environment variable: ANSIBLE_PARAMIKO_PROXY_COMMAND

  • Variable: ansible_paramiko_proxy_command

pty

boolean

sudo usually requires a PTY, true to give a PTY and false to not give a PTY.

Choices:

  • false

  • true ← (default)

Configuration:

  • INI entry:

    [paramiko_connection]
    pty = true
    
  • Environment variable: ANSIBLE_PARAMIKO_PTY

record_host_keys

boolean

Save the host keys to a file.

Choices:

  • false

  • true ← (default)

Configuration:

remote_addr

string

Address of the remote target.

Default: "inventory_hostname"

Configuration:

  • Variable: inventory_hostname

  • Variable: ansible_host

  • Variable: ansible_ssh_host

  • Variable: ansible_paramiko_host

remote_user

string

User to login/authenticate as.

Can be set from the CLI via the --user or -u options.

Configuration:

  • INI entries:

    [defaults]
    remote_user = VALUE
    
    [paramiko_connection]
    remote_user = VALUE
    
  • Environment variable: ANSIBLE_REMOTE_USER

  • Environment variable: ANSIBLE_PARAMIKO_REMOTE_USER

  • Variable: ansible_user

  • Variable: ansible_ssh_user

  • Variable: ansible_paramiko_user

  • Keyword: remote_user

timeout

integer

Number of seconds until the plugin gives up on failing to establish a TCP connection.

Default: 10

Configuration:

  • INI entries:

    [defaults]
    timeout = 10
    
    [ssh_connection]
    timeout = 10
    
    [paramiko_connection]
    timeout = 10
    
  • Environment variable: ANSIBLE_TIMEOUT

  • Environment variable: ANSIBLE_SSH_TIMEOUT

  • Environment variable: ANSIBLE_PARAMIKO_TIMEOUT

  • Variable: ansible_ssh_timeout

  • Variable: ansible_paramiko_timeout

  • CLI argument: –timeout

use_persistent_connections

boolean

Toggles the use of persistence for connections.

Choices:

  • false ← (default)

  • true

Configuration:

use_rsa_sha2_algorithms

boolean

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 false.

Choices:

  • false

  • true ← (default)

Configuration:

vmid

integer

LXC Container ID

Configuration:

  • Variable: proxmox_vmid

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 example sh and the cat command to be available in the PATH 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:

Authors

  • Nils Stein (@mietzen)

Hint

Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up.