# 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 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.3/
    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

   ```sh
   docker run -it -v ${HOME}/ess:/kustomize docker.software.inrupt.com/inrupt-kustomizer:2.3.6 > 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

   ```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](https://docs.inrupt.com/ess/2.3/installation/customize-configurations/customization-start-apps/use-custom-start-app)
* [Use a Custom Approval Template](https://docs.inrupt.com/ess/2.3/installation/customize-configurations/customization-start-apps/customize-approval)

### Security

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

## Logging and Auditing

* [Use Non-JSON Formatted Logging](https://docs.inrupt.com/ess/2.3/installation/customize-configurations/customization-logging/modify-log-format)
* [Update Log Level](https://docs.inrupt.com/ess/2.3/installation/customize-configurations/customization-logging/modify-log-level)
* [Manage Auditing](https://docs.inrupt.com/ess/2.3/installation/customize-configurations/customization-logging/manage-auditing)

## Pod Maintenance and Metrics

* [Modify Prune Configuration](https://docs.inrupt.com/ess/2.3/installation/customize-configurations/customization-pod-maintenance/modify-prune)
* [Modify Storage Metrics Schedule](https://docs.inrupt.com/ess/2.3/installation/customize-configurations/customization-pod-maintenance/modify-storage-metrics)

## General

* [Scale a Deployment Using Replicas](https://docs.inrupt.com/ess/2.3/installation/customize-configurations/general/scale-a-deployment-using-replicas)
* [Use an External Service](https://docs.inrupt.com/ess/2.3/installation/customize-configurations/general/use-an-external-service)
* [Remove Overlay Content](https://docs.inrupt.com/ess/2.3/installation/customize-configurations/general/use-an-external-service)
* [Pin a Version](https://docs.inrupt.com/ess/2.3/installation/customize-configurations/general/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](https://kubernetes.io/docs/tasks/manage-kubernetes-objects/kustomization/#overview-of-kustomize).

* [Start App and Approval Pages](https://docs.inrupt.com/ess/2.3/installation/customize-configurations/customization-start-apps)
* [Security](https://github.com/inrupt/docs-gitbook/blob/main/security/README.md)
* [Logging and Auditing](https://docs.inrupt.com/ess/2.3/installation/customize-configurations/customization-logging)
* [Pod Maintenance and Metrics](https://docs.inrupt.com/ess/2.3/installation/customize-configurations/customization-pod-maintenance)
* [General](https://docs.inrupt.com/ess/2.3/installation/customize-configurations/general)