Customize ESS

You can customize your ESS deployment using Kustomize overlays.

Inrupt provides access to a Git repository containing the Kustomize manifests for ESS. The repository is structured so that you fork it, create your own overlays, and pull upstream tags to upgrade.

Repository Structure

The repository Inrupt provides has the following structure:

ess-kustomize-releases/
  base/                        # Service deployment manifests (managed by Inrupt)
  components/                  # Optional feature components (audit, security, scaling, etc.)
  generated/images/            # Image digest references
  overlays/examples/           # Example overlay configurations
  docs/                        # Quickstart and upgrade guides
  VERSION                      # Release metadata
  CHANGELOG.md                 # Release notes

• base/ contains the Kubernetes manifests for each ESS service. These are managed by Inrupt and should not be modified directly.

• components/ contains optional Kustomize components that you can include in your overlay to enable features such as audit sinks, Kafka encryption, HPA autoscaling, pod security standards, and more.

• overlays/examples/ contains example overlay configurations that you can copy and customize for your environment.

Creating Your Overlay

To customize ESS, create your own overlay by copying an example:

cp -r overlays/examples/production overlays/my-env

Your overlay's kustomization.yaml references the base service manifests and includes the components you need. For example:

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

namespace: ess

# Reference the base service manifests
resources:
  - ../../../base/ess-pod-storage
  - ../../../base/ess-pod-provision
  - ../../../base/authorization/authorization-acp
  - ../../../base/ess-openid
  - ../../../base/ess-webid
  - ../../../base/ess-start
  - ../../../base/ess-notification
  - ../../../base/platform/ess-platform-management
  - ../../../base/platform/ess-purger-service
  - ../../../base/ess-vc-issuer
  # ... additional services as needed

# Include optional components
components:
  - ../../../components/kafka-clients-sasl
  - ../../../components/hpa-autoscaling
  - ../../../components/secure-container-security-context
  # Image versions - MUST BE LAST
  - ../../../generated/images

# Environment-specific patches
patches:
  - path: my-patches.yaml

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.

Warning

CRITICAL SECURITY REQUIREMENT

NEVER commit files containing secrets such as .env or JWT to version control. These files must be managed securely.

As part of updating the inputs for your deployment:

1. Review the template secret files

2. Set strong secrets for the values, such as strong passwords

3. Store the secret securely outside your repository using one of these methods:

   • Cloud secrets management service

   • Enterprise secrets vault solution

   • Kubernetes Secrets with encryption at rest

   • Secure file system with restricted access (development only)

4. Configure your deployment to retrieve credentials from your secure storage at runtime

5. Add the secrets files to your .gitignore file immediately

Apply your overlay directly to the cluster:

kubectl apply -k overlays/my-env

To preview changes before applying, run kustomize build overlays/my-env or kubectl diff -k overlays/my-env. Consider using a GitOps tool such as ArgoCD or Flux to automate deployments from your forked repository.

Adding a Custom Patch

To customize a specific service, add a patch to the patches section of your overlay's kustomization.yaml. For example, to add a custom label to all resources:

1. Create an overlay file named labels.yaml in your overlay directory:

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

2. Reference it in your kustomization.yaml:

   transformers:
     - labels.yaml

To target a specific service deployment, use the target field:

patches:
  - target:
      kind: Deployment
      name: ess-pod-storage
    patch: |-
      apiVersion: apps/v1
      kind: Deployment
      metadata:
        name: ess-pod-storage
      spec:
        replicas: 4

Ensure that your forked repository is private.

Examples

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

Start App and Approval Pages

• Use a Custom Start Application

• Use a Custom Approval Template

Security

• Set Authorization Client Allow List

• Set Initial Pod Clients Allow List

• Manage Token Issuer Allow/Deny Lists

• Use Official Certificate Authority

• Add Custom Certificates to ESS Services

Logging and Auditing

• Use Non-JSON Formatted Logging

• Update Log Level

• Manage Auditing

Pod Maintenance and Metrics

• Modify Prune Configuration

• Modify Storage Metrics Schedule

General

• Scale a Deployment Using Replicas

• Use an External Service

• Remove Overlay Content

• Pin a Version

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 .

• Start App and Approval Pages

• Security

• Logging and Auditing

• Pod Maintenance and Metrics

• General