kubernetes/kops · error

unable to find IAM profile link for instance group %q: %w

Error message

unable to find IAM profile link for instance group %q: %w

What it means

buildLaunchTemplateTask calls LinkToIAMInstanceProfile to resolve the IAM instance profile task for the instance group; when that lookup fails (typically the IAM profile builder produced no matching task or the name lookup errored), the error is wrapped with the instance-group name and aborts the launch-template build.

Source

Thrown at pkg/model/awsmodel/autoscalinggroup.go:167

				HeartbeatTimeout:    heartbeatTimeout,
				LifecycleTransition: aws.String("autoscaling:EC2_INSTANCE_LAUNCHING"),
				Enabled:             &enableHook,
			}

			c.AddTask(lifecyleTask)

		}
	}

	return nil
}

// buildLaunchTemplateTask is responsible for creating the template task into the aws model
func (b *AutoscalingGroupModelBuilder) buildLaunchTemplateTask(c *fi.CloudupModelBuilderContext, name string, ig *kops.InstanceGroup, userData fi.Resource) (*awstasks.LaunchTemplate, error) {
	// @step: add the iam instance profile
	link, err := b.LinkToIAMInstanceProfile(ig)
	if err != nil {
		return nil, fmt.Errorf("unable to find IAM profile link for instance group %q: %w", ig.ObjectMeta.Name, err)
	}

	rootVolumeSize, err := defaults.DefaultInstanceGroupVolumeSize(ig.Spec.Role)
	if err != nil {
		return nil, err
	}
	var rootVolumeType ec2types.VolumeType
	rootVolumeEncryption := DefaultVolumeEncryption
	rootVolumeKmsKey := ""

	if ig.Spec.RootVolume != nil {
		if fi.ValueOf(ig.Spec.RootVolume.Size) > 0 {
			rootVolumeSize = fi.ValueOf(ig.Spec.RootVolume.Size)
		}

		rootVolumeType = ec2types.VolumeType(fi.ValueOf(ig.Spec.RootVolume.Type))

		if ig.Spec.RootVolume.Encryption != nil {

View on GitHub (pinned to 4c8573c808)

Solutions

1. Inspect the wrapped inner error (%w) printed by kops — it names the underlying cause (e.g. name too long, permission denied) and fix that first.
2. Ensure the cluster spec has IAM enabled (no --iam=false) so the IAM instance profile task is generated for the instance group's role.
3. If using a custom IAM profile name, shorten it: AWS instance profile names are limited to 64 characters; adjust spec role naming or the cluster name.
4. Verify AWS credentials/permissions (iam:GetInstanceProfile, iam:ListRoles) so the existing profile can be resolved.
5. Re-run `kops update cluster --target=terraform` or dry-run to confirm the IAM tasks are built before the ASG model.

Example fix

// before
kops update cluster mycluster --iam=false
// after
kops update cluster mycluster  # let kOps build the IAM instance profile task

# preflight: ensure IAM is enabled and profile name within AWS limits
name_len=$((${#CLUSTER_NAME} + ${#IG_NAME} + 20))
[ $name_len -le 64 ] || { echo "IAM instance profile name would exceed 64 chars"; exit 1; }
kops get cluster -oyaml | grep -q 'iam:' && echo "iam configured" || echo "warning: no iam block"

// kops is a CLI: capture and inspect the wrapped cause
if out, err := exec.Command("kops", "update", "cluster", cluster).CombinedOutput(); err != nil {
  if strings.Contains(string(out), "unable to find IAM profile link") {
    // inspect inner %w cause, fix IAM spec/permissions, then retry
  }
}

When it happens

Trigger: `kops update cluster` when the IAM instance profile for the instance group cannot be linked — e.g. the IAM builder did not create the profile task for the group's role, an IAM name/permission conflict caused the IAM task build to fail upstream, or a custom/external IAM profile reference is unresolvable.

Common situations: Clusters with useInstanceProfilesForDNS or custom IAM settings where the profile name collides or exceeds AWS's 64-char profile name limit; running with --iam=false after previously enabling IAM so no profile task exists; permission denied reading existing IAM roles/profiles in the AWS account.

Related errors

• found IAM instance profile assigned to multiple Instance Gro
• IP version is incorrect
• ErrAlreadyExists
• provider ID cannot be empty
• provider ID number cannot be empty

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