# 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).

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

{% 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 %}

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:

   ```sh
   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`** :

   ```yaml
   # labels.yaml
   apiVersion: builtin
   kind: LabelTransformer
   metadata:
     name: author
   labels:
     author: me
   fieldSpecs:
     - path: metadata/labels
       create: true
   ```
3. In your ESS installation directory, edit the **`kustomization.yaml`** to incorporate your customization.\
   For this example, add **`labels.yaml`** to the file:

   <pre class="language-yaml"><code class="lang-yaml">
    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.4/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/
   <strong> ## Added kustomization for the labels.yaml.
   </strong><strong> transformers:
   </strong><strong>   - labels.yaml
   </strong>
    
   </code></pre>

   For other customizations, modify the **`kustomization.yaml`** as appropriate.
4. Build the **`kustomized.yaml`** file (same command found in the **`readme.txt`** during the initial installation/deployment):

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

{% hint style="info" %}
**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:

  ```sh
  kubectl diff -f `kustomized.yaml`
  ```
* Use the **`diff`** option for your source control (e.g., **`git diff`** if using GitHub as your source control):

  ```sh
  git diff `kustomized.yaml`
  ```

{% endhint %}

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

   ```sh
   kubectl apply -f `kustomized.yaml`
   ```

{% hint style="info" %}
Consider using automations to apply your own customization to your cluster.
{% endhint %}

6. Commit the changes to source control.

{% hint style="warning" %}
Ensure that the repo 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/2.4/installation/customize-configurations/customization-start-apps/use-custom-start-app.md)
* [Use a Custom Approval Template](/ess/2.4/installation/customize-configurations/customization-start-apps/customize-approval.md)

### Security

* [Set Authorization Client Allow List](/ess/2.4/installation/customize-configurations/customization-security/modify-authz-client-list.md)
* [Set Initial Pod Clients Allow List](/ess/2.4/installation/customize-configurations/customization-security/modify-pod-client-list.md)
* [Manage OpenID Token Issuer Allow/Deny Lists](/ess/2.4/installation/customize-configurations/customization-security/manage-identity-providers.md)
* [Use Official Certificate Authority](/ess/2.4/installation/customize-configurations/customization-security/use-production-lets-encrypt.md)
* [Add Custom Certificates to ESS Services](/ess/2.4/installation/customize-configurations/customization-security/add-custom-certs.md)

## Logging and Auditing

* [Use Non-JSON Formatted Logging](/ess/2.4/installation/customize-configurations/customization-logging/modify-log-format.md)
* [Update Log Level](/ess/2.4/installation/customize-configurations/customization-logging/modify-log-level.md)
* [Manage Auditing](/ess/2.4/installation/customize-configurations/customization-logging/manage-auditing.md)

## Pod Maintenance and Metrics

* [Modify Prune Configuration](/ess/2.4/installation/customize-configurations/customization-pod-maintenance/modify-prune.md)
* [Modify Storage Metrics Schedule](/ess/2.4/installation/customize-configurations/customization-pod-maintenance/modify-storage-metrics.md)

## General

* [Scale a Deployment Using Replicas](/ess/2.4/installation/customize-configurations/general/scale-a-deployment-using-replicas.md)
* [Use an External Service](/ess/2.4/installation/customize-configurations/general/use-an-external-service.md)
* [Remove Overlay Content](/ess/2.4/installation/customize-configurations/general/use-an-external-service.md)
* [Pin a Version](/ess/2.4/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/2.4/installation/customize-configurations/customization-start-apps.md)
* [Security](https://github.com/inrupt/docs-gitbook/blob/main/security/README.md)
* [Logging and Auditing](/ess/2.4/installation/customize-configurations/customization-logging.md)
* [Pod Maintenance and Metrics](/ess/2.4/installation/customize-configurations/customization-pod-maintenance.md)
* [General](/ess/2.4/installation/customize-configurations/general.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.inrupt.com/ess/2.4/installation/customize-configurations.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.