kubernetes/kops · error

ssm image parameter is required

Error message

ssm image parameter is required

What it means

When the image uses the ssm: prefix, the parameter name after the prefix must be non-empty. An image spec like 'ssm:' with nothing after it leaves buildKarpenterAMITerms with no SSM parameter and it returns 'ssm image parameter is required'.

Source

Thrown at upup/pkg/fi/cloudup/template_functions_karpenter.go:470

		Spec: spec,
	}, nil
}

func buildKarpenterAMITerms(image string) ([]karpenterAMITerm, error) {
	image = strings.TrimSpace(image)
	if image == "" {
		return nil, fmt.Errorf("image is required")
	}
	if strings.Contains(image, "://") {
		return nil, fmt.Errorf("image %q must be ami-*, ssm:<parameter>, <name>, or <owner>/<name>", image)
	}
	if strings.HasPrefix(image, "ami-") {
		return []karpenterAMITerm{{ID: image}}, nil
	}
	if strings.HasPrefix(image, "ssm:") {
		parameter := strings.TrimPrefix(image, "ssm:")
		if parameter == "" {
			return nil, fmt.Errorf("ssm image parameter is required")
		}
		return []karpenterAMITerm{{SSMParameter: parameter}}, nil
	}

	tokens := strings.SplitN(image, "/", 2)
	if len(tokens) == 1 {
		return []karpenterAMITerm{{Name: image, Owner: "self"}}, nil
	}
	if tokens[0] == "" || tokens[1] == "" {
		return nil, fmt.Errorf("image %q must be ami-*, ssm:<parameter>, <name>, or <owner>/<name>", image)
	}
	return []karpenterAMITerm{{Owner: awsup.ResolveImageOwnerAlias(tokens[0]), Name: tokens[1]}}, nil
}

func (tf *TemplateFunctions) karpenterAssociatePublicIP(ig *kops.InstanceGroup) (*bool, error) {
	subnets, err := tf.GatherSubnets(ig)
	if err != nil {
		return nil, err

View on GitHub (pinned to 4c8573c808)

Solutions

1. Provide the full SSM parameter path, e.g. ssm:/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-default-x86_64
2. Fix the templating/env variable that should supply the parameter name
3. Verify the SSM parameter exists in the cluster region and is readable
4. Re-run `kops update cluster`

Example fix

// before
image: ssm:
// after
image: ssm:/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-default-x86_64

// ensure ssm: prefix has a parameter
if strings.HasPrefix(image, "ssm:") && strings.TrimSpace(strings.TrimPrefix(image, "ssm:")) == "" {
	return fmt.Errorf("ssm: image requires a parameter path")
}

if err != nil && strings.Contains(err.Error(), "ssm image parameter is required") {
	return fmt.Errorf("provide the SSM parameter path after ssm:")
}

When it happens

Trigger: Image string starting with 'ssm:' followed by empty text (e.g. 'ssm:' or 'ssm: ') in the Karpenter instance group image field.

Common situations: Environment-variable substitution in the cluster spec resolving to empty (SSM_PARAMETER= left unset); hand-edited yaml truncating the parameter 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

• image is required
• image %q must be ami-*, ssm:<parameter>, <name>, or <owner>/
• --region is required (when --external)
• instance id for cloud instance member cannot be empty
• unknown load balancer Type: %q

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