Customize ESS

You can customize your ESS deployment using Kustomize overlays. The following section contains examples of customizing your ESS deployment.

By using customizations such as those below, you can add and remove the features as needed for your ESS deployment.

Applying Your Customizations

In the reference deployment, you installed ESS using installer.sh -c install. As part of the operation, the script calls the following:

kustomize build <some path>

This builds the Inrupt-provided customization for the reference deployment.

To customize your ESS deployment, you can use your own customization overlays.

Tip

  • Keep your own customizations in a safe place, such as source control.

  • Consider using automations to apply your own customization to your cluster.

  1. Create a new directory for your overlay and navigate to it:

    mkdir my-overlay
    cd my-overlay
    
  2. Now you can refer to the deployment shipped by Inrupt and add the desired changes:

    # kustomization.yaml
    apiVersion: kustomize.config.k8s.io/v1beta1
    kind: Kustomization
    
    resources:
    - <path to ESS scripts>/kubernetes/overlays/minikube/
    - labels.yaml
    
    # labels.yaml
    apiVersion: builtin
    kind: LabelTransformer
    metadata:
       name: author
    labels:
       author: me
    
  3. To verify your overlay, you can build the overlay and output to a file, such as kustomized.yaml, for review:

    kustomize build > kustomized.yaml
    

    You may want to keep an old copy of the kustomized.yaml file for comparison with your new version.

    In the example, notice that your labels are applied to a wide range of objects in the file.

  4. To preview the changes that will be applied to your cluster, you can use kubectl diff:

    kubectl diff -f kustomized.yaml
    
  5. When you are ready, you can apply the changes to your cluster:

    kustomize apply -f kustomized.yaml
    

These techniques allow you to create a number of workflows, such as:

  • approvals

  • dev -> staging -> production

  • security review

  • extra operational overlays

Design Considerations

When designing your customizations, be aware that new features and services will arrive in updates to ESS. As such, consider the following when customizing:

  1. Be selective.

    Try to focus the customization on the specific objects you want to change. For example, specify the deployment name when scaling to 20 replicas.

  2. Use labels to select things by their purpose.

    A number of parts of the deployment have labels such as role:logging to help you choose things to customize.

  3. Use merge and replace behaviors to control what you consume.

    You can choose to extend an existing object, such as a ConfigMap, using merge. If you want to fully replace the original content, you can use replace.

  4. Use namespaces to separate distinct workloads

    For instance, you may be adding logging or certificate management. Consider putting those in other namespaces if they are cluster-wide and serve other workloads, not just ESS.

    However, if you are adding a new web server that will work in tandem with ESS, then using the same namespace as ESS may be preferable.