Prerequisites

• 1: Local Docker
• 2: Linux Server
• 2.1: SSH and Sudo
• 2.2: Server on AWS
• 2.3: Server on Azure
• 2.4: Install K3S
• 2.5: Install MicroK8S
• 3: Kubernetes Cluster
• 3.1: Amazon EKS
• 3.2: Azure AKS
• 3.3: Generic Kubernetes

1 - Local Docker

Prerequisites to install OpenServerless with Docker

You can install OpenServerless on your local machine using Docker. This page lists the prerequisits.

First and before all you need a computer with at least 16 GB of memory and 30GB of available space.

❗ IMPORTANT

8GB are definitely not enough to run OpenServerless on your local machine.

Furthermore, you need to install Docker. Let’s see the which one to install and configure if you have:

1. Windows
2. MacOS
3. Linux

Windows

You require the 64 bit edition in Intel Architecture of a recent version of Windows (at least version 10). The installer ops does not run on 32 bit versions nor in the ARM architecture.

Download and install Docker Desktop for Windows.

Once installed, you can proceed configuring OpenServerless for the installation.

MacOS

You require a recent version of MacOS (at least version 11.xb BigSur). The installer ops is available both for Intel and ARM.

Download and install Docker Desktop for MacOS.

Since MacOS uses a virtual machine for Docker with a constrained memory. you also need also to reserve at least 8GB.

❗ IMPORTANT

On MacOS, Docker defaults to 2GB memoery and they are definitely not enough to run OpenServerless on your local machine.

Instructions to increase the memory reserved to Docker Desktopo on MacOS:

• click on the Docker Desktop icon in the menu

• select Preferences

• click on Resources

• increase the reserved memory up to (at least) 8GB

• click on Apply & Restart

Once installed, you can proceed configuring OpenServerless for the installation.

Linux

Docker Desktop is available also on Linux, however we advice to install instead the Server Docker Engine

On Linux, the Docker Engine for the server does not run in a virtual machine, so it is faster and uses less memory.

Once installed, you can proceed configuring OpenServerless for the installation.

2 - Linux Server

Prerequisites to install OpenServerless in a Linux server

You can install OpenServerless on any server either in your intranet or on in Internet running a Linux distribution, with the following requirements:

1. You know the IP address or DNS name of the server on Internet or in your Intranet.

2. The server requires at least 8GB of memory and 30GB of disk space available.

3. It should be running a Linux distribution supported by K3S.

4. You must open the firewall to access ports 80, 443 and 6443 (for K3S) or 16443 (for MicroK8S) from your machine.

5. You have to install a public ssh key to access it without a password.

6. You have to configure sudo to execute root commands without a password.

You can:

• get a server on any cloud provider or even install by yourself and then configure it

• provision such a server with ops on Amazon Web Services

• provision such a server with ops on on Google Cloud Platform

Once you have such a server you can optionally (it is not required) install K3S or MicroK8S in it.

Once you have configured you server, you can proceed configuring OpenServerless for the installation.

2.1 - SSH and Sudo

Configure a generic Linux server to install OpenServerless

If you have access to a generic Linux server, to be able to install OpenServerless it needs to:

1. be accessible without a password with ssh

2. be able to run root commands without a password with sudo

3. open the ports 80, 443 and 6443 or 16443

If your server does not already satisfy those requirements, read below for information how to create a sshkey, configure sudo and open the firewall

Installing a public SSH key

To connect to a server without a password using openssh (used by the installer), you need a couple of files called ssh keys.

You can generate them on the command line using this command:

ssh-keygen

It will create a couple of files, typically called:

• ~/.ssh/id_rsa

• ~/.ssh/id_rsa.pub

where ~ is your home directory.

You have to keep secret the id_rsa file because it is the private key and contains the information to identify you uniquely. Think to is as your password.

You can copy the id_rsa.pub in the server or even share it publicly, as it is the public key. Think to it as your login name, and adding this file to the server adds you to the users who can login into it.

Once you have generated the public key, access your server, then edit the file ~/.ssh/authorized_keys adding the public key to it.

It is just one line, contained in the id_rsa.pub file.

Create the file if it does not exist. Append the line to the file (as a single line) if it already exists. Do not remove other lines if you do not want to remove access to other users.

Configure Sudo

You normally access Linux servers using a user that is not root (the system administrator with unlimited power on the system).

Depending on the system, the user to use to access be ubuntu, ec2-user, admin or something else entirely. However if you have access to the server, the information of which user to use should have been provided, including a way to access to the root user.

You need to give this user the right to execute commands as root without a password, and you do this by configuring the command sudo.

You usually have either access to root with the su command, or you can execute sudo with a password.

Type either su or sudo bash to become root and edit the file /etc/sudoers adding the following line:

<user> ALL=(ALL) NOPASSWD:ALL

where <user> is the user you use to log into the system.

Open the firewall

You need to open the following ports in the firewall of the server:

• 443 for HTTPS

• 80 for HTTP and provisioning certificates

• 6443 (K3S) or 16443 (MicroK8S) for Kubernetes

For information on how to open the firewall, please consult the documentation of your cloud provider or contact your system administrator, as there are no common procedures and they depends on the cloud provider.

2.2 - Server on AWS

Provision a Linux server in Amazon Web Services

You can provision a server suitable to install OpenServerless in cloud provider Amazon Web Services ops as follows:

1. install aws, the AWS CLI

2. get Access and Secret Key

3. configure AWS

4. provision a server

5. retrieve the ip address to configure a DNS name

Once you have a Linux server up and running you can proceed configuring and installing OpenServerless.

Installing the AWS CLI

Our cli ops uses under the hood the AWS CLI version 2, so you need to dowload and install it following those instructions.

Once installed, ensure it is available on the terminal executing the following command:

aws --version

you should receive something like this:

aws-cli/2.9.4 Python/3.9.11 Linux/5.19.0-1025-aws exe/x86_64.ubuntu.22 prompt/off

Ensure the version is at least 2.

Getting the Access and Secret key

Next step is to retrieve credentials, in the form of an access key and a secret key.

So you need to:

• access the AWS console following those instructions create an access key and secret key;
• give to the credentials the minimum required permissions as described here to build an EKS cluster.

You will end up with a couple of string as follows:

Sample AWS Access Key ID: AKIAIOSFODNN7EXAMPLE Sample AWS Secret Access
Key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

Take note of them as you need them for configuring out CLI.

Configure AWS to provision a server

Before you can provision a Linux server you have to configure AWS typing the command:

ops config aws

The system will then ask the following questions:

*** Please, specify AWS Access Id and press enter.
AKIAIOSFODNN7EXAMPLE

*** Please, specify AWS Secret Key and press enter.
wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
*** Please, specify AWS Region to use and press enter.
To get a list of valid values use:
  aws ec2 describe-regions --output table

Just press enter for default [us-east-1]:

*** Please, specify AWS public SSH key  and press enter.
If you already have a public SSH key in AWS, provide its name here.
If you do not have it, generate a key pair with the following command:
  ssh-keygen
The public key defaults to ~/.ssh/id_rsa.pub and you can import with:
  aws ec2 import-key-pair --key-name nuvolaris-key --public-key-material --region=<your-region> fileb://~/.ssh/id_rsa.pub

Just press enter for default [devkit-74s]:

*** Please, specify AWS Image to use for VMs and press enter.
The suggested image is an Ubuntu 22 valid only for us-east-1
Please check AWS website for alternative images in other zones

Just press enter for default [ami-052efd3df9dad4825]:

*** Please, specify AWS Default user for image to use for VMs and press enter.
Default user to access the selected image.

Just press enter for default [ubuntu]:

*** Please, specify AWS Instance type to use for VMs and press enter.
The suggested instance type has 8GB and 2vcp
To get a list of valid values, use:
aws ec2 describe-instance-types --query 'InstanceTypes[].InstanceType' --output table

Just press enter for default [t3a.large]:

*** Please, specify AWS Disk Size to use for VMs and press enter.
Just press enter for default [100]:

Provision a server

You can provision one or more servers using ops. The servers will use the parameters you have just configured.

You can create a new server with:

ops cloud aws vm-create <server-name>

❗ IMPORTANT

Replace <server-name> with a name you choose, for example ops-server

The command will create a new server in AWS with the parameters you specified in configuration.

You can also:

1. list servers you created with ops cloud aws vm-list

2. delete a server you created and you do not need anymore with ops cloud aws vm-delete <server-name>

Retrieve IP

The server will be provisioned with an IP address assigned by AWS.

You can read the IP address of your server with

ops cloud aws vm-getip <server-name>

You need this IP when configuring a DNS name for the server.

2.3 - Server on Azure

Provision a Linux server in Azure Cloud Platform

You can provision a server suitable to install OpenServerless in cloud provider Azure ops as follows:

1. install az, the Azure CLI

2. get Access and Secret Key

3. configure Azure

4. provision a server

5. retrieve the ip address to configure a DNS name

Once you have a Linux server up and running you can proceed configuring and installing OpenServerless.

Installing the Azure CLI

Our cli ops uses under the hood the az, command so you need to dowload and install it following those instructions.

Once installed, ensure it is available on the terminal executing the following command:

az version

you should receive something like this:

{
    "azure-cli": "2.64.0",
    "azure-cli-core": "2.64.0",
    "azure-cli-telemetry": "1.1.0",
    "extensions": {
        "ssh": "2.0.5"
    }
}

Ensure the version is at least 2.64.0

Connect a subscription

Next step is to connect az to a valid Azure subscription. Azure supports several authentication methods: check which one you prefer.

The easiest is the one described in Sign in interactively:

az login

This will open a browser and you will asked to login to you azure account. Once logged in, the az command will be automatically connected to the choosen subscription.

To check if the az command is properly connected to your subscription, check the output of this command:

   $ az account list --query "[].{subscriptionId: id, name: name, user: user.name}" --output table

   SubscriptionId                        Name                         User
   ------------------------------------  ---------------------------  -------------------------
   xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx  Microsoft Azure Sponsorship  openserverless@apache.org

Configuring Azure to provision a server

Before you can provision a Linux server you have to configure Openserverless for Azure typing the command:

ops config azcloud

The system will then ask the following questions:

   *** Please, specify Azure Project Id and press enter.
   Azure Project Id: openserverless-k3s
   *** Please, specify Azure Zone and press enter.
   To get a list of valid values use:
      az account list-locations -o table
   
   Just press enter for default [eastus]:
   Azure Zone:

   *** Please, specify Azure virtual machine type and press enter.
   To get a list of valid values, use:
     az vm list-sizes --location <location> -o table
   where <location> is your current location.
   
   Just press enter for default [Standard_B4ms]:
   Azure virtual machine type:
   
   *** Please, specify Azure vm disk size in gigabyte and press enter.
   Just press enter for default [50]:
   Azure vm disk size in gigabyte:
   
   *** Please, specify Azure Cloud public SSH key and press enter.
   If you already have a public SSH key provide its path here. If you do not have it, generate a key pair with the following command:
     ssh-keygen
   The public key defaults to ~/.ssh/id_rsa.pub.
   
   Just press enter for default [~/.ssh/id_rsa.pub]:
   Azure Cloud public SSH key:
   
   *** Please, specify Azure Cloud VM image and press enter.
   Just press enter for default [Ubuntu2204]:
   Azure Cloud VM image:

Provision a server

You can provision one or more servers using ops. The servers will use the parameters you have just configured.

You can create a new server with:

    ops cloud azcloud vm-create <server-name>

❗ IMPORTANT

Replace <server-name> with a name you choose, for example ops-server

The command will create a new server in Azure Cloud with the parameters you specified in configuration.

You can also:

1. list servers you created with ops cloud azcloud vm-list

2. delete a server you created and you do not need anymore with ops cloud azcloud vm-delete <server-name>

Retrieve IP

The server will be provisioned with an IP address assigned by Azure Cloud.

You can read the IP address of your server with

ops cloud azcloud vm-getip <server-name>

You need this IP when configuring a DNS name for the server.

2.4 - Install K3S

Install K3S in a server

You can install OpenServerless as described here, and you do not need to install any Kubernetes in it, as it is installed as part of the procedure. In this case it installs K3S.

Or you can install K3S in advance, and then proceed configuring and then installing OpenServerless as in any other Kubernetes cluster.

Installing K3S in a server

Before installing ensure you have satified the prerequisites, most notably:

1. you know the IP address or DNS name

2. your server operating system satisfies the K3S requirements

3. you have passwordless access with ssh

4. you have a user with passwordless sudo rights

5. you have opened the port 6443 in the firewall

Then you can use the following subcommand to install in the server:

ops cloud k3s create <server> [<username>]

where <server> is the IP address or DNS name to access the server, and the optional <username> is the user you use to access the server: if is not specified, the root username will be used.

Those pieces of information should have been provided when provisioning the server.

❗ IMPORTANT

If you installed a Kubernetes cluster in the server this way, you should proceed installing OpenServerless as in a Kubernetes cluster, not as a server.

The installation retrieves also a Kubernetes configuration file, so you can proceed to installing it without any other step involved.

Additional Commands

In addition to create the following subcommands are also available:

• ops cloud k3s delete <server> [<username>]: uninstall K3S from the server

• ops cloud k3s kubeconfig <server> [<username>]: retrieve the kubeconfig from the K3S server

• ops cloud k3s info: some information about the server

• ops cloud k3s status: status of the server

2.5 - Install MicroK8S

Install MicroK8S in a server

You can install OpenServerless as described here and you do not need to install any Kubernetes in it, as it is installed as part of the procedure. In this case it installs K3S.

But you can install MicroK8S instead, if you prefer. Check here for informations about MicroK8S.

If you install MicroK8S in your server, you can then proceed configuring and then installing OpenServerless as in any other Kubernetes cluster.

Installing MicroK8S in a server

Before installing ensure you have satisfied the prerequisites, most notably:

1. you know the IP address or DNS name

2. you have passwordless access with ssh

3. you have an user with passwordless sudo rights

4. you have opened the port 16443 in the firewall

Furthermore, since MicroK8S is installed using snap, you also need to install snap.

💡 NOTE

While snap is available for many linux distributions, it is typically pre-installed and well supported in in Ubuntu and its derivatives. So we recommend MicroK8S only if you are actually using an Ubuntu-like Linux distribution.

If you system is suitable to run MicroK8S you can use the following subcommand to install in the server:

ops cloud mk8s create SERVER=<server> USERNAME=<username>

where <server> is IP address or DNS name to access the server, and <username> is the user you use to access the server.

Those informations should have been provided when provisioning the server.

❗ IMPORTANT

If you installed a Kubernetes cluster in the server in this way, you should proceed installing OpenServerless as in a Kubernetes cluster, not as a server.

The installation retrieves also a kubernets configuration file so you can proceed to installing it without any other step involved.

Additional Commands

In addition to create you have available also the following subcommands:

• ops cloud mk8s delete SERVER=<server> USERNAME=<username>: uninstall K3S from the server

• ops cloud mk8s kubeconfig SERVER=<server> USERNAME=<username>: retrieve the kubeconfig from the MicroK8S server

• ops cloud mk8s info: informations about the server

• ops cloud mk8s status: status of the server

3 - Kubernetes Cluster

Prerequisites to install OpenServerless in a Kubernetes cluster

You can install OpenServerless in any Kubernetes cluster which satisfy some requirements.

Kubernetes clusters are available pre-built from a variety of cloud providers. We provide with our ops tool the commands to install a Kubernetes cluster ready for OpenServerless in the following environments:

• Amazon EKS

• Azure AKS

• Google GKE

• RedHat OpenShift

You can also provision a suitable cluster by yourself, in any cloud or on premises, ensuring the prerequites are satisfied.

Once provisioned, you will receive a configuration file to access the cluster, called kubeconfig.

This file should be placed in ~/.kube/config to give access to the cluster

If you have this file, you can check if you have access to the cluster with the command:

ops debug kube info

You should see something like this:

Kubernetes control plane is running at https://xxxxxx.yyy.us-east-1.eks.amazonaws.com

Once you have got access to the Kubernetes cluster, either installing one with out commands or provisioning one by yourself, you can proceed configuring the installation and then installing OpenServerless in the cluster.

3.1 - Amazon EKS

Prerequisites to install OpenServerless in an Amazon EKS Cluster

Amazon EKS is a pre-built Kubernetes cluster offered by the cloud provider Amazon Web Services.

You can create an EKS Cluster in Amazon AWS for installing using OpenServerless using ops as follows:

1. install aws, the AWS CLI

2. get Access and Secret Key

3. configure EKS

4. provision EKS

5. optionally, retrieve the load balancer address to configure a DNS name

Once you have EKS up and running you can proceed configuring and installing OpenServerless.

Installing the AWS CLI

Our cli ops uses under the hood the AWS CLI version 2, so you need to dowload and install it following those instructions.

Once installed, ensure it is available on the terminal executing the following command:

aws --version

you should receive something like this:

aws-cli/2.9.4 Python/3.9.11 Linux/5.19.0-1025-aws exe/x86_64.ubuntu.22 prompt/off

Ensure the version is at least 2.

Getting the Access and Secret key

Next step is to retrieve credentials, in the form of an access key and a secret key.

So you need to: * access the AWS console following those instructions create an access key and secret key, * give to the credentials the minimum required permissions as described here to build an EKS cluster.

You will end up with a couple of string as follows:

Sample AWS Access Key ID: AKIAIOSFODNN7EXAMPLE Sample AWS Secret Access
Key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

Take note of them as you need them for configuring out CLI.

Configuring Amazon EKS

Once you have the access and secret key you can configure EKS with the command ops config eks answering to all the questions, as in the following example:

$ ops config eks
*** Please, specify AWS Access Id and press enter.
AKIAIOSFODNN7EXAMPLE
*** Please, specify AWS Secret Key and press enter.
wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
*** Please, specify AWS Region to use and press enter.
To get a list of valid values use:
  aws ec2 describe-regions --output table

Just press enter for default [us-east-2]:

*** Please, specify AWS public SSH key  and press enter.
If you already have a public SSH key in AWS, provide its name here.
If you do not have it, generate a key pair with the following command:
  ssh-keygen
The public key defaults to ~/.ssh/id_rsa.pub and you can import with:
  aws ec2 import-key-pair --key-name nuvolaris-key --public-key-material --region=<your-region> fileb://~/.ssh/id_rsa.pub

Just press enter for default [nuvolaris-key]:

*** Please, specify EKS Name for Cluster and Node Group and press enter.
Just press enter for default [nuvolaris]:

*** Please, specify EKS region and press enter.
To get a list of valid values use:
  aws ec2 describe-regions --output table

Just press enter for default [us-east-1]:

*** Please, specify EKS number of worker nodes and press enter.
Just press enter for default [3]:

*** Please, specify EKS virtual machine type and press enter.
To get a list of valid values, use:
  aws ec2 describe-instance-types --query 'InstanceTypes[].InstanceType' --output table

Just press enter for default [m5.xlarge]:

*** Please, specify EKS disk size in gigabyte and press enter.
Just press enter for default [50]:

*** Please, specify EKS Kubernetes Version and press enter.
Just press enter for default [1.25]:

Provisioning Amazon EKS

Once you have configured it, you can create the EKS cluster with the command:

ops cloud eks create

It will take around 20 minutes to be ready. Please be patient.

At the end of the process, you will have access directly to the created Kubernetes cluster for installation.

Retrieving the Load Balancer DNS name

Once the cluster is up and running, you need to retrieve the DNS name of the load balancer.

You can read this with the command:

ops cloud eks lb

Take note of the result as it is required for configuring a dns name for your cluster.

Additional Commands

You can delete the created cluster with: ops cloud eks delete

You can extract again the cluster configuration, if you lose it, reconfiguring the cluster and then using the command ops cloud eks kubeconfig.

3.2 - Azure AKS

Prerequisites to install OpenServerless in an Azure AKS Cluster

Azure AKS is a pre-built Kubernetes cluster offered by the cloud provider Microsoft Azure.

You can create an AKS Cluster in Microsoft Azure for installing using OpenServerless using ops as follows:

1. install az, the Azure CLI

2. configure AKS

3. provision AKS

4. optionally, retrieve the load balancer address to configure a DNS name

Once you have AKS up and running you can proceed configuring and installing OpenServerless.

Installing the Azure CLI

Our CLI ops uses under the hood the Azure CLI, so you need to dowload and install it following those instructions.

Once installed, ensure it is available on the terminal executing the following command:

az version

you should receive something like this:

{
  "azure-cli": "2.51.0",
  "azure-cli-core": "2.51.0",
  "azure-cli-telemetry": "1.1.0",
  "extensions": {}
}

Configuring Azure AKS

Before provisioning your AKS cluster you need to configure AKS with the command ops config aks answering to all the questions, as in the following example:

$ ops config aks
*** Please, specify AKS Name for Cluster and Resource Group and press enter.
Just press enter for default [nuvolaris]:

*** Please, specify AKS number of worker nodes and press enter.
Just press enter for default [3]:

*** Please, specify AKS location and press enter.
To get a list of valid values use:
  az account list-locations -o table

Just press enter for default [eastus]:

*** Please, specify AKS virtual machine type and press enter.
To get a list of valid values use:
  az vm list-sizes --location <location> -o table
where <location> is your current location.

Just press enter for default [Standard_B4ms]:

*** Please, specify AKS disk size in gigabyte and press enter.
Just press enter for default [50]:

*** Please, specify AKS public SSH key in AWS and press enter.
If you already have a public SSH key provide its path here. If you do not have it, generate a key pair with the following command:
  ssh-keygen
The public key defaults to ~/.ssh/id_rsa.pub.

Just press enter for default [~/.ssh/id_rsa.pub]:

Provisioning Azure AKS

Once you have configured it, you can create the AKS cluster with the command:

ops cloud aks create

It will take around 10 minutes to be ready. Please be patient.

At the end of the process, you will have access directly to the created Kubernetes cluster for installation.

Retrieving the Load Balancer DNS name

Once the cluster is up and running, you need to retrieve the DNS name of the load balancer.

You can read this with the command:

ops cloud aks lb

Take note of the result as it is required for configuring a dns name for your cluster.

Additional Commands

You can delete the created cluster with: ops cloud aks delete

You can extract again the cluster configuration, if you lose it, reconfiguring the cluster and then using the command nuv cloud aks kubeconfig.

3.3 - Generic Kubernetes

Kubernetes Cluster requirements

OpenServerless installs in any Kubernetes cluster which satisfies the following requirements:

• cluster-admin access

• at least 3 worker nodes with 4GB of memory each

• support for block storage configured as default storage class

• support for LoadBalancer services

• the nginx ingress already installed

• the cert manager already installed

Once you have such a cluster, you need to retrieve the IP address of the Load Balancer associated with the Nginx Ingress. In the default installation, it is installed in the namespace nginx-ingress and it is called ingress-nginx-controller.

In the default installation you can read the IP address with the following command:

kubectl -n ingress-nginx get svc ingress-nginx-controller

If you have installed it in some other namespace or with another name, change the command accordingly.

The result should be something like this:

NAME                       TYPE           CLUSTER-IP   EXTERNAL-IP    PORT(S)                      AGE
ingress-nginx-controller   LoadBalancer   10.0.9.99    20.62.156.19   80:30898/TCP,443:31451/TCP   4d1h

Take note of the value under EXTERNAL-IP as you need it in the next step of installation, configuring DNS.