Skip to content

ansible/receptor-collection

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

72 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

1. Ansible Receptor Collection

2. Description

This collection prepares and configures a node for running Receptor. The setup role in particular will configure a systemd service to run Receptor. As long as the service is running, the node will remain connected to other Receptor nodes in the mesh. This collection supports defining the peering relationship between nodes.

This collection contains two roles:

  • podman : installs and configures podman on the node
  • setup: installs and configures Receptor on the node

3. Environments Tested

This collection has been tested on the following distributions:

OS Release Tested (Y/N)
Centos >=8 Y
Redhat >=8 Y
Debian >=11 Y

4. Roles

4.1. Podman

Installs and configures podman.

4.1.1. Variables

Parameter Type Defaults Comments
podman_user string podman The user under which podman will be configured.
podman_group string podman The group under which podman will be configured.
default_runtime string crun The default container runtime to use for podman.
default_cgroup_manager string cgroupfs The default cgroup manager to use for podman.

4.2. Setup

Installs and configures a Receptor node.

4.2.1 Overview

The setup role will do the following,

  • Install Receptor
    • By default, Receptor is obtained via the pre-built binary on the Receptor Github release page.
    • For Centos/Redhat/Fedora systems, Receptor can be installed via the dnf package manager.
    • It is also possible to upload a custom Receptor binary from the local filesystem to the node.
  • Configure a systemd service to run whichever Receptor binary was obtained.
    • This service should start automatically on system startup.
  • Generate a Receptor configuration file.
  • Start the Receptor service.

See receptor_install_method for options on how Receptor is installed.

4.2.2. Variables

Parameter Type Defaults Comments
receptor_install_method string release Options are 'release', 'package', or 'local'. If 'package', will use the os-specific package manager to install Receptor. If 'local', will upload a local receptor binary. To be paired with receptor_local_bin_file. If 'release', the receptor binary will be downloaded from receptor Releases on github.
receptor_local_bin_file string '' Path of local Receptor binary, if install method is 'local'.
receptor_install_dir string /usr/bin Directory of the Receptor binary path on remote node. if install method is 'release' or 'local'.
receptor_packages list [] Set the names of the packages needed to install Receptor, if install method is 'package'.
additional_python_packages list [] Install additional python packages.
python_executable string python3 The python executable for installing python packages.
pip_executable string pip3 The pip executable for installing python packages.
additional_system_packages list ["python3-pip"] Install other system packages, probably on a per-node-type basis using groupvars or hostvars.
receptor_user string receptor The user under which Receptor will be configured.
receptor_group string receptor The group under which Receptor will be configured.
receptor_socket_dir string /var/run/receptor Directory for the Receptor control socket file.
receptor_control_filename string receptor.sock Path of the control socket file.
receptor_config_dir string /etc/receptor Path to the Receptor config file.
routable_hostname string '' Hostvar for the routable address to this node. If this is unset ansible_host will be used instead. Must be unique.
receptor_peers list of dict '' Hostvar for the Ansible hosts that this node is peering outwards to. This is expected to be a list of dicts. In the dicts, the 'host' key is required, 'port' and 'protocol' are optional and will default to the overall defaults for receptor_port and receptor_protocol.
receptor_tls boolean false If true, configure Receptor to use TLS for all connections.
receptor_replace_tls string false If true, upload and replace existing TLS certificate and keys. If false, they will only be uploaded if the files are not present on the node.
receptor_mintls13 boolean false If true, force the minimum TLS version to be 1.3. Otherwise, the minimum version will be 1.2. This variable has no effect unless receptor_tls is enabled.
receptor_tls_dir string /etc/receptor/tls Directory on the server where the TLS certificates and keys are located.
receptor_tls_ca_dir string {{ receptor_tls_dir }}/ca Directory on the server where the CA certificates and keys are located.
receptor_tls_certfile string {{ receptor_tls_dir }}/{{ receptor_host_identifier }}.crt Path on the server to the TLS certificate file.
receptor_tls_keyfile string {{ receptor_tls_dir }}/{{ receptor_host_identifier }}.key Path on the server to the TLS key file.
receptor_ca_certfile string "{{ receptor_tls_ca_dir }}/mesh-CA.crt" Path on the server to the certificate authority certificate file.
receptor_ca_keyfile string {{ receptor_tls_ca_dir }}/mesh-CA.key Path on the server to the certificate authority key file.
custom_ca_certfile string '' Path on the local filesystem to user-provided certificate authority certificate file.
custom_ca_keyfile string '' Path on the local filesystem to user-provided certificate authority key file.
custom_tls_certfile string '' Path on the local filesystem to user-provided node certificate file. If used, both must be provided in combination with a custom_ca_certfile that was used to sign them.
custom_tls_keyfile string '' Path on the local filesystem to user-provided node key file. If used, both must be provided in combination with a custom_ca_certfile that was used to sign them.
receptor_sign boolean false If true, Receptor will sign any work that it sends over the Receptor mesh using a private key.
receptor_verify boolean false If true, Receptor will verify any work that it receives using a public key.
receptor_worksign_key_dir string /etc/receptor Directory on the server to the public and private OpenSSL work signing key files.
receptor_worksign_private_keyfile string {{ receptor_worksign_key_dir }}/work_private_key.pem Path on the server to the private OpenSSL work signing key file.
receptor_worksign_public_keyfile string {{ receptor_worksign_key_dir }}/work_public_key.pem Path on the server to the public OpenSSL work signing key file.
custom_worksign_private_keyfile string '' Path on the local filesystem to user-provided OpenSSL work signing key file.
custom_worksign_public_keyfile string '' Path on the local filesystem to user-provided OpenSSL work signing key file.
receptor_log_level string info Options are 'error', 'warning', 'info', and 'debug'.
receptor_log_dir string /var/log/receptor Directory for the Receptor log file. Used only when receptor_install_method is local or release.
receptor_listener boolean true If true, configure Receptor to listen for incoming remote connections.
receptor_local_only boolean false If true, Receptor is not configured with any listeners or peers. This will take precedence over the value of receptor_listener.
receptor_protocol string tcp Protocol for Receptor backend connections. Options are 'tcp', 'udp', and 'ws'.
receptor_port integer 27199 Set the port number used by this instance of Receptor, if receptor_listener is enabled.
receptor_work_commands dict '' The definition of the Receptor work commands. This variable is expected to be a dictionary, with keys the unique worktype name, and values a dict of the rest of the key-value pairs of the work definition.
receptor_kubernetes_commands dict '' The definition of the Receptor work-kubernetes commands. This variable is expected to be a dictionary, with keys the unique worktype name, and values a dict of the rest of the key-value pairs of the work definition.
receptor_github_owner string ansible Owner of the github repository to download Receptor from, if install method is 'release'.
receptor_github_repo string receptor Repository name to download Receptor from, if install method is 'release'.
receptor_github_release string '' Receptor version to download Receptor from, if install method is 'release'. If not specified, the latest release will be used.
receptor_service_name string receptor Name of systemd service that runs Receptor. Used only when receptor_install_method is 'local' or 'release'. If Receptor is installed via a package manager, a systemd is already configured.
receptor_fd_limit_soft integer 4096 The file descriptor limits in PAM for Receptor.
receptor_fd_limit_soft integer 8192 The file descriptor limits in PAM for Receptor.

5. License

Apache 2