# Fleio in Kubernetes

```{warning}
Fleio in Kubernetes is still in beta, and is not intended for production use.
```

```{contents}
:depth: 4
:backlinks: none
```

Fleio can be deployed in Kubernetes using Fleio operator.

Fleio operator can deploy the same version of Fleio as the operator version if Fleio operator is upgraded, 
Fleio will also be upgraded.

## Custom resources

Fleio operator defines and monitors the following custom resources: **FleioDbConnection**, **FleioRedisConnection** and
**FleioDeployment**.

### FleioDbConnection

Fleio needs access to a MariaDB database. Fleio works with MariaDB version 10.11.11 or greater.

FleioDbConnection custom resource defines all details necessary to connect to a MariaDB database like hostname,
port, database name and access credentials. Credentials must be stored in a **kubernetes.io/basic-auth** secret.

Below is a sample of a minimal FleioDbConnection resource. All fields in this resource must be defined.

```yaml
apiVersion: "k8s.fleio.com/v1"
kind: FleioDbConnection
metadata:
  name: fleio-db-connection
spec:
  hostname: "<hostname>"
  port: 3306
  credentialsSecret: fleio-mariadb-credentials
  databaseName: "<databaseName>"
```

Once a new **FleioDbConnection** resource is created, the Fleio operator will detect it and validate it. Invalid
**FleioDbConnection** resources cannot be used to deploy Fleio.

### FleioRedisConnection

Fleio needs access to a Redis server. Fleio works with Redis version 7.4.2 or greater.

FleioRedisConnection custom resource defines all details necessary to connect to a Redis server like hostname,
port, database ID and access credentials. Credentials must be stored in a **kubernetes.io/basic-auth** secret. If 
your redis server used only password for authentication, leave the username empty.

Below is a sample of a minimal FleioRedisConnection resource. All fields in this resource must be defined.

```yaml
apiVersion: "k8s.fleio.com/v1"
kind: FleioRedisConnection
metadata:
  name: fleio-redis-connection
spec:
  hostname: "<hostname>"
  port: 6379
  credentialsSecret: fleio-redis-credentials
  databaseId: "0"
```
Once a new **FleioRedisConnection** resource is created, the Fleio operator will detect it and validate it. Invalid
**FleioRedisConnection** resources cannot be used to deploy Fleio.

### FleioDeployment

A Fleio deployment resource defines all the necessary details to deploy Fleio in Kubernetes. Valid redis and database
resources are needed to deploy Fleio.

A **kubernetes.io/basic-auth** secret containing Fleio admin credentials is also needed.

Below is a sample of a minimal Fleio deployment resource. All fields in this resource must be defined.

```yaml
apiVersion: "k8s.fleio.com/v1"
kind: FleioDeployment
metadata:
  name: prod
spec:
  license:
    uuid: "licenseUUID"
    key: "licenseKey"

  databaseConnection: "fleio-db-connection"
  redisConnection: "fleio-redis-connection"
  adminCredentialsSecret: "fleio-admin-credentials"

  domain: "domainName"
```

To use this replace **licenseUUID** and **licenseKey** with your license details and **domainName** with your
domain. If you install locally **localhost** can be used.

Once a Fleio deployment resource is created, Fleio operator will detect it and deploy Fleio in Kubernetes.

## Deployment process

Fleio deployment is performed in several steps described below:

### Configuration validation

During this step, Fleio operator will check if Fleio deployment resource defines a valid configuration. This includes
checking database and redis connections and admin secret existence.

### Configuration

During this step, Fleio operator will create Kubernetes objects used by Fleio. This includes volume claims, secrets
and config maps.

### Database setup

During this step, Fleio operator will create or update tables in a Fleio database. Admin user will also be created during
this step if it does not exist.

This is performed via a Kubernetes job named **fleio-<deploymentName>-setup-database**.

### License setup

During this step, Fleio operator will set the license for Fleio.

This is performed via a Kubernetes job named **fleio-<deploymentName>-set-license*.

### Final step

During this step, Kubernetes deployments are created for all Fleio containers. Ingress, certificate and scheduled backups
are also setup during this step.

## Upgrading a Fleio deployment

When the Fleio operator is upgraded, it will detect and upgrade any existing Fleio deployments.

## Monitoring and updating Fleio deployment configuration

Once upgrade or deploy processes are completed, Fleio operator will monitor changes to Fleio deployment resource or other 
Fleio related Kubernetes objects and will update Fleio as needed.

## Uninstalling a Fleio deployment

When a FleioDeployment resource is deleted, Fleio operator will attempt to remove the corresponding Fleio deployment 
from the cluster.

Removing a FleioDeployment means removing all containers and jobs associated, config maps, some secrets and other 
related objects.

Persistent volume claims will not be removed to prevent data loss. 

**fleio-\<fleioDeployment\>-deployment-keys** secret will also be kept.

## Kubernetes objects created during Fleio deployment

During deployment, Fleio operator creates various Kubernetes objects needed for Fleio.

(config-maps)=
### Config maps

Fleio operator will create and monitor several config maps containing Fleio settings.

#### fleio-\<deploymentName\>-backend-settings

This config map holds backend settings in **data.settings** field. Based on this config map, Fleio generates
**settings.py** file used in backend containers.

Fleio operator detects changes to this file and automatically applies new configuration and restarts containers.

#### fleio-\<deploymentName\>-frontend-settings

This config map holds frontend settings in **data.enduserConfigFile** and **data.staffConfigFile** fields.

Fleio operator detects changes to this file and automatically applies new configuration and restarts containers.

### Secrets

Fleio operator will create some secrets during Fleio deployment.

#### fleio-\<fleioDeployment\>-deployment-keys

This secret will contain keys used by Fleio to encrypt data, the most relevant fields here are **data.secretKey** and 
**data.ssoSalt**.

### Volumes

Fleio uses several volumes. Fleio operator will set up persistent volume claims for these volumes when deploying Fleio.


#### fleio-\<deploymentName\>-compiled-pvc

This persistent volume claim is used to store compiled Fleio code.

#### fleio-\<deploymentName\>-log-pvc

This persistent volume claim is used to store logs created by Fleio like task logs and periodic task logs. Logs generated 
by containers will not be stored here, we let Kubernetes manage those.

#### fleio-\<deploymentName\>-var-pvc 

This persistent volume claim is used to store temporary files created by Fleio.

(database-backups-volume)=
#### fleio-\<deploymentName\>-database-backups

This persistent volume claim will store database backups if the backup functionality is enabled.

### Cluster issuer

Fleio operator uses cert-manager (https://cert-manager.io/) to generate SSL certificates for Fleio deployments. By 
default, a letsencrypt certificate is generated if possible, if not, a self-singed one is generated.

To achieve this, Fleio operator creates a cluster-issuer resource named **fleio-<deploymentName>-acme-issuer**. 

If something goes wrong and Fleio is unable to get a letsencrypt certificate, you can look at 
**fleio-<deploymentName>-acme-issuer** status and *cert-manager* logs.