kubernetes/kops · error

ClusterName is required

Error message

ClusterName is required

What it means

RunKubectlAuthHelper implements kOps' kubectl exec-credential auth helper, which emits a client.authentication.k8s.io ExecCredential. It refuses to run without knowing which cluster to target, so an empty options.ClusterName returns this error immediately before any state-store access. The --cluster flag populates ClusterName; nothing supplies a default.

Source

Thrown at pkg/commands/helpers/kubectl_auth.go:93

			err := RunKubectlAuthHelper(ctx, f, out, options)
			if err != nil {
				commandutils.ExitWithError(err)
			}
		},
	}

	cmd.Flags().StringVar(&options.APIVersion, "api-version", options.APIVersion, "version of client.authentication.k8s.io schema in use")
	cmd.Flags().StringVar(&options.ClusterName, "cluster", options.ClusterName, "cluster to target")
	cmd.Flags().DurationVar(&options.Lifetime, "lifetime", options.Lifetime, "lifetime of the credential to issue")

	return cmd
}

// RunKubectlAuthHelper implements the kubectl auth helper, which creates an authentication token
func RunKubectlAuthHelper(ctx context.Context, f *util.Factory, out io.Writer, options *HelperKubectlAuthOptions) error {
	if options.ClusterName == "" {
		return fmt.Errorf("ClusterName is required")
	}

	execCredential := &ExecCredential{
		Kind: "ExecCredential",
	}

	switch options.APIVersion {
	case "":
		return fmt.Errorf("api-version must be specified")
	case "v1alpha1":
		execCredential.APIVersion = "client.authentication.k8s.io/v1alpha1"
	case "v1beta1":
		execCredential.APIVersion = "client.authentication.k8s.io/v1beta1"

	default:
		return fmt.Errorf("api-version %q is not supported", options.APIVersion)
	}

View on GitHub (pinned to 4c8573c808)

Solutions

1. Pass --cluster <name> on the kubectl-auth command line.
2. If invoking in Go, set options.ClusterName before calling RunKubectlAuthHelper.
3. Check the kubeconfig exec credential plugin args include --cluster.

Example fix

// before
exec:
  command: kops
  args: ["helpers", "kubectl-auth"]
// after
exec:
  command: kops
  args: ["helpers", "kubectl-auth", "--cluster", "mycluster.k8s.local"]

if options.ClusterName == "" {
    return fmt.Errorf("cannot run kubectl-auth: --cluster is required")
}

When it happens

Trigger: Calling RunKubectlAuthHelper (or the `kops helpers kubectl-auth` command) with HelperKubectlAuthOptions.ClusterName left as the zero value "" — i.e. the --cluster flag was not passed and no wrapper set the field.

Common situations: Running `kubectl-auth` manually without --cluster; embedding the helper in a kubeconfig exec block where args omit --cluster; scripting the command after stripping flags; using options struct in Go code without setting ClusterName.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• --name is required (for safety)
• --region is required (when --external)
• --name is required
• --name is required
• --name is required

AI-assisted analysis of kubernetes/kops@4c8573c808 (2026-09-05). Data as JSON: /api/errors/135b38bd80238903. Report an issue: GitHub.