# Installing on Kubernetes

| Avantra is currently in the process of migrating our existing container registry based solution to Google’s artifact registry as per Google’s guidance as they phase their container registry offering. During this time, existing customer access will continue to function however access for customers for non-production scenarios will not be granted until the new set up has been completed. If this causes you an issue, please contact your customer success manager.

| This documentation assumes you already have a valid and correctly functioning Kubernetes cluster and is only designed to showcase the key commands and configurations required to run Avantra in a Kubernetes cluster. It is not designed to be an exhaustive guide on the operation of a Kubernetes cluster. For detailed information on running a Kubernetes cluster, please consult the online documentation for your chosen environment. Avantra support will not be able to provide guidance on Kubernetes cluster operation best practice or in-depth support for you Kubernetes cluster.

## Prerequsites

The following items are required to complete a successful deployment of Avantra in your Kubernetes environment.

1. Your own Kubernetes cluster

2. Permissions to add a new namespace

3. Permissions to add a new container registry (Avantra)

4. A valid set of credentials from Avantra support to access the Avantra container registry - this is a .json file

5. Permissions to deploy a new application to the cluster

6. A valid Avantra subscription

### Required Containers

Name | Description | Container URL
--- | --- | ---
Operator | Responsible for provisioning and controlling the Avantra installation components (From Avantra) | gcr.io/avantra-cust/avantra/operator/avantra-operator
Avantra Server | The server Container (From Avantra) | gcr.io/avantra-cust/avantra/master
Avantra UI | The UI Container (From Avantra) | gcr.io/avantra-cust/avantra/ui
PostgreSQL Database | The PostgreSQL Container (Official from Docker Hub) | postgres

## Installation Steps

### Prepare installation

1. Create a new namespace for Avantra in Kubernetes with your chosen name. In this guide we will use the namespace `avantra`. Please note that if you opt to use a different namespace, please review each YAML entry below to ensure you update the namespace entries.

       kubectl create namespace avantra

   | You will need your credentials to access the Avantra container registry which are in the form of a JSON file which is named `registry-credentials.json` in the example below. Please contact Avantra Support for credentials if you do not have them.

2. Store the access data for the container registry in Kubernetes

       kubectl -n=avantra create secret docker-registry avantra.com \
         --docker-server gcr.io \
         --docker-username _json_key \
         --docker-email not@val.id \
         --docker-password="$(cat registry-credentials.json)"

   This command adds the `avantra.com` registry with the correct credentials to access the Avantra containers.

### Install Avantra

1. Create Avantra Operator Service Account

   Place the YAML code below in a file for easiest deployment. If the file is called `01_CreateServiceAccount.yaml` then you can run this on your cluster by running `kubectl -n=avantra create -f 01_CreateServiceAccount.yaml`

       ---
       apiVersion: v1
       kind: ServiceAccount
       metadata:
         namespace: avantra
         labels:
           app.kubernetes.io/version: 1.0.0
           app.kubernetes.io/name: avantra-operator
         name: avantra-operator
       ---
       apiVersion: rbac.authorization.k8s.io/v1
       kind: RoleBinding
       metadata:
         name: avantra-operator-view
       roleRef:
         kind: ClusterRole
         apiGroup: rbac.authorization.k8s.io
         name: view
       subjects:
         - kind: ServiceAccount
           name: avantra-operator
       ---
       apiVersion: rbac.authorization.k8s.io/v1
       kind: ClusterRole
       metadata:
         name: avantracontroller-cluster-role
       rules:
         - apiGroups:
             ["", "apps", "avantra.com"]
           resources:
             - avantras
             - avantras/status
             - services
             - configmaps
             - secrets
             - pods
             - statefulsets
             - statefulsets/scale
             - persistentvolumes
             - persistentvolumeclaims
           verbs:
             - get
             - list
             - watch
             - create
             - delete
             - patch
             - update
       ---
       apiVersion: rbac.authorization.k8s.io/v1
       kind: ClusterRole
       metadata:
         name: josdk-crd-validating-cluster-role
       rules:
         - apiGroups:
             - apiextensions.k8s.io
           resources:
             - customresourcedefinitions
           verbs:
             - get
             - list
       ---
       apiVersion: rbac.authorization.k8s.io/v1
       kind: ClusterRoleBinding
       metadata:
         name: avantracontroller-cluster-role-binding
       roleRef:
         kind: ClusterRole
         apiGroup: rbac.authorization.k8s.io
         name: avantracontroller-cluster-role
       subjects:
         - kind: ServiceAccount
           name: avantra-operator
           namespace: avantra
       ---
       apiVersion: rbac.authorization.k8s.io/v1
       kind: ClusterRoleBinding
       metadata:
         name: avantracontroller-crd-validating-role-binding
       roleRef:
         kind: ClusterRole
         apiGroup: rbac.authorization.k8s.io
         name: josdk-crd-validating-cluster-role
       subjects:
         - kind: ServiceAccount
           name: avantra-operator
           namespace: avantra
       ---

2. Assigning credentials to the Avantra Operator Service Account

       kubectl -n=avantra patch serviceaccount avantra-operator \
                 -p '{"imagePullSecrets": [{"name": "avantra.com"}]}'

   This command assigns the access data to the Avantra Operator service account in the namespace. If another service account is to be used, the access data must be assigned to that account.

3. Install Avantra Operator Custom Resource Definition

   Place the YAML code below in a file for easiest deployment. If the file is called `02_CreateServiceDefinition.yaml` then you can run this on your cluster by running `kubectl -n=avantra create -f 02_CreateServiceDefinition.yaml`

       apiVersion: apiextensions.k8s.io/v1
       kind: CustomResourceDefinition
       metadata:
         name: avantras.avantra.com
       spec:
         group: avantra.com
         names:
           kind: Avantra
           plural: avantras
           shortNames:
           - avantra
           singular: avantra
         scope: Namespaced
         versions:
         - name: v1
           schema:
             openAPIV3Schema:
               properties:
                 spec:
                   properties:
                     master:
                       properties:
                         masterCpuSize:
                           type: string
                         indexVolumeSize:
                           type: string
                         annotations:
                           additionalProperties:
                             type: string
                           type: object
                         masterImage:
                           type: string
                         masterMemorySize:
                           type: string
                         masterUI:
                           properties:
                             annotations:
                               additionalProperties:
                                 type: string
                               type: object
                             isActive:
                               type: boolean
                           type: object
                         masterCommunication:
                           properties:
                             annotations:
                               additionalProperties:
                                 type: string
                               type: object
                           type: object
                       type: object
                     ui:
                       properties:
                         uiImage:
                           type: string
                         uiMemorySize:
                           type: string
                         uiFrontend:
                           properties:
                             annotations:
                               additionalProperties:
                                 type: string
                               type: object
                           type: object
                         slrVolumeSize:
                           type: string
                         annotations:
                           additionalProperties:
                             type: string
                           type: object
                         uiEvent:
                           properties:
                             annotations:
                               additionalProperties:
                                 type: string
                               type: object
                           type: object
                         uiCpuSize:
                           type: string
                         indexVolumeSize:
                           type: string
                       type: object
                     name:
                       type: string
                     database:
                       properties:
                         databaseName:
                           type: string
                         databaseImage:
                           type: string
                         databaseUser:
                           type: string
                         annotations:
                           additionalProperties:
                             type: string
                           type: object
                         databasePassword:
                           type: string
                         databaseCpuSize:
                           type: string
                         databaseMemorySize:
                           type: string
                         databaseVolumeSize:
                           type: string
                       type: object
                     serviceAccountName:
                       type: string
                   type: object
                 status:
                   properties:
                     installations:
                       additionalProperties:
                         properties:
                           master-replicas:
                             type: integer
                           name:
                             type: string
                           ui-replicas:
                             type: integer
                         type: object
                       type: object
                   type: object
               type: object
           served: true
           storage: true
           subresources:
             status: {}

4. Install Avantra Operator

   Place the YAML code below in a file for easiest deployment. If the file is called `03_InstallAvantraOperator.yaml` then you can run this on your cluster by running `kubectl -n=avantra create -f 03_InstallAvantraOperator.yaml`

       apiVersion: apps/v1
       kind: Deployment
       metadata:
         namespace: avantra
         labels:
           app.kubernetes.io/version: 1.0.0
           app.kubernetes.io/name: avantra-operator
         name: avantra-operator
       spec:
         replicas: 1
         selector:
           matchLabels:
             app.kubernetes.io/version: 1.0.0
             app.kubernetes.io/name: avantra-operator
         template:
           metadata:
             labels:
               app.kubernetes.io/version: 1.0.0
               app.kubernetes.io/name: avantra-operator
           spec:
             containers:
               - env:
                   - name: KUBERNETES_NAMESPACE
                     valueFrom:
                       fieldRef:
                         fieldPath: metadata.namespace
                 image: gcr.io/avantra-cust/avantra/operator/avantra-operator:latest
                 imagePullPolicy: Always
                 livenessProbe:
                   failureThreshold: 3
                   httpGet:
                     path: /q/health/live
                     port: 8080
                     scheme: HTTP
                   initialDelaySeconds: 0
                   periodSeconds: 30
                   successThreshold: 1
                   timeoutSeconds: 10
                 name: avantra-operator
                 ports:
                   - containerPort: 8080
                     name: http
                     protocol: TCP
                 readinessProbe:
                   failureThreshold: 3
                   httpGet:
                     path: /q/health/ready
                     port: 8080
                     scheme: HTTP
                   initialDelaySeconds: 0
                   periodSeconds: 30
                   successThreshold: 1
                   timeoutSeconds: 10
             serviceAccountName: avantra-operator

5. Install Avantra

   Place the YAML code below in a file for easiest deployment. If the file is called `04_InstallAvantra.yaml` then you can run this on your cluster by running `kubectl -n=avantra create -f 04_InstallAvantra.yaml`. If adjusting to match your environment all additional options are listed below.

       apiVersion: avantra.com/v1
       kind: Avantra
       metadata:
         name: avantra
       spec:
         name: avantra-services
         serviceAccountName: "avantra-operator"
         ui:
           uiImage: gcr.io/avantra-cust/avantra/ui:latest
           uiCpuSize: 1000m
           uiMemorySize: 2048Mi
         master:
           masterImage: gcr.io/avantra-cust/avantra/master:latest
         database:
           databaseImage: postgres:13
           databasePassword: 2e478fe8bc1203a76d83f35d0003941d
           databaseUser: avantra

#### UI Options

Name | Description | Default Value
--- | --- | ---
uiImage | The image for the Avantra UI | Required - no default value
uiCpuSize | The CPU size for the Avantra UI | `2000m`
uiMemorySize | The Memory size for the Avantra UI | `2048Mi`
slrVolumeSize | The size of the volume in which the ui stores its SLR data | `5Gi`
indexVolumeSize | The size of the volume in which the ui stores its index data | `5Gi`

#### Avantra Server (Master) Options

Name | Description | Default Value
--- | --- | ---
masterImage | The image for the Avantra Server | Required - no default value
masterCpuSize | The CPU size for the Avantra Server | `2000m`
masterMemorySize | The Memory size for the Avantra Server | `2048Mi`
indexVolumeSize | The size of the volume in which the server stores its index data | `5Gi`

#### Database Options

Name | Description | Default Value
--- | --- | ---
databaseImage | The image for the database Avantra uses | Required - no default value - Avantra recommends `postgres:13`
databasePassword | The database password | Required - no default value
databaseName | The name of the database | `avantra`
databaseUser | The database user | `avantra`
databaseCpuSize | The CPU size for the database | `2000m`
databaseMemorySize | The Memory size for the database | `2048Mi`
databaseVolumeSize | The size of the volume in which the database stores its data | `10Gi`

#### Overall / Operator Options

Name | Description | Default Value
--- | --- | ---
Name | Is the name of the Avantra deployment | Required - no default value
ServiceAccountName | Is the name of the service account to be used for the deployment. This service account needs the container registry access data | Required - no default value

## Post installation steps

### Logging In

Logging into your Avantra instance for the first time is completed via the avantra-ui container on port 8443. The default username and password, which should be immediately changed, are `root` and `ilsx1234`.

### Domain Names

After an installation, the domain of the Avantra Server may need to be adjusted in the UI. Depending on the set up of your environment, the name of the server container may need to be removed from this domain e.g. `avantra-master-0.avantra-master.avantra.svc.cluster.local` changed to `avantra-master.avantra.svc.cluster.local`. You can adjust this entry in the UI under the `?` menu and under the option `about`. Expand the `Avantra Master` section and adjust the value of the `MasterHost` to match the fully qualified domain name (FQDN) that remote agents will use to reach the Avantra Server. If remote agents cannot resolve this FQDN to reach the Avantra server, you wll have problems connecting remote agents.