Metadata-Version: 2.4
Name: tf-glue
Version: 1.0.0
Summary: Orchestrate OpenTofu (or Terraform) initialization and interactions with Ansible and Incus (including Incus S3 bucket as state backend).
Author-email: Sébastien Hocquet <seb@ipamo.net>
Project-URL: Homepage, https://codeberg.org/ipamo/tf-glue
Project-URL: Bug Tracker, https://codeberg.org/ipamo/tf-glue/issues
Keywords: tofu,opentofu,terraform,ansible,incus,bootstrap,infra,devops,inventory,template,s3,bucket,state,backend,glue
Classifier: Development Status :: 1 - Planning
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Provides-Extra: template
Requires-Dist: pyyaml; extra == "template"
Requires-Dist: jinja2; extra == "template"
Dynamic: license-file

tf-glue
=======

Orchestrate OpenTofu (or Terraform) initialization and interactions with Ansible and Incus (including Incus S3 bucket as state backend).


## Features

This tool provides some frequently needed _glue_ for projects that combine part of, or all of, the following infrastructure automation stack:

- [OpenTofu](https://opentofu.org/) (or [Terraform](https://www.hashicorp.com/fr/products/terraform)): infrastructure-as-code provisioner used to manage the lifecycle (create, update, delete) of the infrastructure resources (hosts, disks, networks, etc). _OpenTofu_ is a fully open-source fork from HashiCorp's _Terraform_. OpenTofu is maintained under the Linux Foundation's [CNCF](https://www.cncf.io/) stewardship. It was created in 2023 following [HashiCorp's decision to switch from the Mozilla Public License to a more restricted license](https://opentofu.org/manifesto/).
- [Ansible](https://docs.ansible.com/): configuration management tool used to deploy applications and assets on hosts (once they are created, e.g. by OpenTofu). _Ansible_ is the open-source engine (licensed under the GNU GPLv3) that powers the [Red Hat Ansible Automation Platform](https://www.redhat.com/fr/technologies/management/ansible).
- [Incus](https://linuxcontainers.org/incus/): VMs and containers platform providing a user experience similar to that of a public cloud. It is well integrated [with _OpenTofu_/_Terraform_](https://registry.terraform.io/providers/lxc/incus/latest/docs) and [with Ansible](https://docs.ansible.com/projects/ansible/latest/collections/community/general/incus_connection.html). It is simple to use and can work efficiently on low-end systems and workstations, making it a great solution to simulate deployments locally. _Incus_ is a community-driven fork of Canonical's _LXD_, created in 2023 following Canonical's decisions to [takeover the project from LXC's community-led gouvernance](https://linuxcontainers.org/lxd/) and to [change the license and require an additional Contributor License Agreement](https://stgraber.org/2023/12/12/lxd-now-re-licensed-and-under-a-cla/) (which gives Canonical the right to re-license the contributed code, e.g. to sell it under a closed-source commercial license). _Incus_ is licensed under the Apache 2.0 license.

Supported interactions between OpenTofu/Terraform and Incus:

- Read Incus client configuration from an [OpenTofu/Terraform variables definition file](https://opentofu.org/docs/language/values/variables/#variable-definitions-tfvars-files) (`variables.auto.tfvar`) if present.
- If not already present, write a `variables.auto.tfvar` file so that OpenTofu/Terraform can use the environment detected by the Incus command-line client.
- Create and/or retrieve connexion details for an [Incus-managed S3 bucket](https://linuxcontainers.org/incus/docs/main/howto/storage_buckets/) that can be used as an OpenTofu/Terraform state backend.
- Create an [OpenTofu/Terraform backend configuration file](https://opentofu.org/docs/language/settings/backends/configuration/#file) (`backend.tfbackend`) to use the Incus-managed S3 bucket.
- [Initialize OpenTofu/Terraform](https://opentofu.org/docs/cli/init/#initialization) with the backend configuration file if applicable.

Supported interactions with Ansible:

- Read Incus client configuration from Ansible inventory's variables defined for [the Incus connection plugin](https://docs.ansible.com/projects/ansible/latest/collections/community/general/incus_connection.html).
- Identify unused IP addresses on Incus networks, reserve them, so that they can be passed as variables to a dynamic Ansible inventory.
- Generate a [dynamic Ansible inventory](https://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_dynamic_inventory.html) by compiling a YAML Jinja2 template with variables coming from Incus client and/or OpenTofu.


## Installation

This tool can be installed [from PyPI](https://pypi.org/project/tf-glue/):

```sh
pip install tf-glue
```

Add the `template` extra (i.e. [pyyaml](https://pypi.org/project/PyYAML/) and [jinja2](https://pypi.org/project/Jinja2/)) to generate dynamic Ansible inventories from templates:

```sh
pip install tf-glue[template]
```


## Usage

This tool can be used as a command-line application. The following example initializes OpenTofu (or Terraform) with an Incus-managed S3 bucket named `myproject-state` as its state backend (the bucket is automatically created if it does not exist yet) and variable definitions related to Incus client configuration:

```sh
tf-glue init --bucket myproject-state
```

See command-line help for available commands and options:

```sh
tf-glue --help
```

This tool can also be used as a Python library. Example:

```py
#!/usr/bin/env python3
from tf_glue.ansible import generate_inventory
from tf_glue.incus import Incus

incus = Incus()  # will use the environment detected by the Incus command-line client
generate_inventory("mytemplate.yml", incus=incus)
```


## Contributing

Pull requests are welcome. See:

- [Main source code repository](https://codeberg.org/ipamo/tf-glue)
- [Bug and issue tracker](https://codeberg.org/ipamo/tf-glue/issues)
- [Contribution guidelines](https://codeberg.org/ipamo/tf-glue/src/tag/v1.0.0/CONTRIBUTING.md)


## Legal

This tool is licensed under the [MIT license](https://codeberg.org/ipamo/tf-glue/src/tag/v1.0.0/LICENSE.txt).

It is not affiliated in any way with OpenTofu, Terraform, Ansible, Incus or any associated organization.
