Repository files navigation

This repository contains the assets required to build theKubernetes website and documentation. We're glad that you want to contribute!

• Contributing to the docs
• Localization READMEs

You can run the website locally usingHugo (Extended version), or you can run it in a container runtime. We strongly recommend using the container runtime, as it gives deployment consistency with the live website.

To use this repository, you need the following installed locally:

• npm
• Go
• Hugo (Extended version)
• A container runtime, likeDocker.

Before you start, install the dependencies. Clone the repository and navigate to the directory:

git clone https://github.com/kubernetes/website.gitcd website

The Kubernetes website uses theDocsy Hugo theme,which can be installed via npm. You can also download a pre-configureddevelopment container image that includes Hugo and Docsy. Additionally, a Gitsubmodule is used for tools that generate the reference documentation.

# fetch submodule dependenciesgit submodule update--init--recursive--depth1

# fetch submodule dependenciesmake module-init

To build the site in a container, run the following:

# You can set $CONTAINER_ENGINE to the name of any Docker-like container toolmake container-serve

If you see errors, it probably means that the hugo container did not have enough computing resources available. To solve it, increase the amount of allowed CPU and memory usage for Docker on your machine (MacOS andWindows).

Open up your browser tohttp://localhost:1313 to view the website. As you make changes to the source files, Hugo updates the website and forces a browser refresh.

To install dependencies, deploy and test the site locally, run:

• For macOS and Linux

  npm cimake serve

• For Windows (PowerShell)

  npm cihugo.exe server--buildFuture--environment development

This will start the local Hugo server on port 1313. Open up your browser tohttp://localhost:1313 to view the website. As you make changes to the source files, Hugo updates the website and forces a browser refresh.

The API reference pages located incontent/en/docs/reference/kubernetes-api are built from the Swagger specification, also known as OpenAPI specification, usinghttps://github.com/kubernetes-sigs/reference-docs/tree/master/gen-resourcesdocs.

To update the reference pages for a new Kubernetes release follow these steps:

1. Pull in theapi-ref-generator submodule:

   git submodule update --init --recursive --depth 1

2. Update the Swagger specification:

   curl'https://raw.githubusercontent.com/kubernetes/kubernetes/master/api/openapi-spec/swagger.json'> api-ref-assets/api/swagger.json

3. Inapi-ref-assets/config/, adapt the filestoc.yaml andfields.yaml to reflect the changes of the new release.

4. Next, build the pages:

   make api-reference

   You can test the results locally by building and serving the site from a container:

   make container-serve

   In a web browser, go tohttp://localhost:1313/docs/reference/kubernetes-api/ to view the API reference.

5. When all changes of the new contract are reflected into the configuration filestoc.yaml andfields.yaml, create a Pull Request with the newly generated API reference pages.

Hugo is shipped in two set of binaries for technical reasons. The current website runs based on theHugo Extended version only. In therelease page look for archives withextended in the name. To confirm, runhugo version and look for the wordextended.

If you runmake serve on macOS and receive the following error:

ERROR 2020/08/01 19:09:18 Error: listen tcp 127.0.0.1:1313: socket: too many open filesmake:*** [serve] Error 1

Try checking the current limit for open files:

launchctl limit maxfiles

Then run the following commands (adapted fromhttps://gist.github.com/tombigel/d503800a282fcadbee14b537735d202c):

#!/bin/sh# These are the original gist links, linking to my gists now.# curl -O https://gist.githubusercontent.com/a2ikm/761c2ab02b7b3935679e55af5d81786a/raw/ab644cb92f216c019a2f032bbf25e258b01d87f9/limit.maxfiles.plist# curl -O https://gist.githubusercontent.com/a2ikm/761c2ab02b7b3935679e55af5d81786a/raw/ab644cb92f216c019a2f032bbf25e258b01d87f9/limit.maxproc.plistcurl -O https://gist.githubusercontent.com/tombigel/d503800a282fcadbee14b537735d202c/raw/ed73cacf82906fdde59976a0c8248cce8b44f906/limit.maxfiles.plistcurl -O https://gist.githubusercontent.com/tombigel/d503800a282fcadbee14b537735d202c/raw/ed73cacf82906fdde59976a0c8248cce8b44f906/limit.maxproc.plistsudo mv limit.maxfiles.plist /Library/LaunchDaemonssudo mv limit.maxproc.plist /Library/LaunchDaemonssudo chown root:wheel /Library/LaunchDaemons/limit.maxfiles.plistsudo chown root:wheel /Library/LaunchDaemons/limit.maxproc.plistsudo launchctl load -w /Library/LaunchDaemons/limit.maxfiles.plist

This works for Catalina as well as Mojave macOS.

Learn more about SIG Docs Kubernetes community and meetings on thecommunity page.

You can also reach the maintainers of this project at:

• Slack
  • Get an invite for this Slack
• Mailing List

You can click theFork button in the upper-right area of the screen to create a copy of this repository in your GitHub account. This copy is called afork. Make any changes you want in your fork, and when you are ready to send those changes to us, go to your fork and create a new pull request to let us know about it.

Once your pull request is created, a Kubernetes reviewer will take responsibility for providing clear, actionable feedback. As the owner of the pull request,it is your responsibility to modify your pull request to address the feedback that has been provided to you by the Kubernetes reviewer.

Also, note that you may end up having more than one Kubernetes reviewer provide you feedback or you may end up getting feedback from a Kubernetes reviewer that is different than the one initially assigned to provide you feedback.

Furthermore, in some cases, one of your reviewers might ask for a technical review from a Kubernetes tech reviewer when needed. Reviewers will do their best to provide feedback in a timely fashion but response time can vary based on circumstances.

For more information about contributing to the Kubernetes documentation, see:

• Contribute to Kubernetes docs
• Page Content Types
• Documentation Style Guide
• Localizing Kubernetes Documentation
• Introduction to Kubernetes Docs

If you need help at any point when contributing, theNew Contributor Ambassadors are a good point of contact. These are SIG Docs approvers whose responsibilities include mentoring new contributors and helping them through their first few pull requests. The best place to contact the New Contributors Ambassadors would be on theKubernetes Slack. Current New Contributors Ambassadors for SIG Docs:

Participation in the Kubernetes community is governed by theCNCF Code of Conduct.

Kubernetes thrives on community participation, and we appreciate your contributions to our website and our documentation!