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 unexpected software running on the host:
- Endpoint security tools that kill Kubernetes processes
- Background agents that interfere with file systems
- Incompatible system configurations or network restrictions
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 host-level 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: 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.
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 host collectors and analyzers documented at troubleshoot.sh/docs/host-collect-analyze/overview.
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