Add guide to upgrading to cert-v2 #223
Conversation
✅ Deploy Preview for nebula-docs-dn ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
|
Now that slackhq/nebula#1359 is merged, the docs can be updated to reference the added logs |
jasikpark
force-pushed
the
guide-to-cert-v2-upgrade
branch
from
420bfb3 to
0f206c5
Compare
There was a problem hiding this comment.
Thanks for putting this together! I haven't quite finished going through it, but I wanted to drop some early feedback. If you take the suggestions, maybe read on through the rest of the guide yourself and see if we can clean anything else up as a result.
When writing technical docs like this, I aim to be precise yet concise, so in some cases I'm advocating for removing duplicate information.
| } | ||
| ``` | ||
|
|
||
| Copy the public key of the CA and add it to the `pki.ca` list in the config for every nebula host: |
There was a problem hiding this comment.
Correct me if I'm wrong, but I think we need to copy the CA certificate (i.e. the newly created file on disk) - not the public key (i.e. 4f1200baedc57f39adfc71e1b5409a3a7dc60fab4e1a2c4decaeb347a2ad4d75 from the above output.)
|
|
||
| In order to move to a network where every host has ipv4 and ipv6, or every host has ipv6 only, it's recommended to start | ||
| by re-issuing all hosts certificates with both v1 and v2 certificates for compatibility. Hosts will continue handshaking | ||
| via the v1 cert while the network is being upgraded. |
There was a problem hiding this comment.
Pretty good, but a couple nits: certv2 supports IPv4 and/or IPv6, but this implies IPv4+IPv6 or IPv6-only. Also, it mentions "every host," but you can have a mix of hosts on the network (though connectivity may be dodgy.) Finally, it's not recommended to do this - it's a strict necessity to use the certv2 format. Maybe something like:
In order to create host certificates with an IPv6 address (in addition to, or in lieu of an IPv4 address), you must use the new v2 certificate format. To avoid downtime during the transition to the new certificate format, Nebula hosts can be configured with both a v1 and v2 certificate.
You may even want to move this all the way up to the CA section though, since that's the first place we introduce the switch to a v2 cert format.
You could include a note about how we'll switch the handshake later, but I don't think it's necessary to include at this step. If you want to explain the whole process earlier, I'd add a summary before the instructions.
| You can create a new v1+v2 cert like this: | ||
|
|
||
| ```bash | ||
| ❯ nebula-cert sign -name "nebula" -networks "192.168.1.1/24" |
There was a problem hiding this comment.
No need to specify the IPv6 network or address? If not, how does Nebula know what network to use, and what address to assign?
| ``` | ||
|
|
||
| By default, nebula-cert will create a v1 and v2 version of the certificate when creating and signing a certificate. This | ||
| allows you to move from v1 to v2 seamlessly. v1 does not support IPv6 though, so we'll move to only v2 soon. |
There was a problem hiding this comment.
I think the first paragraph here can be removed, since the command above demonstrates the fact. I believe we've already stated that v1 does not support IPv6 above, so this can be removed.
Perhaps replace this paragraph with an explanation of the expected result (what files should be created? what do those files contain?)
| By default, nebula-cert will create a v1 and v2 version of the certificate when creating and signing a certificate. This | ||
| allows you to move from v1 to v2 seamlessly. v1 does not support IPv6 though, so we'll move to only v2 soon. | ||
|
|
||
| Using `nebula-cert show` we can see that the certificate has both cert format versions: |
There was a problem hiding this comment.
| Using `nebula-cert show` we can see that the certificate has both cert format versions: | |
| Using `nebula-cert print` we can see that the file contains both a v1 and v2 certificate: |
nitpick, but it's technically two certs.
|
|
||
| ## Upgrade to nebula nightly | ||
|
|
||
| First, download the updated nebula version that has v2 certs and IPv6 support from nightly releases, and move all the |
There was a problem hiding this comment.
| First, download the updated nebula version that has v2 certs and IPv6 support from nightly releases, and move all the | |
| First, upgrade each host in your network to a nebula version with support for v2 certs. Currently this is only available in the nightly releases. |
Maybe add a note on how to check? i.e. nebula -version? What version string should they see?
Hopefully this is a good starter for folks trying to upgrade their network.
Deploy Preview: https://deploy-preview-223--nebula-docs-dn.netlify.app/docs/guides/upgrade-to-cert-v2-and-ipv6/