Report missing Kind and control-plane prerequisites before deployment

cmd/ate-setup/commands.md

@@ -43,6 +43,19 @@ a pre-scan pass, so they may appear anywhere on its command line.
 Both have an environment equivalent, read when the flag is absent:
 `ATE_IMAGE_REPO` and `ATE_IMAGE_TAG`.
 
+Kind deployments check that Docker is available and the resolved kubeconfig
+context exists before doing any install work. If the context is missing, the
+error explains how to export kubeconfig for an existing cluster or create the
+cluster and local registry with `hack/create-kind-cluster.sh`. That script
+replaces an existing cluster with the same name.
+
+Deploy the control plane before deploying demos or benchmarks. These commands
+check for `deployment/ate-controller` in the configured system namespace before
+creating workload resources. An existing Deployment passes this check; normal
+rollout waits still diagnose workloads that cannot become ready. The shell shim
+runs actions in argument order, so put `--deploy-ate-system` before demo or
+benchmark deployment flags when combining them on one command line.
+
 ## Installing a release
 
 Without `--image-repo`, `ate-setup` builds every image from the checkout with

cmd/ate-setup/internal/cmd/demo.go

@@ -56,6 +56,9 @@ func init() {
 			Short: demo.Description(),
 			Args:  cobra.NoArgs,
 			RunE: func(cmd *cobra.Command, _ []string) error {
+				if err := env.RequireControlPlane(cmd.Context()); err != nil {
+					return err
+				}
 				return demo.Deploy(cmd.Context(), env)
 			},
 		}

cmd/ate-setup/internal/cmd/root.go

@@ -112,6 +112,11 @@ is present (skipped for --kind, and by NO_DEV_ENV=1).`,
 		if err := cfg.EnsureClusterCredentials(cmd.Context()); err != nil {
 			return err
 		}
+		if cfg.Kind && isDeployCommand(cmd) {
+			if err := cfg.CheckKindCluster(cmd.Context()); err != nil {
+				return err
+			}
+		}
 		env, err = steps.NewEnv(cfg)
 		if err != nil {
 			return err
@@ -130,6 +135,15 @@ is present (skipped for --kind, and by NO_DEV_ENV=1).`,
 	},
 }
 
+func isDeployCommand(cmd *cobra.Command) bool {
+	for c := cmd; c != nil; c = c.Parent() {
+		if c == deployCmd {
+			return true
+		}
+	}
+	return false
+}
+
 // recordRun writes what this run used, so the next one can reproduce it by
 // pointing --config at the file. Recording is best effort: an install that
 // worked must not be reported as failed because a directory was read-only.

cmd/ate-setup/internal/config/kindcheck.go

@@ -0,0 +1,64 @@
+// Copyright 2026 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package config
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"os/exec"
+	"strings"
+	"time"
+
+	"k8s.io/client-go/tools/clientcmd"
+)
+
+// CheckKindCluster checks local deployment prerequisites without creating or
+// replacing a cluster. It uses the same kubeconfig loading rules as the clients.
+func (c *Config) CheckKindCluster(ctx context.Context) error {
+	ctx, cancel := context.WithTimeout(ctx, 10*time.Second)
+	defer cancel()
+	output, err := exec.CommandContext(ctx, "docker", "info").CombinedOutput()
+	if err != nil {
+		if ctx.Err() != nil {
+			err = ctx.Err()
+		}
+		return fmt.Errorf("cannot access Docker; start Docker and check `docker info` before deploying to Kind: %w\n%s", err, strings.TrimSpace(string(output)))
+	}
+
+	rules := clientcmd.NewDefaultClientConfigLoadingRules()
+	rules.ExplicitPath = c.Kubeconfig
+	config, err := rules.Load()
+	if err != nil && !os.IsNotExist(err) {
+		return fmt.Errorf("while reading kubeconfig: %w", err)
+	}
+	name := c.Context
+	if err == nil {
+		if name == "" {
+			name = config.CurrentContext
+		}
+		if _, exists := config.Contexts[name]; exists {
+			return nil
+		}
+	}
+
+	cluster := c.Resolved().String("kindCluster.name")
+	return fmt.Errorf("Kubernetes context %q was not found. If Kind cluster %q already exists, restore its kubeconfig with:\n"+
+		"  hack/kind.sh export kubeconfig --name=%q\n"+
+		"Otherwise create the cluster and local registry with:\n"+
+		"  KIND_CLUSTER_NAME=%q hack/create-kind-cluster.sh\n"+
+		"The creation script replaces an existing cluster with the same name. For a custom context, check --context and --kubeconfig instead",
+		name, cluster, cluster, cluster)
+}

cmd/ate-setup/internal/steps/benchmarks.go

@@ -65,6 +65,9 @@ func (e *Env) DeployBenchmarks(ctx context.Context, opts BenchmarkOptions) error
 	if err := opts.Validate(); err != nil {
 		return err
 	}
+	if err := e.RequireControlPlane(ctx); err != nil {
+		return err
+	}
 	log.Stepf("deploy_benchmarks (worker_count=%d, sandbox_class=%s)", opts.WorkerCount, opts.SandboxClass)
 
 	// The microvm SandboxConfig lives outside the default set installed by

cmd/ate-setup/internal/steps/preflight.go

@@ -0,0 +1,51 @@
+// Copyright 2026 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package steps
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	apierrors "k8s.io/apimachinery/pkg/api/errors"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+)
+
+// RequireControlPlane refuses workload installs before they create resources
+// that only ate-controller can reconcile into Deployments.
+func (e *Env) RequireControlPlane(ctx context.Context) error {
+	ctx, cancel := context.WithTimeout(ctx, 10*time.Second)
+	defer cancel()
+	_, err := e.Kube.Typed.AppsV1().Deployments(e.Namespace()).Get(ctx, "ate-controller", metav1.GetOptions{})
+	if err == nil {
+		return nil
+	}
+	if !apierrors.IsNotFound(err) {
+		return fmt.Errorf("while checking deployment/ate-controller in namespace %s: %w", e.Namespace(), err)
+	}
+	flags := ""
+	if e.Cfg.Kind {
+		flags += " --kind"
+	}
+	if e.Cfg.Context != "" {
+		flags += fmt.Sprintf(" --context=%q", e.Cfg.Context)
+	}
+	if e.Cfg.Kubeconfig != "" {
+		flags += fmt.Sprintf(" --kubeconfig=%q", e.Cfg.Kubeconfig)
+	}
+	return fmt.Errorf("demos and benchmarks require deployment/ate-controller in namespace %s: %w\n"+
+		"Deploy the control plane first, using the same installation settings:\n"+
+		"  go run ./cmd/ate-setup%s deploy ate-system --credential-provider='{\"name\":\"k8s.io\"}'", e.Namespace(), err, flags)
+}