> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/self-managed-enterprise-edition/use-self-managed-enterprise-edition/smp-installationupgrade/helm-installation/install-using-helm.md).

# Install using Helm

Learn how to use Helm to install on-prem Harness Self-Managed Enterprise Edition.

This document explains how to use Helm to install, upgrade, or uninstall Harness Self-Managed Enterprise Edition. This document describes an installation on Google Kubernetes Engine (GKE). The same installation process, however, applies to installations on Kubernetes versions 1.*x* and later.

Helm package manager provides a declarative approach to Kubernetes application management in which software packages are specified as "charts." For more information, go to the [Helm documentation](https://helm.sh/docs/).

### Helm client version compatibility <a href="#helm-client-version-compatibility" id="helm-client-version-compatibility"></a>

Harness validates Helm client compatibility against the following versions:

* 3.9.4
* 3.10.3
* 3.11.3
* 3.12.3
* 3.13.3
* 3.14.2

{% hint style="info" %}
**NOTE**

You can also install Harness Self-Managed Enterprise Edition in an air-gapped environment. For more information, go to [Install in air-gapped environment](/self-managed-enterprise-edition/use-self-managed-enterprise-edition/smp-installationupgrade/helm-installation/install-in-an-air-gapped-environment.md).
{% endhint %}

### Role requirements <a href="#role-requirements" id="role-requirements"></a>

The account you use to install Harness Self-Managed Enterprise Edition must have the Account Admin role to create service accounts. For more information on role-based permissions, go to [RBAC in Harness](/harness-platform/use-harness-platform/platform-access-control.md).

### Update the override.yaml file <a href="#update-the-overrideyaml-file" id="update-the-overrideyaml-file"></a>

Helm chart values, default value definitions, and field descriptions are available in the [Harness Helm chart repo](https://github.com/harness/helm-charts#values).

Depending on your target environment, you'll need to update the `override.yaml` file to specify a load balancer or to specify the Harness modules to be deployed.

#### Add a load balancer <a href="#add-a-load-balancer" id="add-a-load-balancer"></a>

You can use either Istio or Nginx as your ingress controller based on your specific technical requirements. Harness Self-Managed Enterprise Edition integrates with your chosen solution, providing enhanced traffic management, security, and streamlined DevOps workflows.

Use the following procedure to add a load balancer.

{% tabs %}
{% tab title="NLB" %}
To add the URL for a load balancer, do the following:

1. In the `values.yaml` file, set the `global.loadbalancerURL` field to the URL of your load balancer. This is the URL you use for Harness.

   ```
   global:
    # -- Harness Application URL
    loadbalancerURL: http://<load-balancer-IP-address>
   ```
2. Set the `host_name` field to the IP address of the load balancer.
3. Save the file.
   {% endtab %}

{% tab title="Ingress ALB" %}
To an ingress ALB, do the following:

1. Copy the following YAML, then save it to an `ingress-alb.yaml` file.

   ```yaml
   apiVersion: networking.k8s.io/v1
   kind: Ingress
   metadata:
     annotations:
       alb.ingress.kubernetes.io/backend-protocol: HTTP
       alb.ingress.kubernetes.io/inbound-cidrs: 10.0.0.0/8
       alb.ingress.kubernetes.io/listen-ports: '[{"HTTP":80}]'
       alb.ingress.kubernetes.io/load-balancer-attributes: deletion_protection.enabled=false
       alb.ingress.kubernetes.io/scheme: internal
       alb.ingress.kubernetes.io/ssl-policy: ELBSecurityPolicy-TLS-1-2-Ext-2018-06
       alb.ingress.kubernetes.io/subnets: <subnets>
       alb.ingress.kubernetes.io/target-group-attributes: stickiness.enabled=true,stickiness.lb_cookie.duration_seconds=300
       alb.ingress.kubernetes.io/target-type: ip
       ingress.kubernetes.io/tls-minimum-version: "1.2"
     name: harness-public-ingress
     namespace: harness
   spec:
     ingressClassName: alb
     rules:
     - host: <YOUR_HOST_URL>
       http:
         paths:
         - backend:
             service:
               name: harness-ingress-controller
               port:
                 number: 80
           path: /
           pathType: Prefix
   ```
2. Replace `<YOU_HOST_URL>` with your load balancer's URL.
3. Replace `<YOUR_SUBNETS>` with your subnets.

   This sets traffic to internal only `alb.ingress.kubernetes.io/scheme: internal`.
4. Run the following command.

   ```
   kubectl apply -f ingress-alb.yaml -n <namespace>
   ```

{% endtab %}
{% endtabs %}

#### Optional: Configure a vanity URL based on your load balancer <a href="#optional-configure-a-vanity-url-based-on-your-load-balancer" id="optional-configure-a-vanity-url-based-on-your-load-balancer"></a>

You can use the script provided below to configure a vanity URL based on your load balancer. The script is available in the [Harness Helm chart](https://github.com/harness/helm-charts/blob/main/src/harness/configure-vanity-url.sh) and also accessible at the following path within your Helm manifest: `harness/configure-vanity-url.sh`.

**Prerequisites**

Before using this script, ensure the following prerequisites are met:

* You must have a subdomain URL mapped to your load balancer's static IP. The subdomain URL must adhere to one of the following example formats:
  * `http://mysubdomain.mysite.com`
  * `https://mysubdomain.mysite.com`

**Execution**

Execute this script within your cluster environment, providing three argument inputs:

1. Namespace
2. Account ID
3. Subdomain URL

```
if [ "$#" -ne 3 ]; then
    echo "Usage: $0 <namespace> <accountId> <subdomainUrl>"
    exit 1
fi

# Assign the first argument to namespace
namespace="$1"

# Assign the second argument to accountId
accountId="$2"

# Assign the second argument to subdomainUrl
subdomainUrl="$3"

MONGO_PASS=$(kubectl get secret -n $namespace mongodb-replicaset-chart -o jsonpath={.data.mongodb-root-password} | base64 --decode)
kubectl exec -it mongodb-replicaset-chart-0 -n $namespace -- mongo <<EOF
use admin
db.auth('admin', '${MONGO_PASS}')
use gateway
db.account_refs.update({"uuid":"${accountId}"},{\$set:{"subdomainUrl": "${subdomainUrl}"}})
db.account_refs.find()
use harness
db.accounts.update({"_id":"${accountId}"},{\$set:{"subdomainUrl": "${subdomainUrl}"}})
db.accounts.find()
EOF
kubectl patch configmap ng-auth-ui -n $namespace --type merge -p '{"data":{"EXPECTED_HOSTNAME":"app.harness.io"}}'
kubectl rollout restart -n $namespace deployment -l "app.kubernetes.io/name=ng-auth-ui"
```

The `app.harness.io` value in the command, `kubectl patch configmap ng-auth-ui -n $namespace --type merge -p '{"data":{"EXPECTED_HOSTNAME":"app.harness.io"}}'` should NOT be replaced with your created subdomain value, it should be set to "app.harness.io" itself.

**Example command**

The example command below executes the `configure-vanity-url.sh` script file for the `mynamespace` namespace, `abc123` account ID, and `http://smp.harnessurl.com` subdomain URL.

```
./configure-vanity-url.sh mynamespace abc123 http://smp.harnessurl.com
```

#### Pull images from the Harness private registry <a href="#pull-images-from-the-harness-private-registry" id="pull-images-from-the-harness-private-registry"></a>

{% hint style="info" %}
**HELM CHART 0.41.0 AND LATER**

Starting with **Helm chart 0.41.0**, SMP images have moved from the public `harness` Docker Hub repository to the private `harnesssecure` repository. Configure an image pull secret for the Helm release, or Harness module pods stay in `ImagePullBackOff`.

Installs on **Helm chart 0.40.x and earlier** pull from the public `harness` repository and do not need this step.
{% endhint %}

**Request private Docker Hub credentials**

Sign in to your Harness account and submit a [Zendesk support ticket](/self-managed-enterprise-edition/use-self-managed-enterprise-edition/advanced-configuration/smp-zendesk-configuration.md) to receive private Docker Hub credentials for the `harnesssecure` repository.

Treat the returned username and token as secrets. Do not commit them to source control.

**Create a Kubernetes image pull secret**

Create a [`docker-registry` secret](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/#create-a-secret-by-providing-credentials-on-the-command-line) in the same namespace where you will install Harness:

```bash
kubectl create secret docker-registry harnesssecure-cred \
  --docker-server=<REGISTRY_URL> \
  --docker-username=<dockerhub-username> \
  --docker-password=<dockerhub-token> \
  --docker-email=<email> \
  -n <namespace>
```

**Reference the secret in `override.yaml`**

Add the secret name to `global.imagePullSecrets` in your `override.yaml`:

```yaml
global:
  imagePullSecrets:
    - harnesssecure-cred
```

The secret applies to every Harness module image in the chart. You do not need to set it per module.

**Update the Harness Docker Connector for plugin images**

Plugin images used by Harness pipelines also move to the private `harnesssecure` repository. Edit the Harness Docker Connector at the **account scope** and add the same Docker Hub credentials so Harness can pull plugin images at runtime. Go to the [Docker Registry connector settings reference](https://app.gitbook.com/s/3F2TpHXhur2QtQnORSM9/use-harness-platform/connectors/cloud-providers/ref-cloud-providers/docker-registry-connector-settings-reference) to review the available fields.

For questions or assistance with this transition, contact the [Harness Customer Success team](mailto:support@harness.io).

***

#### Deploy Harness modules <a href="#deploy-harness-modules" id="deploy-harness-modules"></a>

Harness Helm chart includes Harness Platform components. You can add modules by editing the `override.yaml` file.

The Platform component and the module below is enabled by default:

* Harness Continuous Deployment (CD) - Next Generation

The Harness modules below can be enabled or disabled conditionally:

* Harness Chaos Engineering (CE)
* Harness Cloud Cost Management (CCM)
* Harness Continuous Integration (CI)
* Harness Security Testing Orchestration (STO)
* Harness Service Reliability Management (SRM)
* Harness Feature Flags (FF)
* Harness Supply Chain Security (SCS)

You can conditionally disable or enable the modules by specifying a boolean value in the `enabled` field of the YAML:

**Deploy the CI module**

```
ci:
# -- Enable to deploy CI to your cluster
enabled: true
```

**Deploy the SRM module**

```
srm:
# -- Enable to deploy SRM to your cluster
enabled: true
```

**Deploy the FF module**

```
ff:
# -- Enable to deploy FF to your cluster
enabled: true
```

**Deploy the STO module**

```
sto:
# -- Enable to deploy STO to your cluster
enabled: true
```

**Deploy the CCM module**

```
ccm:
# -- Enable to deploy Cloud Cost Management (CCM) to your cluster
enabled: true
```

**Deploy the CE module**

```
chaos:
# -- Enable to deploy Chaos Engineering (CE) to your cluster
enabled: true
```

**Deploy the SCS module**

```
ssca:
# -- Enable to deploy SSCA to your cluster
enabled: true
```

#### Add a Harness license <a href="#add-a-harness-license" id="add-a-harness-license"></a>

Harness Self-Managed Enterprise Edition needs a license to be provisioned for the Harness NextGen platform. Contact [Harness Support](mailto:support@harness.io) to procure the license and add it to the `override.yaml` file.

```
  license:
    # -- Insert NG License String to enable NG license
    ng: ''
```

### Rotate default secrets with a shared secrets override <a href="#rotate-default-secrets-with-a-shared-secrets-override" id="rotate-default-secrets-with-a-shared-secrets-override"></a>

Self-Managed Enterprise Edition ships with hardcoded default values for internal service-to-service secrets, such as JWT signing keys and service tokens. An installation that keeps the chart defaults shares identical key material with every other default installation, because most of these values have no override path of their own.

Helm chart 0.47.0 and later includes an `override-secrets.yaml` file in the [Harness Helm chart repo](https://github.com/harness/helm-charts/blob/main/src/harness/override-secrets.yaml). This file points every affected service at a single generated Kubernetes Secret named `harness-shared-secrets`, instead of the hardcoded chart or image defaults, so each installation gets its own secret material.

To rotate the default secrets, do the following:

1. Download `override-secrets.yaml` from the [Harness Helm chart repo](https://github.com/harness/helm-charts/blob/main/src/harness/override-secrets.yaml).
2. Pass the file alongside your `override.yaml` file when you install the chart.

   ```
   helm upgrade --install my-release harness/harness -n <namespace> -f override.yaml -f override-secrets.yaml
   ```

{% hint style="warning" %}
**USE `HELM UPGRADE --INSTALL` AGAINST THE CLUSTER**

The Secret is generated by a Helm `lookup` against the target namespace, so it can only see the existing values when Helm renders against the live cluster. `helm template` and other client-side dry runs cannot reach the cluster and generate a new random value on every render instead of reusing the existing one. Always apply `override-secrets.yaml` with `helm upgrade --install`, not `helm template`.
{% endhint %}

To pin a specific value instead of letting the chart generate one, for example to reuse a value carried over from an earlier rotation, set it under `global.sharedSecrets.values` in your own override file:

```yaml
global:
  sharedSecrets:
    enabled: true
    secretName: harness-shared-secrets
    values:
      jwtNextGenManagerSecret: <your-value>
```

This override does not rotate the following secrets:

* Secrets the chart already generates randomly per installation, such as the bootstrap database passwords and Looker.
* External third-party credentials, for example OAuth, cloud provider keys, SMTP, and Split/FME.
* Keys tied to integrations that are disabled by default.
* `SECURITY_SECRETS_ENCRYPTION_KEY`. Rotating this value strands data that is already encrypted with the old key.

The generated Secret carries the `helm.sh/resource-policy: keep` annotation, so it survives a `helm uninstall` and is reused if you reinstall into the same namespace.

Go to [Upgrade the Helm chart](/self-managed-enterprise-edition/use-self-managed-enterprise-edition/smp-installationupgrade/helm-installation/upgrade-helm-chart.md#include-the-shared-secrets-override-on-upgrade) to continue passing `override-secrets.yaml` on subsequent upgrades.

### Install the Helm chart <a href="#install-the-helm-chart" id="install-the-helm-chart"></a>

To use the charts, you must install Helm. To get started with Helm, go to the [Helm documentation](https://helm.sh/docs/). After you install Helm, follow the instructions below.

To install the Helm chart, do the following:

1. Add the repository.

   ```
   helm repo add harness https://harness.github.io/helm-charts
   ```
2. Create a namespace for your installation.

   ```
   kubectl create namespace <namespace>
   ```
3. Modify the `override.yaml` file with your environment settings.
4. Install the Helm chart.

   ```
   helm install my-release harness/harness -n <namespace> -f override.yaml
   ```

{% hint style="info" %}
**INSTALL THE UMBRELLA CHART, NOT INDIVIDUAL SUB-CHARTS**

The supported install path is `helm install`/`helm upgrade` against the single umbrella chart shown above, with modules toggled through `override.yaml`. Applying individual sub-charts directly with `kubectl apply` (for example, applying only the `srm` and `cd` sub-charts) is not a supported install method. The umbrella chart's bootstrap database layer (MongoDB, PostgreSQL, TimescaleDB) is a dependency of the other modules; if it isn't installed and ready first, dependent services fail to start, for example a GitOps pod stuck in `Init:CrashLoopBackOff` waiting on Mongo or Postgres, or CV Nextgen failing schema migrations against an uninitialized database.
{% endhint %}

### Verify the installation <a href="#verify-the-installation" id="verify-the-installation"></a>

After the installation completes, the services that were installed are enumerated with their status.

![](https://3633054177-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1JSJEIDB6mn0Z3a6vdyY%2Fuploads%2Fgit-blob-d7ad9d27cae9841875e6f067e2c997feaa051ff4%2Finstall-harness-self-managed-enterprise-edition-using-helm-ga-00.png?alt=media)

The services that appear depend on the modules that were installed.

To verify installation, do the following:

1. Review the list of services.
2. In your browser, type the following instruction:

   ```
   http://<load-balancer-IP-address>/auth/#/signup
   ```

   If the installation was successful, the Harness **Sign up** page appears.

### Helm chart values <a href="#helm-chart-values" id="helm-chart-values"></a>

For details about the chart values, explanations of the default values, and descriptions of the fields, go to <https://github.com/harness/helm-charts#values>.

### Use self-signed certificates with Helm-based installations <a href="#use-self-signed-certificates-with-helm-based-installations" id="use-self-signed-certificates-with-helm-based-installations"></a>

There are additional steps for self-signed certificates:

1. [Install delegates with custom certificates](/harness-platform/use-harness-platform/delegates/delegate/secure-delegates/install-delegates-with-custom-certs.md)
2. [Configure a Kubernetes build farm to use self-signed certificates](/continuous-integration/use-harness-ci/use-harness-ci/set-up-build-infrastructure/k8s-build-infrastructure/configure-a-kubernetes-build-farm-to-use-self-signed-certificates.md)
3. [Configure GitOps Agent with self-signed certificates](/continuous-delivery/use-gitops/gitops-entities/agents/harness-git-ops-agent-with-self-signed-certificates.md)

### Next steps <a href="#next-steps" id="next-steps"></a>

After installation is complete, you should create the initial Harness account, and then [create organizations and projects](/harness-platform/new-to-harness-platform/get-started.md#create-an-organization).

To get started with the modules, review the following topics:

* For Harness Continuous Integration, go to the [CI key concepts](/continuous-integration/new-to-harness-ci/key-concepts.md).
* For Harness Continuous Delivery & GitOps, go to the [CD key concepts](/continuous-delivery/new-to-continuous-delivery/overview.md#key-concepts).
* For Harness Security Testing Orchestration, go to the [STO overview](/security-testing-orchestration/new-to-sto/overview.md).
* For Harness Chaos Engineering, go to [Get started with Harness Chaos Engineering](/resilience-testing/chaos-engineering/new-to-chaos-engineering/key-concepts.md).
* For Harness Cloud Cost Management, go to [Manage cloud costs by using Harness Self-Managed Enterprise Edition](/cloud-cost-management/resources/self-managed-enterprise-edition.md).

{% @harness-feedback/feedback %}