> For the complete documentation index, see [llms.txt](https://docs.inrupt.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.inrupt.com/ess/3.0/installation/customize-configurations.md). # Customize ESS You can customize your ESS deployment using [Kustomize](https://github.com/kubernetes-sigs/kustomize) [overlays](https://kubernetes.io/docs/tasks/manage-kubernetes-objects/kustomization/#bases-and-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: ```bash 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: ```yaml 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 {% hint style="info" %} **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. {% endhint %} {% hint style="danger" %} **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** {% endhint %} Apply your overlay directly to the cluster: ```bash kubectl apply -k overlays/my-env ``` {% hint style="info" %} 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. {% endhint %} ### 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: ```yaml # 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`**: ```yaml transformers: - labels.yaml ``` To target a specific service deployment, use the `target` field: ```yaml patches: - target: kind: Deployment name: ess-pod-storage patch: |- apiVersion: apps/v1 kind: Deployment metadata: name: ess-pod-storage spec: replicas: 4 ``` {% hint style="warning" %} Ensure that your forked repository is **private**. {% endhint %} ## Examples The pages in this section contain examples for customizing your ESS deployment. ### Start App and Approval Pages * [Use a Custom Start Application](/ess/3.0/installation/customize-configurations/customization-start-apps/use-custom-start-app.md) * [Use a Custom Approval Template](/ess/3.0/installation/customize-configurations/customization-start-apps/customize-approval.md) ### Security * [Set Authorization Client Allow List](/ess/3.0/installation/customize-configurations/customization-security/modify-authz-client-list.md) * [Set Initial Pod Clients Allow List](/ess/3.0/installation/customize-configurations/customization-security/modify-pod-client-list.md) * [Manage Token Issuer Allow/Deny Lists](/ess/3.0/installation/customize-configurations/customization-security/manage-identity-providers.md) * [Use Official Certificate Authority](/ess/3.0/installation/customize-configurations/customization-security/use-production-lets-encrypt.md) * [Add Custom Certificates to ESS Services](/ess/3.0/installation/customize-configurations/customization-security/add-custom-certs.md) ## Logging and Auditing * [Use Non-JSON Formatted Logging](/ess/3.0/installation/customize-configurations/customization-logging/modify-log-format.md) * [Update Log Level](/ess/3.0/installation/customize-configurations/customization-logging/modify-log-level.md) * [Manage Auditing](/ess/3.0/installation/customize-configurations/customization-logging/manage-auditing.md) ## Pod Maintenance and Metrics * [Modify Prune Configuration](/ess/3.0/installation/customize-configurations/customization-pod-maintenance/modify-prune.md) * [Modify Storage Metrics Schedule](/ess/3.0/installation/customize-configurations/customization-pod-maintenance/modify-storage-metrics.md) ## General * [Scale a Deployment Using Replicas](/ess/3.0/installation/customize-configurations/general/scale-a-deployment-using-replicas.md) * [Use an External Service](/ess/3.0/installation/customize-configurations/general/use-an-external-service.md) * [Remove Overlay Content](/ess/3.0/installation/customize-configurations/general/use-an-external-service.md) * [Pin a Version](/ess/3.0/installation/customize-configurations/general/pin-a-version.md) ## 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](https://kubernetes.io/docs/tasks/manage-kubernetes-objects/kustomization/#overview-of-kustomize) . * [Start App and Approval Pages](/ess/3.0/installation/customize-configurations/customization-start-apps.md) * [Security](https://github.com/inrupt/docs-gitbook/tree/main/security/README.md) * [Logging and Auditing](/ess/3.0/installation/customize-configurations/customization-logging.md) * [Pod Maintenance and Metrics](/ess/3.0/installation/customize-configurations/customization-pod-maintenance.md) * [General](/ess/3.0/installation/customize-configurations/general.md)