kubernetes/kops · error

error describing instances: %v

Error message

error describing instances: %v

What it means

ListInstances paginates EC2 DescribeInstances; any failure fetching a page is wrapped as 'error describing instances: %v', aborting the resource listing. This is used when enumerating instances for `kops delete cluster` / rolling-update inspection.

Source

Thrown at pkg/resources/aws/aws.go:380

func ListInstances(cloud fi.Cloud, vpcID, clusterName string) ([]*resources.Resource, error) {
	ctx := context.TODO()
	c := cloud.(awsup.AWSCloud)

	klog.V(2).Infof("Querying EC2 instances")
	filters := BuildEC2Filters(cloud)
	filters = append(filters, awsup.NewEC2Filter("vpc-id", vpcID))
	filters = append(filters, awsup.NewEC2Filter("instance-state-name", string(ec2types.InstanceStateNameRunning)))
	request := &ec2.DescribeInstancesInput{
		Filters: filters,
	}

	var resourceTrackers []*resources.Resource

	paginator := ec2.NewDescribeInstancesPaginator(c.EC2(), request)
	for paginator.HasMorePages() {
		page, err := paginator.NextPage(ctx)
		if err != nil {
			return nil, fmt.Errorf("error describing instances: %v", err)
		}
		for _, reservation := range page.Reservations {
			for _, instance := range reservation.Instances {
				id := aws.ToString(instance.InstanceId)

				resourceTracker := &resources.Resource{
					Name:         FindName(instance.Tags),
					ID:           id,
					Type:         string(ec2types.ResourceTypeInstance),
					GroupDeleter: DeleteInstances,
					GroupKey:     fi.ValueOf(instance.SubnetId),
					Dumper:       DumpInstance,
					Obj:          instance,
				}

				var blocks []string
				blocks = append(blocks, "subnet:"+aws.ToString(instance.SubnetId))
				blocks = append(blocks, "vpc:"+aws.ToString(instance.VpcId))

View on GitHub (pinned to 4c8573c808)

Solutions

1. Read the wrapped cause for the AWS error code; fix credentials/region if AuthFailure
2. Add ec2:DescribeInstances to the IAM policy/instance profile in use
3. Re-run after a pause if the cause is throttling; reduce concurrent jobs
4. Use `aws ec2 describe-instances` with the same credentials to validate access outside kops

// pre-flight: verify credentials and permissions before listing
out, err := sts.GetCallerIdentity(ctx, &sts.GetCallerIdentityInput{})
if err != nil {
	return fmt.Errorf("AWS credentials invalid: %w", err)
}
_, err = ec2Client.DescribeInstances(ctx, &ec2.DescribeInstancesInput{MaxResults: aws.Int32(5)})
if err != nil {
	return fmt.Errorf("EC2 DescribeInstances preflight failed: %w", err)
}

instances, err := ListInstances(ctx, c, clusterName)
if err != nil {
	if isThrottling(err) { // e.g. code RequestLimitExceeded / Throttling
		time.Sleep(2 * time.Second)
		instances, err = ListInstances(ctx, c, clusterName)
	}
	if err != nil {
		return fmt.Errorf("instance listing failed: %w", err)
	}
}

When it happens

Trigger: DescribeInstances returns AuthFailure (bad credentials/region), UnauthorizedOperation (missing ec2:DescribeInstances), Throttling/RequestLimitExceeded, or transient network/5xx errors during pagination.

Common situations: Expired or mis-scoped AWS credentials (AWS_PROFILE/region mismatch), IAM policies without ec2:DescribeInstances, heavy parallel kops usage hitting EC2 rate limits.

Related errors

• error listing AutoScaling LaunchTemplates: %v
• describing instance for arn %q
• error terminating instances: %v
• error describing addresses: %v
• error describing volumes: %v

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