From c134c90a54a284e254dae605aecf6c32bb4bf7f2 Mon Sep 17 00:00:00 2001 From: Nick Veitch Date: Tue, 6 Aug 2024 12:15:41 +0100 Subject: [PATCH] Moonray docs (#581) * add moonray docs --- .github/workflows/automatic-doc-checks.yml | 15 + .wokeignore | 1 + docs/moonray/.custom_wordlist.txt | 0 docs/moonray/.gitignore | 14 + docs/moonray/.readthedocs.yaml | 30 ++ docs/moonray/.sphinx/.wordlist.txt | 61 ++++ docs/moonray/.sphinx/_static/favicon.png | Bin 0 -> 2258 bytes docs/moonray/.sphinx/_static/tag.png | Bin 0 -> 6781 bytes docs/moonray/.sphinx/_templates/header.html | 36 +++ docs/moonray/.sphinx/get_vale_conf.py | 29 ++ docs/moonray/.sphinx/pa11y.json | 9 + docs/moonray/.sphinx/requirements.txt | 2 + docs/moonray/.sphinx/spellingcheck.yaml | 30 ++ docs/moonray/.wokeignore | 4 + docs/moonray/Makefile | 30 ++ docs/moonray/Makefile.sp | 110 +++++++ docs/moonray/_parts/test.md | 3 + docs/moonray/conf.py | 227 ++++++++++++++ docs/moonray/doc-cheat-sheet-myst.md | 261 ++++++++++++++++ docs/moonray/doc-cheat-sheet.rst | 285 ++++++++++++++++++ docs/moonray/explanation/about.md | 12 + docs/moonray/explanation/index.md | 36 +++ docs/moonray/howto/index.md | 40 +++ docs/moonray/howto/install.md | 5 + docs/moonray/index.md | 74 +++++ docs/moonray/make.bat | 35 +++ docs/moonray/reference/index.md | 34 +++ docs/moonray/reference/test.md | 3 + docs/moonray/reuse/links.txt | 1 + docs/moonray/reuse/substitutions.yaml | 4 + docs/moonray/tutorial/index.md | 36 +++ docs/src/capi/explanation/index.md | 4 +- docs/src/capi/howto/index.md | 4 +- docs/src/capi/index.md | 10 +- docs/src/capi/reference/index.md | 4 +- docs/src/capi/tutorial/getting-started.md | 6 +- docs/src/capi/tutorial/index.md | 4 +- docs/src/charm/explanation/about.md | 4 +- docs/src/charm/explanation/index.md | 6 +- docs/src/charm/howto/charm.md | 4 +- docs/src/charm/howto/contribute.md | 12 +- docs/src/charm/howto/cos-lite.md | 12 +- docs/src/charm/howto/etcd.md | 20 +- docs/src/charm/howto/index.md | 4 +- docs/src/charm/howto/proxy.md | 4 +- docs/src/charm/index.md | 8 +- docs/src/charm/reference/charms.md | 4 +- docs/src/charm/reference/community.md | 4 +- docs/src/charm/reference/index.md | 4 +- docs/src/charm/tutorial/getting-started.md | 8 +- docs/src/charm/tutorial/index.md | 4 +- docs/src/index.md | 12 +- docs/src/snap/explanation/about.md | 10 +- docs/src/snap/explanation/channels.md | 8 +- docs/src/snap/explanation/clustering.md | 12 +- docs/src/snap/explanation/index.md | 4 +- docs/src/snap/explanation/ingress.md | 10 +- docs/src/snap/explanation/security.md | 12 +- docs/src/snap/howto/backup-restore.md | 2 +- docs/src/snap/howto/contribute.md | 12 +- docs/src/snap/howto/external-datastore.md | 8 +- docs/src/snap/howto/index.md | 4 +- docs/src/snap/howto/install/index.md | 4 +- docs/src/snap/howto/install/lxd.md | 22 +- docs/src/snap/howto/install/multipass.md | 4 +- docs/src/snap/howto/install/offline.md | 18 +- docs/src/snap/howto/install/snap.md | 4 +- docs/src/snap/howto/networking/default-dns.md | 6 +- .../snap/howto/networking/default-ingress.md | 4 +- .../howto/networking/default-loadbalancer.md | 4 +- .../snap/howto/networking/default-network.md | 4 +- docs/src/snap/howto/networking/index.md | 2 +- docs/src/snap/howto/proxy.md | 2 +- docs/src/snap/howto/storage/ceph.md | 4 +- docs/src/snap/howto/storage/index.md | 2 +- docs/src/snap/howto/storage/storage.md | 4 +- docs/src/snap/howto/support.md | 6 +- docs/src/snap/index.md | 10 +- docs/src/snap/reference/architecture.md | 6 +- docs/src/snap/reference/community.md | 6 +- docs/src/snap/reference/index.md | 4 +- docs/src/snap/reference/proxy.md | 4 +- docs/src/snap/reference/releases.md | 8 +- docs/src/snap/reference/roadmap.md | 4 +- docs/src/snap/reference/troubleshooting.md | 2 +- docs/src/snap/tutorial/add-remove-nodes.md | 8 +- docs/src/snap/tutorial/getting-started.md | 18 +- docs/src/snap/tutorial/index.md | 4 +- docs/src/snap/tutorial/kubectl.md | 6 +- docs/tools/conf.py | 10 + docs/tools/reuse/substitutions.yaml | 4 + 91 files changed, 1637 insertions(+), 198 deletions(-) create mode 100644 .github/workflows/automatic-doc-checks.yml create mode 120000 .wokeignore create mode 100644 docs/moonray/.custom_wordlist.txt create mode 100644 docs/moonray/.gitignore create mode 100644 docs/moonray/.readthedocs.yaml create mode 100644 docs/moonray/.sphinx/.wordlist.txt create mode 100644 docs/moonray/.sphinx/_static/favicon.png create mode 100644 docs/moonray/.sphinx/_static/tag.png create mode 100644 docs/moonray/.sphinx/_templates/header.html create mode 100644 docs/moonray/.sphinx/get_vale_conf.py create mode 100644 docs/moonray/.sphinx/pa11y.json create mode 100644 docs/moonray/.sphinx/requirements.txt create mode 100644 docs/moonray/.sphinx/spellingcheck.yaml create mode 100644 docs/moonray/.wokeignore create mode 100644 docs/moonray/Makefile create mode 100644 docs/moonray/Makefile.sp create mode 100644 docs/moonray/_parts/test.md create mode 100644 docs/moonray/conf.py create mode 100644 docs/moonray/doc-cheat-sheet-myst.md create mode 100644 docs/moonray/doc-cheat-sheet.rst create mode 100644 docs/moonray/explanation/about.md create mode 100644 docs/moonray/explanation/index.md create mode 100644 docs/moonray/howto/index.md create mode 100644 docs/moonray/howto/install.md create mode 100644 docs/moonray/index.md create mode 100644 docs/moonray/make.bat create mode 100644 docs/moonray/reference/index.md create mode 100644 docs/moonray/reference/test.md create mode 100644 docs/moonray/reuse/links.txt create mode 100644 docs/moonray/reuse/substitutions.yaml create mode 100644 docs/moonray/tutorial/index.md create mode 100644 docs/tools/reuse/substitutions.yaml diff --git a/.github/workflows/automatic-doc-checks.yml b/.github/workflows/automatic-doc-checks.yml new file mode 100644 index 000000000..5472b1662 --- /dev/null +++ b/.github/workflows/automatic-doc-checks.yml @@ -0,0 +1,15 @@ +name: Core Documentation Checks + +on: + - workflow_dispatch + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + documentation-checks: + uses: canonical/documentation-workflows/.github/workflows/documentation-checks.yaml@main + with: + working-directory: 'docs/moonray' + diff --git a/.wokeignore b/.wokeignore new file mode 120000 index 000000000..a7dd62476 --- /dev/null +++ b/.wokeignore @@ -0,0 +1 @@ +docs/moonray/.wokeignore \ No newline at end of file diff --git a/docs/moonray/.custom_wordlist.txt b/docs/moonray/.custom_wordlist.txt new file mode 100644 index 000000000..e69de29bb diff --git a/docs/moonray/.gitignore b/docs/moonray/.gitignore new file mode 100644 index 000000000..149ab4937 --- /dev/null +++ b/docs/moonray/.gitignore @@ -0,0 +1,14 @@ +/*env*/ +.sphinx/venv/ +.sphinx/warnings.txt +.sphinx/.wordlist.dic +.sphinx/.doctrees/ +.sphinx/node_modules/ +package*.json +_build +.DS_Store +__pycache__ +.idea/ +.vscode/ +.sphinx/styles/* +.sphinx/vale.ini diff --git a/docs/moonray/.readthedocs.yaml b/docs/moonray/.readthedocs.yaml new file mode 100644 index 000000000..a3d34d2b6 --- /dev/null +++ b/docs/moonray/.readthedocs.yaml @@ -0,0 +1,30 @@ +# .readthedocs.yaml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Set the version of Python and other tools you might need +build: + os: ubuntu-22.04 + tools: + python: "3.11" + jobs: + pre_install: + - git fetch --unshallow || true + +# Build documentation in the docs/ directory with Sphinx +sphinx: + builder: dirhtml + configuration: docs/moonray/conf.py + fail_on_warning: false + +# If using Sphinx, optionally build your docs in additional formats such as PDF +formats: + - pdf + +# Optionally declare the Python requirements required to build your docs +python: + install: + - requirements: docs/moonray/.sphinx/requirements.txt diff --git a/docs/moonray/.sphinx/.wordlist.txt b/docs/moonray/.sphinx/.wordlist.txt new file mode 100644 index 000000000..fb4137d3b --- /dev/null +++ b/docs/moonray/.sphinx/.wordlist.txt @@ -0,0 +1,61 @@ +# This wordlist is from the Sphinx starter pack and should not be +# modified. Add any custom terms to .custom_wordlist.txt instead. + +addons +API +APIs +balancer +Charmhub +CLI +Diátaxis +dropdown +EBS +EKS +enablement +favicon +Furo +Git +GitHub +Grafana +IAM +installable +JSON +Juju +Kubeflow +Kubernetes +Launchpad +linter +LTS +LXD +Makefile +Makefiles +Matrix +Mattermost +MicroCeph +MicroCloud +MicroOVN +MyST +namespace +namespaces +NodePort +Numbat +observability +OEM +OLM +Permalink +pre +Quickstart +ReadMe +reST +reStructuredText +roadmap +RTD +subdirectories +subfolders +subtree +Ubuntu +UI +UUID +VM +webhook +YAML diff --git a/docs/moonray/.sphinx/_static/favicon.png b/docs/moonray/.sphinx/_static/favicon.png new file mode 100644 index 0000000000000000000000000000000000000000..7f175e4617695f752022d2671a0f97fa95bfd895 GIT binary patch literal 2258 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 literal 0 HcmV?d00001 diff --git a/docs/moonray/.sphinx/_static/tag.png b/docs/moonray/.sphinx/_static/tag.png new file mode 100644 index 0000000000000000000000000000000000000000..f6f6e5aa4bc55fb934c973726b10a0efc92445a8 GIT binary patch literal 6781 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 literal 0 HcmV?d00001 diff --git a/docs/moonray/.sphinx/_templates/header.html b/docs/moonray/.sphinx/_templates/header.html new file mode 100644 index 000000000..1a128b6f8 --- /dev/null +++ b/docs/moonray/.sphinx/_templates/header.html @@ -0,0 +1,36 @@ + diff --git a/docs/moonray/.sphinx/get_vale_conf.py b/docs/moonray/.sphinx/get_vale_conf.py new file mode 100644 index 000000000..e95294868 --- /dev/null +++ b/docs/moonray/.sphinx/get_vale_conf.py @@ -0,0 +1,29 @@ +#! /usr/bin/env python + +import requests +import os + +DIR=os.getcwd() + +def main(): + + if os.path.exists(f"{DIR}/.sphinx/styles/Canonical"): + print("Vale directory exists") + else: + os.makedirs(f"{DIR}/.sphinx/styles/Canonical") + + url = "https://api.github.com/repos/canonical/praecepta/contents/styles/Canonical" + r = requests.get(url) + for item in r.json(): + download = requests.get(item["download_url"]) + file = open(".sphinx/styles/Canonical/" + item["name"], "w") + file.write(download.text) + file.close() + + config = requests.get("https://raw.githubusercontent.com/canonical/praecepta/main/vale.ini") + file = open(".sphinx/vale.ini", "w") + file.write(config.text) + file.close() + +if __name__ == "__main__": + main() diff --git a/docs/moonray/.sphinx/pa11y.json b/docs/moonray/.sphinx/pa11y.json new file mode 100644 index 000000000..04dc1e1c5 --- /dev/null +++ b/docs/moonray/.sphinx/pa11y.json @@ -0,0 +1,9 @@ +{ + "chromeLaunchConfig": { + "args": [ + "--no-sandbox" + ] + }, + "reporter": "cli", + "standard": "WCAG2AA" +} diff --git a/docs/moonray/.sphinx/requirements.txt b/docs/moonray/.sphinx/requirements.txt new file mode 100644 index 000000000..c019f178a --- /dev/null +++ b/docs/moonray/.sphinx/requirements.txt @@ -0,0 +1,2 @@ +git+https://github.com/canonical/canonical-sphinx@main#egg=canonical-sphinx +sphinx-autobuild diff --git a/docs/moonray/.sphinx/spellingcheck.yaml b/docs/moonray/.sphinx/spellingcheck.yaml new file mode 100644 index 000000000..5f3dbad35 --- /dev/null +++ b/docs/moonray/.sphinx/spellingcheck.yaml @@ -0,0 +1,30 @@ +matrix: +- name: rST files + aspell: + lang: en + d: en_GB + dictionary: + wordlists: + - .sphinx/.wordlist.txt + - .custom_wordlist.txt + output: .sphinx/.wordlist.dic + sources: + - _build/**/*.html + pipeline: + - pyspelling.filters.html: + comments: false + attributes: + - title + - alt + ignores: + - code + - pre + - spellexception + - link + - title + - div.relatedlinks + - strong.command + - div.visually-hidden + - img + - a.p-navigation__link + - a.contributor diff --git a/docs/moonray/.wokeignore b/docs/moonray/.wokeignore new file mode 100644 index 000000000..c64a60376 --- /dev/null +++ b/docs/moonray/.wokeignore @@ -0,0 +1,4 @@ +# the cheat sheets contain a link to a repository with a block word which we +# cannot avoid for now, ie +# https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html +doc-cheat-sheet* diff --git a/docs/moonray/Makefile b/docs/moonray/Makefile new file mode 100644 index 000000000..a861ba84a --- /dev/null +++ b/docs/moonray/Makefile @@ -0,0 +1,30 @@ +# This Makefile stub allows you to customize starter pack (SP) targets. +# Consider this file as a bridge between your project +# and the starter pack's predefined targets that reside in Makefile.sp. +# +# You can add your own, non-SP targets here or override SP targets +# to fit your project's needs. For example, you can define and use targets +# named "install" or "run", but continue to use SP targets like "sp-install" +# or "sp-run" when working on the documentation. + +# Put it first so that "make" without argument is like "make help". +help: + @echo "\n" \ + "------------------------------------------------------------- \n" \ + "* watch, build and serve the documentation: make run \n" \ + "* only build: make html \n" \ + "* only serve: make serve \n" \ + "* clean built doc files: make clean-doc \n" \ + "* clean full environment: make clean \n" \ + "* check links: make linkcheck \n" \ + "* check spelling: make spelling \n" \ + "* check spelling (without building again): make spellcheck \n" \ + "* check inclusive language: make woke \n" \ + "* check accessibility: make pa11y \n" \ + "* check style guide compliance: make vale \n" \ + "* check style guide compliance on target: make vale TARGET=* \n" \ + "* other possible targets: make \n" \ + "------------------------------------------------------------- \n" + +%: + $(MAKE) -f Makefile.sp sp-$@ diff --git a/docs/moonray/Makefile.sp b/docs/moonray/Makefile.sp new file mode 100644 index 000000000..a7f4a7121 --- /dev/null +++ b/docs/moonray/Makefile.sp @@ -0,0 +1,110 @@ +# Minimal makefile for Sphinx documentation +# +# `Makefile.sp` is from the Sphinx starter pack and should not be +# modified. +# Add your customisation to `Makefile` instead. + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXDIR = .sphinx +SPHINXOPTS ?= -c . -d $(SPHINXDIR)/.doctrees +SPHINXBUILD ?= $(VENVDIR)/bin/sphinx-build +SOURCEDIR = . +BUILDDIR = _build +VENVDIR = $(SPHINXDIR)/venv +PA11Y = $(SPHINXDIR)/node_modules/pa11y/bin/pa11y.js --config $(SPHINXDIR)/pa11y.json +VENV = $(VENVDIR)/bin/activate +TARGET = * +ALLFILES = *.rst **/*.rst + +.PHONY: sp-full-help sp-woke-install sp-pa11y-install sp-install sp-run sp-html \ + sp-epub sp-serve sp-clean sp-clean-doc sp-spelling sp-spellcheck sp-linkcheck sp-woke \ + sp-pa11y Makefile.sp sp-vale + +sp-full-help: $(VENVDIR) + @. $(VENV); $(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + @echo "\n\033[1;31mNOTE: This help texts shows unsupported targets!\033[0m" + @echo "Run 'make help' to see supported targets." + +# If requirements are updated, venv should be rebuilt and timestamped. +$(VENVDIR): + python3 -c "import venv" || \ + (echo "You must install python3-venv before you can build the documentation."; exit 1) + @echo "... setting up virtualenv" + python3 -m venv $(VENVDIR) + . $(VENV); pip install --require-virtualenv \ + --upgrade -r $(SPHINXDIR)/requirements.txt \ + --log $(VENVDIR)/pip_install.log + @test ! -f $(VENVDIR)/pip_list.txt || \ + mv $(VENVDIR)/pip_list.txt $(VENVDIR)/pip_list.txt.bak + @. $(VENV); pip list --local --format=freeze > $(VENVDIR)/pip_list.txt + @touch $(VENVDIR) + +sp-woke-install: + @type woke >/dev/null 2>&1 || \ + { echo "Installing \"woke\" snap... \n"; sudo snap install woke; } + +sp-pa11y-install: + @type $(PA11Y) >/dev/null 2>&1 || { \ + echo "Installing \"pa11y\" from npm... \n"; \ + mkdir -p $(SPHINXDIR)/node_modules/ ; \ + npm install --prefix $(SPHINXDIR) pa11y; \ + } + +sp-install: $(VENVDIR) + +sp-run: sp-install + . $(VENV); $(VENVDIR)/bin/sphinx-autobuild -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) + +# Doesn't depend on $(BUILDDIR) to rebuild properly at every run. +sp-html: sp-install + . $(VENV); $(SPHINXBUILD) -W --keep-going -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" -w $(SPHINXDIR)/warnings.txt $(SPHINXOPTS) + +sp-epub: sp-install + . $(VENV); $(SPHINXBUILD) -b epub "$(SOURCEDIR)" "$(BUILDDIR)" -w $(SPHINXDIR)/warnings.txt $(SPHINXOPTS) + +sp-serve: sp-html + cd "$(BUILDDIR)"; python3 -m http.server --bind 127.0.0.1 8000 + +sp-clean: sp-clean-doc + @test ! -e "$(VENVDIR)" -o -d "$(VENVDIR)" -a "$(abspath $(VENVDIR))" != "$(VENVDIR)" + rm -rf $(VENVDIR) + rm -rf $(SPHINXDIR)/node_modules/ + rm -rf $(SPHINXDIR)/styles + rm -rf $(SPHINXDIR)/vale.ini + +sp-clean-doc: + git clean -fx "$(BUILDDIR)" + rm -rf $(SPHINXDIR)/.doctrees + +sp-spellcheck: + . $(VENV) ; python3 -m pyspelling -c $(SPHINXDIR)/spellingcheck.yaml -j $(shell nproc) + +sp-spelling: sp-html sp-spellcheck + +sp-linkcheck: sp-install + . $(VENV) ; $(SPHINXBUILD) -b linkcheck "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) || { grep --color -F "[broken]" "$(BUILDDIR)/output.txt"; exit 1; } + exit 0 + +sp-woke: sp-woke-install + woke $(ALLFILES) --exit-1-on-failure \ + -c https://github.com/canonical/Inclusive-naming/raw/main/config.yml + +sp-pa11y: sp-pa11y-install sp-html + find $(BUILDDIR) -name *.html -print0 | xargs -n 1 -0 $(PA11Y) + +sp-vale: sp-install + @. $(VENV); test -d $(SPHINXDIR)/venv/lib/python*/site-packages/vale || pip install vale + @. $(VENV); test -f $(SPHINXDIR)/vale.ini || python3 $(SPHINXDIR)/get_vale_conf.py + @. $(VENV); find $(SPHINXDIR)/venv/lib/python*/site-packages/vale/vale_bin -size 195c -exec vale --config "$(SPHINXDIR)/vale.ini" $(TARGET) > /dev/null \; + @echo "" + @echo "Running Vale against $(TARGET). To change target set TARGET= with make command" + @echo "" + @. $(VENV); vale --config "$(SPHINXDIR)/vale.ini" --glob='*.{md,txt,rst}' $(TARGET) + + + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile.sp + . $(VENV); $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/moonray/_parts/test.md b/docs/moonray/_parts/test.md new file mode 100644 index 000000000..788be2534 --- /dev/null +++ b/docs/moonray/_parts/test.md @@ -0,0 +1,3 @@ +# Test file for inclusion + +This is a test for the {{product}} documentation set \ No newline at end of file diff --git a/docs/moonray/conf.py b/docs/moonray/conf.py new file mode 100644 index 000000000..f9836e3a3 --- /dev/null +++ b/docs/moonray/conf.py @@ -0,0 +1,227 @@ +import datetime +import os +import yaml + +# Configuration for the Sphinx documentation builder. +# All configuration specific to your project should be done in this file. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html +# For our custom configuration, see the Canonical Sphinx extension: +# https://github.com/canonical/canonical-sphinx +# +# If you're not familiar with Sphinx and don't want to use advanced +# features, it is sufficient to update the settings in the "Project +# information" section. + +############################################################ +### Project information +############################################################ + +# Product name +project = 'Moonray' +author = 'Canonical Ltd.' + +# The title you want to display for the documentation in the sidebar. +# You might want to include a version number here. +# To not display any title, set this option to an empty string. +html_title = project + ' documentation' + +# The default value uses CC-BY-SA as the license and the current year +# as the copyright year. +# +# If your documentation needs a different copyright license, use that +# instead of 'CC-BY-SA'. Also, if your documentation is included as +# part of the code repository of your project, it'll inherit the license +# of the code. So you'll need to specify that license here (instead of +# 'CC-BY-SA'). +# +# For static works, it is common to provide the year of first publication. +# Another option is to give the first year and the current year +# for documentation that is often changed, e.g. 2022–2023 (note the en-dash). +# +# A way to check a GitHub repo's creation date is to obtain a classic GitHub +# token with 'repo' permissions here: https://github.com/settings/tokens +# Next, use 'curl' and 'jq' to extract the date from the GitHub API's output: +# +# curl -H 'Authorization: token ' \ +# -H 'Accept: application/vnd.github.v3.raw' \ +# https://api.github.com/repos/canonical/ | jq '.created_at' + +copyright = '%s CC-BY-SA, %s' % (datetime.date.today().year, author) + +## Open Graph configuration - defines what is displayed as a link preview +## when linking to the documentation from another website (see https://ogp.me/) +# The URL where the documentation will be hosted (leave empty if you +# don't know yet) +ogp_site_url = 'https://canonical-starter-pack.readthedocs-hosted.com/' +# The documentation website name (usually the same as the product name) +ogp_site_name = project +# The URL of an image or logo that is used in the preview +ogp_image = 'https://assets.ubuntu.com/v1/253da317-image-document-ubuntudocs.svg' + +# Update with the local path to the favicon for your product +# (default is the circle of friends) +# html_favicon = '.sphinx/_static/favicon.png' + +# (Some settings must be part of the html_context dictionary, while others +# are on root level. Don't move the settings.) +html_context = { + + # Change to the link to the website of your product (without "https://") + # For example: "ubuntu.com/lxd" or "microcloud.is" + # If there is no product website, edit the header template to remove the + # link (see the readme for instructions). + 'product_page': 'documentation.ubuntu.com', + + # Add your product tag (the orange part of your logo, will be used in the + # header) to ".sphinx/_static" and change the path here (start with "_static") + # (default is the circle of friends) + # 'product_tag': '_static/tag.png', + + # Change to the discourse instance you want to be able to link to + # using the :discourse: metadata at the top of a file + # (use an empty value if you don't want to link) + 'discourse': 'https://discourse.ubuntu.com', + + # Change to the Mattermost channel you want to link to + # (use an empty value if you don't want to link) + 'mattermost': 'https://chat.canonical.com/canonical/channels/documentation', + + # Change to the Matrix channel you want to link to + # (use an empty value if you don't want to link) + 'matrix': 'https://matrix.to/#/#documentation:ubuntu.com', + + # Change to the GitHub URL for your project + # This is used, for example, to link to the source files and allow creating GitHub issues directly from the documentation. + 'github_url': 'https://github.com/canonical/sphinx-docs-starter-pack', + + # Change to the branch for this version of the documentation + # 'github_version': 'main', + + # Change to the folder that contains the documentation + # (usually "/" or "/docs/") + 'github_folder': '/docs/moonray/', + + # Change to an empty value if your GitHub repo doesn't have issues enabled. + # This will disable the feedback button and the issue link in the footer. + # 'github_issues': 'enabled', + + # Controls the existence of Previous / Next buttons at the bottom of pages + # Valid options: none, prev, next, both + # 'sequential_nav': "none", + + # Uncomment to disable displaying the contributors for each file. + # (You can also limit the time frame for displaying contributors + # by setting a "display_contributors_since" variable.) + # "display_contributors": False, + +} + +# If your project is on documentation.ubuntu.com, specify the project +# slug (for example, "lxd") here. +# slug = "" + +# These paths are needed if you want to override any default assets. +# You can comment them out if you don't need this (but you can also just +# leave them). + +html_static_path = ['.sphinx/_static'] +templates_path = ['.sphinx/_templates'] + +############################################################ +### Redirects +############################################################ + +# Set up redirects (https://documatt.gitlab.io/sphinx-reredirects/usage.html) +# For example: 'explanation/old-name.html': '../how-to/prettify.html', +# You can also configure redirects in the Read the Docs project dashboard +# (see https://docs.readthedocs.io/en/stable/guides/redirects.html). +# NOTE: If this variable is not defined, set to None, or the dictionary is empty, +# the sphinx_reredirects extension will be disabled. +redirects = {} + +############################################################ +### Link checker exceptions +############################################################ + +# Links to ignore when checking links +linkcheck_ignore = [ + 'http://127.0.0.1:8000' + ] + +# Pages on which to ignore anchors +# (This list will be appended to linkcheck_anchors_ignore_for_url) +linkcheck_anchors_ignore_for_url = [ + r'https://github\.com/.*' +] + +############################################################ +### Additions to default configuration +############################################################ + +## The following settings are appended to the default configuration. +## Use them to extend the default functionality. + +# By default, the following MyST extensions are enabled: +# substitution, deflist, linkify +# If you need more extensions, add them here. +# myst_enable_extensions = set() + +# You must include the canonical_sphinx extension here. +# This extension automatically enables the following Sphinx extensions: +# custom-rst-roles, myst_parser, notfound.extension, related-links, +# sphinx_copybutton, sphinx_design, sphinx_tabs.tabs, +# sphinx_reredirects, sphinxcontrib.jquery, sphinxext.opengraph, +# terminal-output, youtube-links +# If you need more extensions, add them here (in addition to +# canonical_sphinx). +extensions = [ + 'canonical_sphinx' + ] + +# Add files or directories that should be excluded from processing. +exclude_patterns = [ + 'doc-cheat-sheet*', + ] + +# Add custom CSS files (located in .sphinx/_static/) +# html_css_files = [] + +# Add custom JavaScript files (located in .sphinx/_static/) +# html_js_files = [] + +## The following settings override the default configuration. + +# Specify a reST string that is included at the end of each file. +# The suggested value pulls the reuse/links.txt file into each reST file. +rst_epilog = ''' +.. include:: /reuse/links.txt +''' + +# By default, the documentation includes a feedback button at the top. +# You can disable it by setting the following configuration to True. +# disable_feedback_button = False + +# If you are using the :manpage: role, set this variable to the URL for the version +# that you want to link to: +# manpages_url = "https://manpages.ubuntu.com/manpages/noble/en/man{section}/{page}.{section}.html" + +############################################################ +### Additional configuration +############################################################ + +## Add any configuration that is not covered by the common conf.py file. + +# Define a :center: role that can be used to center the content of table cells. +rst_prolog = ''' +.. role:: center + :class: align-center +''' + +############################################################ +### Myst configuration +############################################################ +if os.path.exists('./reuse/substitutions.yaml'): + with open('./reuse/substitutions.yaml', 'r') as fd: + myst_substitutions = yaml.safe_load(fd.read()) diff --git a/docs/moonray/doc-cheat-sheet-myst.md b/docs/moonray/doc-cheat-sheet-myst.md new file mode 100644 index 000000000..6257c9db0 --- /dev/null +++ b/docs/moonray/doc-cheat-sheet-myst.md @@ -0,0 +1,261 @@ +--- +orphan: true +myst: + substitutions: + reuse_key: "This is **included** text." + advanced_reuse_key: "This is a substitution that includes a code block: + ``` + code block + ```" +--- + + + +(cheat-sheet-myst)= +# Markdown/MyST cheat sheet + + + +This file contains the syntax for commonly used Markdown and MyST markup. +Open it in your text editor to quickly copy and paste the markup you need. + +See the [MyST style guide](https://canonical-documentation-with-sphinx-and-readthedocscom.readthedocs-hosted.com/style-guide-myst/) for detailed information and conventions. + +Also see the [MyST documentation](https://myst-parser.readthedocs.io/en/latest/index.html) for detailed information on MyST, and the [Canonical Documentation Style Guide](https://docs.ubuntu.com/styleguide/en) for general style conventions. + +## H2 heading + +### H3 heading + +#### H4 heading + +##### H5 heading + +## Inline formatting + +- {guilabel}`UI element` +- `code` +- {command}`command` +- {kbd}`Key` +- *Italic* +- **Bold** + +## Code blocks + +Start a code block: + + code: + - example: true + +``` +# Demonstrate a code block +code: + - example: true +``` + +```yaml +# Demonstrate a code block +code: + - example: true +``` + +(a_section_target_myst)= +## Links + +- [Canonical website](https://canonical.com/) +- {ref}`a_section_target_myst` +- {ref}`Link text ` +- {doc}`index` +- {doc}`Link text ` + +## Navigation + +Use the following syntax:: + + ```{toctree} + :hidden: + + sub-page1 + sub-page2 + ``` + +## Lists + +1. Step 1 + - Item 1 + * Sub-item + - Item 2 + 1. Sub-step 1 + 1. Sub-step 2 +1. Step 2 + 1. Sub-step 1 + - Item + 1. Sub-step 2 + +Term 1 +: Definition + +Term 2 +: Definition + +## Tables + +## Markdown tables + +| Header 1 | Header 2 | +|------------------------------------|----------| +| Cell 1
Second paragraph | Cell 2 | +| Cell 3 | Cell 4 | + +Centred: + +| Header 1 | Header 2 | +|:----------------------------------:|:--------:| +| Cell 1
Second paragraph | Cell 2 | +| Cell 3 | Cell 4 | + +## List tables + +```{list-table} + :header-rows: 1 + +* - Header 1 + - Header 2 +* - Cell 1 + + Second paragraph + - Cell 2 +* - Cell 3 + - Cell 4 +``` + +Centred: + +```{list-table} + :header-rows: 1 + :align: center + +* - Header 1 + - Header 2 +* - Cell 1 + + Second paragraph + - Cell 2 +* - Cell 3 + - Cell 4 +``` + +## Notes + +```{note} +A note. +``` + +```{tip} +A tip. +``` + +```{important} +Important information +``` + +```{caution} +This might damage your hardware! +``` + +## Images + +![Alt text](https://assets.ubuntu.com/v1/b3b72cb2-canonical-logo-166.png) + +```{figure} https://assets.ubuntu.com/v1/b3b72cb2-canonical-logo-166.png + :width: 100px + :alt: Alt text + + Figure caption +``` + +## Reuse + +### Keys + +Keys can be defined at the top of a file, or in a `myst_substitutions` option in `conf.py`. + +{{reuse_key}} + +{{advanced_reuse_key}} + +### File inclusion + +```{include} index.md + :start-after: include_start + :end-before: include_end +``` + +## Tabs + +````{tabs} +```{group-tab} Tab 1 + +Content Tab 1 +``` + +```{group-tab} Tab 2 +Content Tab 2 +``` +```` + +## Glossary + +```{glossary} + +some term + Definition of the example term. +``` + +{term}`some term` + +## More useful markup + +- ```{versionadded} X.Y +- {abbr}`API (Application Programming Interface)` + +---- + +## Custom extensions + +Related links at the top of the page (surrounded by `---`): + + relatedlinks: https://github.com/canonical/lxd-sphinx-extensions, [RTFM](https://www.google.com) + discourse: 12345 + +Terms that should not be checked by the spelling checker: {spellexception}`PurposelyWrong` + +A single-line terminal view that separates input from output: + +```{terminal} + :input: command + :user: root + :host: vampyr + :dir: /home/user/directory/ + +the output +``` + +A multi-line version of the same: + +```{terminal} + :user: root + :host: vampyr + :dir: /home/user/directory/ + +:input: command 1 +output 1 +:input: command 2 +output 2 +``` + +A link to a YouTube video: + +```{youtube} https://www.youtube.com/watch?v=iMLiK1fX4I0 + :title: Demo +``` diff --git a/docs/moonray/doc-cheat-sheet.rst b/docs/moonray/doc-cheat-sheet.rst new file mode 100644 index 000000000..ca3fd0622 --- /dev/null +++ b/docs/moonray/doc-cheat-sheet.rst @@ -0,0 +1,285 @@ +:orphan: + +.. vale off + +.. _cheat-sheet: + +ReStructuredText cheat sheet +============================ + +.. vale on + +This file contains the syntax for commonly used reST markup. +Open it in your text editor to quickly copy and paste the markup you need. + +See the `reStructuredText style guide `_ for detailed information and conventions. + +Also see the `Sphinx reStructuredText Primer `_ for more details on reST, and the `Canonical Documentation Style Guide `_ for general style conventions. + +H2 heading +---------- + +H3 heading +~~~~~~~~~~ + +H4 heading +^^^^^^^^^^ + +H5 heading +.......... + +Inline formatting +----------------- + +- :guilabel:`UI element` +- ``code`` +- :file:`file path` +- :command:`command` +- :kbd:`Key` +- *Italic* +- **Bold** + +Code blocks +----------- + +Start a code block:: + + code: + - example: true + +.. code:: + + # Demonstrate a code block + code: + - example: true + +.. code:: yaml + + # Demonstrate a code block + code: + - example: true + +.. _a_section_target: + +Links +----- + +- `Canonical website `_ +- `Canonical website`_ (defined in ``reuse/links.txt`` or at the bottom of the page) +- https:\ //canonical.com/ +- :ref:`a_section_target` +- :ref:`Link text ` +- :doc:`index` +- :doc:`Link text ` + + +Navigation +---------- + +Use the following syntax:: + + .. toctree:: + :hidden: + + sub-page1 + sub-page2 + + +Lists +----- + +1. Step 1 + + - Item 1 + + * Sub-item + - Item 2 + + i. Sub-step 1 + #. Sub-step 2 +#. Step 2 + + a. Sub-step 1 + + - Item + #. Sub-step 2 + +Term 1: + Definition +Term 2: + Definition + +Tables +------ + ++----------------------+------------+ +| Header 1 | Header 2 | ++======================+============+ +| Cell 1 | Cell 2 | +| | | +| Second paragraph | | ++----------------------+------------+ +| Cell 3 | Cell 4 | ++----------------------+------------+ + ++----------------------+------------------+ +| :center:`Header 1` | Header 2 | ++======================+==================+ +| Cell 1 | Cell 2 | +| | | +| Second paragraph | | ++----------------------+------------------+ +| Cell 3 | :center:`Cell 4` | ++----------------------+------------------+ + +.. list-table:: + :header-rows: 1 + + * - Header 1 + - Header 2 + * - Cell 1 + + Second paragraph + - Cell 2 + * - Cell 3 + - Cell 4 + +.. rst-class:: align-center + + +----------------------+------------+ + | Header 1 | Header 2 | + +======================+============+ + | Cell 1 | Cell 2 | + | | | + | Second paragraph | | + +----------------------+------------+ + | Cell 3 | Cell 4 | + +----------------------+------------+ + +.. list-table:: + :header-rows: 1 + :align: center + + * - Header 1 + - Header 2 + * - Cell 1 + + Second paragraph + - Cell 2 + * - Cell 3 + - Cell 4 + +Notes +----- + +.. note:: + A note. + +.. tip:: + A tip. + +.. important:: + Important information + +.. caution:: + This might damage your hardware! + +Images +------ + +.. image:: https://assets.ubuntu.com/v1/b3b72cb2-canonical-logo-166.png + +.. figure:: https://assets.ubuntu.com/v1/b3b72cb2-canonical-logo-166.png + :width: 100px + :alt: Alt text + + Figure caption + +Reuse +----- + +.. |reuse_key| replace:: This is **included** text. + +|reuse_key| + +.. include:: index.rst + :start-after: include_start + :end-before: include_end + +Tabs +---- + +.. tabs:: + + .. group-tab:: Tab 1 + + Content Tab 1 + + .. group-tab:: Tab 2 + + Content Tab 2 + + +Glossary +-------- + +.. glossary:: + + example term + Definition of the example term. + +:term:`example term` + +More useful markup +------------------ + +- .. versionadded:: X.Y +- | Line 1 + | Line 2 + | Line 3 +- .. This is a comment +- :abbr:`API (Application Programming Interface)` + +---- + +Custom extensions +----------------- + +Related links at the top of the page:: + + :relatedlinks: https://github.com/canonical/lxd-sphinx-extensions, [RTFM](https://www.google.com) + :discourse: 12345 + +Terms that should not be checked by the spelling checker: :spellexception:`PurposelyWrong` + +A single-line terminal view that separates input from output: + +.. terminal:: + :input: command + :user: root + :host: vampyr + :dir: /home/user/directory/ + + the output + +A multi-line version of the same: + +.. terminal:: + :user: root + :host: vampyr + :dir: /home/user/directory/ + + :input: command 1 + output 1 + :input: command 2 + output 2 + +A link to a YouTube video: + +.. youtube:: https://www.youtube.com/watch?v=iMLiK1fX4I0 + :title: Demo + + + +.. LINKS +.. _Canonical website: https://canonical.com/ diff --git a/docs/moonray/explanation/about.md b/docs/moonray/explanation/about.md new file mode 100644 index 000000000..44f93df2c --- /dev/null +++ b/docs/moonray/explanation/about.md @@ -0,0 +1,12 @@ +# What is {{product}}? + +At its core, {{product}} is a full implementation of upstream +[Kubernetes][] delivered in a compact, secure, reliable [snap][] package. As the +upstream Kubernetes services are not all that is required for a fully +functional cluster, additional services and features are built in. You can +deploy the snap and have a single-node cluster up and running in minutes. + + + +[Kubernetes]: https://kubernetes.io/ +[snap]: https://snapcraft.io/docs \ No newline at end of file diff --git a/docs/moonray/explanation/index.md b/docs/moonray/explanation/index.md new file mode 100644 index 000000000..833b6a071 --- /dev/null +++ b/docs/moonray/explanation/index.md @@ -0,0 +1,36 @@ +# Explanation + +For a better understanding of how {{product}} works and related +topics such as security, these pages will help expand your knowledge and +get the most out of Kubernetes. + +```{toctree} +:hidden: +Overview +``` + +```{toctree} +:titlesonly: +about +``` + +--- + +## Other documentation types + +If you are just getting started, the [Tutorials section] contains +step-by-step tutorials to help guide you through exploring and using +{{product}}. + +If you have a specific goal our [How-to guides] have more in-depth +detail than tutorials and can be applied to a broader set of applications. +They’ll help you achieve an end-result but may require you to understand and +adapt the steps to fit your specific requirements. + +Finally, our [Reference section] is for when you need to check specific +details or information such as the command reference or release notes. + + +[Tutorials section]: ../tutorial/index +[How-to guides]: ../howto/index +[Reference section]: ../reference/index diff --git a/docs/moonray/howto/index.md b/docs/moonray/howto/index.md new file mode 100644 index 000000000..041e13e6c --- /dev/null +++ b/docs/moonray/howto/index.md @@ -0,0 +1,40 @@ +# How-to guides + +If you have a specific goal, but are already familiar with Kubernetes, our +How-to guides are more specific and contain less background information. +They’ll help you achieve an end result but may require you to understand and +adapt the steps to fit your specific requirements. + +```{toctree} +:hidden: +Overview +``` + +```{toctree} +:glob: +:titlesonly: +install + +``` + +--- + +## Other documentation types + +Our Reference section is for when you need to check specific details or +information such as the command reference or release notes. + +Alternatively, the [Tutorials section] contains step-by-step tutorials to help +guide you through exploring and using Canonical Kubernetes. + +For a better understanding of how {{product}} works and related topics +such as security, our [Explanation section] helps you expand your knowledge +and get the most out of Kubernetes. + +Finally, our [Reference section] is for when you need to check specific details +or information such as the command reference or release notes. + + +[Tutorials section]: ../tutorial/index +[Explanation section]: ../explanation/index +[Reference section]: ../reference/index diff --git a/docs/moonray/howto/install.md b/docs/moonray/howto/install.md new file mode 100644 index 000000000..df8040541 --- /dev/null +++ b/docs/moonray/howto/install.md @@ -0,0 +1,5 @@ +```{include} ../../src/snap/howto/install/snap.md + +``` + + diff --git a/docs/moonray/index.md b/docs/moonray/index.md new file mode 100644 index 000000000..9d3278ce8 --- /dev/null +++ b/docs/moonray/index.md @@ -0,0 +1,74 @@ +# {{product}} documentation + +{{product}} is a performant, lightweight, secure and +opinionated distribution of **Kubernetes** which includes everything needed to +create and manage a scalable cluster suitable for all use cases. + +You can find out more about {{product}} on this [overview page] or +see a more detailed explanation in our [architecture documentation]. + +![Illustration depicting working on components and clouds][logo] + +```{toctree} +:hidden: +:titlesonly: +Home +tutorial/index +howto/index +explanation/index +reference/index +``` + + +--- + +## In this documentation + +````{grid} 1 1 2 2 + +```{grid-item-card} [Tutorial](tutorial/index) + +**Start here!** A hands-on introduction to {{product}} for new users +``` + +```{grid-item-card} [How-to guides](howto/index) + +**Step-by-step guides** covering key operations and common tasks +``` + +```` + +````{grid} 1 1 2 2 + + +```{grid-item-card} [Reference](reference/index) + +**Technical information** - specifications, APIs, architecture +``` + +```{grid-item-card} [Explanation](explanation/index) + +**Discussion and clarification** of key topics +``` + +```` + +--- + +## Project and community + +{{product}} is an open source project which welcomes community involvement, +contributions, suggestions, fixes and constructive feedback. + +- Our [Code of Conduct] + + + + +[logo]: https://assets.ubuntu.com/v1/843c77b6-juju-at-a-glace.svg + + + +[Code of Conduct]: https://ubuntu.com/community/ethos/code-of-conduct + + diff --git a/docs/moonray/make.bat b/docs/moonray/make.bat new file mode 100644 index 000000000..32bb24529 --- /dev/null +++ b/docs/moonray/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/moonray/reference/index.md b/docs/moonray/reference/index.md new file mode 100644 index 000000000..e6ea1a4bc --- /dev/null +++ b/docs/moonray/reference/index.md @@ -0,0 +1,34 @@ +# Reference + +Our Reference section is for when you need to check specific details or +information such as the command reference or release notes. + +```{toctree} +:hidden: +Overview +``` + +```{toctree} +:titlesonly: +test + +``` + +## Other documentation types + +Alternatively, the [Tutorials section] contains step-by-step tutorials to help +guide you through exploring and using {{product}}. + +If you have a specific goal our [How-to guides] have more in-depth detail than +tutorials and can be applied to a broader set of applications. They’ll help you +achieve an end-result but may require you to understand and adapt the steps to +fit your specific requirements. + +Finally, for a better understanding of how {{product}} works and +related topics such as security, our [Explanation section] helps you to expand +your knowledge and get the most out of Kubernetes. + + +[Tutorials section]: ../tutorial/index +[How-to guides]: ../howto/index +[Explanation section]: ../explanation/index diff --git a/docs/moonray/reference/test.md b/docs/moonray/reference/test.md new file mode 100644 index 000000000..50a9257a9 --- /dev/null +++ b/docs/moonray/reference/test.md @@ -0,0 +1,3 @@ +```{include} ../_parts/test.md + +``` \ No newline at end of file diff --git a/docs/moonray/reuse/links.txt b/docs/moonray/reuse/links.txt new file mode 100644 index 000000000..f9d3d5cdc --- /dev/null +++ b/docs/moonray/reuse/links.txt @@ -0,0 +1 @@ +.. _link text: https://example.com diff --git a/docs/moonray/reuse/substitutions.yaml b/docs/moonray/reuse/substitutions.yaml new file mode 100644 index 000000000..a0c8eeddd --- /dev/null +++ b/docs/moonray/reuse/substitutions.yaml @@ -0,0 +1,4 @@ +product: 'Moonray' +formatted_text: |- + *Multi-line* text + that uses basic **markup**. diff --git a/docs/moonray/tutorial/index.md b/docs/moonray/tutorial/index.md new file mode 100644 index 000000000..d63865e3b --- /dev/null +++ b/docs/moonray/tutorial/index.md @@ -0,0 +1,36 @@ +# Tutorials + +This section contains a step-by-step guide to help you start exploring how to +install and use {{product}}. + +```{toctree} +:hidden: +Overview +``` + +```{toctree} +:glob: +:titlesonly: + +``` + +--- + +## Other documentation types + +If you have a specific goal our [How-to guides] have more in-depth detail than +tutorials and can be applied to a broader set of applications. They’ll help you +achieve an end-result but may require you to understand and adapt the steps to +fit your specific requirements. + +For a better understanding of how {{product}} works and related topics +such as security, our [Explanation section] helps you to expand your knowledge +and get the most out of Kubernetes. + +Finally, our [Reference section] is for when you need to check specific details +or information such as the command reference or release notes. + + +[How-to guides]: ../howto/index +[Explanation section]: ../explanation/index +[Reference section]: ../reference/index diff --git a/docs/src/capi/explanation/index.md b/docs/src/capi/explanation/index.md index d065c1227..617844bf0 100644 --- a/docs/src/capi/explanation/index.md +++ b/docs/src/capi/explanation/index.md @@ -1,6 +1,6 @@ # Explanation -For a better understanding of how Canonical Kubernetes works and related +For a better understanding of how {{product}} works and related topics such as security, these pages will help expand your knowledge and help you get the most out of Kubernetes. @@ -22,7 +22,7 @@ Overview If you are just getting started, the [Tutorials section] contains step-by-step tutorials to help guide you through exploring and using -Canonical Kubernetes. +{{product}}. If you have a specific goal our [How-to guides] have more in-depth detail than tutorials and can be applied to a broader set of applications. diff --git a/docs/src/capi/howto/index.md b/docs/src/capi/howto/index.md index 1f364b641..3bb592cf4 100644 --- a/docs/src/capi/howto/index.md +++ b/docs/src/capi/howto/index.md @@ -25,9 +25,9 @@ Our Reference section is for when you need to check specific details or information such as the command reference or release notes. Alternatively, the [Tutorials section] contains step-by-step tutorials to help -guide you through exploring and using Canonical Kubernetes. +guide you through exploring and using {{product}}. -For a better understanding of how Canonical Kubernetes works and related topics +For a better understanding of how {{product}} works and related topics such as security, our [Explanation section] helps you expand your knowledge and get the most out of Kubernetes. diff --git a/docs/src/capi/index.md b/docs/src/capi/index.md index 814de5b9f..df4102a01 100644 --- a/docs/src/capi/index.md +++ b/docs/src/capi/index.md @@ -1,8 +1,6 @@ -# Canonical Kubernetes +# Installing {{product}} with Cluster API -XxxxxX XXXxx Xxxxxxxxx xxxxx xxxx xx xxxxxxxx xxxx xxx xxx xxx xxxxxxxxxx xx -xxx xxxxxx xxx XXX. Xxxx x xxxxx xx xxxxx xxxxx Xxxxxxx xx xxxx xxxxxx -xxxxxxxxxxx xxx xxx xx xxxx x xxxxxxx xxx xxxxxxxx. +Cluster API (CAPI) is a Kubernetes project focused on providing declarative APIs and tooling to simplify provisioning, upgrading, and operating multiple Kubernetes clusters. The supporting infrastructure, like virtual machines, networks, load balancers, and VPCs, as well as the cluster configuration are all defined in the same way that cluster operators are already familiar with. {{product}} supports deploying and operating Kubernetes through CAPI. ![Illustration depicting working on components and clouds][logo] @@ -12,7 +10,7 @@ xxxxxxxxxxx xxx xxx xx xxxx x xxxxxxx xxx xxxxxxxx. ```{grid-item-card} [Tutorial](tutorial/index) -**Start here!** A hands-on introduction to Canonical K8s for new users +**Start here!** A hands-on introduction to {{product}} for new users ``` ```{grid-item-card} [How-to guides](howto/index) @@ -41,7 +39,7 @@ xxxxxxxxxxx xxx xxx xx xxxx x xxxxxxx xxx xxxxxxxx. ## Project and community -Canonical Kubernetes is a member of the Ubuntu family. It's an open source +{{product}} is a member of the Ubuntu family. It's an open source project which welcomes community involvement, contributions, suggestions, fixes and constructive feedback. diff --git a/docs/src/capi/reference/index.md b/docs/src/capi/reference/index.md index 7db0080ff..af114b439 100644 --- a/docs/src/capi/reference/index.md +++ b/docs/src/capi/reference/index.md @@ -17,14 +17,14 @@ Overview ## Other documentation types Alternatively, the [Tutorials section] contains step-by-step tutorials to help -guide you through exploring and using Canonical Kubernetes. +guide you through exploring and using {{product}}. If you have a specific goal our [How-to guides] have more in-depth detail than tutorials and can be applied to a broader set of applications. They’ll help you achieve an end-result but may require you to understand and adapt the steps to fit your specific requirements. -Finally, for a better understanding of how Canonical Kubernetes works and +Finally, for a better understanding of how {{product}} works and related topics such as security, our [Explanation section] helps you to expand your knowledge and get the most out of Kubernetes. diff --git a/docs/src/capi/tutorial/getting-started.md b/docs/src/capi/tutorial/getting-started.md index f3f8e4e20..40a4d386f 100644 --- a/docs/src/capi/tutorial/getting-started.md +++ b/docs/src/capi/tutorial/getting-started.md @@ -1,6 +1,6 @@ # Cluster provisioning with CAPI and Canonical K8s -This guide covers how to deploy a Canonical Kubernetes multi-node cluster +This guide covers how to deploy a {{product}} multi-node cluster using Cluster API (CAPI). ## Install `clusterctl` @@ -114,9 +114,9 @@ apply the cluster manifests with the specifications of the cluster you want to provision. You can generate a cluster manifest for a selected set of commonly used -infrastructures via templates provided by the Canonical Kubernetes team. +infrastructures via templates provided by the {{product}} team. Ensure you have initialized the desired infrastructure provider and fetch -the Canonical Kubernetes provider repository: +the {{product}} provider repository: ``` git clone https://github.com/canonical/cluster-api-k8s diff --git a/docs/src/capi/tutorial/index.md b/docs/src/capi/tutorial/index.md index 02352b6dd..17ef956b7 100644 --- a/docs/src/capi/tutorial/index.md +++ b/docs/src/capi/tutorial/index.md @@ -1,7 +1,7 @@ # Tutorials This section contains a step-by-step guide to help you start exploring how to -install and use Canonical Kubernetes. +install and use {{product}}. ```{toctree} :hidden: @@ -23,7 +23,7 @@ tutorials and can be applied to a broader set of applications. They’ll help yo achieve an end-result but may require you to understand and adapt the steps to fit your specific requirements. -For a better understanding of how Canonical Kubernetes works and related topics +For a better understanding of how {{product}} works and related topics such as security, our [Explanation section] helps you to expand your knowledge and get the most out of Kubernetes. diff --git a/docs/src/charm/explanation/about.md b/docs/src/charm/explanation/about.md index db76ad76a..edcfb24e3 100644 --- a/docs/src/charm/explanation/about.md +++ b/docs/src/charm/explanation/about.md @@ -1,5 +1,5 @@ -# What is Canonical Kubernetes? +# What is {{product}}? ```{include} ../../snap/explanation/about.md -:start-after: '# What is Canonical Kubernetes?' +:start-after: '# What is {{product}}?' ``` diff --git a/docs/src/charm/explanation/index.md b/docs/src/charm/explanation/index.md index 85da690d0..58409c598 100644 --- a/docs/src/charm/explanation/index.md +++ b/docs/src/charm/explanation/index.md @@ -1,6 +1,6 @@ # Explanation -For a better understanding of how Canonical Kubernetes works and related +For a better understanding of how {{product}} works and related topics such as security, these pages will help expand your knowledge and help you get the most out of Kubernetes. @@ -16,7 +16,7 @@ channels security ``` -For topics specifically relating to the snap version of Canonical Kubernetes, +For topics specifically relating to the snap version of {{product}}, please see the [explanation topic]. --- @@ -25,7 +25,7 @@ please see the [explanation topic]. If you are just getting started, the [Tutorials section] contains step-by-step tutorials to help guide you through exploring and using -Canonical Kubernetes. +{{product}}. If you have a specific goal our [How-to guides] have more in-depth detail than tutorials and can be applied to a broader set of applications. diff --git a/docs/src/charm/howto/charm.md b/docs/src/charm/howto/charm.md index 953885d77..7e9940b40 100644 --- a/docs/src/charm/howto/charm.md +++ b/docs/src/charm/howto/charm.md @@ -1,6 +1,6 @@ -# Install Canonical Kubernetes from a charm +# Install {{product}} from a charm -Canonical Kubernetes is packaged as a [charm], available from Charmhub for all +{{product}} is packaged as a [charm], available from Charmhub for all supported platforms. ## What you'll need diff --git a/docs/src/charm/howto/contribute.md b/docs/src/charm/howto/contribute.md index 5e3c729e3..eda251301 100644 --- a/docs/src/charm/howto/contribute.md +++ b/docs/src/charm/howto/contribute.md @@ -1,12 +1,12 @@ -# How to contribute to Canonical Kubernetes +# How to contribute to {{product}} -Canonical Kubernetes is proudly open source, published under the GPLv3 license. +{{product}} is proudly open source, published under the GPLv3 license. We welcome and encourage contributions to the code and the documentation. See the [community page][] for ways to get in touch and provide feedback. ## Contribute to the code -Canonical Kubernetes is shipped as a snap package. To contribute to the code, +{{product}} is shipped as a snap package. To contribute to the code, you should first make sure you can build and test the snap locally. ### Build the snap @@ -68,18 +68,18 @@ lxc delete snapcraft-k8s ### Contribute changes -We welcome any improvements and bug-fixes to the Canonical Kubernetes code. +We welcome any improvements and bug-fixes to the {{product}} code. Once you have tested your changes, please make a pull request on the [code repository][code repo] and we will review it as soon as possible. ## Contribute to the documentation Our aim is to provide easy-to-understand documentation on all aspects of -Canonical Kubernetes, so we greatly appreciate your feedback and contributions. +{{product}}, so we greatly appreciate your feedback and contributions. See our [community page][] for ways of getting in touch. The source of the documentation and the system used to build it are included in -the [main repository for the Canonical Kubernetes snap][code repo]. +the [main repository for the {{product}} snap][code repo]. ### Documentation framework diff --git a/docs/src/charm/howto/cos-lite.md b/docs/src/charm/howto/cos-lite.md index ad34bfc62..80efeebe3 100644 --- a/docs/src/charm/howto/cos-lite.md +++ b/docs/src/charm/howto/cos-lite.md @@ -5,13 +5,13 @@ cluster itself is running or not. It may also be useful to integrate monitoring into existing setups. To make monitoring your cluster a delightful experience, Canonical provides -first-class integration between Canonical Kubernetes and COS Lite (Canonical +first-class integration between {{product}} and COS Lite (Canonical Observability Stack). This guide will help you integrate a COS Lite -deployment with a Canonical Kubernetes deployment. +deployment with a {{product}} deployment. This document assumes you have a controller with an installation of Canonical -Kubernetes. If you have not yet installed Canonical Kubernetes, please see -["Installing Canonical Kubernetes"][how-to-install]. +Kubernetes. If you have not yet installed {{product}}, please see +["Installing {{product}}"][how-to-install]. ## Preparing a platform for COS Lite @@ -81,9 +81,9 @@ At this point, you’ve established a MicroK8s model on Ubuntu and incorporated it into Juju as a Kubernetes cloud. You then used this cloud as a substrate for the COS Lite deployment. You therefore have 2 models on the same controller. -## Integrating COS Lite with Canonical Kubernetes +## Integrating COS Lite with {{product}} -Switch to your Canonical Kubernetes model (if you forgot the name of your model, +Switch to your {{product}} model (if you forgot the name of your model, you can run `juju models` to see a list of available models): ``` diff --git a/docs/src/charm/howto/etcd.md b/docs/src/charm/howto/etcd.md index 7ec3ea462..00495ba25 100644 --- a/docs/src/charm/howto/etcd.md +++ b/docs/src/charm/howto/etcd.md @@ -1,9 +1,9 @@ -# How to integrate Canonical Kubernetes with etcd +# How to integrate {{product}} with etcd -Integrating **etcd** with your Canonical Kubernetes deployment provides a +Integrating **etcd** with your {{product}} deployment provides a robust, distributed key-value store that is essential for storing critical data needed for Kubernetes' clustering operations. This guide will walk you -through the process of deploying Canonical Kubernetes with an external etcd +through the process of deploying {{product}} with an external etcd cluster. ## What you will need @@ -11,7 +11,7 @@ cluster. - A Juju controller with access to a cloud environment (see the [Juju setup] guide for more information). -```{warning} Once you deploy your Canonical Kubernetes cluster with a +```{warning} Once you deploy your {{product}} cluster with a particular datastore, you cannot switch to a different datastore post-deployment. Planning for your datastore needs ahead of time is crucial, particularly if you opt for an external datastore like **etcd**. @@ -20,7 +20,7 @@ crucial, particularly if you opt for an external datastore like **etcd**. ## Preparing the Deployment 1. **Creating the Deployment Model**: - Begin by creating a Juju model specifically for your Canonical Kubernetes + Begin by creating a Juju model specifically for your {{product}} cluster deployment. ```bash @@ -64,21 +64,21 @@ crucial, particularly if you opt for an external datastore like **etcd**. Now you have to integrate etcd with your certificate authority; this will issue the required certificates for secure communication between etcd and your -Canonical Kubernetes cluster: +{{product}} cluster: ```bash juju integrate etcd easyrsa ``` -## Deploying Canonical Kubernetes +## Deploying {{product}} -Deploy the control plane units of Canonical Kubernetes with the command: +Deploy the control plane units of {{product}} with the command: ```bash juju deploy k8s --config datastore=etcd -n 3 ``` -This command deploys 3 units of the Canonical Kubernetes control plane (`k8s`) +This command deploys 3 units of the {{product}} control plane (`k8s`) and configures them to use **etcd** as the backing datastore, ensuring high availability. @@ -87,7 +87,7 @@ Remember to run `juju expose k8s`. This will open the required ports to reach your cluster from outside. ``` -## Integrating Canonical Kubernetes with etcd +## Integrating {{product}} with etcd Now that we have both the etcd datastore deployed alongside our Canonical Kubernetes cluster, it is time to integrate our cluster with our etcd datastore. diff --git a/docs/src/charm/howto/index.md b/docs/src/charm/howto/index.md index 446f521e1..b9e9279d3 100644 --- a/docs/src/charm/howto/index.md +++ b/docs/src/charm/howto/index.md @@ -30,9 +30,9 @@ Our Reference section is for when you need to check specific details or information such as the command reference or release notes. Alternatively, the [Tutorials section] contains step-by-step tutorials to help -guide you through exploring and using Canonical Kubernetes. +guide you through exploring and using {{product}}. -For a better understanding of how Canonical Kubernetes works and related topics +For a better understanding of how {{product}} works and related topics such as security, our [Explanation section] helps you expand your knowledge and get the most out of Kubernetes. diff --git a/docs/src/charm/howto/proxy.md b/docs/src/charm/howto/proxy.md index abfd79de6..7a514dee9 100644 --- a/docs/src/charm/howto/proxy.md +++ b/docs/src/charm/howto/proxy.md @@ -1,12 +1,12 @@ # Configuring proxy settings for K8s -Canonical Kubernetes packages a number of utilities (eg curl, helm) which need +{{product}} packages a number of utilities (eg curl, helm) which need to fetch resources they expect to find on the internet. In a constrained network environment, such access is usually controlled through proxies. ## Adding proxy configuration for the k8s charms -For the charm deployments of Canonical Kubernetes, Juju manages proxy +For the charm deployments of {{product}}, Juju manages proxy configuration through the [Juju model]. For example, assume we have a proxy running at `http://squid.internal:3128` and diff --git a/docs/src/charm/index.md b/docs/src/charm/index.md index 44ce56364..5ebb51296 100644 --- a/docs/src/charm/index.md +++ b/docs/src/charm/index.md @@ -1,6 +1,6 @@ -# Canonical Kubernetes charm documentation +# {{product}} charm documentation -The Canonical Kubernetes charm, `k8s`, is an operator: software which wraps an +The {{product}} charm, `k8s`, is an operator: software which wraps an application and contains all of the instructions necessary for deploying, configuring, scaling, integrating the application on any cloud supported by [Juju][]. @@ -9,7 +9,7 @@ The `k8s` charm takes care of installing and configuring the [k8s snap package][] on cloud instances managed by Juju. Operating Kubernetes through this charm makes it significantly easier to manage at scale, on remote cloud instances and also to integrate other operators to enhance or customise your -Kubernetes deployment. You can find out more about Canonical Kubernetes on this +Kubernetes deployment. You can find out more about {{product}} on this [overview page][] or see a more detailed explanation in our [architecture documentation][arch]. @@ -50,7 +50,7 @@ documentation][arch]. ## Project and community -Canonical Kubernetes is a member of the Ubuntu family. It's an open source +{{product}} is a member of the Ubuntu family. It's an open source project which welcomes community involvement, contributions, suggestions, fixes and constructive feedback. diff --git a/docs/src/charm/reference/charms.md b/docs/src/charm/reference/charms.md index 65ef5abd6..29450218a 100644 --- a/docs/src/charm/reference/charms.md +++ b/docs/src/charm/reference/charms.md @@ -1,6 +1,6 @@ -# Canonical Kubernetes charms +# {{product}} charms -Canonical Kubernetes can be deployed via [Juju][] with the following charms: +{{product}} can be deployed via [Juju][] with the following charms: - **k8s**, which deploys a complete Kubernetes implementation - **k8s-worker**, which deploys Kubernetes without the control plane for units diff --git a/docs/src/charm/reference/community.md b/docs/src/charm/reference/community.md index 6a714c63d..33c2916bb 100644 --- a/docs/src/charm/reference/community.md +++ b/docs/src/charm/reference/community.md @@ -1,4 +1,4 @@ -# Welcome to the Canonical Kubernetes community +# Welcome to the {{product}} community ```{include} ../../snap/reference/community.md -:start-after: '# Welcome to the Canonical Kubernetes community' +:start-after: '# Welcome to the {{product}} community' ``` diff --git a/docs/src/charm/reference/index.md b/docs/src/charm/reference/index.md index b4520ab3c..606de9a9a 100644 --- a/docs/src/charm/reference/index.md +++ b/docs/src/charm/reference/index.md @@ -22,14 +22,14 @@ community ## Other documentation types Alternatively, the [Tutorials section] contains step-by-step tutorials to help -guide you through exploring and using Canonical Kubernetes. +guide you through exploring and using {{product}}. If you have a specific goal our [How-to guides] have more in-depth detail than tutorials and can be applied to a broader set of applications. They’ll help you achieve an end-result but may require you to understand and adapt the steps to fit your specific requirements. -Finally, for a better understanding of how Canonical Kubernetes works and +Finally, for a better understanding of how {{product}} works and related topics such as security, our [Explanation section] helps you to expand your knowledge and get the most out of Kubernetes. diff --git a/docs/src/charm/tutorial/getting-started.md b/docs/src/charm/tutorial/getting-started.md index 9c7182ea6..c43b189e5 100644 --- a/docs/src/charm/tutorial/getting-started.md +++ b/docs/src/charm/tutorial/getting-started.md @@ -1,6 +1,6 @@ # Getting started -The Canonical Kubernetes `k8s` charm takes care of installing and configuring +The {{product}} `k8s` charm takes care of installing and configuring Kubernetes on cloud instances managed by Juju. Operating Kubernetes through this charm makes it significantly easier to manage at scale, on remote cloud instances and also to integrate other operators to enhance or customise your @@ -9,7 +9,7 @@ Kubernetes and some common first steps. ## What you will learn -- How to install Canonical Kubernetes +- How to install {{product}} - Making a cluster - Deploying extra workers - Using Kubectl @@ -79,7 +79,7 @@ juju status --watch 2s ``` When the status reports that K8s is "idle/ready" you have successfully deployed -a Canonical Kubernetes control-plane using Juju. +a {{product}} control-plane using Juju. ```{note} For High Availability you will need at least three units of the k8s charm. Scaling the deployment is covered below. @@ -231,7 +231,7 @@ kube-system metrics-server-6f66c6cc48-wdxxk 1/1 Running 0 35 Congratulations - you now have a functional Kubernetes cluster! In the near future more charms are on the way to simplify usage and extend the base -functionality of Canonical Kubernetes. Bookmark the [releases page] to keep +functionality of {{product}}. Bookmark the [releases page] to keep informed of updates. diff --git a/docs/src/charm/tutorial/index.md b/docs/src/charm/tutorial/index.md index 02352b6dd..17ef956b7 100644 --- a/docs/src/charm/tutorial/index.md +++ b/docs/src/charm/tutorial/index.md @@ -1,7 +1,7 @@ # Tutorials This section contains a step-by-step guide to help you start exploring how to -install and use Canonical Kubernetes. +install and use {{product}}. ```{toctree} :hidden: @@ -23,7 +23,7 @@ tutorials and can be applied to a broader set of applications. They’ll help yo achieve an end-result but may require you to understand and adapt the steps to fit your specific requirements. -For a better understanding of how Canonical Kubernetes works and related topics +For a better understanding of how {{product}} works and related topics such as security, our [Explanation section] helps you to expand your knowledge and get the most out of Kubernetes. diff --git a/docs/src/index.md b/docs/src/index.md index 1e1ab1240..a97b5d8cb 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -1,10 +1,10 @@ -# Canonical Kubernetes documentation +# {{product}} documentation -Canonical Kubernetes is a performant, lightweight, secure and +{{product}} is a performant, lightweight, secure and opinionated distribution of **Kubernetes** which includes everything needed to create and manage a scalable cluster suitable for all use cases. -You can find out more about Canonical Kubernetes on this [overview page] or +You can find out more about {{product}} on this [overview page] or see a more detailed explanation in our [architecture documentation]. ![Illustration depicting working on components and clouds][logo] @@ -60,7 +60,7 @@ capi/reference/index ### [Install K8s from a snap ›](snap/index) ^^^ Our tutorials, How To guides and other pages will explain how to install, - configure and use the Canonical Kubernetes 'k8s' snap. + configure and use the {{product}} 'k8s' snap. ``` ```{grid-item-card} @@ -68,7 +68,7 @@ Our tutorials, How To guides and other pages will explain how to install, ### [Deploy K8s using Juju ›](charm/index) ^^^ Our tutorials, How To guides and other pages will explain how to install, - configure and use the Canonical Kubernetes 'k8s' charm. + configure and use the {{product}} 'k8s' charm. ``` ```` @@ -76,7 +76,7 @@ Our tutorials, How To guides and other pages will explain how to install, ## Project and community -Canonical Kubernetes is a member of the Ubuntu family. It's an open source +{{product}} is a member of the Ubuntu family. It's an open source project which welcomes community involvement, contributions, suggestions, fixes and constructive feedback. diff --git a/docs/src/snap/explanation/about.md b/docs/src/snap/explanation/about.md index 0c24bd337..eaa3ff068 100644 --- a/docs/src/snap/explanation/about.md +++ b/docs/src/snap/explanation/about.md @@ -1,6 +1,6 @@ -# What is Canonical Kubernetes? +# What is {{product}}? -At its core, Canonical Kubernetes is a full implementation of upstream +At its core, {{product}} is a full implementation of upstream [Kubernetes] delivered in a compact, secure, reliable [snap] package. As the upstream Kubernetes services are not all that is required for a fully functional cluster, additional services and features are built in. You can @@ -17,7 +17,7 @@ maintain and easy to upgrade. ## What else comes with it? In addition to the upstream Kubernetes services, -Canonical Kubernetes also includes: +{{product}} also includes: - a DNS service for the node - a CNI for the node/cluster @@ -29,7 +29,7 @@ Canonical Kubernetes also includes: ## Where can I install it? -The Canonical Kubernetes snap can be installed on a Linux OS, wherever it may +The {{product}} snap can be installed on a Linux OS, wherever it may be: run it in several local containers or VMs for example, or use it on public/private cloud instances. For deploying with [Juju], a machine [charm] to deploy @@ -37,7 +37,7 @@ the snap is also available. ## Can I use it to make a cluster? -Yes. Canonical Kubernetes is designed to be eminently scalable. You can start +Yes. {{product}} is designed to be eminently scalable. You can start with a single node and add more as and when the need arises. Scale up or down at any time. Systems with more than three nodes will automatically become Highly Available. diff --git a/docs/src/snap/explanation/channels.md b/docs/src/snap/explanation/channels.md index 988a739b0..96db5b02a 100644 --- a/docs/src/snap/explanation/channels.md +++ b/docs/src/snap/explanation/channels.md @@ -1,18 +1,18 @@ # Channels -Canonical Kubernetes uses the concept of `channels` to make sure you always get +{{product}} uses the concept of `channels` to make sure you always get the version of Kubernetes you are expecting, and that future upgrades can be handled with minimum, if any, disruption. ## Choosing the right channel -When installing or updating Canonical Kubernetes you can (and should in most +When installing or updating {{product}} you can (and should in most cases) specify a channel. The channel specified is made up of two components; the **track** and the **risk level**. The track matches the minor version of upstream Kubernetes. For example, specifying the `1.30` track will match upstream releases of the same minor -version ("1.30.0", "1.30.1", "1.30.x" etc.). Releases of Canonical Kubernetes +version ("1.30.0", "1.30.1", "1.30.x" etc.). Releases of {{product}} closely follow the upstream releases and usually follow within 24 hours. The 'risk level' component of the channel is one of the following: @@ -79,7 +79,7 @@ Use `--channel=/beta` for beta releases. Use `--channel=/candidate` for candidate releases. -- **I am waiting to test a bug fix on Canonical Kubernetes** +- **I am waiting to test a bug fix on {{product}}** Use `--channel=/edge`. diff --git a/docs/src/snap/explanation/clustering.md b/docs/src/snap/explanation/clustering.md index ada764246..a185a6f8c 100644 --- a/docs/src/snap/explanation/clustering.md +++ b/docs/src/snap/explanation/clustering.md @@ -3,7 +3,7 @@ Kubernetes clustering allows you to manage a group of hosts as a single entity. This enables applications to be deployed across a cluster of machines without tying them specifically to one host, providing high availability and -scalability. In Canonical Kubernetes the addition of `k8sd` to the Kubernetes +scalability. In {{product}} the addition of `k8sd` to the Kubernetes ecosystem introduces enhanced capabilities for cluster coordination and management. @@ -11,19 +11,19 @@ management. A Kubernetes cluster consists of at least one control plane node and multiple worker nodes. Each node is a server (physical or virtual) that runs -[Kubernetes components]. In Canonical Kubernetes, the components are bundled +[Kubernetes components]. In {{product}}, the components are bundled inside the `k8s-snap`. The cluster's topology divides responsibilities between the control plane node(s) and the worker nodes, ensuring efficient management and scheduling of workloads. -This is the overview of a Canonical Kubernetes cluster: +This is the overview of a {{product}} cluster: ```{kroki} ../../assets/ck-cluster.puml ``` ## The Role of `k8sd` in Kubernetes Clustering -`k8sd` plays a vital role in the Canonical Kubernetes architecture, enhancing +`k8sd` plays a vital role in the {{product}} architecture, enhancing the functionality of both the Control Plane and Worker nodes through the use of [microcluster]. This component simplifies cluster management tasks, such as adding or removing nodes and integrating them into the cluster. It also @@ -32,7 +32,7 @@ streamlining the entire process for a more efficient operation. ## Integration into the Kubernetes Cluster Topology -For Canonical Kubernetes, the detailed view of the two types of node is as +For {{product}}, the detailed view of the two types of node is as follows: ### Control Plane Node @@ -67,7 +67,7 @@ entire life-cycle. Their components include: by the user. - **Kube-Proxy (kube-proxy)**: Manages network communication within the cluster. - **Container Runtime**: The software responsible for running containers. In - Canonical Kubernetes the runtime is `containerd`. + {{product}} the runtime is `containerd`. diff --git a/docs/src/snap/explanation/index.md b/docs/src/snap/explanation/index.md index f788b3bfb..57efc1ace 100644 --- a/docs/src/snap/explanation/index.md +++ b/docs/src/snap/explanation/index.md @@ -1,6 +1,6 @@ # Explanation -For a better understanding of how Canonical Kubernetes works and related +For a better understanding of how {{product}} works and related topics such as security, these pages will help expand your knowledge and get the most out of Kubernetes. @@ -24,7 +24,7 @@ ingress If you are just getting started, the [Tutorials section] contains step-by-step tutorials to help guide you through exploring and using -Canonical Kubernetes. +{{product}}. If you have a specific goal our [How-to guides] have more in-depth detail than tutorials and can be applied to a broader set of applications. diff --git a/docs/src/snap/explanation/ingress.md b/docs/src/snap/explanation/ingress.md index d1e0b4379..6e7c73c5d 100644 --- a/docs/src/snap/explanation/ingress.md +++ b/docs/src/snap/explanation/ingress.md @@ -3,23 +3,23 @@ In Kubernetes, understanding how inbound traffic is managed inside of your cluster can be complex. This explanation provides you with the essentials -to successfully manage your Canonical Kubernetes cluster. +to successfully manage your {{product}} cluster. ## Network -When you install Canonical Kubernetes, the default Network is automatically enabled. +When you install {{product}}, the default Network is automatically enabled. This is also a requirement for the default Ingress to function. Since upstream Kubernetes comes without a network provider, it requires the use of a [network plugin][network plugin]. This network plugin facilitates communication between pods, services, and external resources, ensuring smooth traffic flow within the cluster. -The current implementation of Canonical Kubernetes leverages a widely adopted +The current implementation of {{product}} leverages a widely adopted CNI (Container Network Interface) called [Cilium][Cilium]. If you wish to use a different network plugin the implementation and configuration falls under your responsibility. -Learn how to use the Canonical Kubernetes default network in the [networking HowTo guide][Network]. +Learn how to use the {{product}} default network in the [networking HowTo guide][Network]. ## Kubernetes Pods and Services @@ -57,7 +57,7 @@ which operates at layer 4 and routes traffic directly to individual pods. ```{kroki} ../../assets/ingress.puml ``` -With Canonical Kubernetes, enabling Ingress is easy: +With {{product}}, enabling Ingress is easy: See the [default Ingress guide][Ingress]. Once enabled, you will have a working [Ingress Controller][Cilium Ingress Controller] in your cluster. diff --git a/docs/src/snap/explanation/security.md b/docs/src/snap/explanation/security.md index 02964b5ab..53f5ea727 100644 --- a/docs/src/snap/explanation/security.md +++ b/docs/src/snap/explanation/security.md @@ -1,12 +1,12 @@ # Security This page provides an overview of various aspects of security to be considered -when operating a cluster with **Canonical Kubernetes**. To consider security +when operating a cluster with **{{product}}**. To consider security properly, this means not just aspects of Kubernetes itself, but also how and where it is installed and operated. A lot of important aspects of security therefore lie outside the direct scope -of **Canonical Kubernetes**, but links for further reading +of **{{product}}**, but links for further reading are provided. ## Security of the snap/executable @@ -19,7 +19,7 @@ space. ## Security of the OCI images -**Canonical Kubernetes** relies on OCI standard images published as `rocks` to +**{{product}}** relies on OCI standard images published as `rocks` to deliver the services which run and facilitate the operation of the Kubernetes cluster. The use of Rockcraft and `rocks` gives Canonical a way to maintain and patch images to remove vulnerabilities at their source, which is fundamental to @@ -30,15 +30,15 @@ information on how these images are maintained and published, see the ## Kubernetes Security -The Kubernetes cluster deployed by Canonical Kubernetes can be secured using +The Kubernetes cluster deployed by {{product}} can be secured using any of the methods and options described by the upstream [Kubernetes Security Documentation][]. -Canonical Kubernetes enables RBAC (Rules Based Access Control) by default. +{{product}} enables RBAC (Rules Based Access Control) by default. ## Cloud security -If you are deploying **Canonical Kubernetes** on public or private cloud +If you are deploying **{{product}}** on public or private cloud instances, anyone with credentials to the cloud where it is deployed may also have access to your cluster. Describing the security mechanisms of these clouds is out of the scope of this documentation, but you may find the following links diff --git a/docs/src/snap/howto/backup-restore.md b/docs/src/snap/howto/backup-restore.md index 30d056fed..cb5345ac4 100644 --- a/docs/src/snap/howto/backup-restore.md +++ b/docs/src/snap/howto/backup-restore.md @@ -14,7 +14,7 @@ an S3 compatible object store. ## What you will need -- A running Canonical Kubernetes with DNS enabled +- A running {{product}} with DNS enabled - MinIO (install described below) or other S3 bucket - Velero (install described below) - An example workload diff --git a/docs/src/snap/howto/contribute.md b/docs/src/snap/howto/contribute.md index 3005d731d..05e08f1d2 100644 --- a/docs/src/snap/howto/contribute.md +++ b/docs/src/snap/howto/contribute.md @@ -1,12 +1,12 @@ -# How to contribute to Canonical Kubernetes +# How to contribute to {{product}} -Canonical Kubernetes is proudly open source, published under the GPLv3 license. +{{product}} is proudly open source, published under the GPLv3 license. We welcome and encourage contributions to the code and the documentation. See the [community page][] for ways to get in touch and provide feedback. ## Contribute to the code -Canonical Kubernetes is shipped as a snap package. To contribute to the code, +{{product}} is shipped as a snap package. To contribute to the code, you should first make sure you can build and test the snap locally. ### Build the snap @@ -68,18 +68,18 @@ lxc delete snapcraft-k8s ### Contribute changes -We welcome any improvements and bug-fixes to the Canonical Kubernetes code. +We welcome any improvements and bug-fixes to the {{product}} code. Once you have tested your changes, please make a pull request on the [code repository][code repo] and we will review it as soon as possible. ## Contribute to the documentation Our aim is to provide easy-to-understand documentation on all aspects of -Canonical Kubernetes, so we greatly appreciate your feedback and contributions. +{{product}}, so we greatly appreciate your feedback and contributions. See our [community page][] for ways of getting in touch. The source of the documentation and the system used to build it are included in -the [main repository for the Canonical Kubernetes snap][code repo]. +the [main repository for the {{product}} snap][code repo]. ### Documentation framework diff --git a/docs/src/snap/howto/external-datastore.md b/docs/src/snap/howto/external-datastore.md index a4bb3903e..2595beda6 100644 --- a/docs/src/snap/howto/external-datastore.md +++ b/docs/src/snap/howto/external-datastore.md @@ -1,6 +1,6 @@ # How to use an external datastore -Canonical Kubernetes supports using an external datastore such as etcd +{{product}} supports using an external datastore such as etcd instead of the bundled dqlite datastore. This guide walks you through configuring an external etcd datastore. @@ -10,9 +10,9 @@ This guide assumes the following: - You have root or sudo access to the machine - You have an external etcd cluster -- You have installed the Canonical Kubernetes snap - (see How-to [Install Canonical Kubernetes from a snap][snap-install-howto]). -- You have not bootstrapped the Canonical Kubernetes cluster yet +- You have installed the {{product}} snap + (see How-to [Install {{product}} from a snap][snap-install-howto]). +- You have not bootstrapped the {{product}} cluster yet ```{warning} The selection of the backing datastore can only be changed during the bootstrap process. diff --git a/docs/src/snap/howto/index.md b/docs/src/snap/howto/index.md index 22e66e214..582fb7c89 100644 --- a/docs/src/snap/howto/index.md +++ b/docs/src/snap/howto/index.md @@ -32,9 +32,9 @@ Our Reference section is for when you need to check specific details or information such as the command reference or release notes. Alternatively, the [Tutorials section] contains step-by-step tutorials to help -guide you through exploring and using Canonical Kubernetes. +guide you through exploring and using {{product}}. -For a better understanding of how Canonical Kubernetes works and related topics +For a better understanding of how {{product}} works and related topics such as security, our [Explanation section] helps you expand your knowledge and get the most out of Kubernetes. diff --git a/docs/src/snap/howto/install/index.md b/docs/src/snap/howto/install/index.md index f2cef5104..6c7403acc 100644 --- a/docs/src/snap/howto/install/index.md +++ b/docs/src/snap/howto/install/index.md @@ -1,11 +1,11 @@ -# Installing Canonical Kubernetes +# Installing {{product}} ```{toctree} :hidden: Install ``` -There's more than one way to install Canonical Kubernetes. You'll find links to +There's more than one way to install {{product}}. You'll find links to the current How-to guides below. ```{toctree} diff --git a/docs/src/snap/howto/install/lxd.md b/docs/src/snap/howto/install/lxd.md index 54488e06f..e81a1c11b 100644 --- a/docs/src/snap/howto/install/lxd.md +++ b/docs/src/snap/howto/install/lxd.md @@ -1,7 +1,7 @@ -# Install Canonical Kubernetes in LXD +# Install {{product}} in LXD -Canonical Kubernetes can also be installed inside an LXD container. This is a -great way, for example, to test out clustered Canonical Kubernetes without the +{{product}} can also be installed inside an LXD container. This is a +great way, for example, to test out clustered {{product}} without the need for multiple physical hosts. ## Installing LXD @@ -13,9 +13,9 @@ sudo snap install lxd sudo lxd init ``` -## Add the Canonical Kubernetes LXD profile +## Add the {{product}} LXD profile -Canonical Kubernetes requires some specific settings to work within LXD (these +{{product}} requires some specific settings to work within LXD (these are explained in more detail below). These can be applied using a custom profile. The first step is to create a new profile: @@ -48,9 +48,9 @@ Remove the copied content from your directory: rm k8s.profile ``` -## Start an LXD container for Canonical Kubernetes +## Start an LXD container for {{product}} -We can now create the container that Canonical Kubernetes will run in. +We can now create the container that {{product}} will run in. ``` lxc launch -p default -p k8s ubuntu:22.04 k8s @@ -60,9 +60,9 @@ This command uses the `default` profile created by LXD for any existing system settings (networking, storage, etc.), before also applying the `k8s` profile - the order is important. -## Install Canonical Kubernetes in an LXD container +## Install {{product}} in an LXD container -First, we’ll need to install Canonical Kubernetes within the container. +First, we’ll need to install {{product}} within the container. ``` lxc exec k8s -- sudo snap install k8s --classic --channel=latest/edge @@ -74,11 +74,11 @@ available channels with `snap info k8s` and see the [channels][] explanation page for more details on channels, tracks and versions. ``` -## Access Canonical Kubernetes services within LXD +## Access {{product}} services within LXD Assuming you accepted the [default bridged networking][default-bridged-networking] when you initially setup LXD, there is -minimal effort required to access Canonical Kubernetes services inside the LXD +minimal effort required to access {{product}} services inside the LXD container. Simply note the `eth0` interface IP address from the command: diff --git a/docs/src/snap/howto/install/multipass.md b/docs/src/snap/howto/install/multipass.md index a634ee97b..7c15847c5 100644 --- a/docs/src/snap/howto/install/multipass.md +++ b/docs/src/snap/howto/install/multipass.md @@ -2,7 +2,7 @@ **Multipass** is a simple way to run Ubuntu in a virtual machine, no matter what your underlying OS. It is the recommended way -to run Canonical Kubernetes on Windows and macOS systems, and is equally useful +to run {{product}} on Windows and macOS systems, and is equally useful for running multiple instances of the `k8s` snap on Ubuntu too. ## Install Multipass @@ -82,7 +82,7 @@ enter will be executed on the Ubuntu instance you created. You can now use this terminal to install the `k8s` snap, following the standard [install instructions][], or following along with the [Getting started][] -tutorial if you are new to Canonical Kubernetes. +tutorial if you are new to {{product}}. To end the shell session on the instance, enter: diff --git a/docs/src/snap/howto/install/offline.md b/docs/src/snap/howto/install/offline.md index 04d3cf1d6..6cf0327b0 100644 --- a/docs/src/snap/howto/install/offline.md +++ b/docs/src/snap/howto/install/offline.md @@ -1,19 +1,19 @@ -# Installing Canonical Kubernetes in air-gapped environments +# Installing {{product}} in air-gapped environments There are situations where it is necessary or desirable to run Canonical Kubernetes on a machine that is not connected to the internet. Based on different degrees of separation from the network, different solutions are offered to accomplish this goal. This guide documents any necessary extra preparation for air-gap deployments, as well the steps that are needed to -successfully deploy Canonical Kubernetes in such environments. +successfully deploy {{product}} in such environments. ## Prepare for Deployment In preparation for the offline deployment download the Canonical Kubernetes snap, fulfil the networking requirements based on your scenario and -handle images for workloads and Canonical Kubernetes features. +handle images for workloads and {{product}} features. -### Download the Canonical Kubernetes snap +### Download the {{product}} snap From a machine with access to the internet download the `k8s` and `core20` snap with: @@ -50,7 +50,7 @@ Below we discuss the requirements that the deployment needs to fulfil. Ensure that all cluster nodes are reachable from each other. +ports used by {{product}}. --> #### Default Gateway @@ -90,7 +90,7 @@ curl -v https://registry-1.docker.io/v2 All workloads in a Kubernetes cluster are run as an OCI image. Kubernetes needs to be able to fetch these images and load them into the container runtime. -For Canonical Kubernetes, it is also necessary to fetch the images used +For {{product}}, it is also necessary to fetch the images used by its features (network, dns, etc.) as well as any images that are needed to run specific workloads. @@ -156,7 +156,7 @@ This requires three steps: the desired registry deployment. 2. Using [regsync][regsync], load all images from the upstream source and push to your registry mirror. -3. Configure the Canonical Kubernetes container runtime (`containerd`) to load +3. Configure the {{product}} container runtime (`containerd`) to load images from the private registry mirror instead of the upstream source. This will be described in the [Configure registry mirrors](#private-registry) section. @@ -205,12 +205,12 @@ To create a bundle of images, use the [regctl][regctl] tool or invoke the Upon choosing this option, place all images under `/var/snap/k8s/common/images` and they will be picked up by containerd. -## Deploy Canonical Kubernetes +## Deploy {{product}} Once you've completed all the preparatory steps for your air-gapped cluster, you can proceed with the deployment. -### Step 1: Install Canonical Kubernetes +### Step 1: Install {{product}} Transfer the following files to the target node: diff --git a/docs/src/snap/howto/install/snap.md b/docs/src/snap/howto/install/snap.md index 248d8f5a4..cc16e7cd6 100644 --- a/docs/src/snap/howto/install/snap.md +++ b/docs/src/snap/howto/install/snap.md @@ -1,6 +1,6 @@ -# Install Canonical Kubernetes from a snap +# Install {{product}} from a snap -Canonical Kubernetes is packaged as a [snap], available from the +{{product}} is packaged as a [snap], available from the snap store for all supported platforms. ## What you'll need diff --git a/docs/src/snap/howto/networking/default-dns.md b/docs/src/snap/howto/networking/default-dns.md index 5f6ef7e3a..34722d3a1 100644 --- a/docs/src/snap/howto/networking/default-dns.md +++ b/docs/src/snap/howto/networking/default-dns.md @@ -1,6 +1,6 @@ # How to use default DNS -Canonical Kubernetes includes a default DNS (Domain Name System) which is +{{product}} includes a default DNS (Domain Name System) which is essential for internal cluster communication. When enabled, the DNS facilitates service discovery by assigning each service a DNS name. When disabled, you can integrate a custom DNS solution into your cluster. @@ -10,7 +10,7 @@ integrate a custom DNS solution into your cluster. This guide assumes the following: - You have root or sudo access to the machine. -- You have a bootstrapped Canonical Kubernetes cluster (see the [Getting +- You have a bootstrapped {{product}} cluster (see the [Getting Started][getting-started-guide] guide). ## Check DNS status @@ -74,7 +74,7 @@ desired values for your DNS configuration. ## Disable DNS -Canonical Kubernetes also allows you to disable the built-in DNS, +{{product}} also allows you to disable the built-in DNS, if you desire a custom solution: ``` {warning} Disabling DNS will disrupt internal cluster communication. Ensure diff --git a/docs/src/snap/howto/networking/default-ingress.md b/docs/src/snap/howto/networking/default-ingress.md index 01918c592..ce9f792d0 100644 --- a/docs/src/snap/howto/networking/default-ingress.md +++ b/docs/src/snap/howto/networking/default-ingress.md @@ -1,6 +1,6 @@ # How to use default Ingress -Canonical Kubernetes allows you to configure Ingress into your cluster. When +{{product}} allows you to configure Ingress into your cluster. When enabled, it tells your cluster how external HTTP and HTTPS traffic should be routed to its services. @@ -9,7 +9,7 @@ routed to its services. This guide assumes the following: - You have root or sudo access to the machine -- You have a bootstrapped Canonical Kubernetes cluster (see the [Getting +- You have a bootstrapped {{product}} cluster (see the [Getting Started][getting-started-guide] guide). ## Check Ingress status diff --git a/docs/src/snap/howto/networking/default-loadbalancer.md b/docs/src/snap/howto/networking/default-loadbalancer.md index fa1f33f7d..88a2a20fb 100644 --- a/docs/src/snap/howto/networking/default-loadbalancer.md +++ b/docs/src/snap/howto/networking/default-loadbalancer.md @@ -1,6 +1,6 @@ # How to use the default load-balancer -Canonical Kubernetes includes a default load-balancer. As this is not an +{{product}} includes a default load-balancer. As this is not an essential service for all deployments, it is not enabled by default. This guide explains how to configure and enable the load-balancer. @@ -9,7 +9,7 @@ explains how to configure and enable the load-balancer. This guide assumes the following: - You have root or sudo access to the machine. -- You have a bootstraped Canonical Kubernetes cluster (see the [Getting +- You have a bootstraped {{product}} cluster (see the [Getting Started][getting-started-guide] guide). ## Check the status and configuration diff --git a/docs/src/snap/howto/networking/default-network.md b/docs/src/snap/howto/networking/default-network.md index 246184fe7..bde0aad9e 100644 --- a/docs/src/snap/howto/networking/default-network.md +++ b/docs/src/snap/howto/networking/default-network.md @@ -1,6 +1,6 @@ # How to use the default Network -Canonical Kubernetes includes a high-performance, advanced network plugin +{{product}} includes a high-performance, advanced network plugin called Cilium. The network component allows cluster administrators to leverage software-defined networking to automatically scale and secure network policies across their cluster. @@ -10,7 +10,7 @@ across their cluster. This guide assumes the following: - You have root or sudo access to the machine. -- You have a bootstrapped Canonical Kubernetes cluster (see the [Getting +- You have a bootstrapped {{product}} cluster (see the [Getting Started][getting-started-guide] guide). ## Check Network status diff --git a/docs/src/snap/howto/networking/index.md b/docs/src/snap/howto/networking/index.md index 39ec9bbc2..2f62c6b3a 100644 --- a/docs/src/snap/howto/networking/index.md +++ b/docs/src/snap/howto/networking/index.md @@ -6,7 +6,7 @@ Networking ``` Networking is a core part of a working Kubernetes cluster. These topics cover -how to configure and use key capabilities of Canonical Kubernetes. +how to configure and use key capabilities of {{product}}. ```{toctree} :titlesonly: diff --git a/docs/src/snap/howto/proxy.md b/docs/src/snap/howto/proxy.md index d029a6a4e..ad4186625 100644 --- a/docs/src/snap/howto/proxy.md +++ b/docs/src/snap/howto/proxy.md @@ -1,6 +1,6 @@ # Configure proxy settings for K8s -Canonical Kubernetes packages a number of utilities (eg curl, helm) which need +{{product}} packages a number of utilities (eg curl, helm) which need to fetch resources they expect to find on the internet. In a constrained network environment, such access is usually controlled through proxies. diff --git a/docs/src/snap/howto/storage/ceph.md b/docs/src/snap/howto/storage/ceph.md index c8325e693..b448cab9f 100644 --- a/docs/src/snap/howto/storage/ceph.md +++ b/docs/src/snap/howto/storage/ceph.md @@ -3,7 +3,7 @@ Distributed, redundant storage is a must-have when you want to develop reliable applications. [Ceph] is a storage solution which provides exactly that, and is built with distributed clusters in mind. In this tutorial, we'll be looking at -how to integrate Canonical Kubernetes with a Ceph cluster. Specifically, by the +how to integrate {{product}} with a Ceph cluster. Specifically, by the end of this tutorial you'll have a Kubernetes pod with a mounted RBD-backed volume. RBD stands for RADOS Block Device and it is the abstraction used by Ceph to provide reliable and distributed storage. This how-to guide is adapted from @@ -14,7 +14,7 @@ to provide reliable and distributed storage. This how-to guide is adapted from This guide assumes the following: - You have root or sudo access to the machine -- You have a bootstrapped Canonical Kubernetes cluster (see the +- You have a bootstrapped {{product}} cluster (see the [getting-started-guide]) - You have a running Ceph cluster diff --git a/docs/src/snap/howto/storage/index.md b/docs/src/snap/howto/storage/index.md index f53d5445b..4310beac7 100644 --- a/docs/src/snap/howto/storage/index.md +++ b/docs/src/snap/howto/storage/index.md @@ -7,7 +7,7 @@ Storage Most Kubernetes clusters will need some type of persistent storage for running workloads. These guides contain information on setting up storage, or using the -default storage built-in to Canonical Kubernetes. +default storage built-in to {{product}}. ```{toctree} :titlesonly: diff --git a/docs/src/snap/howto/storage/storage.md b/docs/src/snap/howto/storage/storage.md index 12b401284..dbba33631 100644 --- a/docs/src/snap/howto/storage/storage.md +++ b/docs/src/snap/howto/storage/storage.md @@ -1,6 +1,6 @@ # How to use default storage -Canonical Kubernetes offers a local-storage option to quickly set up and run a +{{product}} offers a local-storage option to quickly set up and run a cluster, especially for single-node support. This guide walks you through enabling and configuring this feature. @@ -9,7 +9,7 @@ enabling and configuring this feature. This guide assumes the following: - You have root or sudo access to the machine -- You have a bootstrapped Canonical Kubernetes cluster (see the +- You have a bootstrapped {{product}} cluster (see the [getting-started-guide]) ## Enable Local Storage diff --git a/docs/src/snap/howto/support.md b/docs/src/snap/howto/support.md index 60b1b1c9d..a6f41b3a2 100644 --- a/docs/src/snap/howto/support.md +++ b/docs/src/snap/howto/support.md @@ -1,12 +1,12 @@ # How to get support -Support for Canonical Kubernetes is available in a variety of ways: +Support for {{product}} is available in a variety of ways: -- Engagement with the [Canonical Kubernetes Community] +- Engagement with the [{{product}} Community] - Understanding common [Troubleshooting Techniques] - Professional support services with [Ubuntu Support] -[Canonical Kubernetes Community]: ../reference/community +[{{product}} Community]: ../reference/community [Troubleshooting Techniques]: ../reference/troubleshooting [Ubuntu Support]: https://ubuntu.com/support diff --git a/docs/src/snap/index.md b/docs/src/snap/index.md index 8ab90ef4f..7022a799f 100644 --- a/docs/src/snap/index.md +++ b/docs/src/snap/index.md @@ -1,13 +1,13 @@ -# Canonical Kubernetes snap documentation +# {{product}} snap documentation -The Canonical Kubernetes snap is a performant, lightweight, secure and +The {{product}} snap is a performant, lightweight, secure and opinionated distribution of **Kubernetes** which includes everything needed to create and manage a scalable cluster suitable for all use cases. -You can find out more about Canonical Kubernetes on this [overview page] or +You can find out more about {{product}} on this [overview page] or see a more detailed explanation in our [architecture documentation]. -For deployment at scale, Canonical Kubernetes is also available as a +For deployment at scale, {{product}} is also available as a [Juju charm][] ![Illustration depicting working on components and clouds][logo] @@ -49,7 +49,7 @@ For deployment at scale, Canonical Kubernetes is also available as a ## Project and community -Canonical Kubernetes is a member of the Ubuntu family. It's an open source +{{product}} is a member of the Ubuntu family. It's an open source project which welcomes community involvement, contributions, suggestions, fixes and constructive feedback. diff --git a/docs/src/snap/reference/architecture.md b/docs/src/snap/reference/architecture.md index 0a8b74fd4..30905a45d 100644 --- a/docs/src/snap/reference/architecture.md +++ b/docs/src/snap/reference/architecture.md @@ -3,11 +3,11 @@ A system architecture document is the starting point for many interested participants in a project, whether you intend contributing or simply want to understand how the software is structured. This documentation lays out the -current design of Canonical Kubernetes, following the [C4 model]. +current design of {{product}}, following the [C4 model]. ## System context -This overview of Canonical Kubernetes demonstrates the interactions of +This overview of {{product}} demonstrates the interactions of Kubernetes with users and with other systems. ```{kroki} ../../assets/overview.puml @@ -138,7 +138,7 @@ The `k8s` charm also supports the integration of other compatible charms, enabling integrations such as connectivity with an external `etcd` datastore and the sharing of observability data with the [`Canonical Observability Stack (COS)`][COS docs]. This modular and integrated approach facilitates a robust -and flexible Canonical Kubernetes deployment managed through Juju. +and flexible {{product}} deployment managed through Juju. diff --git a/docs/src/snap/reference/community.md b/docs/src/snap/reference/community.md index 6742f812f..661c2f51b 100644 --- a/docs/src/snap/reference/community.md +++ b/docs/src/snap/reference/community.md @@ -1,4 +1,4 @@ -# Welcome to the Canonical Kubernetes community +# Welcome to the {{product}} community This rapidly growing community is a diverse bunch of people - developers, Kubernetes admins, inventors, researchers, students… and we all share the joy @@ -8,7 +8,7 @@ the project as a whole and how valuable your contributions are. ## Do you have questions? -Do you have questions about Canonical Kubernetes? Perhaps you want some ideas +Do you have questions about {{product}}? Perhaps you want some ideas on how to best achieve a certain goal or maybe some aspect of your Kubernetes doesn't behave the way you expect. Perhaps you'd just like some advice from more experienced users. There are a number of ways to get in touch: @@ -34,7 +34,7 @@ aim to triage all bug reports within three working days. ## Contributing to the code? -Canonical Kubernetes is proudly open source, published under the GPLv3 license. +{{product}} is proudly open source, published under the GPLv3 license. We welcome and encourage contributions to the code. Please see the [Developer guide] for more information on contributing. diff --git a/docs/src/snap/reference/index.md b/docs/src/snap/reference/index.md index 48ae69025..7cce42640 100644 --- a/docs/src/snap/reference/index.md +++ b/docs/src/snap/reference/index.md @@ -24,14 +24,14 @@ roadmap ## Other documentation types Alternatively, the [Tutorials section] contains step-by-step tutorials to help -guide you through exploring and using Canonical Kubernetes. +guide you through exploring and using {{product}}. If you have a specific goal our [How-to guides] have more in-depth detail than tutorials and can be applied to a broader set of applications. They’ll help you achieve an end-result but may require you to understand and adapt the steps to fit your specific requirements. -Finally, for a better understanding of how Canonical Kubernetes works and +Finally, for a better understanding of how {{product}} works and related topics such as security, our [Explanation section] helps you to expand your knowledge and get the most out of Kubernetes. diff --git a/docs/src/snap/reference/proxy.md b/docs/src/snap/reference/proxy.md index fc51b180c..1fa29f765 100644 --- a/docs/src/snap/reference/proxy.md +++ b/docs/src/snap/reference/proxy.md @@ -1,6 +1,6 @@ # Proxy environment variables -Canonical Kubernetes uses the standard system-wide environment variables to +{{product}} uses the standard system-wide environment variables to control access through proxies. On Ubuntu and other Linux operating systems, proxies are configured through @@ -17,7 +17,7 @@ system-wide environment variables defined in the `/etc/environment` file. When configuring proxies, it is important to note that there are always some CIDRs which need to be excluded and added to the `no-proxy` lists. For -Canonical Kubernetes these are: +{{product}} these are: - The range used by Kubernetes services (defaults to **10.152.183.0/24**) - The range used by the Kubernetes pods (defaults to **10.1.0.0/16**) diff --git a/docs/src/snap/reference/releases.md b/docs/src/snap/reference/releases.md index e769d80d7..319f16737 100644 --- a/docs/src/snap/reference/releases.md +++ b/docs/src/snap/reference/releases.md @@ -2,7 +2,7 @@ ## Rolling preview release -In advance of a GA release of Canonical Kubernetes, you can still install and +In advance of a GA release of {{product}}, you can still install and try out the newest distribution of Kubernetes. You need two commands to get a single node cluster, one for installation and @@ -14,16 +14,16 @@ sudo snap install k8s --channel=1.30-classic/beta --classic sudo k8s bootstrap ``` -Currently Canonical Kubernetes is working towards general availability, but you +Currently {{product}} is working towards general availability, but you can install it now to try: - **Clustering** - need high availability or just an army of worker nodes? - Canonical Kubernetes is emminently scaleable, see the [tutorial on adding + {{product}} is emminently scaleable, see the [tutorial on adding more nodes][nodes]. - **Networking** - Our built-in network component allows cluster administrators to automatically scale and secure network policies across the cluster. Find out more in our [how-to guides][networking]. -- **Observability** - Canonical Kubernetes ships with [COS Lite], so you never +- **Observability** - {{product}} ships with [COS Lite], so you never need to wonder what your cluster is actually doing. See the [observability documentation] for more details. diff --git a/docs/src/snap/reference/roadmap.md b/docs/src/snap/reference/roadmap.md index bf9fc7b2b..63550f85c 100644 --- a/docs/src/snap/reference/roadmap.md +++ b/docs/src/snap/reference/roadmap.md @@ -1,6 +1,6 @@ # Roadmap -The Canonical Kubernetes team enthusiastically supports the idea of a public +The {{product}} team enthusiastically supports the idea of a public roadmap, letting everyone know the headline features we are working on and the future direction and priorities of the project. @@ -10,7 +10,7 @@ release cycle of Kubernetes versions, so please consult the [release notes] for specifics of whatfeatures have been delivered. -``` {csv-table} Canonical Kubernetes public roadmap +``` {csv-table} {{product}} public roadmap :file: ../../assets/roadmap.csv :widths: 30, 30 :header-rows: 1 diff --git a/docs/src/snap/reference/troubleshooting.md b/docs/src/snap/reference/troubleshooting.md index 1a888f7b8..f6b44a3f1 100644 --- a/docs/src/snap/reference/troubleshooting.md +++ b/docs/src/snap/reference/troubleshooting.md @@ -1,6 +1,6 @@ # Troubleshooting -This page provides techniques for troubleshooting common Canonical Kubernetes +This page provides techniques for troubleshooting common {{product}} issues. diff --git a/docs/src/snap/tutorial/add-remove-nodes.md b/docs/src/snap/tutorial/add-remove-nodes.md index ad325e20d..736474b46 100644 --- a/docs/src/snap/tutorial/add-remove-nodes.md +++ b/docs/src/snap/tutorial/add-remove-nodes.md @@ -6,7 +6,7 @@ availability and resilience. This tutorial simplifies the concept by creating a cluster within a controlled environment using two Multipass VMs. The approach here allows us to focus on -the foundational aspects of clustering using Canonical Kubernetes without the +the foundational aspects of clustering using {{product}} without the complexities of a full-scale, production setup. If your nodes are already installed, you can skip the multipass setup and go to [step 2](step2). @@ -45,7 +45,7 @@ multipass shell control-plane This will behave as a local terminal session on the virtual machine, so you can run commands. -Install Canonical Kubernetes on both VMs with the following command: +Install {{product}} on both VMs with the following command: ``` sudo snap install --classic --edge k8s @@ -62,7 +62,7 @@ Bootstrap the control plane node: sudo k8s bootstrap ``` -Canonical Kubernetes allows you to create two types of nodes: control plane and +{{product}} allows you to create two types of nodes: control plane and worker nodes. In this example, we're creating a worker node. Generate the token required for the worker node to join the cluster by executing @@ -142,7 +142,7 @@ multipass purge ## Next Steps - Discover how to enable and configure Ingress resources [Ingress][Ingress] -- Keep mastering Canonical Kubernetes with kubectl [How to use +- Keep mastering {{product}} with kubectl [How to use kubectl][Kubectl] - Explore Kubernetes commands with our [Command Reference Guide][Command Reference] diff --git a/docs/src/snap/tutorial/getting-started.md b/docs/src/snap/tutorial/getting-started.md index 53c4107f1..d613e202b 100644 --- a/docs/src/snap/tutorial/getting-started.md +++ b/docs/src/snap/tutorial/getting-started.md @@ -1,6 +1,6 @@ # Getting started -Installing Canonical Kubernetes should only take a few minutes. This tutorial +Installing {{product}} should only take a few minutes. This tutorial explains how to install the snap package and some typical operations. ## What you will need @@ -11,9 +11,9 @@ explains how to install the snap package and some typical operations. - System Requirements: Your machine should have at least 40G disk space and 4G of memory -### 1. Install Canonical Kubernetes +### 1. Install {{product}} -Install the Canonical Kubernetes snap with: +Install the {{product}} snap with: ``` sudo snap install k8s --edge --classic @@ -57,7 +57,7 @@ You will observe at least three pods running: - **Network operator**: Manages the life-cycle of the networking solution. - **Network agent**: Facilitates network management. -Confirm that Canonical Kubernetes has transitioned to the `k8s is ready` state +Confirm that {{product}} has transitioned to the `k8s is ready` state by running: ``` @@ -68,7 +68,7 @@ sudo k8s status --wait-ready The standard tool for deploying and managing workloads on Kubernetes is [kubectl](https://kubernetes.io/docs/reference/kubectl/). -For convenience, Canonical Kubernetes bundles a version of +For convenience, {{product}} bundles a version of kubectl for you to use with no extra setup or configuration. For example, to view your node you can run the command: @@ -128,7 +128,7 @@ sudo k8s kubectl get pods In scenarios where you need to preserve application data beyond the life-cycle of the pod, Kubernetes provides persistent volumes. -With Canonical Kubernetes, you can enable local-storage to configure +With {{product}}, you can enable local-storage to configure your storage solutions: ``` @@ -180,9 +180,9 @@ Next, disable the local storage: sudo k8s disable local-storage ``` -### 10. Remove Canonical Kubernetes (Optional) +### 10. Remove {{product}} (Optional) -To uninstall the Canonical Kubernetes snap, execute: +To uninstall the {{product}} snap, execute: ``` sudo snap remove k8s @@ -202,7 +202,7 @@ This option ensures complete removal of the snap and its associated data. ## Next Steps -- Keep mastering Canonical Kubernetes with kubectl: [How to use kubectl] +- Keep mastering {{product}} with kubectl: [How to use kubectl] - Explore Kubernetes commands with our [Command Reference Guide] - Learn how to set up a multi-node environment [Setting up a K8s cluster] - Configure storage options [Storage] diff --git a/docs/src/snap/tutorial/index.md b/docs/src/snap/tutorial/index.md index df1a18041..237c89aed 100644 --- a/docs/src/snap/tutorial/index.md +++ b/docs/src/snap/tutorial/index.md @@ -1,7 +1,7 @@ # Tutorials This section contains a step-by-step guide to help you start exploring how to -install and use Canonical Kubernetes. +install and use {{product}}. ```{toctree} :hidden: @@ -25,7 +25,7 @@ tutorials and can be applied to a broader set of applications. They’ll help yo achieve an end-result but may require you to understand and adapt the steps to fit your specific requirements. -For a better understanding of how Canonical Kubernetes works and related topics +For a better understanding of how {{product}} works and related topics such as security, our [Explanation section] helps you to expand your knowledge and get the most out of Kubernetes. diff --git a/docs/src/snap/tutorial/kubectl.md b/docs/src/snap/tutorial/kubectl.md index 5d0215125..2f9fed807 100644 --- a/docs/src/snap/tutorial/kubectl.md +++ b/docs/src/snap/tutorial/kubectl.md @@ -9,7 +9,7 @@ tool. Before you begin, make sure you have the following: -- A bootstrapped Canonical Kubernetes cluster (See +- A bootstrapped {{product}} cluster (See [Getting Started]) - You are using the built-in `kubectl` command from the snap. @@ -18,7 +18,7 @@ Before you begin, make sure you have the following: The `kubectl` command communicates with the [Kubernetes API server][kubernetes-api-server]. -The `kubectl` command included with Canonical Kubernetes is built from the +The `kubectl` command included with {{product}} is built from the original upstream source into the `k8s` snap you have installed. ### 2. How To Use Kubectl @@ -34,7 +34,7 @@ sudo k8s kubectl ### 3. Configuration -In Canonical Kubernetes, the `kubeconfig` file that is being read to display +In {{product}}, the `kubeconfig` file that is being read to display the configuration when you run `kubectl config view` lives at `/etc/kubernetes/admin.conf`. You can change this by setting a `KUBECONFIG` environment variable or passing the `--kubeconfig` flag to a diff --git a/docs/tools/conf.py b/docs/tools/conf.py index 7fbb35475..f4346485e 100644 --- a/docs/tools/conf.py +++ b/docs/tools/conf.py @@ -1,4 +1,6 @@ import sys +import os +import yaml sys.path.append('./') from custom_conf import * @@ -138,3 +140,11 @@ if 'github_issues' in html_context and html_context['github_issues'] and not disable_feedback_button: html_js_files.append('github_issue_links.js') html_js_files.extend(custom_html_js_files) + + +############################################################ +### Myst configuration +############################################################ +if os.path.exists('./reuse/substitutions.yaml'): + with open('./reuse/substitutions.yaml', 'r') as fd: + myst_substitutions = yaml.safe_load(fd.read()) diff --git a/docs/tools/reuse/substitutions.yaml b/docs/tools/reuse/substitutions.yaml new file mode 100644 index 000000000..41fd9e08e --- /dev/null +++ b/docs/tools/reuse/substitutions.yaml @@ -0,0 +1,4 @@ +product: 'Canonical Kubernetes' +multi_line_example: |- + *Multi-line* text + that uses basic **markup**.