Merge pull request #3618 from mrbobbytables/subproject-site
Add subproject site request guidelines.
This commit is contained in:
Kubernetes Prow Robot
GitHub
commit
ba87104a2a
|
|
@ -0,0 +1,164 @@
|
|||
# Subproject Site Requests
|
||||
|
||||
Official Kubernetes subprojects can request a domain and site hosting for
|
||||
their project specific documentation. The Kubernetes community has standardized
|
||||
on [Netlify] for this purpose. Netlify was chosen for its ease of use,
|
||||
integrations such as offering automatic site previews per PR, and its support
|
||||
for multiple site generation frameworks.
|
||||
|
||||
**NOTE:** This process is only for requesting a domain and hosting, not the
|
||||
building and design of the site itself. The responsibility for maintaining the
|
||||
subproject site belongs to the subproject itself.
|
||||
|
||||
If you are unsure of what site framework to use, [Hugo] is a lightweight Go
|
||||
based framework. It's used for the Kubernetes website and several subprojects.
|
||||
|
||||
|
||||
- [Requesting a Netlify Site](#requesting-a-netlify-site)
|
||||
- [Example Netlify Configuration](#example-netlify-configuration)
|
||||
- [Requesting a Subproject Domain](#requesting-a-subproject-domain)
|
||||
- [Example Subproject Domain Request](#example-subproject-domain-request)
|
||||
- [Processing a Netlify Site Request](#processing-a-netlify-site-request)
|
||||
|
||||
|
||||
## Requesting a Netlify Site
|
||||
|
||||
|
||||
- Create an issue in the [kubernetes/org] repository using the
|
||||
[Netlify Site Request Template]. It will ask for:
|
||||
- Requesting sub-project and associated information. Linking to an issue or
|
||||
other supporting material for the Netlify request associated with the
|
||||
subproject is encouraged and will speed processing of the request.
|
||||
- Desired domain name. It should follow the pattern of
|
||||
`<sub-project>.sigs.k8s.io` and match the
|
||||
[request](#requesting-a-subproject-domain) for a subproject domain.
|
||||
|
||||
- A member of the GitHub Admin team handling Netlify requests will respond and
|
||||
follow up with any questions in the issue.
|
||||
|
||||
- Once Netlify has been configured, [request a subproject
|
||||
domain](#subproject-domain-request) and reference the issue you created. You
|
||||
may use the Netlify site URL (example: `kubernetes-sigs-foo.netlify.com`) till
|
||||
the DNS request has been processed.
|
||||
|
||||
- Update the project to include a [site specific][site-config] configuration
|
||||
file at the root of the repository ([`netlify.toml`][site-config]). Below is a
|
||||
[Hugo] based example that you may use as a reference.
|
||||
|
||||
|
||||
Once complete, the site should be accessible.
|
||||
|
||||
|
||||
### Example Netlify Configuration
|
||||
|
||||
```toml
|
||||
[build]
|
||||
base = "site/"
|
||||
publish = "site/public/"
|
||||
command = "hugo"
|
||||
|
||||
[build.environment]
|
||||
HUGO_VERSION = "0.53"
|
||||
|
||||
[context.production.environment]
|
||||
HUGO_ENV = "production"
|
||||
HUGO_BASEURL = "https://foo.sigs.k8s.io/"
|
||||
|
||||
[context.deploy-preview]
|
||||
command = "hugo --enableGitInfo --buildFuture -b $DEPLOY_PRIME_URL"
|
||||
|
||||
[context.branch-deploy]
|
||||
command = "hugo --enableGitInfo --buildFuture -b $DEPLOY_PRIME_URL"
|
||||
```
|
||||
|
||||
## Subproject Domain Request
|
||||
|
||||
Subproject domains may be requested for a Kubernetes Org managed Netlify site in
|
||||
the form of: `<project>.sigs.k8s.io`.
|
||||
|
||||
To do so, create an issue using the [DNS Update Request] issue template in the
|
||||
[kubernetes/k8s.io] repository. Use the below guidelines for your
|
||||
[DNS Update Request].
|
||||
|
||||
- **Type of DNS update:** Create
|
||||
- **Domain being modified:** `k8s.io`
|
||||
- **New DNS Record:**
|
||||
```yaml
|
||||
# https://github.com/kubernetes-sigs/<project> (<contact or owners>)
|
||||
<project>.sigs:
|
||||
type: CNAME
|
||||
value: <netlify url>
|
||||
```
|
||||
- **Reason for update:** Provide a description and link to the Netlify request
|
||||
issue made in [kubernetes/org].
|
||||
|
||||
|
||||
### Example Subproject Domain Request
|
||||
|
||||
````
|
||||
### Type of DNS update:
|
||||
Create
|
||||
|
||||
### Domain being modified:
|
||||
k8s.io
|
||||
|
||||
### New DNS Record:
|
||||
```yaml
|
||||
# https://github.com/kubernetes-sigs/foo (@bar)
|
||||
foo.sigs:
|
||||
type: CNAME
|
||||
value: kubernetes-sigs-foo.netlify.com
|
||||
```
|
||||
### Reason for update:
|
||||
The sig-foo subproject has requested a netlify site to host its documentation. ref #0000, #0000.
|
||||
````
|
||||
|
||||
|
||||
## Processing a Netlify Site Request
|
||||
|
||||
**NOTE:** For use by the GitHub Admin team. You must be both an Org owner and
|
||||
Netlify admin to follow the procedure.
|
||||
|
||||
- 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 Kubernetes and
|
||||
**Branch to deploy** is set to `master`. 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.
|
||||
|
||||
- Follow up with the requestor in the issue and let them know the site has been
|
||||
deployed and give them the Netlify site url (site name + `netlify.com`).
|
||||
Example `kubernetes-sigs-foo.netlify.com`. They may use this address for
|
||||
testing and use before their DNS Request has been processed.
|
||||
|
||||
Once complete, the rest of the Netlify site configuration can be handled by the
|
||||
project owner in their [netlify.toml][site-config] config.
|
||||
|
||||
|
||||
[netlify]: https://www.netlify.com/
|
||||
[kubernetes website]: https://git.k8s.io/website
|
||||
[hugo]: https://gohugo.io
|
||||
[dns update request]: https://github.com/kubernetes/k8s.io/issues/new/choose
|
||||
[kubernetes/org]: https://git.k8s.io/org
|
||||
[kubernetes/k8s.io]: https://git.k8s.io/k8s.io
|
||||
[netlify site request template]: https://github.com/kubernetes/org/issues/new/choose
|
||||
[dns zone config]: https://git.k8s.io/k8s.io/dns/zone-configs/k8s.io.yaml
|
||||
[site-config]: https://www.netlify.com/docs/netlify-toml-reference/
|
||||
[add custom domain]: https://www.netlify.com/docs/custom-domains/
|
||||
Loading…
Reference in New Issue