Running preflight checks

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

Overview

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:

Preflight check results

Preflight checks can return the following results:

SUCCESS

The field and its value passed the check.

FAILURE

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.

SKIPPED

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.

UNKNOWN

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.

Example

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] gcr.io/gke-on-prem-release 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

• Installing using static IP addresses
• Installing using a DHCP server