Create a kubernetes cluster¶
This document describes how you can use OpenAppStack to install k3s, a lightweight Kubernetes distribution on a virtual private server.
For OpenAppStack we will set up a “single-node” kubernetes cluster. This means everything runs on the same VPS. Support for “multi-node” clusters (a Kubernetes cluster on more than one VPS) will come in the future.
Prerequisites¶
During these instructions, you are asked to create a VPS, or have a bare metal server ready. The server should meet these requirements:
Debian “buster” installed
A public IP address
The ability to create DNS records for this IP
6 cores and 12 GB of RAM
At least 25GB of disk space for installation, plus more for application data. We recommend starting with 30GB.
Root ssh access
ssh-agent
to give you access to your VPS
In this guide, we will create a cluster with IP address 1.2.3.4
on domain
oas.example.org
. Substitute these two variables with your IP address and
your domain.
Step 1: Create cluster configuration¶
To create a config for your cluster, use the create
subcommand of the
OpenAppStack CLI. First, choose a name (we chose oas.example.org
) for
your cluster. Then run the following command to get information about
the create
subcommand:
$ python -m openappstack oas.example.org create --help
If you want the installation script to automatically create a VPS for you, check Cluster creation with the Greenhost API. Otherwise, continue here.
If you want to install OpenAppStack on a non-Greenhost VPS, we assume you already have a machine with a world-facing IP address. Make sure that your VPS meets our prerequisites. You’ll need its hostname and its IP address.
Create the initial OpenAppStack configuration for your VPS by running the following command:
$ python -m openappstack oas.example.org create \
oas.example.org \
--ip-address 1.2.3.4
This configures your cluster under the fully qualified domain name (FQDN)
oas.example.org
, To break down the command:
the first, positional argument
oas.example.org
tells the cluster the domain it will be hosted on. This should be a (subdomain of a) domain you own.--ip-address 1.2.3.4
tells the script the IP address of your VPS. This will be used to find the VPS during the installation procedure.
The configuration has now been written to the clusters/oas.example.org
on
your provisioning machine.
Step 2: Configure DNS¶
Next, make sure that you have two DNS records that point to your cluster. Create these two DNS records:
An
A
recordoas.example.org
pointing to the VPS’s IP address,A
CNAME
record*.oas.example.org
pointing tooas.example.org
.
Note
It is also possible to host OpenAppStack on a domain (with
no dedicated subdomain). That does imply that the included WordPress site
will be hosted on your root domain example.org
. In that case, make these
DNS records instead:
An
A
recordexample.org
pointing to the VPS’s IP address,A
CNAME
record*.example.org
pointing toexample.org
.
OpenAppStack will fetch https certificates with Let’s Encrypt by default. In order to do this DNS entries need to be created.
Step 3: Create cluster¶
You’re almost ready to start the OpenAppStack installation script. First, make sure your DNS configuration is propagated. To do so, make sure ‘ping’ shows your VPS’s IP address:
$ ping oas.example.org
The install
command will try to log into your machine as the root
user
using SSH.
Run the install
command with the CLI to completely configure your VPS for
OpenAppStack.
$ python -m openappstack oas.example.org install
This will take a few minutes. It installs k3s, a lightweight Kubernetes and useful tools like kubectl (Kubernetes cli tool), krew (a kubectl plugin manager), flux (used for automated updates) and velero (Kubernetes resources and persistent volumes backup) on it.
Note
It is possible to re-run the install
command with a newer version of the
installation script. This usually updates k3s and can have other benefits.
Now you have a single-node k3s/Kuberetes cluster running and can continue with Install OpenAppStack.
Advanced installation¶
Cluster creation with the Greenhost API¶
Before you can start, you need to have an API key with Customer rights.
In the Cosmos service centre, click your webmaster account name on the top right corner
Go to “User settings”
Click “API keys”
Click “New API key”
Click “Generate new key”
Give the key “Customer”, “CloudCustomer” or “API” access rights. You will need “Customer” rights if you want to automatically generate DNS rules. If you do not have this right, you have to manually set the right DNS rules later.
Copy the generated key and run export it to this variable in a terminal:
$ export COSMOS_API_TOKEN=<paste your API key here>
In the same terminal, you can now use the
create
subcommand
There are two ways to let the installation program know which VPS to use:
Based on an already existing Greenhost VPS, using the
--droplet-id
argument.Find the ID of your VPS either in the Greenhost Cosmos interface (it is the numeric part of the URL in the “Manage VPS” screen).
By creating a new VPS through the API, using the
--create-droplet
argument.In that case, make sure to also provide the
--create-hostname
and--ssh-key-id
arguments.You can find your SSH key ID by going to VPS Cloud -> SSH keys and checking the link under “Show key”. The numerical part is your SSH key ID.
Note: You can also use the API to list ssh keys and find it there. Read the `Greenhost API documentation <https://service.greenhost.net/cloud/ApiDoc#/default>`__ for more information
In both cases you need to provide the
DOMAIN_NAME
positional argument.If you use a subdomain (e.g.
oas.yourdomain.com
), use the--subdomain
command as follows:$ python -m openappstack oas.example.org create --subdomain oas example.org
Here is an example of a complete creation command:
$ python -m openappstack oas.example.org create \ --create-droplet \ --create-hostname oas.example.org \ --ssh-key-id 112 \ --create-domain-records \ --subdomain oas \ example.org
Let’s break down the arguments:
--create-droplet
: Use the Greenhost API to create a new VPS--create-hostname oas.example.org
: Create a VPS with hostnameoas.example.org
--ssh-key-id 112
: Use SSH key ID 112 (you can find your SSH key ID in the Cosmos Service Centre under VPS Cloud -> Installation SSH Keys. Hover over a button there to see the ID in the URL it uses.--create-domain-records
: Use the Greenhost API to create DNS records If you do this, you can skip Step 2: Configure DNS. The following records are created:An
A
recordoas.example.org
pointing to the VPSs IP addressA
CNAME
record*.oas.example.org
pointing tooas.example.org
.
--subdomain oas
: Only needed when you use--create-domain-records
so the Greenhost API can find your domain. Instead of using positional argumentoas.example.org
you need to provide
You can now continue to Step 2: Configure DNS, or Step 3: Create cluster if you used the API to create the DNS records.