Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Reorder explanation index, ensure header style consistency #978

Merged
merged 1 commit into from
Jan 20, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 10 additions & 5 deletions docs/src/snap/explanation/certificates.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ In Kubernetes, [X.509][] certificates are primarily used for
[Transport Layer Security][] (TLS), securing the communication between the
cluster's components.

## What Is a Certificate Refresh?
## What is a certificate refresh?

A certificate refresh in {{product}} refers to the process of renewing or
rotating certificates before they expire. Kubernetes certificates have
Expand All @@ -22,13 +22,13 @@ entire cluster.
Regular certificate refreshes ensure that the certificates in use are valid and
secure, preventing unauthorised access or communication failures.

## Importance of Certificate Refreshes
## Importance of certificate refreshes

Regularly refreshing certificates in Kubernetes is essential for maintaining
the reliability of the cluster. Here are some reasons why certificate refreshes
are important:

### Maintaining Cluster Security
### Maintaining cluster security

Certificates are crucial for securing Kubernetes clusters, ensuring encrypted
and authenticated communication between components. If a certificate expires
Expand All @@ -37,23 +37,28 @@ risks, potentially exposing it to unauthorised access. Regular certificate
refreshes prevent this by ensuring only valid certificates are used,
maintaining the cluster's security.

### Preventing Downtime
### Preventing downtime

Kubernetes relies on certificates for internal communication between critical
components, such as the kubelet, API server, and datastore. Expired
certificates can hinder this communication, leading to potential downtime and
workload disruptions. Proactively refreshing certificates before they expire
helps maintain uninterrupted cluster operations.

### Security Compliance
### Security compliance

Security standards, such as [CIS][], often require the regular rotation of
credentials, including certificates. Periodically renewing Kubernetes
certificates ensures that the cluster meets security standards and compliance
requirements.

## Performing certificate refreshes

If you would like to refresh the certificates of your {{product}} cluster see our [how-to guide].

<!-- LINKS -->

[CIS]: https://www.cisecurity.org/controls
[Transport Layer Security]: https://datatracker.ietf.org/doc/html/rfc8446
[X.509]: https://datatracker.ietf.org/doc/html/rfc5280
[how-to guide]: ../howto/refresh-certs
8 changes: 4 additions & 4 deletions docs/src/snap/explanation/channels.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,8 @@ 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 {{product}}
specifying the `1.32` track will match upstream releases of the same minor
version ("1.32.0", "1.32.1", "1.32.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:
Expand Down Expand Up @@ -43,7 +43,7 @@ More information can be found in the [Snapcraft documentation][]
## Updates and switching channels

Updates for upstream patch releases will happen automatically by default. For
example, if you have selected the channel `1.30/stable`, your snap will refresh
example, if you have selected the channel `1.32-classic/stable`, your snap will refresh
itself regularly keeping your cluster up-to-date with the latest patches.
For deployments where this behaviour is undesirable you are given the option to
postpone, schedule or even block automatic updates.
Expand All @@ -69,7 +69,7 @@ factors. We can give some general guidance for the following cases:
- **I want to always be on the latest stable version matching a specific
upstream K8s release (recommended).**

Specify the release, for example: `--channel=1.30/stable`.
Specify the release, for example: `--channel=1.32-classic/stable`.

- **I want to test-drive a pre-stable release**

Expand Down
6 changes: 3 additions & 3 deletions docs/src/snap/explanation/cis.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ primary goal of CIS hardening is to reduce the attack surface and enhance the
overall security posture of an environment by enforcing configurations that are
known to protect against common vulnerabilities and threats.

## Why is CIS Hardening Important for Kubernetes?
## Why is CIS hardening important for Kubernetes?

Kubernetes, by its nature, is a complex system with many components interacting
in a distributed environment. This complexity can introduce numerous security
Expand All @@ -17,12 +17,12 @@ service disruption. CIS hardening for Kubernetes focuses on configuring various
components of a Kubernetes cluster to meet the security standards specified in
the [CIS Kubernetes Benchmark].

## Apply CIS Hardening to {{product}}
## Apply CIS hardening to {{product}}

If you would like to apply CIS hardening to your cluster see our [how-to guide].

<!-- LINKS -->
[benchmarks]: https://www.cisecurity.org/cis-benchmarks
[Center for Internet Security]: https://www.cisecurity.org/
[CIS Kubernetes Benchmark]: https://www.cisecurity.org/benchmark/kubernetes
[how-to guide]: ../howto/cis-hardening.md
[how-to guide]: ../howto/cis-hardening.md
10 changes: 5 additions & 5 deletions docs/src/snap/explanation/clustering.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ scalability. In {{product}} the addition of `k8sd` to the Kubernetes
ecosystem introduces enhanced capabilities for cluster coordination and
management.

## Kubernetes Cluster Topology
## Kubernetes cluster topology

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
Expand All @@ -20,7 +20,7 @@ This is the overview of a {{product}} cluster:

![cluster6][]

## The Role of `k8sd` in Kubernetes Clustering
## The role of `k8sd` in Kubernetes clustering

`k8sd` plays a vital role in the {{product}} architecture, enhancing
the functionality of both the Control Plane and Worker nodes through the use
Expand All @@ -29,12 +29,12 @@ adding or removing nodes and integrating them into the cluster. It also
manages essential features like DNS and networking within the cluster,
streamlining the entire process for a more efficient operation.

## Integration into the Kubernetes Cluster Topology
## Integration into the Kubernetes cluster topology

For {{product}}, the detailed view of the two types of node is as
follows:

### Control Plane Node
### Control plane node

The control plane node orchestrates the cluster, making decisions about
scheduling, deployment and management. With the addition of `k8sd`, the control
Expand All @@ -53,7 +53,7 @@ plane node's components include:
- **k8sd**: Implements and exposes the operations functionality needed for
managing the Kubernetes cluster.

### Worker Node
### Worker node

Worker nodes are responsible for running the applications and workloads. Worker
nodes, can interact with the `k8sd` API, gaining capabilities to manage its
Expand Down
4 changes: 2 additions & 2 deletions docs/src/snap/explanation/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,13 +13,13 @@ Overview <self>
:titlesonly:
about
installation-methods.md
certificates
channels
clustering
high-availability
certificates
ingress
load-balancer
epa
high-availability
security
cis
```
Expand Down
2 changes: 1 addition & 1 deletion docs/src/snap/explanation/ingress.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ please follow the [alternative-cni] guide.

Learn how to use the {{product}} default network in the [networking how-to guide][Network].

## Kubernetes Pods and Services
## Kubernetes pods and services

In Kubernetes, the smallest unit is a pod, which encapsulates application containers.
Since pods are ephemeral and their IP addresses change when destroyed and restarted,
Expand Down
4 changes: 2 additions & 2 deletions docs/src/snap/explanation/security.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@ useful.
- [Microsoft Azure security][]
- [VMware VSphere hardening guides][]

## Security Compliance
## Security compliance

As with previously released Kubernetes software from Canonical, we aim to
satisfy the needs of various security compliance standards. This is a process
Expand All @@ -64,7 +64,7 @@ check the [roadmap][] for current areas of work.
[rocks-security]: https://canonical-rockcraft.readthedocs-hosted.com/en/latest/explanation/rockcraft/
[roadmap]: ../reference/roadmap
[Amazon Web Services security]: https://aws.amazon.com/security/
[Google Cloud Platform security]:https://cloud.google.com/security/
[Google Cloud Platform security]:https://cloud.google.com/security
[Metal As A Service(MAAS) hardening]:https://maas.io/docs/how-to-enhance-maas-security
[Microsoft Azure security]:https://docs.microsoft.com/en-us/azure/security/azure-security
[VMware VSphere hardening guides]: https://www.vmware.com/security/hardening-guides.html
Loading