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 record oas.example.org pointing to the VPS’s IP address,

  • A CNAME record *.oas.example.org pointing to oas.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 record example.org pointing to the VPS’s IP address,

  • A CNAME record *.example.org pointing to example.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 rootuser 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.

    1. In the Cosmos service centre, click your webmaster account name on the top right corner

    2. Go to “User settings”

    3. Click “API keys”

    4. Click “New API key”

    5. Click “Generate new key”

    6. 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.

    7. Copy the generated key and run export it to this variable in a terminal:

      $ export COSMOS_API_TOKEN=<paste your API key here>

    8. 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:

    1. 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).

    2. 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 hostname oas.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 record oas.example.org pointing to the VPSs IP address

      • A CNAME record *.oas.example.org pointing to oas.example.org.

    • --subdomain oas: Only needed when you use --create-domain-records so the Greenhost API can find your domain. Instead of using positional argument oas.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.