Understanding Preflight checks

Understanding Preflight checks#

Check the results of the Preflight check to ensure all installation-related secrets are valid.

Role focus: Site reliability engineer (SRE) / Infrastructure Engineer

Prerequisites#

Outcomes#

  • Ability to diagnose and resolve secret-related blockers during Hybrid Manager (HM) installation.

When you start the HM installation, the operator automatically creates a Preflight custom resource. This resource validates that all required Kubernetes secrets exist and are correctly structured before the operator proceeds to deploy the platform services.

!!!Note

You do not create the Preflight resource yourself. The operator creates it automatically after the HybridControlPlane resource is created.

After you apply your HybridControlPlane manifest, the operator:

  1. Reconciles the HybridControlPlane resource.

  2. Creates a Preflight resource with the secret requirements for the deployment.

  3. Validates each secret requirement: verifies the secret exists, then evaluates validation rules against the secret content.

  4. Reports the result in the preflight resource status.

If all requirements pass, the operator proceeds with deploying the platform services. If any requirement fails, deployment is blocked and the operator retries every 30 seconds until the issues are resolved.

Checking the preflight status#

If the installation appears stuck after running the installation Helm command , inspect the preflight status:

kubectl get preflight -o yaml

The status.secretRequirementsStatus section shows the result for each checked secret:

status:
  observedGeneration: 1
  secretRequirementsStatus:
    - secret:
        name: hm-portal-bootstrap
        namespace: default
      state: Valid
    - secret:
        name: edb-object-storage
        namespace: default
      state: Invalid
      messages:
        - "failed to pass the rule: aws-configurations"
    - secret:
        name: langflow-secret
        namespace: default
      state: SecretNotFound

Understanding the states#

State

Meaning

Action required

Valid

Secret exists and passes all validation rules.

None.

Invalid

Secret exists but one or more validation rules failed.

Review the messages field to identify which rules failed, then fix the secret content.

SecretNotFound

The referenced secret does not exist.

Create the secret in the correct namespace with the required keys.

!!!Warning

Deployment remains blocked until every secret requirement reaches the Valid state. The operator retries automatically every 30 seconds. Once all requirements pass, deployment proceeds without manual intervention.

Each secret requirement is associated with an installation scenario: core , migration , ai , or analytics . The operator uses the scenarios configured in spec.scenarios on the HybridControlPlane to filter which requirements are checked.

  • If your configuration defines specific scenarios (for example, core, ai ), only requirements matching those scenarios are validated. Requirements for other scenarios (such as migration ) are skipped.

  • If your configuration does not define spec.scenarios , all secret requirements are validated regardless of scenario.

This means you only need to provide the secrets for the scenarios you are actually deploying. For example, if you are not using the analytics scenario, you do not need to provide the Lakekeeper confounding key secret.

Troubleshooting preflight failures#

Installation appears stuck#

If the Helm command completes but pods are not starting, the preflight checks may be blocking the deployment. Check the preflight status first:

kubectl get preflight -o yaml

Look at status.secretRequirementsStatus for any entries that are not Valid .

Secret not found#

If a requirement shows SecretNotFound , verify the secret exists:

kubectl get secret <secret-name> -n <namespace>

If the secret does not exist, create it following the documentation for Preparing your environment . Ensure the name and namespace match exactly what the preflight expects.

Validation rule failures#

If a requirement shows Invalid , the messages field identifies which rules failed. For example:

failed to pass the rule: aws-configurations

This means the secret exists but does not meet the expected structure. Inspect the secret:

kubectl get secret <secret-name> -n <namespace> -o yaml

Compare the secret’s data keys and values against the rule message. Common causes include:

  • Missing keys — The secret is missing a required data field (for example, aws_region or bucket_name for AWS object storage).

  • Missing annotations — Some secrets require specific replicator annotations to be set on the secret metadata.

  • Wrong secret type — For example, a TLS secret requires type kubernetes.io/tls .

  • Empty values — A required field exists but contains no data.

After fixing the secret, the operator automatically re-evaluates within 30 seconds.

Requirements not being checked#

If you expect a requirement to be validated but it does not appear in the status, check the scenario configuration:

  1. Verify which scenarios are defined for your HM installation:

kubectl get hybridcontrolplane <name> -o jsonpath={.spec.scenarios}

  1. Confirm the established scenario matches the scenarios established by the CTO / Architect / Lead Engineer during the Planning architecture phase. If the output of the command doesn’t match the expected scenarios, it means that the installation was not carried out as planned, and one or several of the scenarios were skipped during the installation.

Contents