Installing complex software in customer environments often feels like walking into the unknown. Whether you’re deploying into airgapped systems, regulated industries, or heavily secured environments, it’s common to hit unexpected issues — and even more common for those issues to derail the install entirely.
One of the most frustrating causes? Security tools like antivirus or EDR silently interfering with Kubernetes components, blocking or killing processes behind the scenes.
To help solve this, we’re introducing a targeted, modular preflight check pattern — starting with a real-world use case: detecting host-level security tools. This approach improves installation reliability by catching blockers before installation even begins — and gives vendors a repeatable process they can use to define their own checks for system requirements, networking, and more.
Why Installs Fail — and Why It’s Preventable
Through field observations and support cases, we’ve seen installs fail repeatedly due to various issues, including but not limited to:
Host-level issues (embedded cluster installs):
- Endpoint security tools that kill Kubernetes processes
- Background agents that interfere with file systems
- Incompatible system configurations or network restrictions
Cluster-level issues (existing cluster installs):
- Customer-provided clusters that are misconfigured or missing required components
- Insufficient resources across the cluster
- Incompatible Kubernetes versions or missing operators
These issues are hard to catch during install — and even harder to fix mid-session.
What’s needed is a way to catch them early, in a standardized and vendor-specific way.
The Solution: Modular Preflight Checks
Our installer already includes a set of built-in preflight checks that validate system compatibility, resources, and core network requirements. These are maintained and updated regularly as part of our release cycle.
However, we recognize that not all environments — or all application requirements — can be captured universally. That’s why we’re enabling vendors to build custom preflight checks, with a flexible pattern that works alongside the installer.
This pattern allows creating preflight checks that are:
- Targeted – each check, or suite of checks validates a specific concern
- Modular – you can combine multiple YAMLs to form a complete check suite
- Repeatable – shareable with customers and maintainable in source control
Used consistently, it gives field and support teams a reliable way to validate customer environments before the installer ever runs.
Make It a Prerequisite, Not an Afterthought
Field Engineers, Solution Architects, and Success Engineers:
This ought to be a required step before any install session is scheduled.
Instead of discovering blockers live during an install:
- Ask your customer to run your preflight checks as part of your install readiness process
- Require the results to pass, or be reviewed and accepted, before proceeding
- Use the results to adjust configurations or escalate issues ahead of time
This small process change can prevents a major class of failures — and can lead to building trust with your customer.
Example 1: Run Security Tools Preflight Checks
Step 1: Download the Preflight Spec
curl -LO https://raw.githubusercontent.com/replicatedhq/troubleshoot-specs/refs/heads/main/host/security-tools-preflights.yaml
Downloading this spec is needed the target environment will limit outbound requests to the url.
This YAML file includes checks for commonly deployed antivirus and endpoint protection software that have interfered with Kubernetes in the past.
Step 2: Run Base Installer Preflights (Extracts Binary)
sudo ./<installer> install run-preflights --license license.yaml --airgap-bundle <bundle>.airgap
Omit --airgap-bundle if you’re doing an online install.
Step 3: Run the Security Tools Check
sudo <data-dir>/bin/kubectl-preflight security-tools-preflights.yaml --interactive=false
Preflight check results are printed on screen. In addition, a .tar.gz archive containing the data collected and used by the preflights will be available in the current working directory. It can be reviewed, or shared with support or field teams for further analysis.
Example 2: Run Cluster-Level Preflight Checks
While host-level checks validate individual nodes, cluster-level preflights validate the entire Kubernetes environment. These checks are essential for applications with specific cluster requirements like minimum node counts, resource availability across the cluster, or specific Kubernetes configurations.
Step 1: Create the Cluster Preflight Spec
Save the following YAML as cluster-requirements-preflight.yaml:
apiVersion: troubleshoot.sh/v1beta2
kind: Preflight
metadata:
name: sample
spec:
analyzers:
- nodeResources:
checkName: Must have at least 3 nodes in the cluster
outcomes:
- fail:
when: "count() < 3"
message: This application requires at least 3 nodes
- warn:
when: "count() < 5"
message: This application recommends at least 5 nodes.
- pass:
message: This cluster has enough nodes.
This example checks for minimum node requirements, but cluster preflights can validate many other aspects like:
- Total cluster CPU/memory resources
- Storage class availability
- Kubernetes version compatibility
- Required cluster operators or controllers
- Network policies and ingress configurations
Step 2: Install the Preflight Binary (if not already available)
If you don’t have kubectl-preflight installed via the installer, you can install it standalone:
curl https://krew.sh/preflight | bash
Or download directly from the releases page.
Step 3: Run the Cluster Preflight Check
kubectl preflight cluster-requirements-preflight.yaml --interactive=false
The preflight will connect to your current kubectl context and evaluate the cluster against your requirements. Results will be displayed on screen, with pass/warn/fail status for each check.
Note: Unlike host preflights that run locally, cluster preflights require kubectl access to the target cluster. Ensure your kubeconfig is properly configured before running.
Vendors: Define Your Own Modular Preflight Checks
The real power of this pattern is in customization.
As a vendor, you can write your own YAML preflight specs that check for requirements needed by your application such as system resource minimums (CPU, RAM, disk), required open network ports or proxy access, device support (GPUs, NICs, storage drivers), custom environment variables or app dependencies etc.
You can then combine them at runtime:
sudo <data-dir>/bin/kubectl-preflight \
security-tools-preflights.yaml \
minimum-system-resources.yaml \
https://bigbank.com/installer/required-network-ports.yaml \
--interactive=false
To build your own checks, use the available collectors and analyzers documented at https://troubleshoot.sh/docs.
Each of these specs can be version-controlled, shared internally, and updated as your application evolves.
We’ve published the security tools preflight as an example — and we encourage vendors to build and share their own using the same pattern.
Why This Works
By validating the environment before starting the install, you:
- Build a catalog of known checks from previous failure conditions unique to your application and customer environments
- Prevent known blockers early
- Avoid live debugging under pressure
- Reduce install time and frustration
- Build a repeatable install process
- Create space for automation down the line
It’s a lightweight, high-leverage change that improves reliability without requiring heavy tooling or rework.
Start Now
Here’s how to get started:
- Download and test the Security Tools Preflight
- Add it to your pre-install checklist and customer prep docs
- Require results before booking install sessions
- Build your own modular checks using the same format
- Refer to troubleshoot.sh to craft effective collectors and analyzers