receptor
2Roles
Description
Receptor installer
Readme
Ansible Receptor Collection (ansible.receptor)
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.
Requirements
ansible_core >= 2.15.0 Python >= 3.9
Installation
Before using this collection, you need to install it with the Ansible Galaxy command-line tool:
ansible-galaxy collection install ansible.receptor
You can also include it in a requirements.yml file and install it with:
ansible-galaxy collection install -r requirements.yml
using the format:
collections:
- name: ansible.receptor
Note that if you install any collections from Ansible Galaxy, they will not be upgraded automatically when you upgrade the Ansible package. To upgrade the collection to the latest available version, run the following command:
ansible-galaxy collection install ansible.receptor --upgrade
You can also install a specific version of the collection, for example, if you need to downgrade when something is broken in the latest version (please report an issue in this repository). Use the following syntax to install version 1.0.0:
ansible-galaxy collection install ansible.receptor:==1.0.0
See using Ansible collections for more details.
Use Cases
This collection contains two roles:
- podman : installs and configures podman on the node
- setup: installs and configures Receptor on the node
Podman Role
Installs and configures podman.
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. |
Setup Role
Installs and configures a Receptor node by doing 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
dnfpackage 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.
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. |
Testing
This collection has been tested on the following distributions:
| OS | Release | Tested (Y/N) |
|---|---|---|
| Centos | >=8 | Y |
| Redhat | >=8 | Y |
| Debian | >=11 | Y |
Code Quality
This project uses SonarCloud for continuous code quality analysis.
- Quality Analysis: All pull requests are automatically analyzed for code quality
- Quality Gate: New code must meet quality standards including maintainability, reliability, and security
- Dynamic Analysis: SonarCloud performs continuous code quality checks on all contributions
Note: This is an Ansible collection with YAML-based roles. Testing is performed using Molecule.
To run tests locally:
pip install -r molecule/requirements.txt
molecule test
Contributing
We value all feedback. To report an issue or propose an enhancement, please open an issue in our GitHub project.
We also encourage and welcome contributions! To fix an issue or make code changes, please create a fork and submit a pull request PR.
Support
As Red Hat Ansible Certified Content, this collection is entitled to support through the Ansible Automation Platform (AAP) using the Create issue button on the top right corner. If a support case cannot be opened with Red Hat and the collection has been obtained either from Galaxy or GitHub, there may community help available on the Ansible Forum.
Release Notes and Roadmap
License Information
Certification
| Product |
|---|
| Red Hat Ansible Automation Platform 2.4 |
| Red Hat Ansible Automation Platform 2.5 |
| Red Hat Ansible Automation Platform 2.6 |
No dependencies
There are currently no dependencies for this collection.
