Mirrors/dokku
1
0
Fork 0
mirror of https://github.com/dokku/dokku.git synced 2025-12-29 00:25:08 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #6517 from dokku/josegonzalez-patch-1

Browse Source 
Remove k3s tutorial from documentation
This commit is contained in:
Jose Diaz-Gonzalez
2024-01-23 11:38:47 -05:00
committed by GitHub
parent 54a12c9c89 bbf9febe30
commit 4f26913e44
1 changed files with 0 additions and 132 deletions
Download Patch File Download Diff File Expand all files Collapse all files

132
docs/deployment/schedulers/k3s.md
View File

@@ -275,138 +275,6 @@ By default, Dokku assumes that all it controls all actions on the cluster, and t
dokku scheduler-k3s:show-kubeconfig
```
## Tutorial
### Single-node cluster
Initialize the cluster in single-node mode. This will start k3s on the Dokku node itself.
```shell
# must be run as root
dokku scheduler-k3s:initialize
```
The above command will initialize a cluster with the following configuration:
- etcd distributed backing store
- Wireguard as the networking flannel
- K3s automatic upgrader
- Longhorn distributed block storage
- Traefik configured to run on all nodes in the cluster
Additionally, an internal token for authentication will be automatically generated. This token should be stored securely for later recovery, and can be displayed with via the `scheduler-k3s:report` command:
```shell
dokku scheduler-k3s:report --global
```
```
=====> --global scheduler-k3s information
scheduler k3s token: topsecret:server:token
```
Setup registry authentication. The K3s scheduler plugin will automatically pick up any newly configured registry backends and ensure nodes in the cluster have the credentials in place for pulling images from the cluster.
```shell
# hub.docker.com
dokku registry:login hub.docker.com $USERNAME $PASSWORD
```
To ensure images are pushed and pulled from the correct registry, set the correct `server` registry property. This can be set on a per-app basis, but we will set it globally here for this tutorial.
```shell
dokku registry:set --global server hub.docker.com
```
If using docker hub, you'll need to use a custom repository name. This can be set via a global template, allowing users access to the app name as the variable `AppName` as shown below.
```shell
dokku registry:set --global image-repo-template "my-awesome-prefix/{{ .AppName }}"
```
Additionally, apps should be configured to push images on the release phase via the `push-on-release` registry property.
```shell
dokku registry:set --global push-on-release true
```
As routing is handled by traefik managed on the k3s plugin, set the proxy plugin to `k3s` as well.
```shell
dokku proxy:set --global k3s
```
Ensure any other proxy implementations are disabled. Typically at least nginx will be running on the Dokku host and should be stopped if the host is used as load balancer.
```shell
dokku nginx:stop
```
Finally, set the scheduler to `k3s` so that app deploys will work on k3s.
```shell
dokku scheduler:set --global selected k3s
```
At this point, all app deploys will be performed against the k3s cluster.
> [!NOTE]
> HTTP requests for apps can be performed against any node in the cluster. Without extra configuration, many other ports may also be available on the host. For security reasons, it may be desirable to place the k3s cluster behind one or more TCP load balancers while shutting off traffic to all cluster ports. Please consult your hosting provider for more information on how to provision a TCP load balancer and shut off all ports other than 22/80/443 access to the outside world.
### Running a multi-cluster node
> [!WARNING]
> Certain ports must be open for cross-server communication. Refer to the [K3s networking documentation](https://docs.k3s.io/installation/requirements?os=debian#networking) for the required open ports between servers prior to running the command.
For high-availability, it is recommended to add both worker and server nodes to the cluster. Dokku will default to starting the cluster with an embedded Etcd database backend, and is ready to add new worker or server nodes immediately.
When attaching an worker or server node, the K3s plugin will look at the IP associated with the `eth0` interface and use that to connect the new node to the cluster. To change this, set the `network-interface` property to the appropriate value.
```shell
dokku scheduler-k3s:set --global network-interface eth1
```
Dokku will connect to remote servers via the `root` user with the `dokku` user's SSH key pair. Dokku servers may not have an ssh key pair by default, but they can be generated as needed via the `git:generate-deploy-key` command.
```shell
dokku git:generate-deploy-key
```
This key can then be displayed with the `git:public-key` command, and copied to the remote server's `/root/.ssh/authorized_keys` file.
```shell
dokku git:public-key
```
Multiple server nodes can be added with the `scheduler-k3s:cluster-add` command. This will ssh onto the specified server, install k3s, and join it to the current Dokku node in server mode.
```shell
dokku scheduler-k3s:cluster-add --role server ssh://root@server-1.example.com
```
Server nodes allow any workloads to be scheduled on them by default, in addition to the control-plane, etcd, and the scheduler itself. To avoid app workloads being scheduled on your control-plane, use the `--taint-scheduling` flag:
```shell
dokku scheduler-k3s:cluster-add --role server --taint-scheduling ssh://root@server-1.example.com
```
If the server isn't in the `known_hosts` file, the connection will fail. This can be bypassed by setting the `--insecure-allow-unknown-hosts` flag:
```shell
dokku scheduler-k3s:cluster-add --role server --insecure-allow-unknown-hosts ssh://root@worker-1.example.com
```
Server nodes are typically used to replicate the cluster state, and it is recommended to have an odd number of nodes spread across several availability zones (datacenters in close proximity within a region). This allows for higher availability in the event of a cluster failure. Server nodes run control-plane services such as the traefik load balancer and the etcd backing store.
> [!NOTE]
> Only the initial Dokku server will be properly configured for push deployment, and should be considered your git remote. Additional server nodes are for ensuring high-availability of the K3s etcd state. Ensure this server is properly backed up and restorable or deployments will not work.
Worker nodes are used to run. To add an worker, run the `scheduler-k3s:cluster-add` with the `--role worker` flag. This will ssh onto the specified server, install k3s, and join it to the current Dokku node in worker mode. Workers are typically used to run app workloads.
```shell
dokku scheduler-k3s:cluster-add --role worker ssh://root@worker-1.example.com
```
## Scheduler Interface
The following sections describe implemented and unimplemented scheduler functionality for the `k3s` scheduler.