containers.podman.podman_system_connection module – Manage podman system connections

Note

This module is part of the containers.podman collection (version 1.18.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 containers.podman. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: containers.podman.podman_system_connection.

New in containers.podman 1.18.0

Synopsis

  • Manage podman system connections with podman system connection command.

  • Add, remove, rename and set default connections to Podman services.

Requirements

The below requirements are needed on the host that executes this module.

  • podman

Parameters

Parameter

Comments

default

boolean

Make this connection the default for this user

Choices:

  • false

  • true

destination

string

Destination for the connection. Required when state=present.

Can be in the format [user@]hostname[:port], ssh://[user@]hostname[:port], unix://path, tcp://hostname:port

executable

string

Path to podman executable if it is not in the $PATH on the machine running podman

Default: "podman"

identity

string

Path to SSH identity file

name

string / required

Name of the connection

new_name

string

New name for the connection when renaming (used with state=present)

port

integer

SSH port (default is 22)

socket_path

string

Path to the Podman service unix domain socket on the ssh destination host

state

string

State of the connection

Choices:

  • "present" ← (default)

  • "absent"

Examples

- name: Add a basic SSH connection
  containers.podman.podman_system_connection:
    name: production
    destination: [email protected]
    state: present

- name: Add SSH connection with custom port and identity
  containers.podman.podman_system_connection:
    name: staging
    destination: [email protected]
    port: 2222
    identity: ~/.ssh/staging_rsa
    state: present

- name: Add connection and set as default
  containers.podman.podman_system_connection:
    name: development
    destination: [email protected]
    default: true
    state: present

- name: Add unix socket connection
  containers.podman.podman_system_connection:
    name: local
    destination: unix:///run/podman/podman.sock
    state: present

- name: Add TCP connection
  containers.podman.podman_system_connection:
    name: remote_tcp
    destination: tcp://remote.example.com:8080
    state: present

- name: Rename a connection
  containers.podman.podman_system_connection:
    name: old_name
    new_name: new_name
    state: present

- name: Remove a connection
  containers.podman.podman_system_connection:
    name: old_connection
    state: absent

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key

Description

actions

list / elements=string

Actions performed on the connection

Returned: always

Sample: ["Connection 'production' added", "Connection 'production' set as default"]

connection

dictionary

Connection information in podman JSON format

Returned: always

Sample: {"Default": true, "Name": "production", "ReadWrite": true, "URI": "ssh://root@server.example.com:22/run/user/0/podman/podman.sock"}

Authors

  • Sagi Shnaidman (@sshnaidm)