EventStore / documentation

Next-gen documentation website
https://developers.eventstore.com/
10 stars 17 forks source link

Start with basic migration guide on how to upgrade between server versions #454

Closed mat-mcloughlin closed 3 months ago

mat-mcloughlin commented 3 years ago

Create a basic guide for upgrading, include basic cert instructions

alexeyzimarev commented 3 years ago

Things to consider when upgrading to v20+.

General

A number of settings of v5 are not compatible with v20+. The most obvious ones are the ExtHttpPort and IntHttpPort. The latest versions also crash when an unknown setting is found, to prevent people from using the deprecated settings and expect them to work.

To support the migration, we need to clearly define a list of unsupported old settings. We also need to tell people what new settings replace those deprecated settings, if applicable.

It is important to consider the impact on client apps, as migrating the server is only a part of the job. The v5 client is insecure by default, so when moving from insecure to secure, it needs an updated TLS/SSL setting. It would be better if we recommend upgrading the TCP client package to use the latest version at the same time.

Overall, the planned downtime needs to include at least the time required to upgrade the server, plus the time to redeploy all the client apps with new client and/or new settings.

Insecure cluster to insecure cluster

We do not recommend using EventStoreDB in insecure more. Those who will do it for the purpose of easy migration will face lots of warnings produced by the server when client applications will still send credentials when doing operations with an insecure cluster. Potentially, the logs will eat up all the disk space.

Secure to secure with self-signed certs

Self-signed certificates used for v5 might be unusable for v20+. It's because all the nodes must have the same CN in their certificates, which is eventstore-node by default, but can be overridden. Previously, it was possible to issue three different certificates, one for each node, and it worked. It won't work anymore as each of those certificates has a different CN.

When using cluster DNS gossip, certificates also need to have SAN for the cluster DNS name.

As previously cluster DNS gossip was resolving IP addresses, and all the nodes were configured to use IP addresses only, as well as clients, in the end, only used IP addresses, it was not an issue with certificates as long as the certificate has the node IP address in its CN (or SAN).

One "improvement" today is that all the nodes can use one certificate. For this to work, the certificate must include IP addresses of all the nodes as SANs. When using cluster DNS gossip, they also need the DNS name to be in SAN or CN.

Clients of the existing cluster should normally work fine with new certificates as long as the same root CA is used to generate them, as well as the root CA itself is trusted by clients. If clients trust individual node certificates, it will not work as certificates need to be updated.

Secure to secure with trusted CA

The same issue applies to certificates that are signed by a trusted CA. However, such certificates do not normally include SANs for IP addresses. Therefore, the only way for a trusted certificate to work is to use a wildcard certificate.

One wildcard certificate with the CN *.esdb.myorg.com does not work for DNS server gossip using cluster.esdb.myorg.com, and will only work with gossip seed for three nodes like node1.esdb.myorg.com, etc. However, both DNS and seed gossip will work from the client.

The setting to override eventstore-node as a trusted name must be changed to use the certificate CN (the wildcard itself).

The good part is that when using a trusted CA, the clients will trust by default, so the impact on clients is low. However, clients must get updated connection settings to use hostnames if they use IP addresses now.

Insecure to secure

This scenario is straightforward on the server side, both for self-signed and trusted CA certificates.

However, all the clients need to get their connection settings updated. Two scenarios there:

mat-mcloughlin commented 2 years ago

Link to the docs in the support knowledge base https://github.com/EventStore/Support-KB/wiki#migrating-v5--v2010--v2110

@jageall @Lougarou can you please look through and comment on the guide