Source for: https://kyverno.io
The Kyverno website follows the same support policy as Kyverno, an N-2 policy. Documentation will be made available for the current release and the two previous minor releases. While this extends to the version list on the website, users may still access earlier versions of the documentation by navigating to a specific version by URL.
Documentation for each version is published at a URL like https://release-X-Y-0.kyverno.io/
where X
is the major version and Y
is the minor version. To access the documentation for version 1.9.0, navigate to the URL https://release-1-9-0.kyverno.io/.
Made with contributors-img.
This site makes use of the Docsy theme and Hugo Extended is required to render it.
To contribute changes, use the fork & pull approach.
1. First create a fork of the Kyverno website repository to your GitHub account. By default, the forked repository will be named website
but can be changed in the settings for your repository if desired. You will later created a PR (pull request) using this fork.
2. Next, create a local clone using the command:
git clone https://github.com/{YOUR-GITHUB-ID}/website kyverno-website/
3. Then navigate to the local folder and build the website for local viewing of changes:
cd kyverno-website
hugo server
Note For Windows Users: When running the hugo server
command, make sure to execute it with administrator privileges in your terminal. This is necessary to ensure proper access and functionality during the server execution.
By default, Hugo runs the website at: https://localhost:1313 and will re-build the site on changes.
The project uses Hugo Modules to manage the theme:
Run hugo mod get -u ./...
from project root.
To clean the module cache use hugo mod clean
.
Policies found at https://kyverno.io/policies/ are generated in Markdown from the source repository at kyverno/policies. For any changes to appear on https://kyverno.io/policies/, edits must be made to the upstream policy YAML files at kyverno/policies, and the render
tool run from this repository to generate the respective Markdown. See render README for more details.
The Kyverno website has established several writing conventions in the interest of consistency and accuracy.
Active voice is preferred in most writing examples. Ex., "this ClusterPolicy mutates incoming Pods..." and not "incoming Pods are mutated by this ClusterPolicy".
- Kubernetes resource kinds are considered proper nouns and are distinguished from other nouns by the initial letter capitalization. Ex., "a Kubernetes Pod will be annotated".
- Anything intended to be proper code or typed at a CLI is formatting using Markdown code syntax with backticks or in blocks (surrounded by three backticks).
- Code represented in blocks should prefer a syntax declaration for this theme's highlighting ability. Ex., when displaying YAML notate the code block with three backticks and "yaml".
- We standardize on use of the Oxford comma.
In order to ensure that broken link detection works optimally as well as providing a way for users to find linked content when viewing the raw Markdown files on GitHub, links should be made using relative paths to files and not relative rendered paths. Following this method ensures not only pages can be found but anchor links are still valid.
This is a good link:
[some link text](foo.md#my-anchor)
This is a bad link:
[some link text](/docs/foo/#my-anchor)
The Kyverno website now uses releases to organize documentation by the specified release making it easier for users to find the information that pertains to their version. Releases are defined by branches of kyverno/website and a combination of exposing them in the website configuration and modifying hosting parameters.
Here are the rules for managing release versions:
-
All fixes and feature changes go to the
main
branch (we may in a few rare cases make fixes to prior versions of the documentation.) The main branch can be accessed athttps://main.kyverno.io
. -
When a new release is ready for GA, a new release branch is created (see steps below). Release branches are named
release-{major}-{minor}-{patch}
for examplerelease-1-4-2
. The release branch can be accessed using the{branch}.kyverno.io
and the latest release is available atkyverno.io
.
To create a new release branch:
-
Create and push the branch using
git checkout -b release-{major}-{minor}-{patch}
or via GitHub. -
Update Netlify to point
production
to the new release branch. -
Also in Netlify, go into the Domain management settings of the site and add a new subdomain for the branch representing the previous version. For example, if the release to be cut is 1.8.0, there will not be a
release-1-7-0.kyverno.io
record which exists. One must be created forrelease-1-7-0.kyverno.io
.
In the main
branch:
-
Update the versions list in params.toml to add the next release.
-
Update
version_menu
andversion
in params.toml for the next release. -
Create a PR.
-
Clear the Netlify cache!
In the current release branch:
- Update
params.toml
so thatversion_menu
andversion
reflect the version of that release branch, NOTmain
. This is so when users navigate to the version of the docs represented in that version it shows the correct number.
Ideally all changes will go to main
and then be promoted to a release branch. However, occasionally we will need to fix documentation issues for already released versions. Rendered policies will always go to all branches because the policy samples themselves declare minimum capable versions via the policies.kyverno.io/minversion
annotation.
Use the cherry pick bot to request a PR be cherry picked to a target branch. Call for the bot with a comment on the desired PR with /cherry-pick release-1-12-0
to cherry pick this PR to the release-1-12-0
branch. A new PR will be opened with release-1-12-0
as the target branch.
There are several ways to create multiple PRs, but here is one easy flow:
- Create a PR for the
main
branch, as usual. - For each additional branch, checkout the branch (
git checkout <branch>
), and then cherry pick the commit(s) to that branch usinggit --cherry-pick <commit>
. If using GitHub Desktop, a commit can be cherry picked by setting the source branch where the PR was merged, accessing the History tab, and dragging-and-dropping that commit to the destination branch. - Submit PRs for each release branch.
Edit the .toml
files inside the config/_default
directory.
If needing to create a new page under the Policies
heading that adopts the same CSS styling, assign type = "policies"
to the page.