---
title: "Namespace-scoped RBAC using KOTS"
description: ""
url: "https://docs.itrsgroup.com/docs/itrs-analytics/platform/2.18.0/prerequisites/minimal-rbac/index.html"
---
This guide explains how to install ITRS Analytics using KOTS with namespace-scoped RBAC. It covers both online and air-gapped installations, walking you through all steps: required components, basic RBAC setup, and how to manually run preflight checks.

You must also have access to the Customer's Download Portal. If you do not have the URL or password, please contact your ITRS Account Manager or submit a [support request](https://support.itrsgroup.com/requests/new).

## Online namespace-scoped RBAC installation


**Important**


If your cluster enforces the highest Pod Security Standards (PSS) level, the standard ITRS Analytics installation procedures will not work due to the strict security constraints. In these environments, you are responsible for installing and managing all required prerequisites, including `cert-manager`, `ingress-nginx`, and `Linkerd` (if mutual TLS is needed).



This guide walks you through the installation of namespace-scoped RBAC using KOTS in an online environment.


**Note**


To deploy in an online environment with minimal RBAC privileges, follow these [instructions](#deploy-with-minimal-rbac-privileges-for-online).



1. Use the following command to authenticate with the OCI Helm Registry. You can find your username and password in the Customer's Download Portal under **Install instructions > Helm**.

    ```
    helm registry login registry.itrsgroup.com --username <username> --password <password>
    ```

2. Run the following command to create the `itrs` namespace, which will be used for installing KOTS and the application.

    ```
    kubectl create ns itrs
    ```

3. Install the required prerequisites. All prerequisites must be installed outside the `itrs` namespace by a user with admin-level permissions. Note that `2.x.x` should be modified to reflect the specific version you intend to use (for example, `2.16.0`).

    #### Install cert-manager

    a. Create the namespace if it does not already exist. Run this command:
      ```
      kubectl create ns cert-manager
      ```

    b. Create the secret for that namespace if it hasn’t been created yet. The credentials used here are the same ones used for authentication with the OCI Helm Registry.
      ```
      kubectl create secret -n cert-manager docker-registry replicated-pull-secret \
        --docker-server=proxy.itrsgroup.com \
        --docker-username={{username}} \
        --docker-password={{password}}
      ```
      
    c. Install using `helm upgrade --install`.
      ```
      helm upgrade --install --namespace cert-manager --atomic --wait \
        cert-manager \
        oci://registry.itrsgroup.com/itrs-analytics/stable/cert-manager \
        --version 2.X.X
      ```

    #### Install ingress-nginx

    a. Create the namespace if it does not already exist. Run this command:
      ```
      kubectl create ns ingress-nginx
      ```

    b. Create the secret for that namespace if it hasn’t been created yet. The credentials used here are the same ones used for authentication with the OCI Helm Registry.
      ```
      kubectl create secret -n ingress-nginx docker-registry replicated-pull-secret \
        --docker-server=proxy.itrsgroup.com \
        --docker-username={{username}} \
        --docker-password={{password}}
      ```

    c. Install using `helm upgrade --install`.
      ```
      helm upgrade --install --namespace ingress-nginx --atomic --wait \
        ingress-nginx \
        oci://registry.itrsgroup.com/itrs-analytics/stable/ingress-nginx \
        --version 2.X.X
      ```

4. If you require mutual TLS (mTLS), you can install `trust-manager` and `linkerd` using the following commands.

    #### For trust-manager command

    a. Install using `helm upgrade --install`.

      ```
      helm upgrade --install --namespace cert-manager --atomic --wait \
        trust-manager \
        oci://registry.itrsgroup.com/itrs-analytics/stable/trust-manager \
        --version 2.X.X
      ```

    #### For linkerd command

      a. Create the namespace for `linkerd-cni` if it does not already exist. Run this command.
      ```
      kubectl create ns linkerd-cni
      ```

      b. Create the secret for that namespace if it hasn’t been created yet. The credentials used here are the same as those used to authenticate with the OCI Helm Registry.
      ```
      kubectl create secret -n linkerd-cni docker-registry replicated-pull-secret \
        --docker-server=proxy.itrsgroup.com \
        --docker-username={{username}} \
        --docker-password={{password}}
      ```

      c. Install `linkerd-cni` using this command.
      ```
      helm upgrade --install --namespace linkerd-cni --atomic --wait \
        linkerd2-cni \
        oci://registry.itrsgroup.com/itrs-analytics/stable/linkerd2-cni \
        --version 2.X.X
      ```

      d. Create the namespace for `linkerd-control-plane` if it does not already exist. Run this command.

      ```
      kubectl create ns linkerd
      ```

      e. Create the secret for that namespace if it hasn’t been created yet. The credentials used here are the same as those used to authenticate with the OCI Helm Registry.
      ```
      kubectl create secret -n linkerd docker-registry replicated-pull-secret \
        --docker-server=proxy.itrsgroup.com \
        --docker-username={{username}} \
        --docker-password={{password}}
      ```

      f. Install using this command.
      ```
      helm upgrade --install --namespace linkerd --atomic --wait \
        linkerd-control-plane \
        oci://registry.itrsgroup.com/itrs-analytics/stable/linkerd-control-plane \
        --version 2.X.X
      ```

    ##### OpenShift
    
    On OpenShift, Linkerd containers must run within the namespace's allocated UID range.

      a. Before installing `linkerd2-cni` and `linkerd-control-plane`, read the UID range from the `itrs` namespace and pass the values as `--set` overrides:
      ```
      uid_range_start=$(kubectl get namespace itrs -o jsonpath='{.metadata.annotations.openshift\.io/sa\.scc\.uid-range}' | cut -d/ -f1)
      uid_range_start_plus_one=$((uid_range_start + 1))
      ```

      b. Add this flag to the `linkerd2-cni` install command:
      ```
      --set linkerd2-cni.proxyUID=$uid_range_start
      ```

      c. Add these flags to the `linkerd-control-plane` install command:
      ```
      --set linkerd-control-plane.proxy.uid=$uid_range_start
      --set linkerd-control-plane.networkValidator.securityContext.runAsUser=$uid_range_start_plus_one
      --set linkerd-control-plane.networkValidator.securityContext.runAsGroup=$uid_range_start_plus_one
      ```

      Then continue with the remaining steps in [For linkerd command](#for-linkerd-command) above.

5. When upgrading from a previous version, you must first uninstall the currently installed `iax-operator`. In addition, certain resources need to be manually removed. Perform this step once when upgrading to ITRS Analytics version 2.16.0; for subsequent versions, this step is no longer required.

    To do this, run the following commands:

    ```
    helm uninstall iax-operator -n itrs;
    kubectl delete secret -n itrs iax-operator-webhook-tls iax-operator-webhook-tls-password;
    kubectl delete validatingwebhookconfigurations iax-operator-itrs-validator
    ```

6. Install only the CRD and VWC components. Ensure that you replace `2.x.x` with the specific version you intend to use (for example, `2.16.0`).

    ```
    helm upgrade --install iax-operator-crd oci://registry.itrsgroup.com/itrs-analytics/stable/iax-operator-crd \
      --namespace <namespace> \
      --create-namespace \
      --wait \
      --timeout 5m \
      --version 2.x.x
    ```
    
7. Install ITRS Analytics through KOTS, matching the `app-version-label` and operating in minimal RBAC mode. Ensure that you replace `2.x.x` with the specific version you intend to use (for example, `2.16.0`).

    ```
    kubectl kots install itrs-analytics/stable -n itrs --app-version-label 2.x.x --use-minimal-rbac
    ```

8. Follow the instructions to manually run the pre-flight checks using a custom Service Account (SA). See [Configure custom preflight checks](#configure-custom-preflight-checks).

### Deploy with minimal RBAC privileges for online

To begin, you must manually deploy an [RBAC manifest YAML file](/itrs-analytics-platform/downloads/kots-minimal-rbac-v5.yaml "Download KOTS minimal RBAC file") that defines a `Role` and `RoleBinding` with the minimum privileges necessary to install KOTS and deploy ITRS Analytics within the target namespace.

When running the KOTS installation, be sure to include the following flags:

- `--use-minimal-rbac` — installs KOTS using namespaced-scope permissions only.
- `--ensure-rbac=false`— prevents the creation of a `Role` with wildcard privileges in the target namespace.
- `--skip-rbac-check` — skips the verification for an existing `Role` with wildcard privileges in the target namespace.


**Note**


These steps closely follow the procedure outlined in [Online namespace-scoped RBAC installation](#online-namespace-scoped-rbac-installation), with a few exceptions and additional flags.



1. Before running the authentication command for the OCI Helm Registry, create the `itrs` namespace by running the following command.

    ```
    kubectl create ns itrs
    ```

2. Once the namespace has been created, apply the [RBAC manifest YAML file](/itrs-analytics-platform/downloads/kots-minimal-rbac-v5.yaml "Download KOTS minimal RBAC file") within the KOTS installation namespace.

    ```
    kubectl apply -f kots-minimal-rbac-v5.yaml -n itrs
    ```

3. Proceed with the same steps as outlined above in the [Online namespace-scoped RBAC installation](#online-namespace-scoped-rbac-installation) section for license upload, configuration, and pulling the required images via your private registry.

4. When you are ready to install ITRS Analytics with minimal RBAC, use the `--use-minimal-rbac` flag along with the following command. This includes the additional flags `--ensure-rbac=false` and `--skip-rbac-check`. 

    ```
    kubectl kots install itrs-analytics/stable -n itrs --app-version-label 2.x.x --use-minimal-rbac --ensure-rbac=false --skip-rbac-check
    ```

    Note that `2.x.x` should be modified to reflect the specific version you intend to use (for example, `2.16.0`).

5. Follow the instructions to manually run the pre-flight checks using a custom Service Account (SA). See [Configure custom preflight checks](#configure-custom-preflight-checks).

## Air-gapped namespace-scoped RBAC installation


**Important**


If your cluster enforces the highest Pod Security Standards (PSS) level, the standard ITRS Analytics installation procedures will not work due to the strict security constraints. In these environments, you are responsible for installing and managing all required prerequisites, including `cert-manager`, `ingress-nginx`, and `Linkerd` (if mutual TLS is needed).



This guide walks you through the installation of namespace-scoped RBAC using KOTS in an air-gapped environment.


**Note**


To deploy in an air-gapped environment with minimal RBAC privileges, follow these [instructions](#deploy-with-minimal-rbac-privileges-for-air-gapped).



1. Create the `itrs` namespace using the following command.

    ```
    kubectl create ns itrs

    ```

2. Download the following files from the download portal.

    - KOTS CLI
    - KOTS Admin Console Bundle (`kotsadm.tar.gz`)
    - ITRS Analytics App Bundle (`itrs-analytics-<version>.airgap`)

3. Upload the admin console and application images to your internal image registry.

    ```
    kubectl kots admin-console push-images ./kotsadm.tar.gz REGISTRY_HOST/REGISTRY_NAMESPACE \   
    --registry-username RW_USERNAME \   
    --registry-password RW_PASSWORD
    ```

    ```
    kubectl kots admin-console push-images itrs-analytics-<version>.airgap REGISTRY_HOST/REGISTRY_NAMESPACE \   
    --registry-username RW_USERNAME \   
    --registry-password RW_PASSWORD
    ```

4. Extract the airgap bundle and helm charts.

    ```
    tar xvzf itrs-analytics-<version>.airgap app.tar.gz airgap.yaml
    mkdir -p charts
    tar xvzf app.tar.gz -C charts
    ```

5. Install prerequisites from the extracted helm charts. These prerequisites must be installed outside the KOTS installation namespace by an admin-level user.
  
**Note**


A secret must be created for each namespace in order for the command to function, and the namespace itself must be created beforehand.



    #### Install cert-manager

    a. Create the namespace if it does not already exist. Run this command:
      ```
      kubectl create ns cert-manager
      ```

    b. Create the secret for that namespace if it hasn’t been created yet.

      ```
      kubectl create secret -n cert-manager docker-registry pull-secret \
          --docker-server={{REGISTRY_URL}} \
          --docker-username={{{REGISTRY_USERNAME}} \
          --docker-password={{{REGISTRY_PASSWORD}}
      ```
      
    c. Install using `helm upgrade --install`.

      ```
      helm upgrade --install --namespace cert-manager --atomic --wait \
        cert-manager \
        charts/cert-manager-*.tgz \
        --values cert-manager-values.yaml
      ```

      Sample `cert-manager-values.yaml` file:

      ```yaml
      cert-manager:
        installCRDs: true
        # Uncomment if your registry requires authentication
        # global:
        #   imagePullSecrets:
        #     - name: pull-secret
        image:
          registry: {{REGISTRY_URL}}
          repository: ${REGISTRY_NAMESPACE}/cert-manager-controller
        webhook:
          image:
            registry: {{REGISTRY_URL}}
            repository: ${REGISTRY_NAMESPACE}/cert-manager-webhook
        cainjector:
          image:
            registry: {{REGISTRY_URL}}
            repository: ${REGISTRY_NAMESPACE}/cert-manager-cainjector
        startupapicheck:
          image:
            registry: {{REGISTRY_URL}}
            repository: ${REGISTRY_NAMESPACE}/cert-manager-startupapicheck
        acmesolver:
          image:
            registry: {{REGISTRY_URL}}
            repository: ${REGISTRY_NAMESPACE}/cert-manager-acmesolver
      ```

    #### Install ingress-nginx

    a. Create the namespace if it does not already exist. Run this command:
      ```
      kubectl create ns ingress-nginx
      ```

    b. Create the secret for that namespace if it hasn’t been created yet.

      ```
      kubectl create secret -n ingress-nginx docker-registry pull-secret \
          --docker-server={{REGISTRY_URL}} \
          --docker-username={{{REGISTRY_USERNAME}} \
          --docker-password={{{REGISTRY_PASSWORD}}
      ```
      
    c. Install using `helm upgrade --install`.

      ```
      helm upgrade --install --namespace ingress-nginx --atomic --wait \
        ingress-nginx \
        charts/ingress-nginx-*.tgz \
        --values ingress-nginx-values.yaml
      ```

      Sample `ingress-nginx-values.yaml` file:

      ```yaml
      ingress-nginx:
        # Uncomment if your registry requires authentication
        # imagePullSecrets:
        #   - name: pull-secret
        controller:
          image:
            repository: {{REGISTRY_URL}}/{{REGISTRY_NAMESPACE}}/ingress-nginx-controller
          admissionWebhooks:
            patch:
              image:
                repository: {{REGISTRY_URL}}/{{REGISTRY_NAMESPACE}}/kube-webhook-certgen
      ```

6. If you require mutual TLS (mTLS), you can install `trust-manager` and `linkerd` using the following commands.

    #### For trust-manager command

      ```
      helm upgrade --install --namespace cert-manager --atomic --wait \
        trust-manager \
        charts/trust-manager-*.tgz \
        --values trust-manager-values.yaml
      ```

      Sample `trust-manager-values.yaml` file:

      ```yaml
      trust-manager:
        app:
          trust:
            namespace: cert-manager
        # Uncomment if your registry requires authentication
        # imagePullSecrets:
        #   - name: pull-secret
        image:
          registry: {{REGISTRY_URL}}
          repository: {{REGISTRY_NAMESPACE}}/trust-manager
      ```

    #### For linkerd command

      a. Create the namespace for `linkerd-cni` if it does not already exist. Run this command.
      ```
      kubectl create ns linkerd-cni
      ```

      b. Create the secret for that namespace if it hasn’t been created yet.
      ```
      kubectl create secret -n linkerd-cni docker-registry pull-secret \
          --docker-server={{REGISTRY_URL}} \
          --docker-username={{{REGISTRY_USERNAME}} \
          --docker-password={{{REGISTRY_PASSWORD}}
      ```

      c. Install using `helm upgrade --install`:
      ```
      helm upgrade --install --namespace linkerd-cni --atomic --wait \
        linkerd2-cni \
        charts/linkerd2-cni-*.tgz \
        --values linkerd-cni-values.yaml
      ```

      Sample `linkerd-cni-values` file:

      ```yaml
      imagePullSecretName: pull-secret
      linkerd2-cni:
        # Uncomment if your registry requires authentication
        # imagePullSecrets:
        #   - name: pull-secret
        # Uncomment on OpenShift - set to the namespace UID range start
        # proxyUID: <uid_range_start>
        image:
          name: {{REGISTRY_URL}}/{{REGISTRY_NAMESPACE}}/linkerd-cni-plugin
      ```

      d. Create the namespace `linkerd-control-plane` if it does not already exist. Run this command.

      ```
      kubectl create ns linkerd
      ```

      e. Create the secret for that namespace if it hasn’t been created yet.

      ```
      kubectl create secret -n linkerd docker-registry pull-secret \
          --docker-server={{REGISTRY_URL}} \
          --docker-username={{{REGISTRY_USERNAME}} \
          --docker-password={{{REGISTRY_PASSWORD}}
      ```

      f. Install using `helm upgrade --install`.

      ```
      helm upgrade --install --namespace linkerd --atomic --wait \
        linkerd-control-plane \
        charts/linkerd-control-plane-*.tgz \
        --values linkerd-values.yaml
      ```

    ##### OpenShift

    On OpenShift, Linkerd containers must run within the namespace's allocated UID range.

      a. Before installing `linkerd2-cni` and `linkerd-control-plane`, read the UID range from the `itrs` namespace:
      ```
      uid_range_start=$(kubectl get namespace itrs -o jsonpath='{.metadata.annotations.openshift\.io/sa\.scc\.uid-range}' | cut -d/ -f1)
      uid_range_start_plus_one=$((uid_range_start + 1))
      ```

      b. In the `linkerd-cni-values.yaml` file, uncomment and set the `proxyUID` field. 
      c. In the `linkerd-values.yaml` file, uncomment and set the `proxy.uid`, `networkValidator.securityContext.runAsUser`, and `networkValidator.securityContext.runAsGroup` fields.

      Then continue with the remaining steps in [For linkerd command](#for-linkerd-command-1) above.

      Sample `linkerd-values` file:

      ```yaml
      # Uncomment if your registry requires authentication
      # imagePullSecretName: pull-secret

      replicatedTools:
        image:
          name: {{REGISTRY_URL}}/{{REGISTRY_NAMESPACE}}/replicated-tools

      linkerd-control-plane:
        # Uncomment if your registry requires authentication
        # imagePullSecrets:
        #   - name: pull-secret
        # Uncomment on OpenShift - set to the namespace UID range start and start+1
        # proxy:
        #   uid: <uid_range_start>
        # networkValidator:
        #   securityContext:
        #     runAsUser: <uid_range_start_plus_one>
        #     runAsGroup: <uid_range_start_plus_one>
        controllerImage: {{REGISTRY_URL}}/{{REGISTRY_NAMESPACE}}/linkerd-controller
        proxy:
          image:
            name: {{REGISTRY_URL}}/{{REGISTRY_NAMESPACE}}/linkerd-proxy
        debugContainer:
          image:
            name: {{REGISTRY_URL}}/{{REGISTRY_NAMESPACE}}/linkerd-debug
      ```

7. When upgrading from a previous version, you must first uninstall the currently installed `iax-operator`. In addition, certain resources need to be manually removed. Perform this step once when upgrading to ITRS Analytics version 2.16.0; for subsequent versions, this step is no longer required.

    To do this, run the following commands:

    ```
    helm uninstall iax-operator -n itrs;
    kubectl delete secret -n itrs iax-operator-webhook-tls iax-operator-webhook-tls-password;
    kubectl delete validatingwebhookconfigurations iax-operator-itrs-validator
    ```

8. Install only the CRD and VWC components using the following command:

    ```
    helm upgrade --install iax-operator-crd charts/iax-operator-crd-*.tgz \
      --namespace itrs \
      --wait \
      --timeout 5m
    ```

9. Install ITRS Analytics using minimal RBAC `--use-minimal-rbac` flag. Ensure that you replace `2.x.x` with the specific version you intend to use (for example, `2.16.0`).
 
    ```
    kubectl kots install itrs-analytics/stable -n itrs \
    --app-version-label 2.x.x \
    --kotsadm-registry REGISTRY_HOST/REGISTRY_NAMESPACE \   
    --registry-username RW_USERNAME \
    --registry-password RW_PASSWORD \
    --use-minimal-rbac
    ```

10. Log in to the KOTS Admin Console and follow the instructions to [upload the airgap bundle](https://docs.itrsgroup.com/docs/itrs-analytics/platform/2.18.0/install/install-via-kots-airgap/index.html#log-in-to-the-admin-console). Make sure to enable the **Disable Pushing Images to Registry** option, since the images were already uploaded.

11. Follow the instructions to manually run the pre-flight checks using a custom Service Account (SA). See [Configure custom preflight checks](#configure-custom-preflight-checks).

### Deploy with minimal RBAC privileges for air-gapped

If you wish to install ITRS Analytics in an air-gapped, namespace-scoped environment with minimal RBAC, follow these additional steps. Instead of allowing KOTS to automatically create RBAC resources, you must manually deploy a predefined RBAC manifest that grants only the necessary privileges.

When running the KOTS installation, be sure to include the following flags:

- `--use-minimal-rbac` — installs KOTS using namespaced-scope permissions only.
- `--ensure-rbac=false`— prevents the creation of a `Role` with wildcard privileges in the target namespace.
- `--skip-rbac-check` — skips the verification for an existing `Role` with wildcard privileges in the target namespace.


**Note**


These steps closely follow the procedure outlined in [Air-gapped namespace-scoped RBAC installation](#air-gapped-namespace-scoped-rbac-installation), with a few exceptions and additional flags.



1. Once the namespace has been created, apply the [RBAC manifest YAML file](/itrs-analytics-platform/downloads/kots-minimal-rbac-v5.yaml "Download KOTS minimal RBAC file") within the KOTS installation namespace.

    ```
    kubectl apply -f kots-minimal-rbac-v5.yaml -n itrs
    ```

2. Ensure that `kots-minimal-rbac-v5.yaml` includes only the essential RBAC roles required for KOTS to function.

3. Proceed with the same steps as outlined above in the [Air-gapped namespace-scoped RBAC installation](#air-gapped-namespace-scoped-rbac-installation) section for license upload, configuration, and pulling the required images via your private registry.

4. When you are ready to install ITRS Analytics with minimal RBAC, use the `--use-minimal-rbac` flag along with the following command. This includes the additional flags `--ensure-rbac=false` and `--skip-rbac-check`.

    ```
    kubectl kots install itrs-analytics/stable -n itrs \
    --app-version-label 2.x.x \
    --kotsadm-registry REGISTRY_HOST/REGISTRY_NAMESPACE \   
    --registry-username RW_USERNAME \
    --registry-password RW_PASSWORD \
    --use-minimal-rbac \
    --ensure-rbac=false \
    --skip-rbac-check
    ```

    Note that `2.x.x` should be modified to reflect the specific version you intend to use (for example, `2.16.0`).

5. Log in to the KOTS Admin Console and follow the instructions to [upload the airgap bundle](https://docs.itrsgroup.com/docs/itrs-analytics/platform/2.18.0/install/install-via-kots-airgap/index.html#log-in-to-the-admin-console). Make sure to enable the **Disable Pushing Images to Registry** option, since the images were already uploaded.

6. Follow the instructions to manually run the pre-flight checks using a custom Service Account (SA). See [Configure custom preflight checks](#configure-custom-preflight-checks).

## Configure custom preflight checks

When installing KOTS with the `--use-minimal-rbac` flag, it cannot automatically run preflight checks. In this scenario, you must run the preflight checks manually. Furthermore, most preflight checks are expected to fail due to the restricted permissions of the default `kotsadm` Service Account. 

To address this, you must supply a custom **Preflight Service Account** with cluster-wide access.


**Note**


Beginning with ITRS Analytics 2.18.1, the static manifest approach for creating the preflight `ServiceAccount` and RBAC resources, previously provided as a downloadable YAML file, is deprecated. It is replaced by a chart-driven workflow that renders the `ServiceAccount` and RBAC bindings directly from the `iax-installation-support` Helm chart.



To configure the preflight service account, follow these steps:

1. Obtain the `iax-installation-support` chart that matches your ITRS Analytics version.

   For online installations, pull the chart from the ITRS OCI registry. You can find your username and password in the customer's Download Portal under **Install instructions > Helm**.

   ```bash
   helm registry login registry.itrsgroup.com --username USERNAME --password PASSWORD
   helm pull oci://registry.itrsgroup.com/itrs-analytics/stable/iax-installation-support \
     --version <version>
   ```

   For air-gapped installations, the chart is already included in the airgap bundle. After extracting `app.tar.gz` (see [Extract the airgap bundle and helm charts](#air-gapped-namespace-scoped-rbac-installation)), change into the extracted charts directory by running `cd charts/` so that subsequent commands can find `iax-installation-support-*.tgz`. This keeps the same `helm template` command valid for both online and air-gapped workflows.

2. Generate the Preflight Service Account and RBAC resources from the chart, then apply them to your cluster.

   ```bash
   helm template sa-only iax-installation-support-*.tgz \
     --namespace itrs \
     --show-only charts/iax-troubleshoot/templates/serviceaccount.yaml \
     --show-only charts/iax-troubleshoot/templates/roles.yaml \
     --show-only charts/iax-troubleshoot/templates/clusterroles.yaml \
     --set iax-troubleshoot.kots.enabled=true \
     --set iax-troubleshoot.rbac.serviceAccount.name=custom-preflight-sa \
     | kubectl apply -f -
   ```

   This creates a `ServiceAccount`, `Role`, `RoleBinding`, `ClusterRole`, and `ClusterRoleBinding` with the minimum permissions required by preflight checks. For more information, see [Namespace-scoped RBAC using KOTS](#air-gapped-namespace-scoped-rbac-installation).

3. Navigate to the **Preflight Settings** section and specify `custom-preflight-sa` as the custom Preflight Service Account.

    ![Preflight Settings](https://docscdn.itrsgroup.com/itrs-analytics-platform/images/rbac-preflight-settings-field.png)

4. After saving any changes via the Config UI, a message will appear stating that KOTS cannot automatically run preflight checks.

    ![KOTS warning prompt](https://docscdn.itrsgroup.com/itrs-analytics-platform/images/rbac-preflight-settings-kots-prompt.png)

5. Follow the provided CLI instructions to run the preflight checks manually. You must have admin-level permissions to perform this task.

   ```bash
   curl https://krew.sh/preflight | bash
   kubectl preflight secret/itrs/kotsadm-itrs-analytics-preflight
   ```

6. After the preflight checks are completed, the KOTS Admin Console will refresh and display the standard preflight results screen, as it does when operating in non-namespaced (cluster-scoped) mode.

### Minimum access requirements for the custom Preflight Service Account

To ensure correct operation, the service account must be granted both namespace-scoped and cluster-wide permissions.

#### Namespace-scoped permissions

Within the installation namespace, the service account requires the ability to:

- Read Kubernetes secrets
- Read Kubernetes services (supported starting from ITRS Analytics 2.13.0)
- List pods
- Initiate port-forwarding sessions
- Collect basic pod metrics
- Access application configuration data
- Create and delete jobs
- Create, get, and delete `PersistentVolumeClaims`
- Create and update `ConfigMaps`
- Get pod logs
- Get and list `IAXPlatform` and `Obcerv` custom resources

#### Cluster-wide permissions

At the cluster level, the service account must be permitted to:

- Read node information
- Proxy to node endpoints
- Retrieve node-level metrics
- List available storage classes
- List available VolumeSnapshotClasses (supported starting with ITRS Analytics 2.12.0+1)
- List and get ConfigMaps (required for Linkerd version detection; supported starting with ITRS Analytics version 2.16.0)

These permissions are defined using a `Role` and `RoleBinding` for namespace-scoped access, and a `ClusterRole` and `ClusterRoleBinding` for cluster-wide access.


