website

The kubernetes/website repository is the official source for the Kubernetes documentation website. It contains all the content, configuration, and tooling necessary to build and maintain kubernetes.io, which serves as the primary resource for users, administrators, and developers working with Kubernetes.

Pros

Comprehensive and up-to-date documentation for Kubernetes
Open-source project with active community contributions
Supports multiple languages for internationalization
Utilizes Hugo static site generator for efficient content management

Cons

Large repository size due to extensive documentation and multiple language versions
Complex contribution process for newcomers
Frequent updates may lead to occasional inconsistencies or outdated information
Requires familiarity with Git, Markdown, and Hugo for effective contributions

Getting Started

To contribute to the Kubernetes documentation:

Fork the kubernetes/website repository on GitHub

Clone your fork locally:

git clone https://github.com/YOUR-USERNAME/website.git
cd website

Install Hugo and dependencies:
```
npm install
```
Run the local development server:
```
npm run develop
```
Make changes to the content in the content/en/docs/ directory
Commit your changes, push to your fork, and create a pull request

For more detailed instructions, refer to the CONTRIBUTING.md file in the repository.

Competitor Comparisons

kubebuilder

7,734

Kubebuilder - SDK for building Kubernetes APIs using CRDs

Pros of Kubebuilder

Focused on Kubernetes operator development, providing a more specialized toolset
Includes scaffolding and code generation features for faster development
Offers a streamlined approach to creating custom resources and controllers

Cons of Kubebuilder

Limited scope compared to the broader Kubernetes documentation
May require more technical expertise to use effectively
Less comprehensive coverage of general Kubernetes concepts

Code Comparison

Kubebuilder (main.go):

func main() {
    mgr, err := ctrl.NewManager(ctrl.GetConfigOrDie(), ctrl.Options{})
    if err != nil {
        setupLog.Error(err, "unable to start manager")
        os.Exit(1)
    }
    // ... (controller setup)
}

Website (config.toml):

[params]
time_format_blog = "Monday, January 02, 2006"
description = "Production-Grade Container Orchestration"
showedit = true

Summary

Kubebuilder is a specialized tool for Kubernetes operator development, offering code generation and scaffolding features. It's more focused but requires deeper technical knowledge. The Kubernetes Website repository, on the other hand, provides comprehensive documentation and is more accessible to a broader audience. While Kubebuilder's code is Go-based and centered around controller development, the Website repository primarily contains content and configuration files for the Kubernetes documentation site.

kustomize

10,890

Customization of kubernetes YAML configurations

Pros of Kustomize

Focused on customizing Kubernetes manifests, providing a powerful tool for configuration management
Lightweight and easy to integrate into existing workflows
Supports declarative configuration without templating

Cons of Kustomize

Limited scope compared to the comprehensive Kubernetes documentation
May require additional learning for users unfamiliar with Kustomize concepts
Less frequent updates and contributions compared to the Kubernetes website

Code Comparison

Kustomize example:

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- deployment.yaml
- service.yaml

Kubernetes website example (Markdown):

---
title: Deployments
content_type: concept
weight: 10
---

# Deployments

A Deployment provides declarative updates for Pods and ReplicaSets.

The Kustomize repository focuses on YAML configurations for customizing Kubernetes resources, while the Kubernetes website repository primarily contains Markdown files for documentation purposes. Kustomize is a practical tool for managing Kubernetes configurations, whereas the Kubernetes website serves as a comprehensive resource for learning and understanding Kubernetes concepts and best practices.

kind

13,281

Kubernetes IN Docker - local clusters for testing Kubernetes

Pros of kind

Focused on local Kubernetes cluster creation, making it easier for developers to set up test environments
Lightweight and fast to deploy, ideal for CI/CD pipelines and quick testing
Supports multi-node clusters, allowing for more complex testing scenarios

Cons of kind

Limited to local development and testing, not suitable for production deployments
Requires Docker to be installed and running on the host machine
Less comprehensive documentation compared to the Kubernetes website

Code Comparison

kind configuration example:

kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
- role: control-plane
- role: worker

website content example (Hugo front matter):

---
title: Kubernetes Documentation
content_type: concept
weight: 10
---

Summary

kind is a specialized tool for creating local Kubernetes clusters, while the Kubernetes website serves as the primary documentation and information hub for the entire Kubernetes project. kind excels in providing a quick and easy way to set up development environments, but it's limited in scope compared to the comprehensive resources available on the Kubernetes website.

community

11,906

Kubernetes community content

Pros of community

More focused on community engagement and governance
Contains contributor guides and community meeting notes
Easier for newcomers to find ways to get involved

Cons of community

Less technical documentation compared to website
May not be as frequently updated with product changes
Potentially overwhelming for users seeking specific Kubernetes usage information

Code comparison

website:

- name: docs
  description: Documentation for Kubernetes
  url: https://kubernetes.io/docs/
  channels:
    - name: kubernetes-docs
      slack: https://kubernetes.slack.com/messages/kubernetes-docs

community:

- name: contributor-comms
  label: area/contributor-comms
  leadership:
    chairs:
    - github: paris
      name: Paris Pittman
      company: Google

The website repo focuses on documentation structure, while the community repo emphasizes leadership and governance.

Summary

The community repository is better suited for those looking to engage with the Kubernetes community, contribute to the project, or understand its governance. The website repository, on the other hand, is more appropriate for users seeking comprehensive documentation on Kubernetes usage and features. Both repositories serve distinct purposes within the Kubernetes ecosystem, catering to different aspects of the project's development and user base.

kubernetes

109,710

Production-Grade Container Scheduling and Management

Pros of kubernetes

Contains the core Kubernetes codebase, allowing direct contributions to the platform
Provides deeper insights into Kubernetes internals and implementation details
Offers a more comprehensive view of Kubernetes development and evolution

Cons of kubernetes

Significantly larger codebase, making it more challenging to navigate and contribute
Requires more extensive knowledge of Go and distributed systems
Higher barrier to entry for new contributors compared to the website repository

Code Comparison

kubernetes:

func (kl *Kubelet) syncPod(o syncPodOptions) error {
    // ... (complex pod synchronization logic)
}

website:

- title: Concepts
  path: /docs/concepts/
  section:
    - title: Overview
      path: /docs/concepts/overview/

The kubernetes repository contains the core platform code, primarily written in Go, while the website repository focuses on documentation and is mainly composed of Markdown and YAML files for site structure.

The kubernetes repo is more suitable for developers looking to contribute to the Kubernetes platform itself, while the website repo is ideal for those interested in improving documentation and user experience.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

The Kubernetes documentation

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

Contributing to the docs
Localization READMEs

Using this repository

You can run the website locally using Hugo (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.

Prerequisites

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

npm
Go
Hugo (Extended version)
A container runtime, like Docker.

[!NOTE] Make sure to install the Hugo extended version specified by the HUGO_VERSION environment variable in the netlify.toml file.

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

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

The Kubernetes website uses the Docsy Hugo theme. Even if you plan to run the website in a container, we strongly recommend pulling in the submodule and other development dependencies by running the following:

Windows

# fetch submodule dependencies
git submodule update --init --recursive --depth 1

Linux / other Unix

# fetch submodule dependencies
make module-init

Running the website using a container

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

# You can set $CONTAINER_ENGINE to the name of any Docker-like container tool
make 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 and Windows).

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

Running the website locally using Hugo

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

For macOS and Linux
```
npm ci
make serve
```

For Windows (PowerShell)

npm ci
hugo.exe server --buildFuture --environment development

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

Building the API reference pages

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

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

Pull in the api-ref-generator submodule:

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

Update the Swagger specification:

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

In api-ref-assets/config/, adapt the files toc.yaml and fields.yaml to reflect the changes of the new release.
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 to http://localhost:1313/docs/reference/kubernetes-api/ to view the API reference.
When all changes of the new contract are reflected into the configuration files toc.yaml and fields.yaml, create a Pull Request with the newly generated API reference pages.

Troubleshooting

error: failed to transform resource: TOCSS: failed to transform "scss/main.scss" (text/x-scss): this feature is not available in your current Hugo version

Hugo is shipped in two set of binaries for technical reasons. The current website runs based on the Hugo Extended version only. In the release page look for archives with extended in the name. To confirm, run hugo version and look for the word extended.

Troubleshooting macOS for too many open files

If you run make 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 files
make: *** [serve] Error 1

Try checking the current limit for open files:

launchctl limit maxfiles

Then run the following commands (adapted from https://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.plist

curl -O https://gist.githubusercontent.com/tombigel/d503800a282fcadbee14b537735d202c/raw/ed73cacf82906fdde59976a0c8248cce8b44f906/limit.maxfiles.plist
curl -O https://gist.githubusercontent.com/tombigel/d503800a282fcadbee14b537735d202c/raw/ed73cacf82906fdde59976a0c8248cce8b44f906/limit.maxproc.plist

sudo mv limit.maxfiles.plist /Library/LaunchDaemons
sudo mv limit.maxproc.plist /Library/LaunchDaemons

sudo chown root:wheel /Library/LaunchDaemons/limit.maxfiles.plist
sudo chown root:wheel /Library/LaunchDaemons/limit.maxproc.plist

sudo launchctl load -w /Library/LaunchDaemons/limit.maxfiles.plist

This works for Catalina as well as Mojave macOS.

Get involved with SIG Docs

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

You can also reach the maintainers of this project at:

Contributing to the docs

You can click the Fork button in the upper-right area of the screen to create a copy of this repository in your GitHub account. This copy is called a fork. 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:

New contributor ambassadors

If you need help at any point when contributing, the New 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 the Kubernetes Slack. Current New Contributors Ambassadors for SIG Docs:

Name	Slack	GitHub
Sreeram Venkitesh	@sreeram.venkitesh	@sreeram-venkitesh

Localization READMEs

Language	Language
Bengali	Korean
Chinese	Polish
French	Portuguese
German	Russian
Hindi	Spanish
Indonesian	Ukrainian
Italian	Vietnamese
Japanese

Code of conduct

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

Thank you

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

Top Related Projects

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot