Running preflight checks

This topic explains how to run preflight checks against your GKE on-prem configuration file.


During installation, you run gkectl create-config to generate a GKE on-prem configuration file. The configuration file drives your installation: you provide information about your vSphere environment, your network and load balancer, and how you'd like your clusters to look. You're able to generate a configuration file before or after you've created an admin workstation. For certain checks to pass, they need to be run from the admin workstation.

After you've modified the file to meet the needs of your environment and your clusters, you use the file to create your clusters in your on-prem environment.

Before you create clusters, you run gkectl check-config to validate the configuration file with several preflight checks.

Preflight check modes and skipping validations

gkectl check-config has a default mode and a fast mode:

  • In default mode, the command comprehensively validates each field. Also, the default mode creates temporary vSphere virtual machines (VMs) as part of its validations, which can take more time.
  • In fast mode, the command skips checks that create test VMs and runs only the fast checks. You enable fast mode by passing in the --fast flag.

You can skip specific validations by passing in other flags, which are described in gkectl check-config --help.

When should I run preflight checks?

It is a best practice to run preflight checks early and before attempting to create clusters. Running preflight checks early can help confirm that you've configured your vSphere environment and your network correctly.

If you are using GKE on-prem version 1.2.0-gke.6, run gkectl check-config twice:

  1. Run gkectl check-config --fast.

  2. Run gkectl prepare.

  3. Run gkectl check-config again, without the --fast flag.

The reason for running twice is that gkectl prepare uploads the VM template for the cluster node OS image to your vSphere environment. That VM template must be in place before you run the full set of validations.

In GKE on-prem version 1.2.1 and later, the check-config command itself uploads the VM template, so you can run the full set of validations before you run gkectl prepare:

  1. Run gkectl check-config, without the --fast flag.

  2. Run gkectl prepare.

The preflight checks validate the values you've provided to the file. You don't need to fill every field in the configuration file to run preflight checks against the file; rather, you can validate the file iteratively as you populate its fields. For example, if you only wanted to validate your vCenter configuration, you could fill only the vcenter fields and run checks against those.

Keep in mind that your GKE on-prem configuration becomes immutable after you've created your clusters. Running preflight checks helps you discover and resolve issues in your configuration before creating your clusters.

Preserving the test VM for debugging

Starting with GKE on-prem version 1.2.1, the gkectl check-config command has a --cleanup flag.

When gkectl check-config performs a full set of validations, it creates a test VM and an associated SSH key. If you want to preserve the test VM and the SSH key for debugging purposes, set --cleanup to false.

The default value of --cleanup is true.

List of preflight checks

The preflight checks validate each field in the configuration file. Here are the current checks:

Category Description
Configuration file

Generally validates that each field and specification has the expected format and values.

Skipped with --skip-validation-config flag.

Skip proxy field validation with --skip-validation-proxy flag.


Validates internet access to required domains. Validates proxy configuration based on where you are running gkectl.

Skipped with the --skip-validation-internet flag.

Google Cloud
Project ID
Validates the project IDs provided to various fields in the configuration. If the project ID is missing, the validation is skipped.
Register service account
Validates that the service account hold the required IAM roles. Validates that the required APIs are enabled.
Connect service account
Validates that the service account hold the required IAM roles. Validates that the required APIs are enabled.
Google Cloud Observability service account
Validates that the service account hold the required IAM roles. Validates that the required APIs are enabled.
Skipped with the --skip-validation-gcp flag.
Access to access Validates access to GKE on-prem's container image registry hosted in Container Registry.

Skipped by the --skip-validation-docker flag.

Docker registry
If configured, valiates access to the Docker registry.

Skipped with the --skip-validation-docker flag.

vCenter Checks that all vcenter fields are present, and also checks the following:
Validates authentication to vCenter Server using the provided user credentials.
vSphere version Validates that vSphere is at version 6.5 or 6.7 Update 3.
Validates that the vSphere datacenter exists.
Validates that the vSphere datastore exists.
Data disk
Validates that the vSphere virtual machine disk (VMDK) does not already exist in vSphere.
Resource pool
Validates that the vSphere resource pool exists.
Validates that the vSphere network exists.

Skipped with the --skip-validation-infra flag.

Load balancer

Validates load balancing configuration:

  • If load balancing mode is integrated (lbmode: Integrated), validates that all bigip fields are present in the admincluster and usercluster specifications.
  • If load balancing mode is manual (lbmode: Manual), validates that all manuallbspec fields are present in admincluster and usercluster specifications.
Integrated load balancing
bigip.credentials.[*] Validates your F5 BIG-IP credentials.
bigip.partition Validates that the partition provided exists.
F5 BIG-IP user role Validates that the F5 BIG-IP user provided holds either the Administrator or Resource Administrator role.
bigip.vips.[*] Validates VIPs provided.

Skipped with the --fast or --skip-validation-load-balancer flags.

Manual load balancing
Networking configuration Validates VIPs, node IPs, etc.

Skipped with the --fast or --skip-validation-load-balancer flags.

[*].manuallbspec.[*] Validates the provided node ports.
Skipped with the --skip-validation-load-balancer flag.

Validates that the provided CIDR ranges, VIPs, and static IPs (if configured) are available. Checks that IP addresses don't overlap.

Skipped with the --skip-validation-net-config flag.


Validates that the provided DNS server is available.

Skipped with the --skip-validation-dns flag.


Validates that the provided Network Time Protocol (NTP) server is available.

Skipped with the --skip-validation-tod flag.


Pings the VIPs provided. This check is successful if the ping fails, indicating the expected the VIP is not already taken.

Skipped with the --skip-validation-vips flag.

Node IPs

Pings the node IP addresses provided. This check is successful if the ping fails, indicating the expected the node IP is not already taken.

Skipped with the --skip-validation-node-ips flag.

Preflight check results

Preflight checks can return the following results:

The field and its value passed the check.
The field and/or its value did not pass the check. If a check returns a FAILURE message, fix the issues and validate the file again.

The check was skipped, likely because the check is not relevant to your configuration. For example, if you are using a DHCP server, checks for DNS and node IPs checks—relevant only to a static IP configuration—are skipped.

If you pass in a flag that skips a validation, the skipped check does not return a SKIPPED result; rather, the validation isn't run and doesn't appear in the command output at all.


The skip returned a non-zero code. You can consider UNKNOWN results to be failed checks. UNKNOWN usually indicates that the check failed to run some system package, such as failing to run nslookup or failing to run gcloud.

Coming soon

The following preflight checks will be added in a future release:

  • NTP server

Running preflight checks

You run preflight checks by running the following command:

gkectl check-config --config [CONFIG]

where [CONFIG] is the path to your GKE on-prem configuration file

Running in fast mode

If you prefer, you can run preflight checks in "fast mode," which skips the validations that create temporary test VMs, such as the load balancing VIP and node IP validations. To do so, pass in --fast:

gkectl check-config --config [CONFIG] --fast

Skipping specific validations

You can pass in flags to granularly skip specific validations, such as DNS, proxy, and networking. Each skip flag is prefixed with --skip-[VALIDATION].

To learn about the available skip flags, run the following command. Optionally, see gkectl check-config reference:

gkectl check-config --help

For example, to skip the load balancer validations:

gkectl check-config --config my-config.yaml --skip-validation-load-balancer 

Cancelling preflight checks

If you started running preflight checks and want to cancel, press CTRL + C twice. If a preflight check created a test VM, cancelling should also clean up the VM automatically.

Cleaning up a test VM

If a test VM is leftover after preflight checks are complete, you can delete the VM from vCenter. A test VM has a name like this:

check-config-[dhcp|static]-[random number]

To delete the VM:

  1. Right-click the VM, and click Power > Power Off

  2. After the VM has powered off, right-click the VM again, and click Delete from Disk.


Below is an example of the command's behavior. In this example, the configuration being validated uses integrated load balancing mode and static IPs without an external Docker registry:

gkectl check-config --config config.yaml
- Validation Category: Config Check
    - [SUCCESS] Config

- Validation Category: Internet Access
    - [SUCCESS] Internet access to required domains

- Validation Category: GCP
    - [SUCCESS] GCP Service
    - [SUCCESS] GCP Service Account

- Validation Category: Docker Registry
    - [SUCCESS] access

- Validation Category: vCenter
    - [SUCCESS] Credentials
    - [SUCCESS] Version
    - [SUCCESS] Datacenter
    - [SUCCESS] Datastore
    - [SUCCESS] Data Disk
    - [SUCCESS] Resource Pool
    - [SUCCESS] Network

- Validation Category: F5 BIG-IP
    - [SUCCESS] Admin Cluster F5 (credentials, partition and user role)
    - [SUCCESS] User Cluster F5 (credentials, partition and user role)

- Validation Category: Network Configuration
    - [SUCCESS] CIDR, VIP and static IP (availability and overlapping)

- Validation Category: DNS
    - [SUCCESS] DNS (availability)

- Validation Category: VIPs
    - [SUCCESS] ping (availability)

- Validation Category: Node IPs
    - [SUCCESS] ping (availability)

Now running slow validation checks (creates test VM); use flag --fast to disable.
- Validation Category: F5 BIG-IP
    - [SUCCESS] Admin Cluster VIP and NodeIP
    - [SUCCESS] User Cluster VIP and NodeIP

All validation results were SUCCESS.

Known issue

In GKE on-prem version 1.2.0-gke.6, if you are using nested resource pools or the default resource pool, gkectl check-config fails when you attempt to do a full set of validations. However, you can do a smaller set of validations by passing the --fast flag.

gkectl check-config --config [CONFIG] --fast

This issue will be fixed in version 1.2.1.

What's next