Understanding preflight checks

In Google Distributed Cloud you can run preflight checks for different situations:

  • Google Distributed Cloud runs preflight checks when you create or update admin, hybrid, or standalone clusters and nodepool resources with bmctl. If the checks fail, no changes are made. You can also bypass these checks.
  • You can run a limited set of preflight checks before creating user clusters from an admin or hybrid cluster with the kubectl command.
  • Google Distributed Cloud also runs internal preflight checks when you apply Kubernetes resources to user clusters from an admin or hybrid cluster. The checks are run before changes are actually applied to affected user clusters. If the checks fail, no changes are made. You can also bypass these checks, or run them explicitly.

Preflight checks when creating clusters using bmctl

When you create admin, hybrid, or standalone clusters with the bmctl command, Google Distributed Cloud automatically runs preflight checks before any changes are made.

When the checks pass, Google Distributed Cloud will create the clusters.

Ignoring the results of automated preflight checks

If you want to bypass these automated preflight checks, you can use the optional --force flag in the command.

Running preflight checks independently

You can also run preflight checks by themselves, before you create a cluster. This can help save time by ensuring your machine and node resources pass checks.

  • The following command validates the specified cluster config file, but doesn't try to create the cluster itself:

    bmctl check config --cluster CLUSTER_NAME

  • This command checks whether the machines and network are ready for cluster creation:

    bmctl check preflight --cluster CLUSTER_NAME

Note that you can't create user clusters with bmctl (and there is a preflight check to prevent this).

Preflight checks for user cluster creation

User clusters are created from an existing admin or hybrid cluster, and you use kubectl to run preflight checks. Based on the results of these checks, you can determine if there are errors and fix them before user cluster creation.

Once an admin or hybrid cluster is created and running, you can use kubectl to run preflight checks before creating a user cluster.

  1. Create a user cluster config file following the steps in Creating user clusters in a Multi-Cluster Setup

  2. Create a namespace for the new user cluster. For example, to create a new user cluster named user1, you can create a namespace named cluster-user1. Here is the kubectl command to create the namespace, where ADMIN_KUBECONFIG specifies the path to the admin cluster kubeconfig file:

    kubectl --kubeconfig ADMIN_KUBECONFIG create namespace cluster-user1
    

  3. Upload your SSH private key file into the new namespace as a secret to establish your credentials. Here's the sample command, where ADMIN_KUBECONFIG specifies the path to the admin cluster kubeconfig file, and SSH_PRIVATE_KEY_FILE_PATH specifies the path to the SSH private key file:

    kubectl --kubeconfig ADMIN_KUBECONFIG create secret generic ssh-key -n cluster-user1 --from-file=id_rsa=SSH_PRIVATE_KEY_FILE_PATH
    

  4. Create a new preflight check YAML file, with the following structure. In the configYAML field, enter the text content of the user cluster config file you created in step 1:

    apiVersion: baremetal.cluster.gke.io/v1
    kind: PreflightCheck
    metadata:
    generateName: preflightcheck-
    namespace: cluster-user1
    spec:
    configYAML: |
    # insert user cluster config file content here.
    
  5. The following kubectl command runs the preflight check for the user cluster, where ADMIN_KUBECONFIG specifies the path to the admin cluster kubeconfig file, and USER_CLUSTER_PREFLIGHT_CHECK_CONFIG specifies the path to the preflight check YAML file you created in the previous step:

    kubectl --kubeconfig ADMIN_KUBECONFIG create -f USER_CLUSTER_PREFLIGHT_CHECK_CONFIG
    
    For example, for an admin cluster named cluster1, and a user cluster preflight check config named user1-preflight.yaml, the command is:
    kubectl --kubeconfig bmctl-workspace/cluster1/cluster1-kubeconfig create -f user1-preflight.yaml
    
    The system returns the following message, with the job ID of the preflight check:
    preflightcheck.baremetal.cluster.gke.io/preflightcheck-g7hfo4 created

  6. Query the preflight check job status using kubectl command:

    kubectl --kubeconfig bmctl-workspace/cluster1/cluster1-kubeconfig -n cluster-user1 get preflightchecks preflightcheck-g7hfo4
    

If the preflight check job fails, check its status, and then check the detailed job logs to see which check failed. Fix the issues mentioned in the jobs accordingly, and run the checks again.

Internal preflight checks on existing clusters

Google Distributed Cloud also performs internal preflight checks when you apply Kubernetes resources to an existing admin or hybrid cluster. If any checks fail, Google Distributed Cloud will not make any changes to the related nodes unless you've specifically bypassed the checks.

Bypassing preflight checks when applying Kubernetes resources

To ignore the internal preflight checks when applying resources to existing clusters, you need to set the BypassPreflightCheck field to true in the cluster YAML file.

Here is a fragment of a cluster config YAML file, showing the bypassPreflightCheck field set to true.

# Sample cluster config to bypass preflight check errors:

apiVersion: v1
kind: Namespace
metadata:
  name: cluster-user1
---
apiVersion: baremetal.cluster.gke.io/v1
kind: Cluster
metadata:
  name: user1
  namespace: cluster-user1
spec:
  type: user
  bypassPreflightCheck: true
  # Anthos cluster version.
  anthosBareMetalVersion: v1.6.2
....

Re-enabling preflight checks

You can explicitly trigger a new round of preflight checks so Google Distributed Cloud can update or create new clusters after the preflight check is successful.

  1. Create a new preflight check YAML file with the following content. Fill in the namespace and clusterName fields with the cluster name you are creating:

    apiVersion: baremetal.cluster.gke.io/v1
    kind: PreflightCheck
    metadata:
    generateName: preflightcheck-
    namespace: CLUSTER_NAMESPACE
    spec:
    clusterName: CLUSTER_NAME
    

  2. Issue the kubectl command to run the preflight check for the cluster, where ADMIN_KUBECONFIG specifies the path to the admin cluster kubeconfig file, and CLUSTER_PREFLIGHT_CHECK_CONFIG specifies the path to the preflight check YAML file you created previously in step 1 of preflight checks for user clusters:

    kubectl --kubeconfig ADMIN_KUBECONFIG create -f CLUSTER_PREFLIGHT_CHECK_CONFIG
    
    For example, for an admin cluster named cluster1, and a user cluster preflight check config named user1-preflight.yaml, the command ia:
    kubectl --kubeconfig bmctl-workspace/cluster1/cluster1-kubeconfig create -f user1-preflight.yaml
    
    The systems responds with the job ID of the preflight check:
    preflightcheck.baremetal.cluster.gke.io/preflightcheck-g7hfo4 created
    

  3. Query the preflight check job status ID using kubectl command:

    kubectl --kubeconfig bmctl-workspace/cluster1/cluster1-kubeconfig -n cluster-cluster1 get preflightchecks preflightcheck-g7hfo4
    

Once the preflight check job finished successfully, Google Distributed Cloud creates the cluster and its resources.

Installation preflight check details

Google Distributed Cloud checks a variety of operating system, software, and machine prerequisite conditions when running preflight checks.

For more detailed information, see Installation prerequisites overview.