Namespace-scoped RBAC installation for ITRS Analytics using KOTS

This guide helps you install ITRS Analytics using KOTS with namespace-scoped RBAC. By limiting access to a specific Kubernetes namespace, this method simplifies compliance—ideal for teams operating in multi-tenant or regulated environments.

Whether you’re installing in an online or air-gapped setup, this guide walks you through the entire process, including required components, minimal RBAC setup, and how to manually run preflight checks for a smooth deployment experience.

Online namespace-scoped RBAC installation Copied

This guide walks you through the installation of namespace-scoped RBAC using KOTS in an online environment. It is recommended to use wip as the <channel> value throughout. Remember, <channel> is optional if you’re installing a release from the Stable channel.

Use the following command to authenticate with the OCI Helm Registry.

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

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

Install the required prerequisites. All prerequisites must be installed outside the itrs namespace by a user with admin-level permissions.

Use the following Helm command to install cert-manager in the cert-manager namespace:

helm upgrade --install --namespace cert-manager --create-namespace --atomic --wait \
  cert-manager \
  oci://registry.itrsgroup.com/itrs-analytics/wip/cert-manager \
  --version 2.10.1+7 \
  --set cert-manager.installCRDs=true

Install the ingress-nginx controller in the ingress-nginx namespace with this command:

helm upgrade --install --namespace ingress-nginx --create-namespace --atomic --wait \
  ingress-nginx \
  oci://registry.itrsgroup.com/itrs-analytics/wip/ingress-nginx \
  --version 2.10.1+7 \
  --set-string ingress-nginx.controller.config.strict-validate-path-type="false"

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

helm upgrade --install --namespace cert-manager --create-namespace --atomic --wait \
  trust-manager \
  oci://registry.itrsgroup.com/itrs-analytics/wip/trust-manager \
  --version 2.10.1+7 \
  --set trust-manager.app.trust.namespace=cert-manager

helm upgrade --install --namespace linkerd --create-namespace --atomic --wait \
  linkerd-control-plane \
  oci://registry.itrsgroup.com/itrs-analytics/wip/linkerd-control-plane \
  --version 2.10.1+7 \
  --set kotsInstallationNamespace=itrs \
  --set certManagerNamespace=cert-manager

Install only the CRD and VWC components. Note that <channel> is not necessary for releases promoted to the Stable channel.

helm upgrade -i iax-operator oci://registry.itrsgroup.com/itrs-analytics/wip/iax-operator \
  --install \
  --namespace <namespace> \
  --create-namespace \
  --wait \
  --timeout 5m \
  --version <app-version-label> \
  --values <values yaml file>

For example:

helm upgrade -i iax-operator oci://registry.itrsgroup.com/itrs-analytics/wip/iax-operator \ 
--install \
--namespace itrs \
--create-namespace \
--wait \
--timeout 5m \
--version 2.10.1+7 \
--values replicated-manual-values.yaml

The replicated-manual-values.yaml file should contain the following:

operator:
  fullnameOverride: iax-operator
  installScope: cluster
  rbac:
    clusterRole:
      create: false

Install ITRS Analytics through KOTS, matching the app-version-label and operating in minimal RBAC mode.

kubectl kots install itrs-analytics/wip --wait-duration 5m -n itrs --shared-password password --app-version-label 2.10.1+7 --use-minimal-rbac

Follow the instructions to manually run the pre-flight checks using a custom ServiceAccount (SA).

Air-gapped namespace-scoped RBAC installation Copied

This section provides instructions for performing the same installation in an air-gapped environment. It is recommended to use wip as the <channel> value throughout. Remember, <channel> is optional if you’re installing a release from the Stable channel.

Create the itrs namespace using the following command.
```
kubectl create ns itrs
```
Download the following files from the Custom Download Portal
- KOTS CLI
- KOTS Admin Console Bundle (kotsadm.tar.gz)
- ITRS Analytics App Bundle (itrs-analytics-.airgap)

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

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

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

Install cert-manager:

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

Sample cert-manager-values.yaml file:

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

Install the ingress-nginx controller in the ingress-nginx namespace with this command:

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

Sample ingress-nginx-values.yaml file:

% cat ingress-nginx-values.yaml 

ingress-nginx:
  # Uncomment if your registry requires authentication
  # imagePullSecrets:
  #   - name: pull-secret
  controller:
    image:
      repository: {{REGISTRY_URL}}/{{REGISTRY_NAMESPACE}}/controller
    admissionWebhooks:
      patch:
        image:
          repository: {{REGISTRY_URL}}/{{REGISTRY_NAMESPACE}}/kube-webhook-certgen
    config:
      strict-validate-path-type: "false"

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

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

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

Sample trust-manager-values.yaml file:

% cat trust-manager-values.yaml 
trust-manager:
  app:
    trust:
      namespace: cert-manager
  # Uncomment if your registry requires authentication
  # global:
  #   imagePullSecrets:
  #     - name: pull-secret
  image:
    repository: {{REGISTRY_URL}}/{{REGISTRY_NAMESPACE}}/trust-manager
  defaultPackageImage:
    repository: {{REGISTRY_URL}}/{{REGISTRY_NAMESPACE}}/trust-pkg-debian-bookworm

Sample linkerd file:

% cat linkerd-values.yaml

kotsInstallationNamespace: itrs
certManagerNamespace: cert-manager

linkerd-control-plane:
  # Uncomment if your registry requires authentication
  # global:
  #   imagePullSecrets:
  #     - name: pull-secret
  controllerImage: host.docker.internal:5001/itrs/controller
  policyController:
    image:
      repository: {{REGISTRY_URL}}/{{REGISTRY_NAMESPACE}}/policy-controller
  proxy:
    image:
      repository: {{REGISTRY_URL}}/{{REGISTRY_NAMESPACE}}/proxy
  proxyInit:
    image:
      repository: {{REGISTRY_URL}}/{{REGISTRY_NAMESPACE}}/proxy-init
  debugContainer:
    image:
      repository: {{REGISTRY_URL}}/{{REGISTRY_NAMESPACE}}/debug

Use the following command to install the ITRS Analytics operator into the itrs namespace. This will install the CRD and VWC components.

helm upgrade --install iax-operator charts/iax-operator-*.tgz \
  --install \
  --namespace itrs \
  --create-namespace \
  --wait \
  --timeout 5m \
  --values operator-values.yaml

Sample operator-values.yaml file:

% cat operator-values.yaml 
operator:
  fullnameOverride: iax-operator
  installScope: cluster
  rbac:
    clusterRole:
      create: false

Install ITRS Analytics using minimal RBAC --use-minimal-rbac flag.

kubectl kots install itrs-analytics/wip --wait-duration 5m -n itrs --shared-password password \
--app-version-label 2.10.1+7 \
--kotsadm-registry REGISTRY_HOST/REGISTRY_NAMESPACE \   
--registry-username RW_USERNAME \
--registry-password RW_PASSWORD \
--use-minimal-rbac

Log in to the KOTS Admin Console and follow the instructions to upload the airgap bundle. Make sure to enable the Disable Pushing Images to Registry option, since the images were already uploaded in Step 3.
Follow the instructions to manually run the pre-flight checks using a custom ServiceAccount (SA).

Minimal RBAC permissions to KOTS Copied

You can opt to grant minimal Role-Based Access Control (RBAC) permissions to KOTS if you do not want it to have access to all resources in the namespaces on a Bring-Your-Own (BYO) cluster installation. To enable minimal RBAC, a cluster role as well as cluster role binding are needed so that KOTS can conduct preflight checks and deploy ITRS Analytics.

Download this YAML file to apply the required RBAC manifests for the installation.
Apply the YAML file before installing KOTS (recommended). While the admin console will initially issue a warning, it can be safely ignored and the preflight check will still continue.

However, if you have already installed KOTS, you can still apply the YAML file. The KOTS admin console may indicate that some checks failed due to insufficient permissions. In this case, you can manually apply the YAML file using kubectl and then rerun the preflight check from the command line.

First, download and run the preflight check script:
```
%> curl https://krew.sh/preflight | bash
```
Then run the preflight check for ITRS Analytics installation:
```
%> kubectl preflight secret/itrs/kotsadm-[application-slug]-preflight
```
Following command execution, the KOTS admin console will display the updated preflight check results, enabling you to reinitiate the installation process.
Once the YAML has been applied, install KOTS with the additional --use-minimal-rbac flag.

Pre-flight checks using custom SA Copied

When installing with the --use-minimal-rbac flag, KOTS is unable to automatically execute preflight checks due to limited permissions. As a result, you must run the preflight checks manually.

Since the kotsadm ServiceAccount used in minimal RBAC mode has restricted privileges, most preflight checks will likely fail. To address this, you need to configure a custom Preflight Service Account with cluster-wide access. This can be done in the Preflight Settings section of the Admin Console.

Example scenario: Installation with --use-minimal-rbac flag

Navigate to the Preflight Settings section.
Set a custom Preflight Service Account that has sufficient cluster-level permissions.
After saving any changes via the Config UI, a message will appear stating that KOTS cannot automatically run preflight checks.
Follow the provided CLI instructions to run the preflight checks manually.

Previous article Next article

Namespace-scoped RBAC installation for ITRS Analytics using KOTS

Online namespace-scoped RBAC installation Copied

Air-gapped namespace-scoped RBAC installation Copied

Minimal RBAC permissions to KOTS Copied

Pre-flight checks using custom SA Copied

Was this topic helpful?

Your thoughts...

How can we improve this topic?

Your thoughts...

Thank you for your feedback!