Skip to content

Commit

Permalink
Docs: readthedocs tidyup (#162)
Browse files Browse the repository at this point in the history
* rtd config and links
  • Loading branch information
evilnick authored Feb 27, 2024
1 parent a6e1a8b commit 38c865f
Show file tree
Hide file tree
Showing 8 changed files with 79 additions and 36 deletions.
2 changes: 2 additions & 0 deletions docs/src/howto/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,8 @@ Overview <self>

```{toctree}
:glob:
:titlesonly:
install/index
/howto/contribute
/howto/support
Expand Down
3 changes: 3 additions & 0 deletions docs/src/howto/install/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,9 @@
Install <self>
```

There's more than one way to install Canonical Kubernetes. You'll find links to the current How-to guides below.


```{toctree}
:glob:
:titlesonly:
Expand Down
2 changes: 1 addition & 1 deletion docs/src/howto/install/multipass.md
Original file line number Diff line number Diff line change
@@ -1 +1 @@
# Installing with Multipass
# Install with Multipass (Ubuntu/Mac/Windows)
88 changes: 62 additions & 26 deletions docs/src/reference/architecture.md
Original file line number Diff line number Diff line change
@@ -1,27 +1,51 @@
# Architecture

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].
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].

## System context

This overview of Canonical Kubernetes demonstrates the interactions of Kubernetes with users and with other systems.
This overview of Canonical Kubernetes demonstrates the interactions of
Kubernetes with users and with other systems.

```{kroki} ../assets/overview.puml
```

Two actors interact with the Kubernetes snap:

- **K8s admin**: The administrator of the cluster interacts directly with the Kubernetes API server. Out of the box our K8s distribution offers admin access to the cluster. That initial user is able to configure the cluster to match their needs and of course create other users that may or may not have the same privileges. The K8s admin is also able to maintain workloads running in the cluster.

- **K8s user**: A user consuming the services hosted in the cluster. Users do not have access to the Kubernetes API server. They need to access the cluster through the options (nodeport, ingress, load-balancer) offered by the administrator who deployed the workload they are interested in.

There are non-human users of the K8s snap, for example the [`k8s-operator charm`][K8s charm]. The K8s charm needs to drive the Kubernetes cluster and to orchestrate the multi-node clustering operations.

A set of external systems need to be easily integrated with our K8s distribution. We have identified the following:
- **Loadbalancer**: Although the K8s snap distribution comes with a loadbalancer we expect the end customer environment to have a loadbalancer and thus we need to integrate with it.
- **Storage**: Kubernetes typically expects storage to be external to the cluster. The K8s snap comes with a local storage option but we still need to offer proper integration with any storage solution.
- **Identity management**: Out of the box the K8s snap offers credentials for an admin user. The admin user can complete the integration with any identity management system available or do user management manually.
- **External datastore**: By default, Kubernetes uses etcd to keep track of state. Our K8s snap comes with `dqlite` as its datastore. We should however be able to use any end client owned datastore installation. That should include an external `postgresql` or `etcd`.
- **K8s admin**: The administrator of the cluster interacts directly with the
Kubernetes API server. Out of the box our K8s distribution offers admin
access to the cluster. That initial user is able to configure the cluster to
match their needs and of course create other users that may or may not have
the same privileges. The K8s admin is also able to maintain workloads running
in the cluster.

- **K8s user**: A user consuming the services hosted in the cluster. Users do
not have access to the Kubernetes API server. They need to access the cluster
through the options (nodeport, ingress, load-balancer) offered by the
administrator who deployed the workload they are interested in.

There are non-human users of the K8s snap, for example the [`k8s-operator
charm`][K8s charm]. The K8s charm needs to drive the Kubernetes cluster and to
orchestrate the multi-node clustering operations.

A set of external systems need to be easily integrated with our K8s
distribution. We have identified the following:
- **Loadbalancer**: Although the K8s snap distribution comes with a
loadbalancer we expect the end customer environment to have a loadbalancer
and thus we need to integrate with it.
- **Storage**: Kubernetes typically expects storage to be external to the
cluster. The K8s snap comes with a local storage option but we still need to
offer proper integration with any storage solution.
- **Identity management**: Out of the box the K8s snap offers credentials for
an admin user. The admin user can complete the integration with any identity
management system available or do user management manually.
- **External datastore**: By default, Kubernetes uses etcd to keep track of
state. Our K8s snap comes with `dqlite` as its datastore. We should however
be able to use any end client owned datastore installation. That should
include an external `postgresql` or `etcd`.

## The k8s snap

Expand All @@ -32,22 +56,32 @@ Looking more closely at what is conatined within the K8s snap istelf:

The `k8s` snap distribution includes the following:

- **Kubectl**: through which users and other systems interact with Kubernetes and drive the cluster operations.
- **K8s upstream services**: These are Kubernetes binaries built from upstream and shipped in the snap.
- **Components** are the workloads and features we deem important to be available to our users and therefore are shipped in the snap and are enabled, configured and disabled in a guided way.
- State is backed up by **dqlite** by default, which keeps that state of the Kubernetes cluster as well as the state we maintain for the needs of the cluster operations. The cluster state may optionally be stored in a different, external datastore.
- **Kubectl**: through which users and other systems interact with Kubernetes
and drive the cluster operations.
- **K8s upstream services**: These are Kubernetes binaries built from upstream
and shipped in the snap.
- **Components** are the workloads and features we deem important to be
available to our users and therefore are shipped in the snap and are enabled,
configured and disabled in a guided way.
- State is backed up by **dqlite** by default, which keeps that state of the
Kubernetes cluster as well as the state we maintain for the needs of the
cluster operations. The cluster state may optionally be stored in a
different, external datastore.
- **Runtime**: `containerd` and `runc` are the shipped container runtimes.
- **K8sd**: which implements the operations logic and exposes that functionality via CLIs and REST APIs.
- **K8sd**: which implements the operations logic and exposes that
functionality via CLIs and REST APIs.

## K8sd

K8sd is the component that implements and exposes the operations functionality needed for managing the Kubernetes cluster.
K8sd is the component that implements and exposes the operations functionality
needed for managing the Kubernetes cluster.

```{kroki} ../assets/k8sd-component.puml
```

At the core of the `k8sd` functionality we have the components and cluster managers:
The components manager is responsible for the workload features we deem important for a Kubernetes cluster. Namely:
At the core of the `k8sd` functionality we have the components and cluster
managers: The components manager is responsible for the workload features we
deem important for a Kubernetes cluster. Namely:

- DNS
- CNI
Expand All @@ -57,15 +91,17 @@ The components manager is responsible for the workload features we deem importan
- local storage
- observability

The cluster manager is responsible for implementing the formation of the cluster. This includes operations such as joining/removing nodes into the cluster and reporting status.
The cluster manager is responsible for implementing the formation of the
cluster. This includes operations such as joining/removing nodes into the
cluster and reporting status.

This functionality is exposed via the following interfaces:

- The **CLI**: The CLI is available to only the root user on the K8s snap and all CLI commands are mapped to respective REST calls.

- The **API**: The JSON RPC API serves the CLI and is also used by the charm to programmatically drive the Kubernetes cluster.

- The **CLI**: The CLI is available to only the root user on the K8s snap and
all CLI commands are mapped to respective REST calls.

- The **API**: The JSON RPC API serves the CLI and is also used by the charm to
programmatically drive the Kubernetes cluster.

<!-- LINKS -->
[C4 model]: https://c4model.com/
Expand Down
1 change: 1 addition & 0 deletions docs/src/reference/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@ Overview <self>
/reference/releases
/reference/community
```
## Other documentation types

Alternatively, the [Tutorials section] contains step-by-step tutorials to help
guide you through exploring and using Canonical Kubernetes.
Expand Down
3 changes: 2 additions & 1 deletion docs/tools/.sphinx/_static/github_issue_links.js
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,8 @@ window.onload = function() {
link.href = (
github_url
+ "/issues/new?"
+ "title=docs%3A+TYPE+YOUR+QUESTION+HERE"
+ "title=Docs:+ADD+YOUR+TITLE"
+ "&labels=documentation"
+ "&body=*Please describe the question or issue you're facing with "
+ `"${document.title}"`
+ ".*"
Expand Down
8 changes: 4 additions & 4 deletions docs/tools/.sphinx/_templates/footer.html
Original file line number Diff line number Diff line change
Expand Up @@ -80,9 +80,9 @@
</div>
{% endif %}

{% if mattermost %}
<div class="ask-mattermost">
<a class="muted-link" href="{{ mattermost }}">Ask a question on Mattermost</a>
{% if matrix %}
<div class="ask-matrix">
<a class="muted-link" href="{{ matrix }}">Ask a question on Matrix</a>
</div>
{% endif %}

Expand All @@ -95,7 +95,7 @@
{% endif %}

<div class="edit-github">
<a class="muted-link" href="{{ github_url }}/edit/{{ github_version }}{{ github_folder }}{{ pagename }}{{ page_source_suffix }}">Edit this page on GitHub</a>
<a class="muted-link" href="{{ github_url }}/edit/{{ github_version }}{{ github_folder }}src/{{ pagename }}{{ page_source_suffix }}">Edit this page on GitHub</a>
</div>
{% endif %}

Expand Down
8 changes: 4 additions & 4 deletions docs/tools/custom_conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@
############################################################

# Product name
project = 'Canonical K8s'
project = 'Canonical Kubernetes'
author = 'Canonical Group Ltd'

# The title you want to display for the documentation in the sidebar.
Expand Down Expand Up @@ -47,7 +47,7 @@
## 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/'
ogp_site_url = 'https://documentation.ubuntu.com/canonical-kubernetes'
# 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
Expand Down Expand Up @@ -75,11 +75,11 @@
# 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',
'discourse': ' https://discourse.ubuntu.com/c/kubernetes/180',

# 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',
'matrix': 'https://matrix.to/#/#k8s:ubuntu.com',

# Change to the GitHub URL for your project
'github_url': 'https://github.com/canonical/k8s-snap',
Expand Down

0 comments on commit 38c865f

Please sign in to comment.