Community: Process doc for subproject site requests

[mrbobbytables]

This is a follow-up to several discussions on slack and some preliminary investigation.

Several subprojects have grown large and complex enough to warrant their own site to house easily discoverable documentation. These subprojects fall out of scope for documentation on the main kubernetes.io site. Some notable examples include kind and kubebuilder with others approaching the idea.

These subproject sites should be managed under Kubernetes community owned resources instead of being tied to the personal accounts of subproject owners.

Most of the requirements and original process discovery were mapped by @BenTheElder in https://github.com/kubernetes/k8s.io/issues/184 and put together in a subsequent proposal doc.

A WIP process doc has been started with one large outstanding task:

• Sort out how best to enable netlify integration for specific repos while ensuring they are managed under the correct netlify team.

Currently this requires temporarily adding a sig-docs member with netlify access to be granted write permission to the repo to configure the integration...which is something I don't think we really want to do...

After some investigation, the ideal method would be for a subproject owner to request approval for the netlfiy app where it could then be quickly processed by the github admin team. To do this, we will need to verify this workflow and ensure that any repos processed this way wind up being owned by the correct netlify team.

With that I think there are 4 real AI/questions that remain:

• [x] Test and verify repo/netlify request workflow.
• [x] Decide which repo should own the subproject site request issue template (k/website? k/community? k/org? k/k8s.io?)
• [x] Decide where process doc should be located (k/community/communication?)
• [x] Update process doc with final workflow.

/assign

/sig contributor-experience
/area community-management
/area github-management
/kind feature
/priority important-soon

/cc @BenTheElder @nikhita @zacharysarah @chenopis @parispittman @castrojo

[parispittman]

thanks for putting this all together in one spot @mrbobbytables!! 💟

[mrbobbytables]

/milestone May
/lifecycle active

[mrbobbytables]

/milestone May

[mrbobbytables]

After looking into Netlify teams and permissions there looks to be two paths forward.

1. The current method -- A member of sig-docs that is a netlify collaborator is granted temporary admin access to the repo to enable Netlify integration and configure the site. They are then removed after it is configured.
2. The github admin team (or a subset of them) are added as Netlify collaborators and enable the integration/configure the site for requesting repos.

Note: Configuring the site in this sense is really just giving it a netlify project name and specifying it's intended DNS name. All other configuration is done through the netlify.toml configuration file.

Of the two options I'd lean towards 2, as it minimizes adding/removing people from owner access for the repo. It does however depend on two other things: A) SIG-Docs signs off adding members of the GitHub admin team as Netlify collaborators, and B) The GitHub admin team are okay with taking on this additional role of handling these types of requests.

/cc @spiffxp @cblecker @idvoretskyi
(would like some more eyes from github admin team)

[zacharysarah]

/cc @jaredbhatti @bradamant3 for SIG Docs visibility

[nikhita]

/cc @kubernetes/owners

[davidewatson]

I have followed the Slack conversations in #sig-docs-tools on this issue but it is not clear to me what remains to be done or how I can help move things along. For context, the Cluster API subproject of SIG Cluster Lifecycle has a GitBook which we are hoping to publish using Netlify. Is there any way I can help?

[mrbobbytables]

@davidewatson Right now waiting for review from github admins. It should be possible to get something up and going now with the old method if needed.

[cblecker]

As I understand it, the problem is that there is a step that requires both privileged access to Netlify and GitHub, but then once complete, the rest of the configuration is in the repo? Is that accurate @mrbobbytables?

[mrbobbytables]

@cblecker correct. It really boils down to this (as a member with privileges to both):

• Enable Netlify app for GitHub repo.
• Initial Netlify configuration:
  
  
  
  • Give it a friendly project/site name in netlify (e.g. kubernetes-sigs-contributor-site).
  
  
  • Add a custom domain (CNAME) that should match what is being requested in k/k8s.io (ref kind
    
    )
  
  
  • Enable https for that custom domain (checkbox once custom domain is added).
  
  

After that all configuration can be handled via the netlify.toml file.

[cblecker]

Yeah, I think this is something we could take on.. that said, we would need some clear docs around it.

Namely:

• What steps we need to take (doesn't need to be step by step, but each part of the process should be clear)
• Any naming conventions written down (like the friendly name)
• Any policy dos/donts
• Who to escalate to if we are unclear or have questions

[mrbobbytables]

Definitely can do that 👍

[mrbobbytables]

Some thoughts -- I think the best path would be to have it be a github issue template residing in kubernetes/k8s.io and would essentially be a simpler version of the current DNS request form. The GitHub admin team would have 1 more additional responsibility in addition to creating the netlify site and that would be cutting a PR to add the DNS record. The alternative would be an additional issue or the requestor PR'ing the dns entry.

Here is a draft of the process:

Processing a Netlify Site Request

• Login to [Netlify] and from the home dashboard select New Site from Git.

• On the _"Create a new site"_ page, select GitHub. It will then prompt you to authorize the application for the desired GitHub Organization.

  • Select the GitHub Organization and the desired repo.

• In the _"Deploy Options"_ ensure the Owner is set to [TODO: get org name] and Branch to deploy is set to master. Then Deploy the site. It will take you to the Site overview page.

• Navigate to the Site Settings and then change the Site name following the convention kubernetes-sigs-<repo/project name> e.g. kubernetes-sigs-foo. This will be used as both the Netlify site name and in the auto-generated PR based previews.

• From the left hand menu, select Domain management.

• Select [Add custom domain]. Then enter the domain name requested in the issue. It should follow the pattern of <subproject-name>.sigs.k8s.io.

• From the _"Domain management"_ page, select HTTPS. It will prompt you regarding enabling _"Lets Encrypt"_ for the site. Enable it, and save the settings.

• Create a PR against [kubernetes/k8s.io] updating the [dns zone config] with a CNAME entry pointing to the provisioned Netlify site.

  # <subproject>.sigs - should match domain being requested
  foo.sigs:
  type: CNAME
  value: kubernetes-sigs-foo.netlify.com
  

• In the PR body, add a note fixes #1234 with the issue number of the Netlify request.

• Add a note in the original request referencing the PR that the Netlify site has been provisioned and the domain will configured once the PR is merged.

Once complete, the rest of the Netlify site configuration can be handled by the project owner in their netlify.toml config.

[cblecker]

Process wise, I'd like the doc for this to live in git.k8s.io/community/github-management, and the issues to be opened against k/org instead of k/k8s.io.

Right now the DNS doesn't auto update from git.. one of the DNS admins needs to run the container that does it. Eventually we will get there, but DNS admins are a different group of people than the GitHub admins (I'm the one overlapping member, I think). I'd suggest that the doc for the GitHub admins ends at the PR step, and that it's up to the requester to open up the PR (having docs on that step for them would be good).

[mrbobbytables]

@cblecker kk, that is pretty much what I originally had. :) Thought it might be possible to streamline and save a step. XD

Will get a PR out the door tomorrow.

[mrbobbytables]

Last steps following the merge of #3618 are adding the github admin team to netlify and creating the issue template in k/org.

I can create an issue template later today.

@zacharysarah would you be able to add the github admin team to the netlify org?

[zacharysarah]

@mrbobbytables Sure thing. I need emails for the following folks:

• [ ] @calebamiles
• [ ] @cblecker
• [ ] @fejta

[cblecker]

@zacharysarah my-github-username at gmail dot com

[BenTheElder]

Thank you so much to @mrbobbytables in particular for picking this up ❤️
Thanks to everyone else involved as well :-)

[mrbobbytables]

I think this is safe to close now. We should be good. \o/

/close

[k8s-ci-robot]

@mrbobbytables: Closing this issue.

In response to this:

I think this is safe to close now. We should be good. \o/

/close

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.

[nikhita]

I think @cblecker and @fejta still need to be added to invited to netlify, but we can coordinate that on slack. :+1: