Host Section

Initial configuration options specific to the installer, including how ESS should be deployed.

The first section of the ESS installer GUI is the Host section, here you will configure essential details of how ESS will be installed including; deployment type; subscription credentials; PostgreSQL to use; and whether or not your setup is airgapped.

Settings configured via the UI in this section will mainly be saved to your cluster.yml. If performing a Kubernetes deployment, you will also be able to config Host Admin settings which will save configuration into both internal.yml and deployment.yml.

Depending on your environment you will need to select either Standalone or Kubernetes Application. Standalone will install microk8s locally on your machine, and deploy to it so all pods are running locally on the host machine. Kubernetes Application will deploy to your Kubernetes infrastructure in a context you will need to have already setup via your kube config.

Deployment (Standalone)

Install

spec:
  connectivity:
    dockerhub:
      password: example
      username: example
  install:
    emsImageStore:
      password: example
      username: example
    webhooks:
      caPassphrase: example
  	# Options unique to selecting Standalone
    certManager:
      adminEmail: example@Dexample.com
    microk8s:
      dnsResolvers:
        - 8.8.8.8
        - 8.8.4.4
      postgresInCluster:
        hostPath: /data/postgres
        passwordsSeed: example

An example of the cluster.yml config generated when selecting Standalone, note that no specific flag is used within the config to specify selecting between Standalone or Kubernetes. If you choose to manually configure ESS bypassing the GUI, ensure only config options specific to how you wish to deploy are provided.

Cert Manager

EMS Image Store

spec:
  install:
    emsImageStore:
      password: token
      username: test

MicroK8s

spec:
  install:
    microk8s:
      persistentVolumesPath: /data/changed-location
      registrySize: 25Gi

what do these do? (presumedly control where microk8s data is stored), are there any known caveats to changing we should mention, same question for the registry size.

DNS Resolvers

spec:
  install:
    microk8s:
      dnsResolvers:
        - 8.8.8.8
        - 8.8.4.4

Defaulting to 8.8.8.8 and 8.8.4.4, the DNS server IPs set here will be used by all deployed pods. Click Add more DNS Resovlers to add additional entries as required.

Nginx Extra Configuration

spec:
  install:
    microk8s:
      # Not present when disabled
      nginxExtraConfiguration:
        custom-http-errors: '"404"'
        server-snippet: >-
          error_page 404 /404.html; location = /404.html { internal; return 200
          "<p>Hello World!</p>"; }

As linked via the ESS installer GUI, see the Ingress-Nginx Controller ConfigMaps documentation for the options that can be configured.

For example, if you wanted to replace the standard 404 error page, you could do this using both custom-http-errors and server-snippet. To configure via the installer, simply add the specify custom-http-errors as the Name and click Add to Nginx Extra Configuration, then provide the required value in the newly created field:

Repeat for server-snippet:

The above example is used to explain how to configure the Nginx Extra Configuration, and so is for demonstration purposes only, it is not recommended to use this example config. Ideally your webserver should manage traffic that would otherwise hit a 404 being served by ESS.

PostgreSQL in Cluster

spec:
  install:
    microk8s:
      # postgresInCluster: {} # If disabled
      postgresInCluster:
        hostPath: /data/postgres
        passwordsSeed: example

Deployment (Kubernetes)

Install

spec:
  connectivity:
    dockerhub:
      password: example
      username: example
  install:
    emsImageStore:
      password: example
      username: example
    webhooks:
      caPassphrase: example
  	# Options unique to selecting Standalone
    clusterDeployment: true
    kubeContextName: example
    namespaces: {}
    skipElementCrdsSetup: false
    skipOperatorSetup: false
    skipUpdaterSetup: false

An example of the cluster.yml config generated when selecting Kubernetes, note that no specific flag is used within the config to specify selecting between Standalone or Kubernetes. If you choose to manually configure ESS bypassing the GUI, ensure only config options specific to how you wish to deploy are provided.

Cluster Deployment

spec:
  install:
    clusterDeployment: true

Deploy the operator & the updater using Cluster Roles.

Kube Context Name

spec:
  install:
    kubeContextName: example

The name of the Kubernetes context you have already setup that ESS should be deployed into.

Skip Setup Options

spec:
  install:
    skipElementCrdsSetup: false
    skipOperatorSetup: false
    skipUpdaterSetup: false

Selecting these will allow you to skip the setup of the Element CRDs, Operator and Updater as required.

Namespaces

spec:
  install:
    # namespaces: {} # When left as default namespaces
    # namespaces: # When `Create Namespaces` is disabled
    #   createNamespaces: false
    namespaces: # When custom namespaces are provided
      elementDeployment: element-example # Omit any that should remain as default
      operator: operator-example
      updater: updater-example

Allows you to specify the namespaces you wish to deploy into, with the additional option to create them if they don't exist.

Connectivity

spec:
  connectivity:

Connected

spec:
  connectivity:
    # dockerhub: {} # When Username & Password is disabled per default
    dockerhub:
      password: password
      username: test

Connected means the installer will use the previously provided EMS Image Store credentials to pull the required pod images as part of deployment, optionally, you can specify Dockerhub credentials to reduce potential rate limiting.

Airgapped

spec:
  connectivity:
    airgapped:
      # localRegistry: localregistryurl # Not present when disabled
      sourceDirectory: /home/ubuntu/airgapped/
      # uploadImages: false # Not present when disabled

An airgapped environment is any environment in which the running hosts will not have access to the greater internet. This proposes a situation in which these hosts are unable to get access to various needed bits of software from Element and also are unable to share telemetry data back with Element.

Selecting Airgapped means the installer will rely on images stored in a registry local to your environment, by default the installer will host this registry uploading images found within the specified Source Directory, however you can alternatively specify one already present in your environment instead.

Getting setup within an Airgapped environment

Alongside each Installer binary available for download, for those customers with airgapped permissions, is an equivalent airgapped package element-enterprise-installer-airgapped-<version>-gui.tar.gz. Download and copy this archive to the machine running the installer, then use tar -xzvf element-enterprise-installer-airgapped-<version>-gui.tar.gz to extract out its contents, you should see a folder airgapped with the following directories within:

• pip
• galaxyy
• snaps
• containerd
• images

Copy the full path of the root airgapped folder, for instance, /home/ubuntu/airgapped and paste that into the Source Directory field. Should you ever update the ESS installer binary, you will need to ensure you delete and replace this airgapped folder, with its updated equivalent.

Your airgapped machine will still require access to airgapped linux repositories depending on your OS. If using Red Hat Enterprise Linux, you will also need access to the EPEL repository in your airgapped environment.

Host Admin

The Host Admin section allows you to configure the domain name and certificates to use when serving the ESS installer GUI, when running directly on the host - changes here will take affect the next time you run the installer.