> 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/continuous-delivery/use-continuous-delivery/cd-building-blocks/environments/install-the-cluster-discovery-helm-chart.md).

# Install the cluster discovery Helm chart

Pre-provision the service account and RBAC for the cluster discovery agent when your cluster policy does not allow Harness to create them automatically

By default, Harness provisions the service discovery agent's service account and RBAC automatically when you enable cluster discovery. Use the `helm-cd-cluster-view` chart instead when your cluster policy requires a pre-provisioned (custom) service account, for example when cluster admins do not allow Harness to create ServiceAccount, ClusterRole, ClusterRoleBinding, Role, or RoleBinding objects on their own. When the agent configuration sets `kubernetes.serviceAccount` to an existing account, Harness skips creating these objects and expects them to already exist.

Harness publishes this chart at [github.com/harness/helm-cd-cluster-view](https://github.com/harness/helm-cd-cluster-view).

***

## What you will learn from this topic

* Understand [what the chart creates](#what-the-chart-creates) in your cluster.
* How to [install the chart](#install-the-chart) for cluster-wide discovery, multi-namespace discovery, or an existing service account.
* How to [point the agent at the service account](#point-the-agent-at-the-service-account) that the chart provisions.
* Understand the [chart values](#chart-values-reference) you can set.

***

## Before you begin

Make sure the following requirements are in place before you install the chart:

* **A Kubernetes cluster and Helm**: You need `helm` installed locally and access to install cluster-scoped RBAC objects in the target cluster. Go to the [Helm documentation](https://helm.sh/docs/intro/install/) if you do not already have Helm installed.
* **A working Kubernetes connector**: The agent connects to your cluster through the delegate associated with your Kubernetes connector. Go to [Kubernetes cluster connector settings reference](https://developer.harness.io/docs/platform/connectors/cloud-providers/ref-cloud-providers/kubernetes-cluster-connector-settings-reference) to review connector setup.

***

## What the chart creates

The chart renders the following resources:

* A `Namespace`, if `namespace.create` is set to `true`.
* A `ServiceAccount`, if `serviceAccount.create` is set to `true`, or a reference to an existing one through `serviceAccount.name`.
* A `ClusterRole` named `<release>-view` that grants read-only discovery permissions: `get`, `list`, and `watch` on workloads, pods, services, nodes, namespaces, jobs, and CronJobs, and `get` and `list` on horizontal pod autoscalers, ingresses, and Istio virtual services and gateways.
* A `ClusterRoleBinding` named `<release>-view`, created only when `discovery.scope` is `cluster`.
* A `RoleBinding` named `<release>-view` in each namespace listed under `discovery.namespaces`, created only when `discovery.scope` is `namespaced`. This binds the same ClusterRole with namespace-scoped effect, so the agent gets no cluster-wide grants.
* A `Role` named `<release>-mgmt` that grants write permissions in the agent's own namespace, covering pods, secrets, and configmaps, plus deployment management and pod log access. The agent uses this to run and manage itself; it is not used for discovery.
* A `RoleBinding` named `<release>-mgmt` that binds the mgmt role to the service account.

***

## Install the chart

Choose the installation option that matches how much of the cluster the agent may discover. Each option uses the `helm install` command with different values.

### Cluster-wide discovery

Install the chart with a cluster-scoped ClusterRoleBinding, which lets the agent discover resources across the whole cluster:

```bash
helm install sd-agent-rbac ./chart/service-discovery-agent \
  --namespace discovery-agent \
  --set namespace.create=true \
  --set serviceAccount.name=discovery-agent
```

### Multi-namespace discovery

Install the chart scoped to specific namespaces instead of the whole cluster, so it creates no cluster-wide grants:

```bash
helm install sd-agent-rbac ./chart/service-discovery-agent \
  --namespace discovery-agent \
  --set namespace.create=true \
  --set serviceAccount.name=discovery-agent \
  --set discovery.scope=namespaced \
  --set 'discovery.namespaces={team-a,team-b}'
```

### Bring your own service account

Reference a service account that already exists in your cluster, instead of letting the chart create one:

```bash
helm install sd-agent-rbac ./chart/service-discovery-agent \
  --namespace discovery-agent \
  --set serviceAccount.create=false \
  --set serviceAccount.name=my-existing-sa
```

***

## Point the agent at the service account

After you install the chart, set the same namespace and service account name on the agent configuration, so the server-side manifest uses your pre-provisioned objects instead of creating its own:

```yaml
kubernetes:
  namespace: discovery-agent
  serviceAccount: discovery-agent
  disableNamespaceCreation: true   # when the chart owns the namespace
```

***

## Chart values reference

The following table lists the chart values, their defaults, and what each value controls:

| Key                                  | Default           | Description                                                                     |
| ------------------------------------ | ----------------- | ------------------------------------------------------------------------------- |
| `agentNamespace`                     | Release namespace | Namespace the agent runs in.                                                    |
| `namespace.create`                   | `false`           | Create the agent namespace.                                                     |
| `serviceAccount.create`              | `true`            | Create the service account.                                                     |
| `serviceAccount.name`                | Release fullname  | Service account name. Must match the agent's `kubernetes.serviceAccount` value. |
| `discovery.scope`                    | `cluster`         | `cluster` or `namespaced`.                                                      |
| `discovery.namespaces`               | `[]`              | Target namespaces when `discovery.scope` is `namespaced`.                       |
| `rbac.extraClusterRoleRules`         | `[]`              | Extra rules added to the view ClusterRole.                                      |
| `rbac.extraRoleRules`                | `[]`              | Extra rules added to the mgmt Role.                                             |
| `commonLabels` / `commonAnnotations` | `{}`              | Applied to all resources the chart creates.                                     |

***

## Next steps

Go to [Cluster view](https://developer.harness.io/continuous-delivery/use-continuous-delivery/cd-building-blocks/environments/cluster-view-overview.md) to enable cluster discovery on an infrastructure definition.

{% @harness-feedback/feedback %}
