Namespace-scoped RBAC using KOTS

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.

Online namespace-scoped RBAC installation Copied

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

Use the following command to authenticate with the OCI Helm Registry. You can find your username and password in the Download Portal under Install instructions > Helm.
```
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. Note that 2.x.x+x should be modified to reflect the specific version you intend to use (for example, 2.11.0+6).

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/stable/cert-manager \
  --version 2.x.x+x \
  --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/stable/ingress-nginx \
  --version 2.x.x+x \
  --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.

For trust-manager command:

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

For linkerd command:

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

Install only the CRD and VWC components. Note that 2.x.x+x should be modified to reflect the specific version you intend to use (for example, 2.11.0+6).

helm upgrade --install iax-operator oci://registry.itrsgroup.com/itrs-analytics/stable/iax-operator \
  --namespace <namespace> \
  --create-namespace \
  --wait \
  --timeout 5m \
  --version 2.x.x+x \
  --values <values yaml file>

For example:

helm upgrade --install iax-operator oci://registry.itrsgroup.com/itrs-analytics/stable/iax-operator \
  --namespace itrs \
  --create-namespace \
  --wait \
  --timeout 5m \
  --version 2.x.x+x \
  --values operator-values.yaml

The operator-values.yaml file should contain the following:

operator:
  fullnameOverride: iax-operator
  installScope: cluster

Install ITRS Analytics through KOTS, matching the app-version-label and operating in minimal RBAC mode. Note that 2.x.x+x should be modified to reflect the specific version you intend to use (for example, 2.11.0+6).
```
kubectl kots install itrs-analytics/stable -n itrs --app-version-label 2.x.x+x --use-minimal-rbac
```
Follow the instructions to manually run the pre-flight checks using a custom Service Account (SA). See Configure custom preflight checks.

Deploy with minimal RBAC privileges for online Copied

To begin, you must manually deploy an RBAC manifest YAML 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.

These steps closely follow the procedure outlined above, with a few exceptions and additional flags:

Before running the authentication command for the OCI Helm Registry, create the itrs namespace by running the following command.
```
kubectl create ns itrs
```
Once the namespace has been created, apply the RBAC manifest YAML file within the KOTS installation namespace.
```
kubectl apply -f kots-minimal-rbac.yaml -n itrs
```
Proceed with the same steps as outlined above in the Online namespace-scoped RBAC installation section for license upload, configuration, and pulling the required images via your private registry.
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+x --use-minimal-rbac --ensure-rbac=false --skip-rbac-check
```
Note that 2.x.x+x should be modified to reflect the specific version you intend to use (for example, 2.11.0+6).
Follow the instructions to manually run the pre-flight checks using a custom Service Account (SA). See Configure custom preflight checks.

Air-gapped namespace-scoped RBAC installation Copied

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

Create the itrs namespace using the following command.
```
kubectl create ns itrs
```
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)

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.

For trust-manager command:

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

Sample trust-manager-values.yaml file:

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

For linkerd command:

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

Sample linkerd-values file:

% cat linkerd-values.yaml
kotsInstallationNamespace: itrs
certManagerNamespace: cert-manager

kubectl:
  image:
    name: {{REGISTRY_URL}}/{{REGISTRY_NAMESPACE}}/kubectl

linkerd-control-plane:
  # Uncomment if your registry requires authentication
  # imagePullSecrets:
  #   - name: pull-secret
  controllerImage: {{REGISTRY_URL}}/{{REGISTRY_NAMESPACE}}/controller
  policyController:
    image:
      name: {{REGISTRY_URL}}/{{REGISTRY_NAMESPACE}}/policy-controller
  proxy:
    image:
      name: {{REGISTRY_URL}}/{{REGISTRY_NAMESPACE}}/proxy
  proxyInit:
    image:
      name: {{REGISTRY_URL}}/{{REGISTRY_NAMESPACE}}/proxy-init
  debugContainer:
    image:
      name: {{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 \
  --namespace itrs \
  --create-namespace \
  --wait \
  --timeout 5m \
  --values operator-values.yaml

Sample operator-values.yaml file:

replicated:
  # Uncomment if your registry requires authentication
  # imagePullSecrets:
  #   - name: pull-secret
  image:
    registry: {{REGISTRY_URL}}
    repository: {{REGISTRY_NAMESPACE}}/replicated-sdk-image
  isAirgap: true
operator:
  fullnameOverride: iax-operator
  installScope: cluster

Install ITRS Analytics using minimal RBAC --use-minimal-rbac flag. Note that 2.x.x+x should be modified to reflect the specific version you intend to use (for example, 2.11.0+6).

kubectl kots install itrs-analytics/stable -n itrs \
--app-version-label 2.x.x+x \
--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.
Follow the instructions to manually run the pre-flight checks using a custom Service Account (SA). See Configure custom preflight checks.

Deploy with minimal RBAC privileges for air-gapped Copied

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.

These steps closely follow the procedure outlined above, with a few exceptions and additional flags:

Once the namespace has been created, apply the RBAC manifest YAML file within the KOTS installation namespace.
```
kubectl apply -f kots-minimal-rbac.yaml -n itrs
```
Ensure that kots-minimal-rbac.yaml includes only the essential RBAC roles required for KOTS to function.
Proceed with the same steps as outlined above in the Air-gapped namespace-scoped RBAC installation section for license upload, configuration, and pulling the required images via your private registry.
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+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+x should be modified to reflect the specific version you intend to use (for example, 2.11.0+6).
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.
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 Copied

Important

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.

To configure the preflight service account, follow these steps:

Create a custom Preflight Service Account that has sufficient cluster-level permissions. The service account requires both namespace-scoped and cluster-wide access at a minimum, see Minimum access requirements for the custom Preflight Service Account.

Note
You can use the included sample preflight admin SA manifest file to apply the necessary minimum permissions.

To apply it, run the following command:
```
kubectl apply -f preflight-admin-sa.yaml -n itrs
```
Navigate to the Preflight Settings section and specify the custom Preflight Service Account to use.
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.

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

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 Copied

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

Namespace-scoped permissions Copied

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

Read Kubernetes secrets
List pods
Initiate port-forwarding sessions
Collect basic pod metrics
Access application configuration data

Cluster-wide permissions Copied

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

These permissions should be defined using Role and RoleBinding, along with the appropriate bindings.

Previous article Next article

Namespace-scoped RBAC using KOTS

Online namespace-scoped RBAC installation Copied

Deploy with minimal RBAC privileges for online Copied

Air-gapped namespace-scoped RBAC installation Copied

Deploy with minimal RBAC privileges for air-gapped Copied

Configure custom preflight checks Copied

Minimum access requirements for the custom Preflight Service Account Copied

Namespace-scoped permissions Copied

Cluster-wide permissions Copied

Was this topic helpful?

Your thoughts...

How can we improve this topic?

Your thoughts...

Thank you for your feedback!