Advanced installation

In this guide we show how to customize your cluster installation, i.e. if you want to install additional applications, or change the configuration of extisting apps installed by OAS this is the right place. Customizing other parts of your cluster is possible but not yet covered by this guide. As the name of this guide implies, it is written for users with advanced knowledge of the tools behind Openappstack, most importantly: Kubernetes, Helm, Ansible and Flux 2.

Advanced cluster creation: Setup 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: Additional configuration if you used the API to create the DNS records.

Customization

Warning

Customizing your OAS cluster could break your cluster in a way that it’s not easy to recover. Please be aware of the potential risk when proceeding.

Prerequisites

Customize OAS applications

Apps deployed by OAS are configured using helm values from templates in flux2/apps/<application>/release.yaml. It is possible to override values from the helmrelease by adding a custom ConfigMap or Secret to the cluster. The secret or configmap name is specified in the valuesFrom section of the release.yaml file. Read more in the Flux documentation

Example: Customize Nextcloud to work with staging certificates

Our CI pipeline works with staging certificates from Let’s Encrypt, for that reason we need to allow insecure connections for the integration with ONLYOFFICE. You can find the file at install/overrides/oas-nextcloud-override.yaml.

To apply it, run the following commands:

# If you want to run this on your provisioning machine, tell kubectl to use
# your cluster:
export KUBECONFIG=$PWD/clusters/oas.example.org/kube_config_cluster.yml
# Check the current state of the helmrelease you want to modify:
flux get helmrelease -A
# If all is OK, make sure to apply your override configmap or secret in the
# same namespace as your helmrelease with the '-n' argument
kubectl apply \
  -n oas-apps \
  -f ./install/overrides/oas-nextcloud-override.yaml

Adding custom apps to the cluster

OpenAppStack uses Flux 2 to install and auto-update applications. If you want to install extra applications or other things into the Kubernetes cluster, our advice would be to set up your own GitRepository and add it to the Flux system.

When you do this, you are fully responsible for keeping those applications secure and updated. If any of those applications is insecure, that can also invalidate the security of your OpenAppStack applications, because they are part of the same cluster and VPS.

Refer to the Flux 2 documentation for more information.