Customize ESS#

You can customize your ESS deployment using Kustomize overlays.

You can customize during or after your initial installation/deployment. By using customizations, you can add and remove the features as needed for your ESS deployment.

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

  • approvals

  • dev -> staging -> production

  • security review

  • extra operational overlays

Applying Your Customizations#

Note

The installation and customization tutorials assume Infrastructure as Code (IaC) practice for managing the system and assumes the installation directory is under source control. Specifically, since secrets are stored in the configuration files, the tutorial assumes the directory is stored in a private repository and kept secure.

To customize your ESS deployment, you can create your own customization overlay(s) and apply to the deployment.

  1. Go to your ESS installation directory:

    cd ${HOME}/ess

  2. Create an overlay file with the change you want to make.

    For example, the following creates an overlay file named labels.yaml:

    # labels.yaml
apiVersion: builtin
kind: LabelTransformer
metadata:
  name: author
labels:
  author: me
fieldSpecs:
  - path: metadata/labels
    create: true

    For additional examples, see Examples.

  3. In your ESS installation directory, edit the kustomization.yaml to incorporate your customization.

    For this example, add labels.yaml to the file:

    apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

# This file was initially generated by the Inrupt installer
# You can use this file to fine-tune your environment
# Find out more at: https://docs.inrupt.com/ess/2.0/installation/customize-configurations/

resources:
  - ../release/ess/deployment/kubernetes/overlays/standalone/

components:
  # These are your inputs
  - inputs/
  # inrupt-kustomizer can copy them to the places where they are needed using replacements
  - ../release/ess/deployment/kubernetes/overlays/standalone/replacements/

## Added kustomization for the labels.yaml.
transformers:
  - labels.yaml

    For other customizations, modify the kustomization.yaml as appropriate.

  4. Build the kustomized.yaml file (same command as in the initial installation/deployment):

    docker run -it -v ${HOME}/ess:/kustomize docker.software.inrupt.com/inrupt-kustomizer:2.1 > kustomized.yaml

    Review Changes

    To review the changes that will be applied to your cluster, you can:

    • Use kubectl diff to see the changes from the running cluster:

      kubectl diff -f kustomized.yaml

    • Use the diff option for your source control (e.g., git diff if using GitHub as your source control):

      git diff kustomized.yaml

  5. When you are ready, you can apply the changes to your cluster (same command as in the initial installation/deployment):

    kubectl apply -f kustomized.yaml

    Tip

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

  6. Commit the changes to source control.

    Important

    Ensure that the repo is private.

Examples#

The pages in this section contain examples for customizing your ESS deployment.

Start App and Approval Pages#

Security#

Logging and Auditing#

Pod Maintenance and Metrics#

General#

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.

Additional Information#

For more information on Kustomize, see Declarative Management of Kubernetes Objects Using Kustomize.

On this page