> For the complete documentation index, see [llms.txt](https://docs.trilio.io/openstack/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.trilio.io/openstack/deployment/installing-on-canonical/juju-charms.md).

# Trilio Installation on Canonical (via Juju Charms)

Trilio and Canonical have started a partnership to ensure a native deployment of Trilio using JuJu Charms.

Those JuJu Charms are publicly available as Open Source Charms.

{% hint style="info" %}
Please refer to the [Resources](/openstack/about-trilio-for-openstack/artifacts.md) section for required Charm details.
{% endhint %}

{% hint style="info" %}
This page covers a **fresh install** of T4O 6.2.1 onto a Canonical (Charmed) OpenStack cloud that has no prior Trilio deployment. If you are upgrading an existing Trilio deployment, see [Upgrading on Canonical](/openstack/upgrading-to-t4o-6.x-from-older-supported-versions/upgradetrilio/upgrading-on-canonical.md) instead.
{% endhint %}

{% hint style="warning" %}
This page covers the **classic MAAS + machine-charm** Canonical OpenStack deployment. If your cloud is **Canonical OpenStack Sunbeam** (Kubernetes-based control plane), see [Trilio Installation on Canonical OpenStack (Sunbeam)](/openstack/deployment/installing-on-canonical/sunbeam-canonical.md) instead — it uses different charms (`trilio-wlm-k8s`, `trilio-dm-api-k8s`, `trilio-data-mover-sunbeam`) and a different deployment model.
{% endhint %}

## Prerequisites

* A Canonical (Charmed) OpenStack base setup deployed for a required release, with all units in **active/idle** state. Refer to the [Compatibility Matrix](/openstack/about-trilio-for-openstack/support-matrix.md).
* Juju controller connected to the OpenStack model. Verify with `juju status`.
* The following OpenStack services must already be deployed:
  * **MySQL InnoDB Cluster** — for WLM and DMAPI databases
  * **RabbitMQ Server** — for AMQP messaging (WLM, DMAPI, DataMover, DMS)
  * **Keystone** — for identity service (WLM, DMAPI, and Data-Mover via the `identity-service` relation)
  * **Nova-Compute** — DataMover is a subordinate of nova-compute
  * **OpenStack Dashboard (Horizon)** — for the Horizon Plugin subordinate
  * **Vault** (recommended) — for TLS certificate management
  * **Ceph Mon** — if Ceph is the OpenStack storage backend
  * **OpenStack Barbican** — required by the Dynamic Mount Service (DMS) to retrieve S3 credentials at mount time

{% hint style="info" %}
**Backup targets are NOT configured at deploy time in T4O 6.2.1.** Add them after deployment via the T4O CLI or the Horizon UI — see Step 6, "Add Backup Targets Post-Deployment," below.
{% endhint %}

## Steps to install the Trilio charms

#### 1. Export the OpenStack base bundle

```
juju export-bundle --filename openstack_base_file.yaml
```

#### 2. Create a Trilio overlay bundle as per the OpenStack setup release using the charms given above.

{% hint style="danger" %}
Trilio File Search functionality requires that the Trilio Workload manager (trilio-wlm) be deployed as a virtual machine. File Search *will not* function if the Trilio Workload manager (trilio-wlm) is running as a lxd container(s).
{% endhint %}

{% hint style="danger" %}
If trilio-wlm service is assigned to any nova-compute node then wlm mysql router service fails to start. Hence, please ensure to assign trilio-wlm service to some other node.
{% endhint %}

Sample Trilio overlay bundles (*T4O release wise*) are available in the `triliovault-cfg-scripts` repository at path: `juju-charms/sample_overlay_bundles`

{% hint style="info" %}
Value of `trilio_branch` can be taken from release specific [Resources](/openstack/about-trilio-for-openstack/artifacts.md)
{% endhint %}

```
git clone https://github.com/trilioData/triliovault-cfg-scripts.git
cd triliovault-cfg-scripts
git checkout {{ trilio_branch }}
cd juju-charms/sample_overlay_bundles
```

Copy the sample bundle and customise it for your environment:

```
cp tvo-overlay-bundle.yaml tvo-overlay-bundle-6.2.yaml
# Edit tvo-overlay-bundle-6.2.yaml:
#   - triliovault-pkg-source and revision numbers (from the 6.2.1 build report)
#   - machine placements (`to:` blocks) to match your environment
```

Unlike an upgrade, a fresh install **does** need machine placements set in the overlay bundle — `juju deploy` uses them to place the WLM and DMAPI LXD containers.

The sample bundle already includes the 6.2.1 relation changes:

* `trilio-data-mover:identity-service` → `keystone:identity-service` (replaces the older `keystone-auth-url` config option)
* Charm channel set to `6.2/stable`, with per-charm `revision` variables at the top of the file

{% hint style="info" %}
The `trilio-backup-targets` and `backup-target-type` charm config options used in releases prior to 6.2 are removed from the 6.2 charms — the sample bundle no longer sets them. Backup targets are configured after deployment instead; see Step 6, "Add Backup Targets Post-Deployment," below.
{% endhint %}

Following table provides the details of the values to be updated in the overlay bundle.

| **Parameters**         | **Summary**                                                                                                                      |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| triliovault-pkg-source | Trilio debian package repo url; Refer release specific [Resources](/openstack/about-trilio-for-openstack/artifacts.md) page      |
| machines               | List of Machines available on canonical openstack setup                                                                          |
| channel                | Channel name as provided in release specific [Resources](/openstack/about-trilio-for-openstack/artifacts.md) page                |
| revision               | Latest values as provided by Trilio. Refer release specific [Resources](/openstack/about-trilio-for-openstack/artifacts.md) page |

#### 3. T4O Deployment

3.1] Do a dry run to check if the Trilio bundle is working

{% code fullWidth="true" %}

```
juju deploy --dry-run ./openstack_base_file.yaml --overlay tvo-overlay-bundle-6.2.yaml
```

{% endcode %}

3.2] Trigger deployment

{% code fullWidth="true" %}

```
juju deploy ./openstack_base_file.yaml --overlay tvo-overlay-bundle-6.2.yaml
```

{% endcode %}

3.3] Wait until all the Trilio units are deployed successfully. Check the status via `juju status` command.

{% code fullWidth="true" %}

```
watch -n 5 juju status trilio-wlm trilio-data-mover trilio-dm-api trilio-horizon-plugin
```

{% endcode %}

Expected output — all units should show:

```
Agent    Status   Message
idle     active   Unit is ready
```

#### 4. Post Deployment Steps

4.1] Once the deployment is complete, perform the below operations:

a. Create cloud admin trust & add licence

{% tabs %}
{% tab title="Juju 3.x" %}
{% code overflow="wrap" %}

```
juju run --wait=300s trilio-wlm/leader create-cloud-admin-trust password=<openstack admin password>
juju attach-resource trilio-wlm license=<Path to trilio license file>
juju run --wait=300s trilio-wlm/leader create-license
```

{% endcode %}
{% endtab %}

{% tab title="Juju 2.x" %}
{% code overflow="wrap" %}

```
juju run-action --wait=300s trilio-wlm/leader create-cloud-admin-trust password=<openstack admin password>
juju attach-resource trilio-wlm license=<Path to trilio license file>
juju run-action --wait=300s trilio-wlm/leader create-license
```

{% endcode %}
{% endtab %}
{% endtabs %}

{% hint style="info" %}
`--wait` requires a duration unit (`300s`, not `300`) — `juju run`/`juju run-action` otherwise default to `--wait=0s`, which queues the action asynchronously and returns immediately without its result.
{% endhint %}

**Note**: Reach out to the Trilio support team for the license file.

#### 5. Verify the T4O Deployment

5.1] After T4O deployment steps are over, it can take some time for all units to get deployed successfully. Deployment is considered successful when all the units show `Unit is ready` in the message column.

To verify the same, the following command can be used to fetch the Trilio units/applications:

{% code overflow="wrap" %}

```
juju status | grep -i trilio
```

{% endcode %}

All Trilio units should show status **active** with message **Unit is ready**.

5.2] For a deeper check, verify services and rendered DMS configs on each node type.

On a compute node (DataMover):

```
juju ssh nova-compute/0
sudo systemctl status tvault-contego trilio-dms-server

# Verify the DMS server config was rendered:
cat /etc/triliovault-dms/server.conf
```

On the WLM node:

```
juju ssh trilio-wlm/leader
sudo systemctl status wlm-api wlm-workloads wlm-cron wlm-scheduler trilio-dms-server

# Verify DMS configs:
ls /etc/triliovault-dms/
cat /etc/triliovault-dms/server.conf
cat /etc/triliovault-dms/client.conf
```

On the DMAPI node:

```
juju ssh trilio-dm-api/leader
sudo systemctl status tvault-datamover-api

# Verify the DMS client config. A populated db_url only proves the config
# rendered -- it does NOT prove the credential works. Authenticate with it:
cat /etc/triliovault-dms/client.conf
sudo python3 - <<'EOF'
import configparser, pymysql, urllib.parse as up
c = configparser.ConfigParser(); c.read("/etc/triliovault-dms/client.conf")
u = up.urlparse(c["client"]["db_url"])
if not u.hostname:
    raise SystemExit("FAILED: db_url is empty in client.conf")
pymysql.connect(host=u.hostname, port=u.port or 3306, user=u.username,
                password=up.unquote(u.password), database=u.path.lstrip("/"))
print("OK: DMS client authenticated as", u.username)
EOF
```

The output must be `OK: DMS client authenticated as workloadmgr`.

#### 6. Add Backup Targets Post-Deployment

**Important:** In T4O 6.2.1, backup targets are NOT configured at deploy time. The DMS service dynamically mounts/unmounts targets as needed.

To add a backup target, follow the "Canonical" steps in the admin guide: [Add a new Backup Target](/openstack/admin-guide/backup-targets/add-a-backup-target.md).

#### 7. Troubleshooting T4O Deployment

7.1] To debug any specific unit: `juju debug-log --include <UNIT_NAME_IN_ERROR>`

Eg. If trilio-wlm/6 unit is in 'error' state, its logs can be fetched using the following command. Substitute the correct unit number from your deployment using the `juju status` command.

`juju debug-log --include trilio-wlm/6`

**For multipath enabled environments, perform the following actions**

1. log into each nova compute node
2. add uxsock\_timeout with value as 60000 (i.e. 60 sec) in /etc/multipath.conf
3. restart tvault-contego service