Merge remote-tracking branch 'origin/main' into KU-629/harden-CI

.github/ISSUE_TEMPLATE/create_release_branch.md

@@ -52,7 +52,7 @@ The steps are to be followed in-order, each task must be completed by the person
   - `git pull`
   - `git checkout -b release-1.xx`
   - `git push origin release-1.xx`
-- [ ] **Owner**: Create `1.xx` branch from latest `master` in k8s-dqlite
+- [ ] **Owner**: Create `release-1.xx` branch from latest `master` in k8s-dqlite
   - `git clone [email protected]:canonical/k8s-dqlite.git ~/tmp/release-1.xx`
   - `pushd ~/tmp/release-1.xx`
   - `git switch main`
@@ -101,7 +101,7 @@ The steps are to be followed in-order, each task must be completed by the person
 - [ ] **Reviewer**: Ensure `release-1.xx-strict` branch is based on latest changes on `autoupdate/strict` at the time of the release cut.
 - [ ] **Owner**: Create PR to initialize `release-1.xx` branch:
   - [ ] Update `KUBE_TRACK` to `1.xx` in [/build-scripts/components/kubernetes/version.sh][]
-  - [ ] Update `master` to `1.xx` in [/build-scripts/components/k8s-dqlite/version.sh][]
+  - [ ] Update `master` to `release-1.xx` in [/build-scripts/components/k8s-dqlite/version.sh][]
   - [ ] Update `"main"` to `"release-1.xx"` in [/build-scripts/hack/generate-sbom.py][]
   - [ ] `git commit -m 'Release 1.xx'`
   - [ ] Create PR with the changes and request review from **Reviewer**. Make sure to update the issue `Information` section with a link to the PR.

docs/src/_parts/template-explanation

@@ -0,0 +1,27 @@
+# Explanation docs template
+
+> Explanations are for learning and understanding
+
+There is no set format to an explanation document. Good examples consist of
+easy to understand text and are quite frequently accompanied by diagrams.
+
+## Diagrams
+
+You can include a diagram as an image using the usual Markdown format:
+
+![Illustration depicting working on components and clouds][logo]
+
+The documentation also supports various diagrams-as-code options. We
+prefer to use UML-style diagrams, but you can also use Mermaid or many
+other types.
+
+Diagrams like this are processed using the 'kroki' directive:
+
+```{kroki} ../../assets/ck-cluster.puml
+```
+
+## Links
+
+Explanations frequently include links to other documents. In particular, please
+consider adding a section titled 'Further Reading' at the end to collate
+related topics (internal or external).

docs/src/_parts/template-howto

@@ -0,0 +1,62 @@
+# How to docs template
+
+> A How to guide consists of task-oriented, step-by-step instructions to
+> achieve a specific goal.
+> The title of the document should explain a clear objective.
+
+# How to use default DNS
+
+> Add an introductory paragraph explaining the objective and any background 
+> necessary.
+
+Canonical Kubernetes 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.
+
+
+> ALWAYS start with a list of requirements/assumptions. Link to other docs
+> if helpful
+
+## What you'll need
+
+This guide assumes the following:
+
+- You have root or sudo access to the machine.
+- You have a bootstrapped Canonical Kubernetes cluster (see the [Getting
+  Started][getting-started-guide] guide).
+
+> Proceed with clearly labelled steps. N.B. Use 'imperatives' rather than
+> gerunds ('Enable XXX' rather than 'Enabling XXX', 'Check' rather than
+> 'Checking')
+
+## Check DNS status
+
+> ALWAYS have some text directly after each heading
+
+Find out whether DNS is enabled or disabled with the following command:
+
+
+> Commands are identified by three backticks to start and end the sequence. No
+> need to specify a code type for normal bash commands. DO NOT include '#' or
+> '$' prompts
+
+> ALWAYS separate input and output
+
+```
+sudo k8s status
+```
+
+> Proceed with steps until the task is complete. Consider whether links to related
+> Guides or resources are appropriate
+
+## See also
+
+- [How to xxx with yyy][]
+- [Get more out of zzz][]
+
+> ALWAYS use links by reference for easier maintenance!
+
+<!-- LINKS -->
+
+[getting-started-guide]: /snap/tutorial/getting-started

docs/src/_parts/template-reference

@@ -0,0 +1,84 @@
+# Reference docs template
+
+> Reference guides are technical descriptions of the machinery.
+
+The reference section is distinct from the How to section in that it provides
+information without demonstrating in any depth how that information is to be used.
+What's the point of that?
+
+Often users may need to check some information - "What release included support
+for xxxx?" or "What options can I supply to yyyy". 
+
+The reference section is also distinct from the explanation section in that it
+does not attempt to give any detailed explanation of why this information
+exists or how it is to be used.
+
+Consider an application which deals with many different image formats. A useful
+reference page would list the filetypes supported and maybe a list of common
+file extensions and perhaps a brief decscription:
+
+| FileType | Extensions | Notes                                              |
+|----------|------------|----------------------------------------------------|
+| TIFF     | .tif,.tiff | Tag Image File Format - lossless bitmaps           |
+| JPEG     | .jpg,.jpeg | Compressed photo-quality images                    |
+| PNG      | .png       | Portable Network Graphics - lossless bitmaps        |
+
+This table gives some reference information. It doesn't try to tell you which
+format to use. It doesn't explain in great detail the differences between them.
+It doesn't guide you on how to use them. It is simply a reference. You could use
+it to check whether the application can import or export files in a particular
+format.
+
+## Presentation
+
+As the reference guide is usually about collections of small piece of data,
+there are some specific ways of formatting this information which can be useful
+
+We have already seen the table style. In other situations it may be more
+relevant to use a simple bullet list:
+
+
+- TIFF (.tif,.tiff)
+- PNG (.png)
+- JPEG (.jpg, .jpeg)
+
+Or definition lists:
+
+
+TIFF
+: Tag Image File Format
+
+JPEG
+: Joint Photographic Experts Group
+
+## Automation
+
+For some types of information it may be more expedient to generate details or
+text automatically through a script. there are a few ways this can then be used
+in documentation.
+
+For example, in the command reference we use:
+
+```{include} ../../_parts/commands/k8s_config.md
+   :end-before: '### SEE ALSO'
+```
+which automatically includes the contents of the file (note you can also use a
+simple :start-after: and :end-before: option to filter out parts of the
+original)
+
+Pages can filter information from other sources to, for example:
+
+``` {csv-table} Canonical Kubernetes public roadmap
+   :file: ../../assets/roadmap.csv
+   :widths: 30, 30
+   :header-rows: 1
+```
+
+This defines an input from a CSV file.
+
+## Tips
+
+- Remember this is about presenting information.
+- People are unlikely to read the entire page in one go - use headings, lists,
+  tables etc to direct them to the information they are looking for.
+- Resist the temptation to over-explain, but do provide links to documents which do!

docs/src/_parts/template-tutorial

@@ -0,0 +1,97 @@
+# Tutorial docs template
+
+> Tutorials are explained guides which fulfil the objectives of learning and
+understanding through example.
+
+>Unlike some of the other documentation types, tutorials are structured and easy
+to provide a definitive template.
+
+> Tutorials should start with a short introductory statement outlining the
+objective of the tutorial. For example:
+
+Installing Canonical Kubernetes should only take a few minutes. This tutorial
+explains how to install the snap package and some typical operations. 
+
+> For lengthier tutorials, it is worth considering adding a bullet list
+detailing this:
+
+## What you will learn
+
+- How to install the k8s snap
+- Configuring storage
+- Deploying an application to the cluster
+- Removing an application
+- Turning off the cluster
+
+> Next, ALL tutorials should include a section called 'What you will need'. This
+> is a list (with links if necessary) that covers the requirements to start the
+> tutorial. This could include things like system requirements, assumptions about
+> software already installed and even knowledge. This is essentially the list of
+> assumptions we are making
+
+## What you will need
+
+- Ubuntu 22.04 LTS or 20.04 LTS
+- At least 20G disk space and 4G of memory
+- The [Juju-client]
+
+> The tutorial should proceed with numbered steps if possible, showing the
+> sequence of the tutorial.
+
+### 1. Install Canonical Kubernetes
+
+Install the Canonical Kubernetes snap with:
+
+```
+sudo snap install k8s --edge --classic
+```
+
+> Remember this is a tutorial. It is fine to add words to explain what is going
+on, why we are doing particular things, and what results one might expect. In
+some cases you may even want to deliberately manufacture an error to better
+illustrate how things work and how to solve problems.
+
+> It is often a good idea to include a summarising statement at the end,
+detailing the things the reader should now know about. This isn't entirely a
+self-congratulatory exercise - it is an aid to learning an retention. It
+doesn't have to be long or detailed. For example:
+
+---
+
+Congratulations you have now completed the tutorial. We found out how to
+install the Kubernetes snap, how to change the configuration, deploy a
+workload and remove everything again!
+
+> Almost without exception you will then want to point the reader to other
+> tutorials or how to guides. Please include a "Next Steps" heading with a list
+> of links.
+
+## Next Steps
+
+- Keep mastering Canonical Kubernetes 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]
+- Master Kubernetes networking concepts: [Networking]
+- Discover how to enable and configure Ingress resources [Ingress]
+
+---
+
+> Note that the links throughout should always be by reference. Your document
+should end with a list of these links. This makes it 2000 times easier to
+maintain the document and update the links when necessary!
+
+Note the different type of links:
+
+- for pages in the same category, you can just use the name (not including the
+  file extension)
+- for pages in a different category, it is better to use the full path(relative
+  to the /docs/src/)
+- external links are straightforward
+
+<!-- LINKS -->
+
+[How to use kubectl]: kubectl
+[Command Reference Guide]: /snap/reference/commands
+[Ingress]: http://www.example.com
+

docs/src/snap/howto/contribute.md

@@ -97,6 +97,14 @@ Every page of documentation should fit into one of those categories. If it
 doesn't you may consider if it is actually two pages (e.g. a How to *and* an
 explanation).
 
+We have included some tips and outlines of the different types of docs we 
+create to help you get started:
+
+- [Tutorial template][]
+- [How to template][]
+- [Explanation template][]
+- [Reference template][]
+
 ### Small changes
 
 If you are simply correcting a typo or updating a link, you can follow the
@@ -140,3 +148,7 @@ press `F5` in your browser to reload the page without caching)!
 [Diátaxis website]: https://diataxis.fr/
 [_parts]: https://github.com/canonical/k8s-snap/blob/main/docs/src/_parts/doc-cheat-sheet-myst.md
 [community page]: ../reference/community
+[Tutorial template]: https://raw.githubusercontent.com/canonical/k8s-snap/main/docs/src/_parts/template-tutorial
+[How to template]: https://raw.githubusercontent.com/canonical/k8s-snap/main/docs/src/_parts/template-howto
+[Explanation template]: https://raw.githubusercontent.com/canonical/k8s-snap/main/docs/src/_parts/template-explanation
+[Reference template]: https://raw.githubusercontent.com/canonical/k8s-snap/main/docs/src/_parts/template-reference

src/k8s/pkg/client/helm/chart.go

@@ -0,0 +1,14 @@
+package helm
+
+// InstallableChart describes a chart that can be deployed on a running cluster.
+type InstallableChart struct {
+	// Name is the install name of the chart.
+	Name string
+
+	// Namespace is the namespace to install the chart.
+	Namespace string
+
+	// ManifestPath is the path to the chart's manifest, typically relative to "$SNAP/k8s/manifests".
+	// TODO(neoaggelos): this should be a *chart.Chart, and we should use the "embed" package to load it when building k8sd.
+	ManifestPath string
+}