# Getting started

> Overview of using OneFuse with Red Hat Ansible

---

Site [llms.txt](/llms.txt)

---

Easily integrate CloudBolt OneFuse with Red Hat Ansible (compatible with Ansible Core or [Tower](https://www.ansible.com/products/tower)) to quickly automate and integrate into your business provisioning lifecycle.

The CloudBolt OneFuse integration platform offers integrations to services like Naming, IPAM, DNS, Microsoft Active Directory, Scripting, Ansible Tower and more.

[Upstream providers](/docs/onefuse/consume/what-is-upstream-provider/) like Ansible, Terraform, VMware vRealize Automation, CloudBolt CMP, ServiceNow and others are able to consume the same OneFuse integrations combined with organizational business logic for a standardized approach to automation across the enterprise.

## Prerequisites

1. [Learn](https://www.ansible.com/products/automation-platform) about Red Hat Ansible.
   - Review Red Hat Ansible: [Releases](https://docs.ansible.com/ansible/latest/reference_appendices/release_and_maintenance.html) and [Docs](https://docs.ansible.com/ansible/latest/index.html).
1. [Install](https://docs.ansible.com/ansible/latest/installation_guide/index.html) and setup Red Hat Ansible **Core** or **Tower**.
1. [Get the OneFuse Ansible Module](https://github.com/CloudBoltSoftware/onefuse_ansible_module) via our **GitHub Repo**.

### Python

<div class="alert alert-info" role="alert">


Identify a system to run the Python commands from. This could be your own desktop or a server in your environment. You will need to have Python 3 or greater installed on the system.
</div>


1. Verify **Python** is installed

   ```python
   # Run the following in a Command Prompt/Terminal
   pip install --upgrade onefuse
   ```

   <div class="alert alert-info" role="alert">


   [Python 2 has sunset.](https://www.python.org/doc/sunset-python-2/) If previously installed and on Python 2, upgrade to the latest Python.
   </div>


   - If **Python** is not installed (or upgrading), [download](https://www.python.org/downloads/) the latest Python

1. Verify **pip** is installed

   ```python
   # Run the following in a Command Prompt/Terminal
   pip install onefuse==versions

   # An output error message similar to the below is returned, listing available versions:
   # ~ERROR: Could not find a version that satisfies the requirement onefuse==versions (from versions: <!! versions are listed here !!>)
   # ~ERROR: No matching distribution found for onefuse==versions
   ```

   - [Install pip](https://pip.pypa.io/en/stable/installation/) if it does not exist

1. Review Python's [Installing Packages](https://packaging.python.org/tutorials/installing-packages/)

## Install OneFuse Python Package

OneFuse Python Module is distributed as a Python Package. Install the OneFuse Python Package using `pip`.

<div class="alert alert-info" role="alert">


It is recommended to install the latest OneFuse Python Package that matches the OneFuse Appliance version.
</div>


<div class="alert alert-info" role="alert">


If the OneFuse Python Module is already installed, skip to **Upgrade OneFuse Python Package**.
</div>


1. Open a **Command Prompt** or **Terminal** window
1. Install OneFuse Python Package using instructions below:

### Option 1. Installing the latest

```python
# Run the following in a Command Prompt/Terminal
pip install --upgrade onefuse
```

### Option 2. Installing a specific version

#### Optional: list available OneFuse Python package versions

```python
# Run the following in a Command Prompt/Terminal
pip install onefuse==versions

# An output error message similar to the below is returned, listing available versions:
# ~ERROR: Could not find a version that satisfies the requirement onefuse==versions (from versions: <!! versions are listed here !!>)
# ~ERROR: No matching distribution found for onefuse==versions
```

Then, install with a specific version.

```python
# Replace <version> in the command below with a specific version number (e.g. 1.4.0)
# Run the following in a Command Prompt/Terminal
pip install onefuse==<version>

# An output message similar to the below is returned, where <version> is replaced with the version number installed:
# ~Successfully installed onefuse-<version>
```

### Upgrading the OneFuse Python Package

Upgrade to the latest OneFuse Python Package using `pip`.

1. Open a **Command Prompt** or **Terminal** window
1. Install OneFuse Python Package using the command below:

   ```python
   # Run the following in a Command Prompt/Terminal
   pip install --upgrade onefuse
   ```

## Configure OneFuse Manager

Configure the connection to OneFuse in the `/module_utils/onefuse/config.py` file.

1. Open a **Command Prompt**/**Terminal** window or a **SFTP Application** (for example, FileZilla)
1. **Log in to Ansible Core / Tower** via SSH or a SFTP Application
1. Go to **onefuse_ansible_module** repository > **module_utils** > **onefuse** folder:
   - `/{pathto_onefuse_ansible_module_repo_folder}/module_utils/onefuse/`
1. **For first time setup:**
   - **Copy** the `config.py` file to:
     - **Ansible Core**: `/{ansible_root_folder}/lib/ansible/module_utils/onefuse/`
     - **Ansible Tower**: `/usr/share/ansible/plugins/module_utils/onefuse/`

     <div class="alert alert-info" role="alert">


     The **onefuse** folder will need to get created (if it does not already exist) inside the Ansible `Module_Utils` folder.
     </div>


1. Edit the contents of the `config.py` file in **Ansible Core / Tower** with the following to configure the **OneFuse Manager**:
   - Replace `<username>` with the OneFuse username that has at least the [Workspace Member role](/docs/onefuse/getting-started/roles-and-permissions/#workspace-roles).
   - Replace `<password>` with the password for the OneFuse user.
   - Replace `<host>` with the OneFuse Instance FQDN or IP Address.

   **Accepted optional kwargs:**

   | Key | Value |
   | --- | --- |
   | `protocol` | *(Defaults to `https`)* Specify a protocol: `http` or a non-standard protocol |
   | `port` | *(Defaults to `443`)* Specify the port for the OneFuse Instance |
   | `verify_certs` | *(Defaults to `false`)* Specify whether or not to verify OneFuse Certificates (`true` or `false`) |
   | `logger` | *(Defaults to `onefuse.log` and to the console at the `LOG_LEVEL` set in `configuration.globals`)* Pass in logger information |
   | `source` | *(Defaults to `PYTHON`)* Specify the source so that this class can be called by other Upstream Providers (Ansible, CloudBolt CMP, Terraform, ServiceNow, VMware vRealize Automation, etc). All OneFuse Jobs will show this value as the "Source" of the Job |

1. **Use the OneFuse Manager** to make API calls to OneFuse.

## Resources

- [Learn](https://docs.ansible.com/ansible/latest/user_guide/playbooks.html) about Ansible Playbooks.
- Visit our **GitHub Repo**: [onefuse-examples](https://github.com/CloudBoltSoftware/onefuse-examples)

## Troubleshooting

Refer to Ansible's [Frequently Asked Questions](https://docs.ansible.com/ansible/latest/reference_appendices/faq.html#) and [Debugging modules](https://docs.ansible.com/ansible/latest/dev_guide/debugging.html) guide.

## Next steps

Start integrating with [OneFuse Modules](/docs/onefuse/consume/red-hat-ansible/modules/).