How to migrate to charmed etcd¶
This guide outlines the steps required to migrate an existing etcd cluster to a charmed etcd cluster.
Prerequisites¶
A Juju VM controller with a model
A TLS Provider deployed to that model, in our case we use
self-signed-certificates(see How to enable TLS)An Object Storage Provider deployed to that model, in our case we use
s3-integrator(see How to configure an object storage provider)Your existing etcd cluster must be at least of version 3.0
Summary¶
These are the steps you will need to follow to migrate to charmed etcd:
Create a backup of your existing cluster
Upload the backup to an object storage (s3-compatible or Azure blob storage)
Deploy charmed etcd
Integrate charmed etcd with an object storage provider
Integrate charmed etcd with a TLS provider
[optional]: Apply cluster credentials
Restore the backup to charmed etcd
Switch your application over to charmed etcd
Create a backup¶
Migrating your existing etcd cluster to charmed etcd happens via backup and restore.
First, create a backup of your existing etcd cluster. The following command is an example for a snap-based installation
of etcd in version 3.4.36. It connects to etcd via localhost and creates a backup file
called etcd-backup.db in the current working directory:
etcdctl snapshot save etcd-backup.db
This will prompt the following output (or similar):
{"level":"info","ts":1754036152.734727,"caller":"snapshot/v3_snapshot.go:119","msg":"created temporary db file","path":"etcd-backup.db.part"}
{"level":"info","ts":"2025-08-01T08:15:52.736886Z","caller":"clientv3/maintenance.go:212","msg":"opened snapshot stream; downloading"}
{"level":"info","ts":1754036152.7369702,"caller":"snapshot/v3_snapshot.go:127","msg":"fetching snapshot","endpoint":"127.0.0.1:2379"}
{"level":"info","ts":"2025-08-01T08:15:52.738103Z","caller":"clientv3/maintenance.go:220","msg":"completed snapshot read; closing"}
{"level":"info","ts":1754036152.7385268,"caller":"snapshot/v3_snapshot.go:142","msg":"fetched snapshot","endpoint":"127.0.0.1:2379","size":"20 kB","took":0.003674558}
{"level":"info","ts":1754036152.738597,"caller":"snapshot/v3_snapshot.go:152","msg":"saved","path":"etcd-backup.db"}
Snapshot saved at etcd-backup.db
Upload the backup to object storage¶
For restoring backup files, charmed etcd supports S3-compatible (for example AWS, GCS, MinIO or MicroCeph) or Azure
object storage. In our example, we upload the backup file that we just created to S3-storage by using the S3cmd tool.
If not yet installed, execute the following command to install S3cmd:
sudo apt-get install s3cmd
Ensure the bucket for uploading your backup file exists (replace the placeholders with your credentials). In this case
we want to use a bucket called etcd-backups-test-bucket:
s3cmd ls s3://etcd-backups-test-bucket/ --access_key=<your-access-key> --secret_key=<your-secret>
You should see your bucket listing all available directories:
DIR s3://etcd-backups-test-bucket/etcd-backups/
If the storage bucket you want to use does not exist yet, create a bucket etcd-backups with the following command
(replace the placeholders with your credentials):
s3cmd mb s3://etcd-backups-test-bucket/ --access_key=<your-access-key> --secret_key=<your-secret>
With the following command, you can upload the backup file etcd-backup.db to the newly created bucket
(replace placeholders with your credentials again):
s3cmd put etcd-backup.db s3://etcd-backups-test-bucket/etcd-backups/ --access_key=<your-access-key> --secret_key=<your-secret>
Ensure your backup file was uploaded correctly by repeating the s3cmd ls s3://etcd-backups-test-bucket/etcd-backups/ command:
2025-08-01 08:24 20512 s3://etcd-backups-test-bucket/etcd-backups/etcd-backup.db
Deploy charmed etcd¶
Now it’s time to deploy charmed etcd. Run the following command to deploy a 3-unit cluster:
juju deploy charmed-etcd --channel 3.6/edge -n 3
Wait for the deployment to become available by checking watch juju status --color:
Model Controller Cloud/Region Version SLA Timestamp
backend-store dev-controller localhost/localhost 3.6.5 unsupported 08:34:43Z
App Version Status Scale Charm Channel Rev Exposed Message
charmed-etcd active 3 charmed-etcd 3.6/edge 68 no
s3-integrator active 1 s3-integrator 1/stable 145 no
self-signed-certificates active 1 self-signed-certificates 1/stable 317 no
Unit Workload Agent Machine Public address Ports Message
charmed-etcd/0* active idle 0 10.143.229.222 2379/tcp
charmed-etcd/1 active idle 1 10.143.229.119 2379/tcp
charmed-etcd/2 active idle 2 10.143.229.81 2379/tcp
s3-integrator/0* active idle 4 10.143.229.157
self-signed-certificates/0* active idle 3 10.143.229.160
Integrate charmed etcd with an object storage provider¶
After charmed etcd has been deployed, integrate it with the deployed object storage provider to provide access
the object storage. In our case, this happens with s3-integrator over the s3-credentials interface.
Run the following command:
juju integrate s3-integrator charmed-etcd
Caution
Ensure s3-integrator is configured correctly. Please refer to How to configure an object storage provider for more information.
Shortly after, the relation between them should be established:
Integration provider Requirer Interface Type Message
charmed-etcd:etcd-peers charmed-etcd:etcd-peers etcd_peers peer
charmed-etcd:restart charmed-etcd:restart rolling_op peer
s3-integrator:s3-credentials charmed-etcd:s3-credentials s3 regular
s3-integrator:s3-integrator-peers s3-integrator:s3-integrator-peers s3-integrator-peers peer
Integrate charmed etcd with a TLS provider¶
Because charmed etcd relies on mTLS for client authentication and authorisation, it is mandatory to set up client TLS in
charmed etcd. To do so, integrate with the deployed TLS provider over the tls-certificates interface. In our case,
this is with the self-signed-certificates operator.
Run the following command:
juju integrate self-signed-certificates:certificates charmed-etcd:client-certificates
Charmed etcd will enable client TLS on all units with a rolling restart. After a few moments, the relation should be established and charmed etcd should be settled again:
Model Controller Cloud/Region Version SLA Timestamp
backend-store dev-controller localhost/localhost 3.6.5 unsupported 08:43:12Z
App Version Status Scale Charm Channel Rev Exposed Message
charmed-etcd active 3 charmed-etcd 3.6/edge 68 no
s3-integrator active 1 s3-integrator 1/stable 145 no
self-signed-certificates active 1 self-signed-certificates 1/stable 317 no
Unit Workload Agent Machine Public address Ports Message
charmed-etcd/0* active idle 0 10.143.229.222 2379/tcp
charmed-etcd/1 active idle 1 10.143.229.119 2379/tcp
charmed-etcd/2 active idle 2 10.143.229.81 2379/tcp
s3-integrator/0* active idle 4 10.143.229.157
self-signed-certificates/0* active idle 3 10.143.229.160
[...]
Integration provider Requirer Interface Type Message
charmed-etcd:etcd-peers charmed-etcd:etcd-peers etcd_peers peer
charmed-etcd:restart charmed-etcd:restart rolling_op peer
s3-integrator:s3-credentials charmed-etcd:s3-credentials s3 regular
s3-integrator:s3-integrator-peers s3-integrator:s3-integrator-peers s3-integrator-peers peer
self-signed-certificates:certificates charmed-etcd:client-certificates tls-certificates regular
Though it is optional, it is also recommended to enable peer TLS for encryption between the etcd cluster members.
Run the following command to enable peer TLS:
juju integrate self-signed-certificates:certificates charmed-etcd:peer-certificates
Charmed etcd will enable peer TLS on all units with a rolling restart. After a few moments, the relation should be established and charmed etcd should be settled again:
Integration provider Requirer Interface Type Message
charmed-etcd:etcd-peers charmed-etcd:etcd-peers etcd_peers peer
charmed-etcd:restart charmed-etcd:restart rolling_op peer
s3-integrator:s3-credentials charmed-etcd:s3-credentials s3 regular
s3-integrator:s3-integrator-peers s3-integrator:s3-integrator-peers s3-integrator-peers peer
self-signed-certificates:certificates charmed-etcd:client-certificates tls-certificates regular
self-signed-certificates:certificates charmed-etcd:peer-certificates tls-certificates regular
[optional]: Apply cluster credentials¶
If your previous etcd cluster did not have authentication enabled, this step can be skipped.
If your previous etcd cluster uses authentication, it is required to apply the password of the admin user to charmed etcd.
Otherwise, restoring the backup will fail.
First, create a Juju secret with the admin password. Run the following command to create a secret called etcd-credentials,
replacing the placeholder with your correct admin password:
juju add-secret etcd-credentials root=<your-admin-password>
Take a note on the prompted secret URI, as this will later be configured to charmed etcd:
secret:d268gfktvobctdg3loe0
Now allow charmed etcd access to this secret by running juju grant-secret etcd-credentials charmed-etcd.
Next step is to configure the secret to charmed etcd. Run the following command, replacing the secret URI with the one you noted earlier:
juju config charmed-etcd system-users=secret:<your-secret-URI>
After a few moments, charmed etcd will have updated the credentials internally and be active/idle again. Check the status:
Model Controller Cloud/Region Version SLA Timestamp
backend-store dev-controller localhost/localhost 3.6.5 unsupported 09:29:50Z
App Version Status Scale Charm Channel Rev Exposed Message
charmed-etcd active 3 charmed-etcd 3.6/edge 68 no
s3-integrator active 1 s3-integrator 1/stable 145 no
self-signed-certificates active 1 self-signed-certificates 1/stable 317 no
Unit Workload Agent Machine Public address Ports Message
charmed-etcd/0* active idle 0 10.143.229.222 2379/tcp
charmed-etcd/1 active idle 1 10.143.229.119 2379/tcp
charmed-etcd/2 active idle 2 10.143.229.81 2379/tcp
s3-integrator/0* active idle 4 10.143.229.157
self-signed-certificates/0* active idle 3 10.143.229.160
Restore the backup to charmed etcd¶
After applying your cluster credentials (if needed), it is time to migrate your data to charmed etcd by restoring the previously taken backup.
First, list the available backups in the object storage with this command:
juju run charmed-etcd/leader list-backups
It should list the backup file etcd-backup.db in the output:
Running operation 3 with 1 task
- task 4 on unit-charmed-etcd-0
Waiting for task 4...
backups: |-
backup-id | backup-status
-------------------------------------
etcd-backup.db | finished
Now restore this backup to your charmed etcd cluster by running:
juju run charmed-etcd/leader restore backup-id="etcd-backup.db"
The restore will be initiated on all units of the charmed etcd application:
Running operation 5 with 1 task
- task 6 on unit-charmed-etcd-0
Waiting for task 6...
09:34:41 Initiating restore process for backup-id etcd-backup.db
success: restore initiated for etcd-backup.db
You can follow the progress by running watch juju status --color:
Model Controller Cloud/Region Version SLA Timestamp
backend-store dev-controller localhost/localhost 3.6.5 unsupported 09:34:57Z
App Version Status Scale Charm Channel Rev Exposed Message
charmed-etcd maintenance 3 charmed-etcd 3.6/edge 68 no Database restore is in progress
s3-integrator active 1 s3-integrator 1/stable 145 no
self-signed-certificates active 1 self-signed-certificates 1/stable 317 no
Unit Workload Agent Machine Public address Ports Message
charmed-etcd/0* maintenance executing 0 10.143.229.222 2379/tcp Database restore is in progress
charmed-etcd/1 maintenance executing 1 10.143.229.119 2379/tcp Database restore is in progress
charmed-etcd/2 maintenance executing 2 10.143.229.81 2379/tcp Database restore is in progress
s3-integrator/0* active idle 4 10.143.229.157
self-signed-certificates/0* active idle 3 10.143.229.160
Once the restore is complete, the status will be active/idle again:
Model Controller Cloud/Region Version SLA Timestamp
backend-store dev-controller localhost/localhost 3.6.5 unsupported 09:37:01Z
App Version Status Scale Charm Channel Rev Exposed Message
charmed-etcd active 3 charmed-etcd 3.6/edge 68 no
s3-integrator active 1 s3-integrator 1/stable 145 no
self-signed-certificates active 1 self-signed-certificates 1/stable 317 no
Unit Workload Agent Machine Public address Ports Message
charmed-etcd/0* active idle 0 10.143.229.222 2379/tcp
charmed-etcd/1 active idle 1 10.143.229.119 2379/tcp
charmed-etcd/2 active idle 2 10.143.229.81 2379/tcp
s3-integrator/0* active idle 4 10.143.229.157
self-signed-certificates/0* active idle 3 10.143.229.160
Congratulations: You have migrated your etcd data to charmed etcd!
Switch your application over to charmed etcd¶
Now it’s time to connect your application to charmed etcd. This happens over the etcd_client interface by integrating
the applications:
juju integrate charmed-etcd <your-charm>
The interface requires you to provide a key prefix (the key space in the etcd database you request access to) and a client certificate (for mTLS authentication). Please refer to charm-relation-interfaces/etcd_client for detailed information.
For further information about how to enable your charm to integrate over the etcd_client interface, please refer to How to integrate etcd with an application.