Deploy a Testflinger Server¶
This guide outlines the steps to deploy a Testflinger server using Juju and the Testflinger server charm from Charmhub.
Testflinger server runs as a Kubernetes application and uses MongoDB as its backend. In this guide, MongoDB is deployed as a machine charm and connected to the server through a Juju cross-model relation. For more details, see the Architecture explanation.
Prerequisites¶
The following prerequisites cover the necessary steps to set up K8s and machine-based Juju environments required for the Testflinger server deployment. For a detailed guide on how to set up Juju, refer to the official Juju documentation.
System Requirements¶
Ensure that your system meets the following requirements:
Ubuntu 22.04 LTS or later
At least 4 CPU cores
At least 6 GB of RAM
At least 30 GB of free disk space
Note that these requirements are the minimum recommended for testing and development purposes. For production deployments, we recommend a more robust setup based on your expected workload and usage patterns.
Dependencies¶
Install the following dependencies:
$ sudo snap install juju
$ sudo snap install lxd
$ sudo snap install microk8s --channel 1.34-strict/stable
$ sudo snap install terraform --classic
Note
Juju 3.x requires the strict version of the microk8s snap to be installed.
Note
This guide uses the NGINX Ingress Integrator charm to expose the Testflinger
server API. This requires MicroK8s <1.35, because in later versions the
ingress addon replaced the NGINX Ingress Controller with Traefik.
LXD¶
Make sure LXD is initialized.
$ lxd init --auto
Note
Feel free to initialize LXD with a configuration that suits your needs. LXD is only used in this setup to deploy the machine charms, specifically the MongoDB machine charm.
MicroK8s¶
The Testflinger server deployment depends on the following MicroK8s setup.
$ sudo snap alias microk8s.kubectl kubectl
$ sudo usermod -aG snap_microk8s ubuntu
$ newgrp snap_microk8s # or reboot
$ microk8s status --wait-ready
$ sudo microk8s enable dns
$ sudo microk8s enable hostpath-storage
$ sudo microk8s enable ingress
Juju¶
Set up the Juju controllers needed for the Testflinger server deployment.
$ juju bootstrap localhost localhost-controller
$ microk8s config | juju add-k8s localhost-microk8s --controller localhost-controller
Then create the models for the server and database deployments.
$ juju add-model testflinger-db localhost
$ juju add-model testflinger localhost-microk8s
MongoDB deployment¶
Deploy the MongoDB charm into the testflinger-db model.
$ juju deploy mongodb --channel 6/stable -m testflinger-db
Once the deployment is complete, offer the MongoDB endpoint so that it can
be consumed by the Testflinger server application in the K8s model.
For more information on how to use Juju offer, please refer to the
Juju offer CLI reference.
$ juju offer testflinger-db.mongodb:database mongodb
Testflinger server deployment¶
At this point, you are now ready to deploy the Testflinger server charm. You can choose to deploy the charm using the Juju CLI or automate the deployment using the provided Terraform module.
Juju CLI¶
Tip
The next steps assume the k8s model is active, otherwise you can
switch by running juju switch testflinger.
The following steps outline how to deploy the Testflinger server charm using the Juju CLI.
First, consume the MongoDB endpoint offered in the previous step. For
more information on how to use Juju consume, please refer to the
Juju consume CLI reference.
$ juju consume localhost-controller:admin/testflinger-db.mongodb
Deploy the Testflinger server charm.
$ juju deploy testflinger-k8s --channel stable \
--config jwt_signing_key="<signing-key>"
Note
The jwt_signing_key configuration is required for authenticating
API requests to the Testflinger server. You should generate a secure
random string to use as the signing key.
Note
You can also pass the -n <units> flag to deploy multiple units of the
Testflinger server application. Adjust this number based on your needs
and the resources available in your cluster.
Relate the Testflinger server application with the MongoDB endpoint.
$ juju integrate testflinger-k8s:mongodb_client mongodb:database
Monitor the deployment progress until all units are active.
$ juju status --storage --relations --watch 5s
Once all units are active, deploy and configure the ingress charm to expose the Testflinger server API. In this example, we will use the NGINX Ingress Integrator charm.
$ juju deploy nginx-ingress-integrator --trust
$ juju integrate nginx-ingress-integrator testflinger-k8s
$ juju config testflinger-k8s external_hostname=testflinger.local
The deployment finishes when the status shows Ingress IP(s): 127.0.0.1
on nginx-ingress-integrator. The IP addresses may differ based on your
Kubernetes cluster setup. You can run the juju status command to
monitor the status of the deployment and check the assigned ingress IP address.
$ juju status --storage --relations
Model Controller Cloud/Region Version SLA Timestamp
testflinger localhost-controller localhost-microk8s/localhost 3.6.21 unsupported 11:49:45-06:00
SAAS Status Store URL
mongodb active localhost-controller admin/testflinger-db.mongodb
App Version Status Scale Charm Channel Rev Address Exposed Message
nginx-ingress-integrator 24.2.0 active 1 nginx-ingress-integrator latest/stable 203 10.152.183.35 no Ingress IP(s): 127.0.0.1
testflinger-k8s ... active 1 testflinger-k8s latest/stable 288 10.152.183.88 no
Unit Workload Agent Address Ports Message
nginx-ingress-integrator/0* active idle 10.1.153.199 Ingress IP(s): 127.0.0.1
testflinger-k8s/0* active idle 10.1.153.198
Integration provider Requirer Interface Type Message
mongodb:database testflinger-k8s:mongodb_client mongodb_client regular
nginx-ingress-integrator:nginx-peers nginx-ingress-integrator:nginx-peers nginx-instance peer
nginx-ingress-integrator:nginx-route testflinger-k8s:nginx-route nginx-route regular
Warning
The above ingress deployment steps are intended for testing and development purposes. For production deployments, it is recommended to use TLS for secure communication. For more information on how to set up TLS, refer to the NGINX Ingress Integrator charm documentation.
Terraform¶
Testflinger also provides a Terraform module that automates the deployment of the Testflinger server. The module is located in the server/terraform/ directory of the Testflinger repository.
Important
The Terraform module will only deploy the Testflinger server charm, it is user responsibility to set up a Terraform plan that deploys the Ingress charm and configures the required relations. For a sample Terraform plan, please refer to the server/terraform/dev/main.tf file in the Testflinger repository.
Variables¶
Create a terraform.tfvars file and define the following variables.
jwt_signing_key = "(sensitive value)"
external_hostname = "testflinger.local"
Note
Refer to server/terraform/variables.tf and
server/terraform/README.md for the full list of available variables
and their descriptions.
Apply the Terraform plan¶
Initialize Terraform and apply the plan.
$ terraform init
$ terraform apply # optionally run 'terraform plan' first
Wait for the Juju units to finish their setup.
$ juju status --storage --relations --watch 5s
Networking¶
Ensure that your system can resolve and reach the external_hostname
configured earlier. For local testing, edit /etc/hosts to define
the name resolution.
127.0.0.1 testflinger.local
Testflinger CLI¶
Testflinger CLI defaults to using testflinger.canonical.com as its
Testflinger server. To override the server being used, pass the
--server flag or edit the testflinger-cli.conf configuration file.
First, install Testflinger CLI.
$ sudo snap install testflinger-cli
Then connect to the server.
$ testflinger-cli --server http://testflinger.local list-agents
The CLI should not error out, though the list of agents may be empty.
Refer to the Command Line Interface Configuration reference for details on configuring the CLI.