From 3cdba293661735f278fa6a3188958d313701d819 Mon Sep 17 00:00:00 2001 From: Derek Nola Date: Wed, 7 Sep 2022 15:09:23 -0700 Subject: [PATCH] Fix Automatic Markdown Sidebar (#20) * Convert header 1 markdown anchors * Add vscode to gitignore * Update the README Signed-off-by: Derek Nola --- .gitignore | 1 + README.md | 20 +++++--------------- docs/installation/airgap.md | 8 ++++---- docs/installation/disable-flags.md | 8 ++++---- docs/installation/ha.md | 2 +- docs/installation/private-registry.md | 4 ++-- docs/networking/networking.md | 8 ++++---- docs/reference/resource-profiling.md | 12 ++++++------ 8 files changed, 27 insertions(+), 36 deletions(-) diff --git a/.gitignore b/.gitignore index b2d6de306..2b7f59dd6 100644 --- a/.gitignore +++ b/.gitignore @@ -14,6 +14,7 @@ .env.development.local .env.test.local .env.production.local +.vscode npm-debug.log* yarn-debug.log* diff --git a/README.md b/README.md index ef50edb3f..3872242bb 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,8 @@ -# Website +# K3s Website and Docs -This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator. +This repo contains the content of the K3s landing page and documentation. Please open an issue if you have suggestions for new content or edits. We also gladly accept community PRs. + +The website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator. ### Installation @@ -31,16 +33,4 @@ This command generates static content into the `build` directory and can be serv ### Deployment -Using SSH: - -``` -$ USE_SSH=true yarn deploy -``` - -Not using SSH: - -``` -$ GIT_USER= yarn deploy -``` - -If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch. +An automated GH action will deploy the website to GitHub Pages once a PR has been merged to `main`. diff --git a/docs/installation/airgap.md b/docs/installation/airgap.md index 0e25a3e9c..34563b148 100644 --- a/docs/installation/airgap.md +++ b/docs/installation/airgap.md @@ -7,7 +7,7 @@ import TabItem from '@theme/TabItem'; You can install K3s in an air-gapped environment using two different methods. An air-gapped environment is any environment that is not directly connected to the Internet. You can either deploy a private registry and mirror docker.io, or you can manually deploy images such as for small clusters. -# Private Registry Method +## Private Registry Method This document assumes you have already created your nodes in your air-gap environment and have a Docker private registry on your bastion host. @@ -20,7 +20,7 @@ Follow the [Private Registry Configuration](private-registry.md) guide to create Once you have completed this, you may now go to the [Install K3s](#install-k3s) section below. -# Manually Deploy Images Method +## Manually Deploy Images Method We are assuming you have created your nodes in your air-gap environment. This method requires you to manually deploy the necessary images to each node and is appropriate for edge deployments where running a private registry is not practical. @@ -39,7 +39,7 @@ Place the k3s binary at `/usr/local/bin/k3s` and ensure it is executable. Follow the steps in the next section to install K3s. -# Install K3s +## Install K3s ### Prerequisites @@ -92,7 +92,7 @@ INSTALL_K3S_SKIP_DOWNLOAD=true INSTALL_K3S_EXEC='server' K3S_DATASTORE_ENDPOINT= >**Note:** K3s additionally provides a `--resolv-conf` flag for kubelets, which may help with configuring DNS in air-gap networks. -# Upgrading +## Upgrading ### Install Script Method diff --git a/docs/installation/disable-flags.md b/docs/installation/disable-flags.md index b4d45ebda..6ffe4d078 100644 --- a/docs/installation/disable-flags.md +++ b/docs/installation/disable-flags.md @@ -5,7 +5,7 @@ weight: 60 Starting the K3s server with `--cluster-init` will run all control plane components, including the api server, controller manager, scheduler, and etcd. However, you can run server nodes with certain components and exclude others; the following sections will explain how to do that. -# ETCD Only Nodes +## ETCD Only Nodes This document assumes you run K3s server with embedded etcd by passing `--cluster-init` flag to the server process. @@ -17,7 +17,7 @@ curl -fL https://get.k3s.io | sh -s - server --cluster-init --disable-apiserver You can join other nodes to the cluster normally after that. -# Disable ETCD +## Disable ETCD You can also disable etcd from a server node and this will result in a k3s server running control components other than etcd, that can be accomplished by running k3s server with flag `--disable-etcd` for example to join another node with only control components to the etcd node created in the previous section: @@ -55,7 +55,7 @@ ip-172-31-14-69 Ready control-plane,master 5h45m v1.20.4+k3s1 Notice that role labels has been re-added to the node `ip-172-31-13-32` with the correct labels (control-plane,etcd,master). -# Add disable flags using the config file +## Add disable flags using the config file In any of the previous situations you can use the config file instead of running the curl commands with the associated flags, for example to run an etcd only node you can add the following options to the `/etc/rancher/k3s/config.yaml` file: @@ -71,7 +71,7 @@ and then start K3s using the curl command without any arguents: ```bash curl -fL https://get.k3s.io | sh - ``` -# Disable components using .skip files +## Disable components using .skip files For any yaml file under `/var/lib/rancher/k3s/server/manifests` (coredns, traefik, local-storeage, etc.) you can add a `.skip` file which will cause K3s to not apply the associated yaml file. For example, adding `traefik.yaml.skip` in the manifests directory will cause K3s to skip `traefik.yaml`. diff --git a/docs/installation/ha.md b/docs/installation/ha.md index e0fa20486..bd2a71558 100644 --- a/docs/installation/ha.md +++ b/docs/installation/ha.md @@ -18,7 +18,7 @@ For more details on how these components work together, refer to the [architectu Agents register through the fixed registration address, but after registration they establish a connection directly to one of the server nodes. This is a websocket connection initiated by the `k3s agent` process and it is maintained by a client-side load balancer running as part of the agent process. -# Installation Outline +## Installation Outline Setting up an HA cluster requires the following steps: diff --git a/docs/installation/private-registry.md b/docs/installation/private-registry.md index 84d56696f..8e6e01b5e 100644 --- a/docs/installation/private-registry.md +++ b/docs/installation/private-registry.md @@ -13,7 +13,7 @@ Note that server nodes are schedulable by default. If you have not tainted the s Configuration in containerd can be used to connect to a private registry with a TLS connection and with registries that enable authentication as well. The following section will explain the `registries.yaml` file and give different examples of using private registry configuration in K3s. -# Registries Configuration File +## Registries Configuration File The file consists of two main sections: @@ -149,7 +149,7 @@ mirrors: In order for the registry changes to take effect, you need to restart K3s on each node. -# Adding Images to the Private Registry +## Adding Images to the Private Registry First, obtain the k3s-images.txt file from GitHub for the release you are working with. Pull the K3s images listed on the k3s-images.txt file from docker.io diff --git a/docs/networking/networking.md b/docs/networking/networking.md index 3c38c481f..914c76e2e 100644 --- a/docs/networking/networking.md +++ b/docs/networking/networking.md @@ -18,13 +18,13 @@ For information on which ports need to be opened for K3s, refer to the [ Require - [Disabling the Service LB](#disabling-the-service-lb) - [Nodes Without a Hostname](#nodes-without-a-hostname) -# CoreDNS +## CoreDNS CoreDNS is deployed on start of the agent. To disable, run each server with the `--disable coredns` option. If you don't install CoreDNS, you will need to install a cluster DNS provider yourself. -# Traefik Ingress Controller +## Traefik Ingress Controller [Traefik](https://traefik.io/) is a modern HTTP reverse proxy and load balancer made to deploy microservices with ease. It simplifies networking complexity while designing, deploying, and running applications. @@ -40,7 +40,7 @@ If Traefik is not disabled K3s versions 1.20 and earlier will install Traefik v1 To migrate from an older Traefik v1 instance please refer to the [Traefik documentation](https://doc.traefik.io/traefik/migration/v1-to-v2/) and [migration tool](https://github.com/traefik/traefik-migration-tool). -# Service Load Balancer +## Service Load Balancer Any service load balancer (LB) can be leveraged in your Kubernetes cluster. K3s provides a load balancer known as [Klipper Load Balancer](https://github.com/k3s-io/klipper-lb) that uses available host ports. @@ -82,6 +82,6 @@ To disable the embedded LB, run the server with the `--disable servicelb` option This is necessary if you wish to run a different LB, such as MetalLB. -# Nodes Without a Hostname +## Nodes Without a Hostname Some cloud providers, such as Linode, will create machines with "localhost" as the hostname and others may not have a hostname set at all. This can cause problems with domain name resolution. You can run K3s with the `--node-name` flag or `K3S_NODE_NAME` environment variable and this will pass the node name to resolve this issue. diff --git a/docs/reference/resource-profiling.md b/docs/reference/resource-profiling.md index 53866c533..ac550a78c 100644 --- a/docs/reference/resource-profiling.md +++ b/docs/reference/resource-profiling.md @@ -29,14 +29,14 @@ The results are summarized as follows: - [Primary Resource Utilization Drivers](#primary-resource-utilization-drivers) - [Preventing Agents and Workloads from Interfering with the Cluster Datastore](#preventing-agents-and-workloads-from-interfering-with-the-cluster-datastore) -# Scope of Resource Testing +## Scope of Resource Testing The resource tests were intended to address the following problem statements: - On a single-node cluster, determine the legitimate minimum amount of CPU, memory, and IOPs that should be set aside to run the entire K3s stack server stack, assuming that a real workload will be deployed on the cluster. - On an agent (worker) node, determine the legitimate minimum amount of CPU, memory, and IOPs that should be set aside for the Kubernetes and K3s control plane components (the kubelet and k3s agent). -# Components Included for Baseline Measurements +## Components Included for Baseline Measurements The tested components are: @@ -48,7 +48,7 @@ These are baseline figures for a stable system using only K3s packaged component Resource figures including IOPS are for the Kubernetes datastore and control plane only, and do not include overhead for system-level management agents or logging, container image management, or any workload-specific requirements. -# Methodology +## Methodology A standalone instance of Prometheus v2.21.0 was used to collect host CPU, memory, and disk IO statistics using `prometheus-node-exporter` installed via apt. @@ -58,7 +58,7 @@ Additional detailed K3s memory utilization data was collected from the `process_ Utilization figures were based on 95th percentile readings from steady state operation on nodes running the described workloads. -# Environment +## Environment OS: Ubuntu 20.04 x86_64, aarch64 @@ -67,7 +67,7 @@ Hardware: - AWS c5d.xlarge - 4 core, 8 GB RAM, NVME SSD - Raspberry Pi 4 Model B - 4 core, 8 GB RAM, Class 10 SDHC -# Baseline Resource Requirements +## Baseline Resource Requirements This section captures the results of tests to determine minimum resource requirements for the K3s agent, the K3s server with a workload, and the K3s server with one agent. @@ -118,7 +118,7 @@ The CPU requirements are: 256 M of RAM is required. -# Analysis +## Analysis This section captures what has the biggest impact on K3s server and agent utilization, and how the cluster datastore can be protected from interference from agents and workloads.