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.
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-agentto give you access to your VPS
In this guide, we will create a cluster with IP address
184.108.40.206 on domain
oas.example.org. Substitute these two variables with your IP address and
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
your cluster. Then run the following command to get information about
$ 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 220.127.116.11
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.orgtells the cluster the domain it will be hosted on. This should be a (subdomain of a) domain you own.
--ip-address 18.104.22.168tells 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
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:
oas.example.orgpointing to the VPS’s IP address,
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:
example.orgpointing to the VPS’s IP address,
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
install command will try to log into your machine as the
install command with the CLI to completely configure your VPS for
$ 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.
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.
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
There are two ways to let the installation program know which VPS to use:
Based on an already existing Greenhost VPS, using the
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
In that case, make sure to also provide the
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
If you use a subdomain (e.g.
oas.yourdomain.com), use the
--subdomaincommand 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 hostname
--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:
oas.example.orgpointing to the VPSs IP address
--subdomain oas: Only needed when you use
--create-domain-recordsso the Greenhost API can find your domain. Instead of using positional argument
oas.example.orgyou need to provide