CAPI Book versioning #6017
Comments
k8s-ci-robot
added
the
kind/documentation
|
+1 for the first option, there will be feature differences between minor releases and it would be nice to have stable documentation for every release, I think it provides a good user experience. |
|
I agree option 1 is better if we can have it for free but unfortunately, it might add overhead to the release process. The main issue is that we have no control over the certificates for each release branch because this is something we have to email Netlify support for (there is no option to do it ourselves in the UI). It would be good to email them to ask if the two options you suggested are possible so we know how much cost we're talking about. Ideally, we want to make the release process as easy and automated as possible so we can release early and release often. Having a human manually email Netlify for every single minor release will definitely go against that goal. If we figure out how to get this working, it would be great to have a page in the book with links to documentation for other releases, or even better a dropdown, kind of how k8s does it (https://v1-21.docs.kubernetes.io/ - versions dropdown on the top right). |
|
+1 to ask email Netify the best curse of actions. |
|
Sounds great! I don't really know anything about our Netlify integration / account (?) / ... (apart from a few netlify.toml's). But let me know if I can help. |
|
@sbueringer I just sent a support request to Netlify and added you in the email thread. |
Perfect, thank you! |
|
Sorry for the delay, I missed the reply because it got filtered out of my Inbox. Here's the response I got from Netlify: Thanks for reaching out! We cannot provision a wildcard certificate for the site because we do not host your DNS. You will need to bring your own wildcard custom SSL cert. The second option you've provided would work as well, but the above would be our recommendation.
I've also noticed that you have some misconfigured DNS records for domain k8s.io that you may want to remove here: https://app.netlify.com/teams/kubernetes-docs/dns/k8s.io#delete-dns-zone I hope this helps. Please let us know if you have any followup questions. |
|
I assume we don't have a good way to provide "our own" custom SSL cert. So I think either Netlify has some kind of Let's encrypt support or our only implementation option is 2, if we want to make Option 1 from above happen. |
|
They do automatically create LE certificates for custom domains: https://docs.netlify.com/domains-https/https-ssl/#netlify-managed-certificates https://cluster-api.sigs.k8s.io is also using LE certificates right now, so I'm not sure why support tickets are needed to add further domains to the certificate. |
|
Wow, thx for the info. @CecileRobertMichon Do you see a reason why that documentation might not apply to us? There's the following section
But I think that doesn't apply to us as we don't have and need a wild card certificate if they provision certificates automatically. |
|
As far as I can tell, we don't have branch subdomains setup:
If I click on "Setup Netlify DNS", it says k8s.io is already registered:
I'm guessing this has to do with the fact that we're using the k8s.io domain but we share it with the rest of Kubernetes so we can't register it to this site. Regarding the cert, I do see that it's using Let's Encrypt and has all our release branches as domains but it doesn't let me edit the cert since they manage it for us:
@vincepri @detiber might be able to provide more history / context here. |
|
Might be I'm missing something, but can we follow their suggestion and add SANS for a couple of releases that don't exist yet to the cert (eg. from release-1-2 up release-1-5); If I'm not wrong, this will give 404 until the branch exists, and start responding whenever the branch get created. |
|
@fabriziopandini they said that would work but they recommend using a custom SSL cert instead: "The second option you've provided would work as well, but the above would be our recommendation." +1 on going that route for now unless we are missing something and there is a better way to have them provision wildcard certificates (doesn't look like there is though). |
|
+1 let's try that. I think even in the worst case that we have to write a mail on every release that is preferable to Option 2 above. |
|
I just emailed netlify asking them to add release-1-0.cluster-api.sigs.k8s.io, release-1-1.cluster-api.sigs.k8s.io, release-1-2.cluster-api.sigs.k8s.io, release-1-3.cluster-api.sigs.k8s.io, release-1-4.cluster-api.sigs.k8s.io, and release-1-5.cluster-api.sigs.k8s.io to the cert |
We should be good to go |
|
Thank you, /hold cancel'd kubernetes/k8s.io#3404 (waiting for approval from dims) |
|
@CecileRobertMichon We're getting cert issues on:
Not sure why nslookup cluster-api.sigs.k8s.io
Server: 10.93.9.100
Address: 10.93.9.100#53
Non-authoritative answer:
cluster-api.sigs.k8s.io canonical name = release-1-1--kubernetes-sigs-cluster-api.netlify.app.Maybe some redirect based on Host header? |
|
@sbueringer I don't see the updated cert in the UI... maybe it takes some time? If I still don't see the new branches tomorrow I'll email support again. |
|
Same here, I still see the old certificate |
|
emailed support |
|
Answer: |
|
Looks like release-1.0 and release-1.1 are good now. We might have to click the "renew certificate" button every time we release now. Better than emailing support though. |
|
Thx! Certificates look good. I think one last problem. DNS looks okay: I have no idea how to figure that out / where that could be configured. I suspect there might be something in the Netlify UI? |
|
@sbueringer can you check if it looks good now? There is a "production branch" setting in the UI, I just changed that from main to release-1.1. Hoping that did the trick. |
Interesting. Now the release-1-1.cluster-api.sigs.k8s.io page redirects to cluster-api.sigs.k8s.io. This would be fine in general, but unfortunately both are the book from main (the v1.1-v1.2 page doesn't exist on 1.1) |
|
@CecileRobertMichon Okay not sure if you had to do something. But I think it works now (https://cluster-api.sigs.k8s.io is based on release-1.1) I'll open a few PRs to update the cross-references to other version of the book tomorrow and then we should be finally done here :) (+ I'll update the housekeeping issue so that next time we ~ now what we have to do then) |
|
Interesting I didn't do anything since then... Glad it works now @vincepri how do we get @sbueringer added to Netlify so he can access this stuff too? |
Maybe it was triggered by a merge on release-1.1 after your change. Absolutely no idea how it works, but I assume they are running the book build after every merge (as specified in the netlify.toml), so maybe this triggered a rollout of the config. |
|
I can help with Netlify too, even if it seems there is a bit of magic in it |
Thx that's very good to know. Just to summarize, now Netfliy behaves as expected. It's just about future changes/issues. |
|
Short update, last PR for this issue: #6194 :) |
|
/close Thx to everyone who contributed, especially @CecileRobertMichon ! |
|
@sbueringer: Closing this issue. In response to this:
Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository. |
|
For the record, here is the email I just sent to Netlify via their support request UI: |
Hey folks,
let's discuss how we want to version the CAPI book.
Currently we have the following book versions:
I don't think this is ideal:
I think we have (at least) the following options.
Option 1: One book per version/release
Option 2: One book per contract version (~ current state)
In my opinion we should implement Option 1. With Option 2 the books are mostly correct, but because we are always writing documentation for the current state, it's unrealistic that one version of the book can apply to all versions which use the same contract. For example the current ClusterClass documentation reflects the state of the feature now, with
1.0 a lot of what we documented doesn't work/apply.
When we last talked about it in Slack, there was a concern that when we have a book for every release we have to get a new certificate with every release. Can we maybe mitigate this by either:
xref: previous Slack discussion: https://kubernetes.slack.com/archives/C8TSNPY4T/p1639069957464900?thread_ts=1639068761.463700&cid=C8TSNPY4T
/kind documentation
The text was updated successfully, but these errors were encountered: