Adding first commit for k3s-docs

Signed-off-by: Divya Mohan <[email protected]>

.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

README.md

@@ -1 +1,41 @@
-# docs
+# Website
+
+This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
+
+### Installation
+
+```
+$ yarn
+```
+
+### Local Development
+
+```
+$ yarn start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+### Build
+
+```
+$ yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+### Deployment
+
+Using SSH:
+
+```
+$ USE_SSH=true yarn deploy
+```
+
+Not using SSH:
+
+```
+$ GIT_USER=<Your GitHub username> 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.

babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};

docs/architecture/architecture.md

@@ -0,0 +1,61 @@
+---
+title: Architecture
+weight: 1
+---
+
+import Figure from '../figure'
+
+This page describes the architecture of a high-availability K3s server cluster and how it differs from a single-node server cluster.
+
+It also describes how agent nodes are registered with K3s servers.
+
+A server node is defined as a machine (bare-metal or virtual) running the `k3s server` command. A worker node is defined as a machine running the `k3s agent` command.
+
+This page covers the following topics:
+
+- [Single-server setup with an embedded database](#single-server-setup-with-an-embedded-db)
+- [High-availability K3s server with an external database](#high-availability-k3s-server-with-an-external-db)
+  - [Fixed registration address for agent nodes](#fixed-registration-address-for-agent-nodes)
+- [How agent node registration works](#how-agent-node-registration-works)
+- [Automatically deployed manifests](#automatically-deployed-manifests)
+
+### Single-server Setup with an Embedded DB
+
+The following diagram shows an example of a cluster that has a single-node K3s server with an embedded SQLite database.
+
+In this configuration, each agent node is registered to the same server node. A K3s user can manipulate Kubernetes resources by calling the K3s API on the server node.
+
+<Figure caption="K3s Architecture with a Single Server" src="/img/k3s-architecture-single-server.png" />
+
+### High-Availability K3s Server with an External DB
+
+Single server clusters can meet a variety of use cases, but for environments where uptime of the Kubernetes control plane is critical, you can run K3s in an HA configuration. An HA K3s cluster is comprised of:
+
+* Two or more **server nodes** that will serve the Kubernetes API and run other control plane services
+* An **external datastore** (as opposed to the embedded SQLite datastore used in single-server setups)
+
+<Figure caption="K3s Architecture with a High-availability Server" src="/img/k3s-architecture-ha-server.png" />
+
+### Fixed Registration Address for Agent Nodes
+
+In the high-availability server configuration, each node must also register with the Kubernetes API by using a fixed registration address, as shown in the diagram below.
+
+After registration, the agent nodes establish a connection directly to one of the server nodes.
+
+<Figure caption="k3s HA" src="/img/k3s-production-setup.svg" />
+
+### How Agent Node Registration Works
+
+Agent nodes are registered with a websocket connection initiated by the `k3s agent` process, and the connection is maintained by a client-side load balancer running as part of the agent process.
+
+Agents will register with the server using the node cluster secret along with a randomly generated password for the node, stored at `/etc/rancher/node/password`. The server will store the passwords for individual nodes as Kubernetes secrets, and any subsequent attempts must use the same password. Node password secrets are stored in the `kube-system` namespace with names using the template `<host>.node-password.k3s`.
+
+Note: Prior to K3s v1.20.2 servers stored passwords on disk at `/var/lib/rancher/k3s/server/cred/node-passwd`.
+
+If the `/etc/rancher/node` directory of an agent is removed, the password file should be recreated for the agent, or the entry removed from the server.
+
+A unique node ID can be appended to the hostname by launching K3s servers or agents using the `--with-node-id` flag.
+
+### Automatically Deployed Manifests
+
+The [manifests](https://github.com/rancher/k3s/tree/master/manifests) located at the directory path `/var/lib/rancher/k3s/server/manifests` are bundled into the K3s binary at build time.  These will be installed at runtime by the [rancher/helm-controller.](https://github.com/rancher/helm-controller#helm-controller)

docs/backup-restore/backup-restore.md

@@ -0,0 +1,143 @@
+---
+title: Backup and Restore
+weight: 26
+---
+
+The way K3s is backed up and restored depends on which type of datastore is used.
+
+- [Backup and Restore with External Datastore](#backup-and-restore-with-external-datastore)
+- [Backup and Restore with Embedded etcd Datastore (Experimental)](#backup-and-restore-with-embedded-etcd-datastore-experimental)
+
+### Backup and Restore with External Datastore
+
+When an external datastore is used, backup and restore operations are handled outside of K3s. The database administrator will need to back up the external database, or restore it from a snapshot or dump.
+
+We recommend configuring the database to take recurring snapshots.
+
+For details on taking database snapshots and restoring your database from them, refer to the official database documentation:
+
+- [Official MySQL documentation](https://dev.mysql.com/doc/refman/8.0/en/replication-snapshot-method.html)
+- [Official PostgreSQL documentation](https://www.postgresql.org/docs/8.3/backup-dump.html)
+- [Official etcd documentation](https://etcd.io/docs/latest/op-guide/recovery/)
+
+### Backup and Restore with Embedded etcd Datastore (Experimental)
+
+_Available as of v1.19.1+k3s1_
+
+In this section, you'll learn how to create backups of the K3s cluster data and to restore the cluster from backup.
+
+>**Note on Single-Server with embedded SQLite:** Currently, backups of SQLite are not supported. Instead, make a copy of `/var/lib/rancher/k3s/server` and then delete K3s. 
+
+#### Creating Snapshots
+
+Snapshots are enabled by default.
+
+The snapshot directory defaults to `${data-dir}/server/db/snapshots`. The data-dir value defaults to `/var/lib/rancher/k3s` and can be changed by setting the `--data-dir` flag.
+
+To configure the snapshot interval or the number of retained snapshots, refer to the [options.](#options)
+
+#### Restoring a Cluster from a Snapshot
+
+When K3s is restored from backup, the old data directory will be moved to `${data-dir}/server/db/etcd-old/`. Then K3s will attempt to restore the snapshot by creating a new data directory, then starting etcd with a new K3s cluster with one etcd member.
+
+To restore the cluster from backup, run K3s with the `--cluster-reset` option, with the `--cluster-reset-restore-path` also given:
+
+```
+./k3s server \
+  --cluster-reset \
+  --cluster-reset-restore-path=<PATH-TO-SNAPSHOT>
+```
+
+**Result:**  A message in the logs says that K3s can be restarted without the flags. Start k3s again and should run successfully and be restored from the specified snapshot.
+
+#### Options
+
+These options can be passed in with the command line, or in the [configuration file,](/installation/install-options/#configuration-file ) which may be easier to use.
+
+| Options | Description |
+| ----------- | --------------- |
+| `--etcd-disable-snapshots` | Disable automatic etcd snapshots |
+| `--etcd-snapshot-schedule-cron` value  |  Snapshot interval time in cron spec. eg. every 5 hours `0 */5 * * *`(default: `0 */12 * * *`) |
+| `--etcd-snapshot-retention` value  | Number of snapshots to retain (default: 5) |
+| `--etcd-snapshot-dir` value  | Directory to save db snapshots. (Default location: `${data-dir}/db/snapshots`) |
+| `--cluster-reset`  | Forget all peers and become sole member of a new cluster. This can also be set with the environment variable `[$K3S_CLUSTER_RESET]`.
+| `--cluster-reset-restore-path` value | Path to snapshot file to be restored
+
+#### S3 Compatible API Support
+
+K3s supports writing etcd snapshots to and restoring etcd snapshots from systems with S3-compatible APIs. S3 support is available for both on-demand and scheduled snapshots.
+
+The arguments below have been added to the `server` subcommand. These flags exist for the `etcd-snapshot` subcommand as well however the `--etcd-s3` portion is removed to avoid redundancy.
+
+| Options | Description |
+| ----------- | --------------- |
+| `--etcd-s3` | Enable backup to S3 |
+| `--etcd-s3-endpoint` | S3 endpoint url |
+| `--etcd-s3-endpoint-ca` | S3 custom CA cert to connect to S3 endpoint |
+| `--etcd-s3-skip-ssl-verify` | Disables S3 SSL certificate validation |
+| `--etcd-s3-access-key` |  S3 access key |
+| `--etcd-s3-secret-key` | S3 secret key" |
+| `--etcd-s3-bucket` | S3 bucket name |
+| `--etcd-s3-region` | S3 region / bucket location (optional). defaults to us-east-1 |
+| `--etcd-s3-folder` | S3 folder |
+
+To perform an on-demand etcd snapshot and save it to S3:
+
+```
+k3s etcd-snapshot \
+  --s3 \
+  --s3-bucket=<S3-BUCKET-NAME> \
+  --s3-access-key=<S3-ACCESS-KEY> \
+  --s3-secret-key=<S3-SECRET-KEY>
+```
+
+To perform an on-demand etcd snapshot restore from S3, first make sure that K3s isn't running. Then run the following commands:
+
+```
+k3s server \
+  --cluster-init \
+  --cluster-reset \
+  --etcd-s3 \
+  --cluster-reset-restore-path=<SNAPSHOT-NAME> \
+  --etcd-s3-bucket=<S3-BUCKET-NAME> \
+  --etcd-s3-access-key=<S3-ACCESS-KEY> \
+  --etcd-s3-secret-key=<S3-SECRET-KEY>
+```
+
+#### Etcd Snapshot and Restore Subcommands
+
+k3s supports a set of subcommands for working with your etcd snapshots.
+
+| Subcommand | Description |
+| ----------- | --------------- |
+| delete      |  Delete given snapshot(s) |
+| ls, list, l |  List snapshots |
+| prune       |  Remove snapshots that exceed the configured retention count |
+| save        |  Trigger an immediate etcd snapshot |
+
+*note* The `save` subcommand is the same as `k3s etcd-snapshot`. The latter will eventually be deprecated in favor of the former.
+
+These commands will perform as expected whether the etcd snapshots are stored locally or in an S3 compatible object store.
+
+For additional information on the etcd snapshot subcommands, run `k3s etcd-snapshot`.
+
+Delete a snapshot from S3.
+
+```
+k3s etcd-snapshot delete          \
+  --s3                            \
+  --s3-bucket=<S3-BUCKET-NAME>    \
+  --s3-access-key=<S3-ACCESS-KEY> \
+  --s3-secret-key=<S3-SECRET-KEY> \
+  <SNAPSHOT-NAME>
+```
+
+Prune local snapshots with the default retention policy (5). The `prune` subcommand takes an additional flag `--snapshot-retention` that allows for overriding the default retention policy.
+
+```
+k3s etcd-snapshot prune
+```
+
+```
+k3s etcd-snapshot prune --snapshot-retention 10
+```

docs/cluster-access/cluster-access.md

@@ -0,0 +1,25 @@
+---
+title: Cluster Access
+weight: 21
+---
+
+The kubeconfig file stored at `/etc/rancher/k3s/k3s.yaml` is used to configure access to the Kubernetes cluster. If you have installed upstream Kubernetes command line tools such as kubectl or helm you will need to configure them with the correct kubeconfig path. This can be done by either exporting the `KUBECONFIG` environment variable or by invoking the `--kubeconfig` command line flag. Refer to the examples below for details.
+
+Leverage the KUBECONFIG environment variable:
+
+```
+export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
+kubectl get pods --all-namespaces
+helm ls --all-namespaces
+```
+
+Or specify the location of the kubeconfig file in the command:
+
+```
+kubectl --kubeconfig /etc/rancher/k3s/k3s.yaml get pods --all-namespaces
+helm --kubeconfig /etc/rancher/k3s/k3s.yaml ls --all-namespaces
+```
+
+### Accessing the Cluster from Outside with kubectl
+
+Copy `/etc/rancher/k3s/k3s.yaml` on your machine located outside the cluster as `~/.kube/config`. Then replace the value of the `server` field with the IP or name of your K3s server. `kubectl` can now manage your K3s cluster.

docs/faq/faq.md

@@ -0,0 +1,30 @@
+---
+title: FAQ
+weight: 60
+---
+
+The FAQ is updated periodically and designed to answer the questions our users most frequently ask about K3s.
+
+**Is K3s a suitable replacement for k8s?**
+
+K3s is capable of nearly everything k8s can do. It is just a more lightweight version. See the [main](/) docs page for more details.
+
+**How can I use my own Ingress instead of Traefik?**
+
+Simply start K3s server with `--disable traefik` and deploy your ingress.
+
+**Does K3s support Windows?**
+
+At this time K3s does not natively support Windows, however we are open to the idea in the future.
+
+**How can I build from source?**
+
+Please reference the K3s [BUILDING.md](https://github.com/rancher/k3s/blob/master/BUILDING.md) with instructions.
+
+**Where are the K3s logs?**
+
+The installation script will auto-detect if your OS is using systemd or openrc and start the service.
+
+When running with openrc, logs will be created at `/var/log/k3s.log`.
+
+When running with systemd, logs will be created in `/var/log/syslog` and viewed using `journalctl -u k3s`.

docs/figure.jsx

@@ -0,0 +1,11 @@
+import React from 'react'
+import useBaseUrl from '@docusaurus/useBaseUrl'
+
+export default function Figure({ src, caption }) {
+  return (
+    <figure style={{ border: '1px solid #888', padding: 20 }}>
+      <img src={useBaseUrl(src)} alt={caption} />
+      <figcaption>{`Figure: ${caption}`}</figcaption>
+    </figure>
+  )
+}