kubernetes/kops · error

api-version must be specified

Error message

api-version must be specified

What it means

The helper must emit an ExecCredential with a concrete client.authentication.k8s.io apiVersion (v1alpha1 or v1beta1). If options.APIVersion is empty, the switch in RunKubectlAuthHelper returns this error because kubectl requires a known schema version to parse the output. Normally InitDefaults() sets v1beta1, so the empty value only occurs when defaults were skipped or explicitly cleared.

Solutions

1. Call options.InitDefaults() before running, or pass --api-version v1beta1 explicitly.
2. If Go code bypasses NewCmdHelperKubectlAuth, initialize APIVersion to "v1beta1" (or "v1alpha1") yourself.
3. Fix shell quoting so an empty $VAR doesn't result in an empty flag value.

Example fix

// before
options := &helpers.HelperKubectlAuthOptions{}
err := helpers.RunKubectlAuthHelper(ctx, f, out, options)
// after
options := &helpers.HelperKubectlAuthOptions{}
options.InitDefaults()
err := helpers.RunKubectlAuthHelper(ctx, f, out, options)

opts := &helpers.HelperKubectlAuthOptions{}
opts.InitDefaults() // sets APIVersion to v1beta1
if opts.APIVersion == "" {
    opts.APIVersion = "v1beta1"
}

When it happens

Trigger: Calling RunKubectlAuthHelper with an options struct that never had InitDefaults() called and APIVersion unset (empty string), or a flag wiring bug that passes --api-version "".

Common situations: Constructing HelperKubectlAuthOptions directly in Go without calling InitDefaults; a wrapper script that sets --api-version to an empty variable; refactoring the cobra command away from the default-initialization path.

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

• api-version is not supported
• ClusterName is required
• adding encryptionconfig secret
• adding keypair to is not supported
• applying

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

Appendix: source

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

	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)
	}

	cacheFilePath := cacheFilePath(f.KopsStateStore(), options.ClusterName)
	cached, err := loadCachedExecCredential(cacheFilePath)
	if err != nil {
		klog.Infof("cached credential %q was not valid: %v", cacheFilePath, err)
		cached = nil
	}

	if cached != nil && cached.APIVersion != execCredential.APIVersion {
		klog.Infof("cached credential had wrong api version")

View on GitHub (pinned to 4c8573c808)