DNS REQUEST: kind.sigs.k8s.io subproject docs about k8s.io HOT 19 CLOSED

Understood, just know that it's a slippery slope, and before we set foot onto it, I think we need to know the rules.

Hypothetically, 25 other sig-owned things could see this and say "I want one". Are we OK granting 25 new domains and 25 new netlify sites? Andrew, what are the terms here?

from k8s.io.

@thockin I'm deferring to @chenopis for deep knowledge, but as far as I understand it:

Summary

Setting up a new subdomain is easy from a UI perspective.

Netlify teams make permissions problematic.

Each netlify team requires its own billing plan.

Context

Netlify's UI is pretty straightforward; setting up a new site is almost trivially easy. For example, I've configured a site for kubernetes-sigs/kind. (Currently the build is failing because reasons, but it could theoretically deploy. 🤷‍♂️)

Netlify handles sites, domains, and subsequent billing at what netlify calls the "team" level. Right now, there's a team called Kubernetes Docs (visibility requires membership) that handles all of the sites that collectively form k8s.io--including the k-sigs/kind demo. ☝️

So it seems like the question is maintenance: who sets up a site, subsequently maintains it, and pays for it?

From what I've seen, it's possible to create new teams with unique limited permissions, but only for collaborators who aren't part of the Kubernetes Docs team. The Kubernetes Docs team appears to have owner/collaborator permissions over every site, and it doesn't appear possible to exclude that team.

Currently, adding and maintaining sites doesn't scale well. Adding one site is relatively easy; adding 25 would be a nightmare, both from a logistics and permissions standpoint.

Recommendations

• Verify that the description I've provided matches reality.

• Consider how to optimize netlify teams and scale them nicely.

from k8s.io.

A new URL redirector is ~0 cost, yes. It's the precedent and inconsistency that has potential cost.

a) Do we want every SIG-owned sub-project to get a URL? If so, is this the right template for URLs?

b) Do we want every SIG-owned sub-project to get a netlify? If so, who pays for it, and who administers it?

This is all very fresh in my mind as the wg-infra team chips away at the mass of non-community-run community-owned-by-rights stuff (I know you know, this is for context :). I am loathe to set up something now as a one-off that we don't have a clear understanding of what the logical conclusion is.

from k8s.io.

a) Do we want every SIG-owned sub-project to get a URL? If so, is this the right template for URLs?

We give them https://sigs.k8s.io/project as both a go-import and a redirect to their kubernetes-sigs repo currently. https://project.sigs.k8s.io seemed like a natural extension for documentation.

Excellent point - we redirect sigs.k8s.io/project to the code. You're proposing project.sigs.k8s.io (which is confusingly similar) redirect to docs. That's a little confusing to me. Maybe it's OK, but I want it to be overt. Should we write this down somewhere?

Also, it's worth noting that all of these are .k8s.io but NOT .kubernetes.io. .k8s.io is what we use for gopath because it is short, but for docs, do we want both? I don't know SEO well enough to say whether it helps or hurts. @chenopis

b) Do we want every SIG-owned sub-project to get a netlify?

The netlify here is an experiment per SIG-Docs, the next step after this on my end was to go back to SIG-Docs and update. We're definitely not sure if this is the right pattern. There are two experiments currently (kind and kubebuilder).

OK, I can live with that.

Er the idea here is to make sure that it is community run in addition to community-owned-by-rights? I certainly don't want more of this.

I haven't seen any plan for community-administrators for netlify, but maybe I just missed it? How does Jane Random from community volunteer?

I hoped this would be a small, automated change, not a grand precedent (at least not yet).

Are you new here? :)

I was conflating the desire for a URL with the use of netlify. If docs team considers netlify an experimental implementation, I am OK to ignore that for now.

Answer the questions about URL above and I will approve. Specifically, "is it confusing?" and "do we want .kubernetes.io, too?"

from k8s.io.

/assign @thockin

from k8s.io.

Come to think of it, our 2 year contract is coming up for renewal around June 15th.

As per the original arrangement I negotiated, CNCF prepaid annually to get a discount for the Enterprise (custom) tier. The cost is $4500/yr. We are on an unlimited plan, which you can see in the Team Settings in the Netlify UI. Consequently, we are not currently paying any additional fees for extra Teams.

from k8s.io.

cc @dims @cblecker ref: https://github.com/kubernetes/k8s.io/blob/master/dns/OWNERS

I briefly tested that it is possible to do something like this with my own netlify backed domain (with external DNS) and a subdomain backed by the kind netlify.

From that test I believe this will work fine as long as someone who owns both the k8s.io netlify project (It appears that we have *.docs.k8s.io pointed to netlify) and the kind project does this on the netlify end (I think IE @chenopis 🙏).

I wrote the PR to do this here: #185

from k8s.io.

Is this the right format for docs sites like this (vs. kind.k8s.io or something else).

from k8s.io.

What @cblecker said. I don't have context - are we going to create a netlify site and domain for every sig-owned thing that writes docs?

from k8s.io.

Don't we pay for netlify? Who is paying for this? @dims

from k8s.io.

Either works for me, initially we opted for the more namespaced route to attempt to avoid :bikeshed:. The project is only SIG sponsored / is not a core component etc.

From the subproject's POV we just want to get on a domain other than netlify but distinct from the SIG-Docs maintained primary site. Per previous discussion with SIG-Docs the subproject will be responsible for maintaining these.

from k8s.io.

@thockin This site is under a Netlify Team setup by @chenopis after meeting about subproject docs with SIG-Docs. As far as I know so is https://book.kubebuilder.io/ though that one has another domain.

https://kustomize.io/ and https://cri-o.io/ are independent and not owned by the community AFAIK.

There isn't a solid pattern yet. We're trying to find one going forward.

from k8s.io.

None of those are .k8s.io, though. Is the kubebuilder book something that is community owned? We should make sure that a process is in place to pay for it.

Also, I don't see the relationship between these docs and the kubebuilder site?

Either way, my question stands: are we OK to create a (paid?) netlify site and domain for every sig-owned thing that writes docs, or should those projects be using GH pages or something? This doesn't fall under the Google grant, so I don't know where the money comes from or how much it is, or who should approve how it is spent.

from k8s.io.

The kubebuilder "book" docs are from the kubernetes-sigs repo, my understanding is that it is on a community owned Netlify and the domain was possibly being donated per @mengqiy

What we've setup currently is based on input from SIG-Docs on acheiving alignment on hugo + netlify.
I don't know how / who pays for it exactly, @chenopis set up the team / site and presumably knows this.

I'm happy to retool and use whatever, or setup something unnofficial myself. We've just been trying to find an approved way to do it within the community first. So far that has been this.

from k8s.io.

Thanks for the details @zacharysarah 😅

Understood, just know that it's a slippery slope, and before we set foot onto it, I think we need to know the rules.

Understood @thockin.

FWIW the DNS request is specifically about obtaining a stable community owned (at ~$0 additional cost?) URL which can be re-pointed at whatever host ultimately backs it, and ${project}.sigs.k8s.io was chosen as ~the least official sounding option, with the import path already being sigs.k8s.io/${project}.

Community owned access to everything seemed important from a permissions point of view, but adding cost is not something we're trying to do...

I think whether or not this costs anything additional currently depends on how many users our plan covers, since we are not using any "add ons".

Once we know what is preferable for the project to own / what stack is preferred I am happy to migrate, fund.. We just want to work towards high quality docs that are not as official as https://kubernetes.io/

Ideally as much as possible the subproject should be responsible for maintaining the content & setup, we're not trying to impose on the rest of the project.

from k8s.io.

Detailed answers below. Shorter version is that I didn't expect this to be a big precedent yet, is there a more appropriate avenue to discuss and move forward or should we shut it down and find a different solution?

A new URL redirector is ~0 cost, yes. It's the precedent and inconsistency that has potential cost.

Yes, right now we do have inconsistency... I'd like to change that eventually if we find something that works.

For precedent the netlify(s) have been called an "experiment", alpha, no future guarantees yet.

a) Do we want every SIG-owned sub-project to get a URL? If so, is this the right template for URLs?

Of course I would say yes and yes, I'm not sure who else to ask though, so far I've discussed with SIG-Docs and found and followed the DNS request process. Not sure who else to ask.

With DNS automation the overhead should be small?

We give them https://sigs.k8s.io/project as both a go-import and a redirect to their kubernetes-sigs repo currently. https://project.sigs.k8s.io seemed like a natural extension for documentation.

b) Do we want every SIG-owned sub-project to get a netlify?

The netlify here is an experiment per SIG-Docs, the next step after this on my end was to go back to SIG-Docs and update. We're definitely not sure if this is the right pattern. There are two experiments currently (kind and kubebuilder).

If the administration of creating these isn't a problem on their end, perhaps yes? But that part still remains unclear. This seems distinct from domains though.

If so, who pays for it, and who administers it?

Per above, we're not paying additionally for it, it falls under the existing contract. If this changes I assume we'll require them to migrate, which will be easier if they are behind domains we control.

This is all very fresh in my mind as the wg-infra team chips away at the mass of non-community-run community-owned-by-rights stuff (I know you know, this is for context :).

Er the idea here is to make sure that it is community run in addition to community-owned-by-rights? I certainly don't want more of this.

I am loathe to set up something now as a one-off that we don't have a clear understanding of what the logical conclusion is.

I hear that. How much process do we need to move forward? Or should we just shut this down?

I hoped this would be a small, automated change, not a grand precedent (at least not yet).

from k8s.io.

Excellent point - we redirect sigs.k8s.io/project to the code. You're proposing project.sigs.k8s.io (which is confusingly similar) redirect to docs. That's a little confusing to me. Maybe it's OK, but I want it to be overt.

The content at each of these (the repo, the docs) should link back to each other so if confusion does arise it's probably OK.

For tools users & developers will use the docs URL much more than the import I think.
Libraries might use the repo URL more but are also probably less likely to use more than godoc.org anyhow.

Alternatively, projects with a project.sigs.k8s.io could set go-import meta tags within their pages and not use the sigs.k8s.io/project URL. Going the opposite direction seems less likely.

Should we write this down somewhere?

Not until we know it works! After that, probably somewhere. (In the DNS docs here?)

Also, it's worth noting that all of these are .k8s.io but NOT .kubernetes.io. .k8s.io is what we use for gopath because it is short, but for docs, do we want both? I don't know SEO well enough to say whether it helps or hurts. @chenopis

IMHO it makes sense to distinguish between kubernetes.io (the super duper official core project) and *.k8s.io (various things the SIGS happen to own / use), for the same reasons we do this with GitHub.

FWIW I also haven't really seen *.kubernetes.io in the wild other than the root domain. Googling "kubernetes.io" doesn't turn up any of the subdomains on any of the results pages. Searching "k8s.io" turns up a few.

From an SEO perspective my understanding is that having multiple domains actively used for one site splits up the incoming "link juice" and is unhelpful. Looking around, SEO sites mostly seem to concur.

I haven't seen any plan for community-administrators for netlify, but maybe I just missed it? How does Jane Random from community volunteer?

For kubernetes.io I don't think this is in place yet. That said, most of the time netlify should be pretty hands off, and the config can more or less entirely be checked into the source repo and managed there.
Other than the initial setup and domains we've only needed to touch the in-repo config so far. I've had similar experience with a personal site.

For our specific site / team, the repo admins are in the netlify team, in addition to SIG-Docs owning the team itself and having a member (Andrew) in the team as well.

If someone else became a maintainer of the repo the existing maintainers should also add them to anything run by the subproject incl. netlify, imho.

EDIT: it's also possible to put this in place if it isn't yet, because the project does control it.

Are you new here? :)

... I should have known better 🙃

It's also worth pointing out that even if we approve this, we may not actually be able to get this live without an account that netlify considers owning *.docs.k8s.io adding this subdomain to the kind netlify site through their UI as well. (ref above comment for previous testing of this)

If this fails to work for some reason we probably should abandon netlify in favor of some other stack, but we can re-configure the domain in that case.

from k8s.io.

This DNS change is pushed.

from k8s.io.

Thank you.
Seeing if we can get the netlify end to cooperate.

from k8s.io.