How to migrate to Landscape 26.04 LTS (charm)

Note

The Landscape Server charm for 26.04 is currently in beta. See the 26.04 LTS release notes for details on our changes introduced in 26.04. Note the recommendations for repository management users.

This guide explains how to migrate from an older Landscape Server charm deployment (pre-26.04) to the 26.04 LTS beta+ version with an external HAProxy charm using the haproxy-route interface.

Architectural changes

The 26.04 beta version introduces significant architectural changes:

Aspect

Landscape 26.04 LTS beta+

Pre-26.04

Load balancing

External HAProxy charm (haproxy at 2.8/edge, haproxy-route interface)

External HAProxy charm (reverseproxy interface)

PostgreSQL interface

Modern database interface (PostgreSQL 14+)

Legacy pgsql interface (PostgreSQL 14)

PostgreSQL relation

landscape-server:database → postgresql:database

landscape-server:db → postgresql:db-admin

RabbitMQ relation

landscape-server:inbound-amqp and landscape-server:outbound-amqp → rabbitmq-server (25.10+)

landscape-server:amqp → rabbitmq-server:amqp (pre-25.10)

HAProxy relation

landscape-server:*-haproxy-route → haproxy:haproxy-route (8 route endpoints)

landscape-server:website → haproxy:reverseproxy

TLS certificates

haproxy:certificates → TLS provider (e.g., self-signed-certificates, lego)

HAProxy self-signed or manual config

Access method

HAProxy unit IP or root_url

HAProxy unit IP

HA capabilities

HAProxy units for load balancing

HAProxy units for load balancing

Migration steps

Step 1: Backup your database

Before making any changes, back up your Landscape database following the backup procedures in How to backup and restore a charmed deployment.

Step 2: Remove incompatible relations

Remove the older HAProxy relation:

juju remove-relation landscape-server:website haproxy:reverseproxy --force

For deployments older than 25.10 only:

Remove the older RabbitMQ relation:

juju remove-relation landscape-server:amqp rabbitmq-server:amqp --force

Note

If you’re migrating from 25.10 or later, you already have the inbound-amqp and outbound-amqp relations.

Step 3: Deploy HAProxy and TLS certificates provider

Deploy the HAProxy charm and a TLS certificates provider before refreshing the charm. This gives them time to become active while other operations proceed.

First, deploy the HAProxy charm:

juju deploy haproxy --channel 2.8/edge

For testing/development with self-signed certificates:

juju deploy self-signed-certificates
juju integrate haproxy:certificates self-signed-certificates:certificates
juju integrate haproxy:receive-ca-certs self-signed-certificates:send-ca-cert

For production with Let’s Encrypt:

juju deploy lego --channel 4/stable
juju config lego server="https://acme-v02.api.letsencrypt.org/directory"
juju config lego email="admin@example.com"
juju config lego plugin="http"
juju integrate haproxy:certificates lego:certificates
juju integrate haproxy:receive-ca-certs lego:send-ca-cert

Prerequisites for Let’s Encrypt HTTP-01 challenge:

  • Domain in root_url must resolve to the HAProxy unit IP

  • Port 80 must be accessible for ACME HTTP-01 challenge validation

  • Valid email address for certificate notifications

See the lego charm documentation for DNS-01 challenge configuration.

For custom CA certificates:

Tip

See the manual-tls-certificates charm documentation for more details and a tutorial on creating and using a custom CA.

To use custom CA certificates, deploy the manual-tls-certificates charm.

juju deploy manual-tls-certificates --channel 1/beta

Then, integrate it with HAProxy twice to provide the TLS certificates and trust the signing CA:

juju integrate manual-tls-certificates:certificates haproxy:certificates
juju integrate manual-tls-certificates:trust_certificate haproxy:receive-ca-certs

Now, generate a CA certificate and private key or ensure they are available locally. For example, generate a CA certificate and private key with OpenSSL:

  1. Create a directory to store the certificates:

    mkdir certs

  2. Generate a private key:

    openssl genrsa -out certs/ca.key 2048

  3. Generate a self-signed CA certificate:

    openssl req -new -x509 -days 3650 -key certs/ca.key -out certs/ca.crt -subj "/C=US/CN=landscape.example.com"

After integrating the charms, HAProxy will make a Certificate Signing Request (CSR) that we can extract via the get-outstanding-certificate-requests, and use to create a signed TLS certificate. For example:

juju run manual-tls-certificates/0 get-outstanding-certificate-requests --format=json | jq '.manual-tls-certificates/0.results.result' | jq '.[0].csr' > certs/client.csr

Note

The outstanding certificate requests are grouped by the relation-id; if there are multiple requests (i.e., multiple consumers of the manual TLS certificates), use juju show-unit manual-tls-certificates/0 to identify the correct ID.

If the machine ID of the manual TLS certificates charm is not 0, adjust the above and following commands with the correct ID. Use juju status to identify the Juju machine ID of the manual TLS certificates charms.

Then, it can be used to sign the certificate. For example, with OpenSSL:

openssl x509 -req -in certs/client.csr -CA certs/ca.crt -CAkey certs/ca.key -CAcreateserial -out certs/client.crt -days 365 -sha256

Then, use the provide-certificate action on the manual TLS certificates charm to provide the signed TLS certificate. For example, using the previous example CA/CSR:

juju run manual-tls-certificates/0 provide-certificate \
  certificate="$(base64 -w0 certs/client.crt)" \
  ca-certificate="$(base64 -w0 certs/ca.crt)" \
  certificate-signing-request="$(base64 -w0 certs/client.csr)"

Now, HAProxy is using the custom CA for TLS connections. You can verify HAProxy received the new TLS certificates using the get-certificates action on the HAProxy charm by providing the hostname of the configured Landscape Server root URL, for example:

juju run haproxy/0 get-certificate hostname=landscape.example.com --format=json | jq -r '.["haproxy/0"].["results"].certificate' > cert.pem
openssl x509 -in cert.pem -noout -text

Note

If the machine ID of the HAProxy charm is not 0, adjust the above command with the correct ID. Use juju status to identify the Juju machine ID of the HAProxy charm.

Step 4: Refresh the charm

Refresh the Landscape Server charm to the 26.04 beta version:

juju refresh landscape-server --channel 26.04/beta

Wait for the refresh to complete and the services to restart:

juju status --watch 2s

Step 5: Integrate Landscape Server with HAProxy

Add the HAProxy route integrations for all Landscape Server services:

juju integrate landscape-server:appserver-haproxy-route haproxy:haproxy-route
juju integrate landscape-server:pingserver-haproxy-route haproxy:haproxy-route
juju integrate landscape-server:message-server-haproxy-route haproxy:haproxy-route
juju integrate landscape-server:api-haproxy-route haproxy:haproxy-route
juju integrate landscape-server:package-upload-haproxy-route haproxy:haproxy-route
juju integrate landscape-server:repository-haproxy-route haproxy:haproxy-route
juju integrate landscape-server:hostagent-messenger-haproxy-route haproxy:haproxy-route
juju integrate landscape-server:ubuntu-installer-attach-haproxy-route haproxy:haproxy-route

Important

The ssl_cert and ssl_key charm configuration have been removed and are no longer supported in the 26.04 beta charm. TLS is now managed by the HAProxy charm via the tls-certificates interface.

Step 6: Add new RabbitMQ relations (pre-25.10 deployments only)

Note

This step can be skipped on deployments on 25.10 or newer, as they will already have these relations.

For deployments older than 25.10, add the new separate inbound and outbound AMQP relations:

juju integrate landscape-server:inbound-amqp rabbitmq-server
juju integrate landscape-server:outbound-amqp rabbitmq-server

Step 7: Update PostgreSQL (optional)

If you want to upgrade to a newer PostgreSQL version (e.g., from 14 to 16) as part of this migration, follow the backup and restore procedures in How to backup and restore a charmed deployment to migrate your data to a new PostgreSQL deployment.

Note

PostgreSQL upgrade is optional. The 26.04 beta charm uses the modern database interface which works with PostgreSQL 14 and above.

The legacy db endpoint (legacy pgsql interface) is still supported for backwards compatibility but only works with PostgreSQL 14. It is recommended to migrate to the modern database interface since Charmed PostgreSQL 16+ does not support the legacy interface.

Step 8: Verify the deployment

Check that all services are active:

juju status

Access Landscape via the HAProxy unit IP or your configured root_url. Use juju status to find the HAProxy unit IP address.

Tip

For testing access by hostname before DNS is configured, add the HAProxy unit IP (or your external HAProxy IP if using LBaaS) to /etc/hosts on your local machine with the hostname from your root_url. For example: 10.1.77.133 landscape.example.com

Log in and verify:

  • All computers are visible

  • Activities and alerts are present

  • User accounts and permissions are intact

For more information about juju refresh, see the Juju documentation on charm upgrades.

Additional resources