Kubernetes : Generic

How to install OpenSquiggly on any Kubernetes service.

Overview of Installing on a Generic Kubernetes Engine

Although we’ve written specific installation instructions for some of the most commonly used Kubernetes engines on the market, OpenSquiggly can be installed on any Kubernetes system of your choice. You just need to specify the appropriate values when installing the Helm chart to control the various resources that the Helm chart creates.

If you’re installing on a supported cloud provider, you can skip this section and go to the section for your target cloud provider.

In this section we’ll walk you through the process of installing OpenSquiggly on an unlisted Kubernetes system.

Parameter Simplification

A primary goal of our Helm charts is to simplify and minimize the number of settings you need to specify to get OpenSquiggly running. Though we have quite a few potential settings you can use, we hope that you don’t need to read and understand the entire list of settings to get a basic instance running.

Toward that end, we have the cloudType setting that provides appropriate default values for that particular flavor of Kubernetes. For any specific cloudType, you can always replicate an equivalent configuration using cloudType=other and specifying additional parameters.

cloudType Value Equivalent To
cloudType=aws cloudType=other,storageProvisioner=ebs.csi.aws.com
cloudType=azure cloudType=other,storageProvisioner=disk.csi.azure.com,diskSkuName=LRS_Premium
cloudType=digitalocean cloudType=other,storageProvisioner=dobs.csi.digitalocean.com
cloudType=docker-desktop cloudType=other,storageProvisioner=docker.io/hostpath
cloudType=google cloudType=other,storageProvisioner=pd.csi.storage.gke.io,diskType=pd-ssd
cloudType=linode cloudType=other,storageProvisioner=linodebs.csi.linode.com
cloudType=minikube cloudType=other,storageProvisioner=hostpath.csi.k8s.io (assumes the Host Path CSI driver addon has been installed)

As you can see from the above table, using an unlisted flavor of Kubernetes is simply a matter of determining which storageProvisioner the Kubernetes engine provides, along with any customized disk parameters (the diskSkuName and diskType).

Persistent Volumes, Claims, & Storage Classes

OpenSquiggly needs a persistent volume (PV), which it gets by asking a persistent volume claim (PVC) to give it one. A PVC can be configured to dynamically provision a new PV on request, or it can be configured to serve up an already existing PV.

If the PVC is going to dynamically provision a new PV, then it needs to know needs to know what StorageClass class it should use, and the StorageClass in turn needs to know what Storage Provisioner it should use. Our Helm chart provides switches that can control what resources are needed depending on what you want.

In the following table, we assume you are using Helm to install an OpenSquiggly release named releasename such as with the following command:

helm install releasename opensquiggly/allinone --set cloudType=other,...other parameters to set go here as shown below...
What You Want How to Get It What Happens
Use an already existing PV named xyz useExistingPv=xyz,diskSize=xxx Creates a new PVC named releasename-pvc that serves the existing PV named xyz. You must specify a disk size that is equal to or smaller than the PV you are trying to reuse. Also, the PV you are trying to use must be in the Available state.
Get a PV from an already existing PVC named xyz useExistingPvc=xyz The opensquiggly container in the deployment created by the Helm chart will reference the PVC named xyz. The PVC will either create a new PV or serve up an existing PV depending on how it is configured. The size of the PV will also depend on how the PVC is configured. The diskSize setting, if specified, is ignored.
Dynamically provision a 40Gb PV using an existing storage class named xyz diskSize=40,useExistingStorageClass=xyz Dynamically creates a PV with a name assigned by Kubernetes, and a PVC named releasename-pvc but does not create a storage class.

Note that most default storage classes in Kubernetes have a ReclaimPolicy set to Delete. This means if you uninstall the Helm chart, the PV will be automatically deleted and you will lose your data if you don't have a backup. Be careful about using existing storage classes to ensure you get the behavior you want.
Dynamically provision a 50Gb PV that will not be deleted automatically when the release is uninstalled (ReclaimPolicy = Retain) diskSize=50,storageProvisioner=xyz A new StorageClass is created which uses the specified storage provisioner, with the StorageClass's ReclaimPolicy set to Retain.

Note that additional parameters in the StorageClass may be needed to control what type of disk to use. For example, some cloud providers allow you to choose between a regulard hard drive vs. a higher performance SSD drive (which costs extra, of course).

We recommend using high speed SSD drives when possible.

For SSD drives on Azure, add the setting diskSkuName=LRS_Premium
For SSD drives on Google, add the setting diskType=pd-ssd

If your cloud provider requires additional parameters in the StorageClass, then you'll need to create the StorageClass yourself and then use it with the useExistingStorageClass setting.

Creating a Custom Storage Class

There are limits to OpenSquiggly’s Helm charts for creating storage classes. They don’t have the ability to apply custom annotations or to apply any other parameters to the StorageClass except skuname and type.

In this case, you can always create the StorageClass yourself using a custom manifest file, and then pass the name of the StorageClass to the Helm chart using the useExistingStorageClass parameter.

Here is a template for creating a StorageClass:

apiVersion: storage.k8s.io/v1
kind: StorageClass
allowVolumeExpansion: true
    addonmanager.kubernetes.io/mode: EnsureExists
    kubernetes.io/cluster-service: "true"
  name: your-storageclass-name-here
  skuname:   # For Azure SSD, enter Premium_LRS
  type:      # For Google SSD, enter pd-ssd
provisioner: storageprovisioner-name-here
reclaimPolicy: Retain    # Enter Retain or Delete (Retain recommended)
volumeBindingMode: WaitForFirstConsumer

Save the above template to filename.yaml, fill in the parameters as appropriate, and run the command:

kubectl apply -f filename.yaml

We always recommend using a reclaimPolicy of Retain to prevent accidental deletion of your data in the event you uninstall the Helm chart.

List of All Helm Chart Values

Value Name Default Value Allowed Values Description
Basic Settings
cloudType other aws
Enter the cloud provider type or choose other for a generic system. If you enter 'other', then you must also enter a value for storageProvisioner, or specify one of useExistingPv, useExistingPvc, or useExistingStorageClass.
diskSize 32 An integer, in gigabytes (example: 32 means 32Gb) The size of the persistent volume you wish to create, in gigabytes. The persistent volume should be large enough to store your internally authored pages, cloned repos (for your mount points), logs, and indexes.
Core Storage-Related Settings
storageProvisioner Empty Any String If you want the storage class created by the Helm chart to use a specific storage provisioner supplied by your cloud provider, enter the name of the storage provisioner here. We recommend using the highest performing storage provisioner that your cloud provider allows, but if you need to choose a specific provisioner, enter it here. This option is only valid if useExistingPv, useExistingPvc and useExistingStorageClass are all empty. Consult the opensquiggly.com documentation for additional information on each cloud type and the available provisioners.
useExistingPv Empty Any String If you don't want the Helm chart to create a persistent volume, and instead use an existing persistent volume, enter the persistent volume name here
useExistingPvc Empty Any String If you don't want the Helm chart to create a persistent volume claim, and instead use an existing persistent volume claim, enter the PVC claim name here. This option is only valid if useExistingPv is empty.
useExistingStorageClass Empty Any String If you don't want the Helm chart to create a storage class, and instead use an existing storage class, enter the storage class name in useExistingStorageClass. This option is only valid if BOTH useExistingPv and useExistingPvc are empty.
Advanced Storage-Related Settings
diskSkuName Empty Any String If cloudType=azure then this value defaults to Premium_LRS unless otherwise specified. For all other cloud types, it is empty by default. When present, it adds the skuname parameter to the parameters section of the StorageClass manifest, as shown below.

  skuname: value-here

The purpose of this setting is to control the type of disk used, standard or premium SSD, on Azure. Because OpenSquiggly benefits from high performance SSD disk performance, we recommend choosing it whenever a cloud provider offers it.
diskType Empty Any String If cloudType=google then this value defaults to pd-ssd unless otherwise specified. For all other cloud types, it is empty by default. When present, it adds the type parameter to the parameters section of the StorageClass manifest, as shown below.

  type: value-here

The purpose of this setting is to control the type of disk used, standard or premium SSD, on Google.
HTTP/HTTPS, Ingress, and DNS-Related Settings
exposeWith LoadBalancer LoadBalancer or An available Ingress class name such as 'nginx' How would you like the OpenSquiggly web service exposed to the outside world? Enter 'LoadBalancer' to use a standard load balancer service, or the name of an installed ingress controller such as 'nginx' to use an Nginx-powered ingress controller. Note that using an ingress controller may require additional configuration depending on your cloud provider. See documentation here.
dnsHostName Empty A Valid URL To use OpenSquiggly with a custom DNS name, enter the desired DNS name here. This option is only valid when exposeWith is set to an ingress class (e.g., nginx, etc.)
tlsSecretName Empty Name of a Valid Secret To use OpenSquiggly with HTTPS, upload your TLS certificate as a Kubernetes secret, then enter the name of the secret that stores the certificate here. This option is only valid when exposeWith is set to an ingress class (e.g., nginx, etc.)
Application Configuration
configSecretName Empty Name of a Valid Secret The Kubernetes secret name containing configuration values for the OpenSquiggly application. See documentation here.
esMinHeapSize 512m A Valid Size String Specify the initial (mininum) ElasticSearch heap size, depending on the size of the nodes in your cluster. Heap size should be no larger that 50% of available memory of the node. Use the "m" suffix for megabytes and the "g" suffix for gigabytes.
esMaxHeapSize 512m A Valid Size String Specify the maximum ElasticSearch heap size.