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.

Note

To deploy in an online environment with minimal RBAC privileges, follow these instructions.

1. 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>
   

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 Copied

   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 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 \
     -f cert-manager-values.yaml
   

   Sample cert-manager-values.yaml file:

   cert-manager:
     installCRDs: true
     global:
       imagePullSecrets:
         - name: pull-secret
     image:
       registry: proxy.itrsgroup.com/proxy/itrs-analytics/docker.itrsgroup.com
     webhook:
       image:
         registry: proxy.itrsgroup.com/proxy/itrs-analytics/docker.itrsgroup.com
     cainjector:
       image:
         registry: proxy.itrsgroup.com/proxy/itrs-analytics/docker.itrsgroup.com
     startupapicheck:
       image:
         registry: proxy.itrsgroup.com/proxy/itrs-analytics/docker.itrsgroup.com
     acmesolver:
       image:
         registry: proxy.itrsgroup.com/proxy/itrs-analytics/docker.itrsgroup.com
   

   Install ingress-nginx Copied

   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 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 \
     -f ingress-nginx-values.yaml
   

   Sample ingress-nginx-values.yaml file:

   ingress-nginx:
     imagePullSecrets:
       - name: pull-secret
     controller:
       image:
         registry: proxy.itrsgroup.com/proxy/itrs-analytics/docker.itrsgroup.com
       admissionWebhooks:
         patch:
           image:
             registry: proxy.itrsgroup.com/proxy/itrs-analytics/docker.itrsgroup.com
   

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

   For trust-manager command Copied

   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 \
     -f trust-manager-values.yaml
   

   Sample trust-manager-values.yaml file:

   trust-manager:
     app:
       trust:
         namespace: cert-manager
     imagePullSecrets:
       - name: pull-secret
     image:
       registry: proxy.itrsgroup.com/proxy/itrs-analytics/docker.itrsgroup.com
   

   For linkerd command Copied

   a. Create the namespace if it does not already exist. Run this command.

   kubectl create ns linkerd
   

   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 docker-registry pull-secret \
     --docker-server=proxy.itrsgroup.com \
     --docker-username={{username}} \
     --docker-password={{password}}
   

   c. 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 \
     -f linkerd-values.yaml
   

   Sample linkerd-values.yaml file:

   kotsInstallationNamespace: itrs
   certManagerNamespace: cert-manager
   imagePullSecretName: pull-secret
   
   kubectl:
     image:
       name: proxy.itrsgroup.com/proxy/itrs-analytics/docker.itrsgroup.com/replicated/replicated-tools
     imagePullSecrets:
       - name: pull-secret
   
   linkerd-control-plane:
     imagePullSecrets:
       - name: pull-secret
     controllerImage: proxy.itrsgroup.com/proxy/itrs-analytics/docker.itrsgroup.com/chainguard/linkerd-controller
     proxy:
       image:
         name: proxy.itrsgroup.com/proxy/itrs-analytics/docker.itrsgroup.com/chainguard/linkerd-proxy
     proxyInit:
       image:
         name: proxy.itrsgroup.com/proxy/itrs-analytics/docker.itrsgroup.com/chainguard/linkerd-proxy-init
     debugContainer:
       image:
         name: proxy.itrsgroup.com/proxy/itrs-analytics/docker.itrsgroup.com/chainguard/linkerd-debug
   

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.

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.

Note

These steps closely follow the procedure outlined in 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 within the KOTS installation namespace.

   kubectl apply -f kots-minimal-rbac-v4.yaml -n itrs
   

3. 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.

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.

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.

Note

To deploy in an air-gapped environment with minimal RBAC privileges, follow these instructions.

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 Copied

   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:

   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 Copied

   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:

   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 Copied

   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:

   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 Copied

   a. Create the namespace if it does not already exist. Run this command:

   kubectl create ns linkerd
   

   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 linkerd 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 --atomic --wait \
     linkerd-control-plane \
     charts/linkerd-control-plane-*.tgz \
     --values linkerd-values.yaml
   

   Sample linkerd-values file:

   kotsInstallationNamespace: itrs
   certManagerNamespace: cert-manager
   # Uncomment if your registry requires authentication
   # imagePullSecretName: pull-secret
   
   kubectl:
     image:
       name: {{REGISTRY_URL}}/{{REGISTRY_NAMESPACE}}/replicated-tools
   
   linkerd-control-plane:
     # Uncomment if your registry requires authentication
     # imagePullSecrets:
     #   - name: pull-secret
     controllerImage: {{REGISTRY_URL}}/{{REGISTRY_NAMESPACE}}/linkerd-controller
     proxy:
       image:
         name: {{REGISTRY_URL}}/{{REGISTRY_NAMESPACE}}/linkerd-proxy
     proxyInit:
       image:
         name: {{REGISTRY_URL}}/{{REGISTRY_NAMESPACE}}/linkerd-proxy-init
     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. 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.

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.

Note

These steps closely follow the procedure outlined in 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 within the KOTS installation namespace.

   kubectl apply -f kots-minimal-rbac-v4.yaml -n itrs
   

2. Ensure that kots-minimal-rbac-v4.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 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. 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 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:

1. 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-v4.yaml -n itrs
   

2. Navigate to the Preflight Settings section and specify the custom Preflight Service Account to use.

   

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

   

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

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

5. 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
• 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

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
• 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 should be defined using Role and RoleBinding, along with the appropriate bindings.