Open Service Mesh Docs

📖 This section contains the OSM Docs

🚢 Also the website config to generate docs.openservicemesh.io

🔗 Looking for the main OSM website? Visit osm-www

Editing Content

docs.openservicemesh.io is a static site. The documentation content needs to be located at content/docs/.

The content served on https://docs.openservicemesh.io is served from the latest release on this repo. Most updates should be made only in main and can be previewed at https://main--osm-docs.netlify.app/.

If it's necessary to change published release-specific docs, those changes should be made in the release-specific branch serving those docs. Once configured as described in Adding release-specific docs, PRs to that branch will auto-build just like PRs to main.

References to the osm branch, osm version, and envoy version should be parameterized unless they are in a sample output. For example, a reference to OSM's constants.go should be parameterized as https://github.com/openservicemesh/osm/blob/{{< param osm_branch >}}/pkg/constants/constants.go.

To ensure the docs content renders correctly in the theme, each page will need to have front matter metadata. Example front matter:

---
title: "Docs Home"
linkTitle: "Home"
description: "OSM Docs Home"
weight: 1
type: docs
---

Front Matter Notes:

• inclusion of type: docs is important for the theme to properly index the site contents
• the linkTitle attribute allows you to simplify the name as it appears in the left-side nav bar - ideally it should be short and clear - whereas the title can handle long form names for pages/documents.

Adding release-specific docs

Create a release branch

Look for a branch in the upstream repo named release-vX.Y, where X and Y correspond to the major and minor version of the new release. For example, release-v0.8. If the branch already exists, move to the next step.

Identify the base commit in the main branch for the release and cut a release branch off main.

Note: Care must be taken to ensure the release branch is created from a commit meant for the release. If unsure about the commit to use to create the release branch, please open an issue in the osm repo and a maintainer will assist you with this.

$ git checkout -b release-<version> <commit-id> # ex: git checkout -b release-v0.4 0d05587

Push the release branch to the upstream repo (NOT forked), identified here by the upstream remote.

$ git push upstream release-<version> # ex: git push upstream release-v0.4

Netlify will auto-deploy the branch to a url like https://release-v0-8--osm-docs.netlify.app/. This can be used to preview and test that the branch builds correctly.

Update the release references

Proceed with the following steps once the release branch has been created in the OSM repo.

1. Create a new branch off of the release branch to maintain updates specific to the new version. Let's call it the patch branch. The patch branch should not be created in the upstream repo.

2. On the patch branch, update the osm_branch, osm_version, and envoy_version in config.toml to the new release versions.

   osm_branch = "release-v0.8"
   osm_version = "v0.8.0"
   envoy_version = "v1.17.2"

3. Create a pull request from the patch branch to the release branch. Proceed to the next step once the pull request is approved and merged.

After cutting the OSM release

1. Open an issue in this repo asking for a new DNS record be added to the site (via Netlify), to assign a subdomain to the deployed branch.
2. When published, the newly-added branch will function like https://release-v0-8.docs.openservicemesh.io/

After publishing the new release-specific docs

Update the release branch

1. Create another patch branch off of the release branch (or use the existing patch branch after fetching and rebasing on the release branch).

2. On the patch branch, add the new release as a version parameter in config.toml with the latest tag. The version parameters represent all currently supported versions of OSM and are used to populate the Release drop down menu on the site. The url for the new release is formatted https://release-vX-Y.docs.openservicemesh.io/.

   [[params.versions]]
       version = "v0.8 (latest)"
       url = "https://release-v0-8.docs.openservicemesh.io/"

3. Create a pull request from the patch branch to the release branch. Proceed to the next step once the pull request is approved and merged.

Update main and previous release branches

1. Update the redirects in netlify.toml on the main branch to redirect https://docs.openservicemesh.io/ to https//release-vX-Y.docs.openservicemesh.io/ where release-vX-Y is the newest release.

2. Each previous release-specific site that is still supported needs to be able to access the latest release from the Release drop down. On the previous release branches, update the config.toml to list the new release version as shown above.

3. The latest tag must be removed from all previous versions. For example, the latest tag must be removed from v0.7 (latest) on the release-v0.7 branch.

4. Add the banner to a previous release specific site if it has not been configured.

5. Add or update the version banner parameter in config.toml to enable the banner at the top of each previous release-specific site that will tell visitors which version they are looking at. For example, the version banner for release-v0-7 would be configured as follows:

   [params.versionbanner]
       show = true
       archive = "v0.7"
       latest = "https://release-v0-8.docs.openservicemesh.io/"

Update the release support matrix

Once a new OSM version has been released, update the OSM and Kubernetes support matrix. The Kubernetes version support will be the current releases of Kubernetes at the time of the OSM release.

Site Development

Notes

• built with the Hugo static site generator
• custom theme uses Docsy as a base, with Bootstrap as the underlying css framework and some OSM custom sass
• deployed to Netlify via merges to main. (@flynnduism can grant additional access to account)
• metrics tracked via Google Analytics

Install dependencies:

• Hugo installation guide
• NPM packages are installed by running yarn. Install Yarn if you need to.

Run the site:

// install npm packages
yarn

// rebuild the site (to compile latest css/js)
hugo

// or serve the site for local dev
hugo serve

Deploying the site:

The site auto deploys the main branch via Netlify. Once pull requests are merged the changes will appear at docs.openservicemesh.io after a couple of minutes. Check the logs for details.

hugo serve will run the site locally at localhost:1313