Migrate from Docker-based Nimbra Edge #

Deprecated. The Docker-based Nimbra Edge Core (connectit install core) is deprecated as of R4.2.0 and will be removed in a later release. It remains supported in R4.2 so that existing installations can be migrated. These pages are kept for existing installations; new installations should follow Get started. To move an existing installation, see Migrate from Docker-based Nimbra Edge.

This guide moves an existing Docker-based Nimbra Edge installation to a new Nimbra Edge control plane on Edge OS or Kubernetes. The configuration is moved with a config backup. The appliances that carry video keep running during the migration and reconnect to the new control plane.

How the migration works #

All configuration of a Nimbra Edge installation lives in the core database: regions, appliances, inputs, outputs, users, API tokens and settings. A config backup from a Docker-based core is a dump of that database in the same format that Edge OS and Kubernetes-based installations use, so it can be restored into a new installation from Network Manager.

Appliances reach the control plane through its domain name and authenticate with the identity they were registered with. The new control plane is therefore installed and the backup restored before DNS is changed: when the appliances follow the domain name to the new host, it already knows every appliance. An appliance that reaches a control plane that does not recognize it exits and restarts its control software until it is recognized, so do not point DNS at the new host before the restore is complete. Video streams that are already running on the appliances continue while the control plane changes; only management and monitoring are briefly interrupted.

The following is not migrated:

• Metrics history. A Docker-based installation has no metrics backup.
• Billing and usage history. A billing backup can only be restored with the edge CLI on a Kubernetes-based installation, as described in the installation guide. On Edge OS the usage history starts over.
• The TLS certificate. The new installation provisions its own certificate.

Before you start #

• Upgrade the Docker-based installation to the latest R4.2.x release, see Upgrade. The new installation must run the same Nimbra Edge release as the backup it restores.
• Obtain a license for the new installation from Net Insight before you start. A license for Docker-based Nimbra Edge cannot be used for an Edge OS or Kubernetes-based installation; the new control plane rejects it with “A license for the product Docker-based Nimbra Edge cannot be used for Kubernetes-based Nimbra Edge”. Ask for a Kubernetes-based Nimbra Edge license bound to the same domain name.
• Prepare the new control plane host but do not install Nimbra Edge on it yet. Follow Get started up to the step that installs Nimbra Edge.
• Decide how the new installation gets its TLS certificate. Because DNS still points at the Docker-based core when the new installation is made, the HTTP-01 challenge cannot be used at install time. On an Edge OS core, use the DNS-01 challenge with a Cloudflare API token if you can: the certificate is then in place before DNS changes. Otherwise install with the automatic TLS certificate disabled and enable HTTP-01 in the core settings after DNS has been changed (step 4). Until that certificate is issued the control plane serves a self-signed certificate, which the appliances do not trust, so they stay offline for a minute or two longer. An Edge OS core cannot use a certificate of your own: the control plane always provisions the certificate for port 443, which Network Manager and the appliances connect to, and replaces a certificate uploaded in Network Manager with its own. The TLS certificate page of the appliance web interface only secures that interface on port 9443. On a Kubernetes-based installation made with the edge CLI, a certificate of your own can be used instead: install without --managed-cert and either pass it with --tls-cert and --tls-key, or upload it in Network Manager after the restore (step 3).
• Have access to the DNS zone of the installation’s domain name.
• Lower the TTL of the DNS record for the domain name a day in advance, so that appliances and users pick up the new address quickly when it changes.
• Note the credentials of a Network Manager administrator. After the restore you sign in with the users from the backup.
• Check in Network Manager that all appliances are online, so that any appliance that does not reconnect after the migration can be told apart from one that was already offline.

1. Take a config backup #

Stop making configuration changes in Network Manager; changes made after the backup are not migrated. Then, on the Docker-based core host, with the connectit CLI for the installed release:

sudo ./connectit backup new --type config

The backup is written to the current directory as config-backup_<date>.gz; use --out to write it elsewhere. Verify that the file is readable:

gunzip --test config-backup_*.gz

Copy the file to the computer you will use to reach Network Manager on the new installation.

2. Install Nimbra Edge on the new host #

DNS still points at the Docker-based core, so the Docker-based installation keeps serving its appliances and users while the new one installs. To reach the new installation through its domain name before DNS changes, add a line to the hosts file of your computer that maps the domain name to the address of the new host, for example 203.0.113.10 my.nimbra.edge in /etc/hosts on Linux and macOS or C:\Windows\System32\drivers\etc\hosts on Windows. Do this on the computer you will use to reach Network Manager and, for a Kubernetes-based installation, on the computer that runs the edge CLI before you start the installation: the installer signs in to the new installation through the domain name to set the super user password, and fails with “Failed to access Edge api” if the name still resolves to the Docker-based core. Remove the line again after the migration.

Continue with the installation step of Get started using the same domain name as the Docker-based installation, the new license key and the certificate method you chose. When the edge CLI asks you to ensure that there is a DNS entry for the domain name, press enter without changing DNS; the hosts-file line stands in for it until step 4. The installation takes a few minutes.

Sign in to Network Manager on the new installation when the installation completes, but do not create regions or appliances; the backup brings them.

3. Restore the config backup #

In Network Manager on the new installation:

1. Go to Settings → Global settings → Backups.
2. Under Upload config backup file, choose the config-backup_<date>.gz file and click Upload. The uploaded file appears in the config backups list under a new name.
3. Click Restore and confirm.

The restore replaces the configuration of the new installation with the configuration from the backup. Network Manager is unavailable for about half a minute while the database is replaced, and your session is signed out. When it is back, sign in with the credentials that were active on the Docker-based installation when the backup was taken. The appliances are listed with their previous names and IDs but show as offline, because they still talk to the Docker-based core.

If you chose to use a certificate of your own on a Kubernetes-based installation and did not pass it to the edge CLI at install time, upload it now, before DNS changes: go to Settings → Global settings → TLS certificate, paste the private key and the certificate in PEM format and click Save. The appliances only connect to a control plane whose certificate they trust, so the certificate must be in place when DNS changes. Do not use this page on an Edge OS core: the control plane replaces the uploaded certificate with its own.

4. Point DNS at the new host #

Change the DNS record of the domain name to the public address of the new control plane host. The appliances move to the new control plane as their hosts pick up the new address and their connections to the old core are renewed. With a 60-second TTL this takes about a minute; allow the TTL plus a few minutes. The appliance software is not restarted by the move. If you installed an Edge OS core with the automatic TLS certificate disabled, enable it with HTTP-01 in the core settings of the appliance now, after the domain name resolves to the new host. The appliances reconnect once the certificate has been issued, usually within a couple of minutes.

Running video streams are not affected. Users reach Network Manager on the new installation through the domain name from now on, so remove the hosts-file line from step 2.

5. Verify #

• Settings → Appliances: every appliance that was online before the migration is online again. If an appliance stays offline, check on its host that the domain name resolves to the new address and that the host can reach it on TCP port 443 with a certificate it trusts, for example with curl https://<domain name>/. If the certificate is the problem, point DNS back at the Docker-based core, which reconnects the appliances without affecting video, fix the certificate and change DNS again. Restarting an appliance does not help with a certificate problem, and a restart of the appliance host stops its video, so only restart an appliance once the host reaches the new control plane.
• Inputs and Outputs: the status of every input and output is the same as before the migration and thumbnails update.
• Alarms: no new alarms other than those caused by the short interruption of the control plane.

6. Decommission the Docker-based core #

When everything has been verified, remove the Docker-based core from the old host:

sudo ./connectit uninstall core

Keep the config backup file until the new installation has produced backups of its own. Video appliances and Edge Connect appliances that were installed with the connectit CLI stay as they are; they are not deprecated and keep working with the new control plane.