kubernetes/kops · error

describing instance for arn %q

Error message

describing instance for arn %q

What it means

Once the ARN passes validation, kOps extracts the EC2 instance ID from the session segment and calls ec2:DescribeInstances to find the instance. This error wraps any failure of that EC2 API call — it discards the underlying AWS error and only reports the ARN context.

Source

Thrown at pkg/bootstrap/awsbootstrap/verifier.go:298

		return nil, fmt.Errorf("arn %q contains too few slashes", arn)
	}
	found := false
	for _, role := range a.opt.NodesRoles {
		if resource[1] == role {
			found = true
			break
		}
	}
	if !found {
		return nil, fmt.Errorf("arn %q does not contain acceptable node role", arn)
	}

	instanceID := resource[2]
	instances, err := a.ec2.DescribeInstances(ctx, &ec2.DescribeInstancesInput{
		InstanceIds: []string{instanceID},
	})
	if err != nil {
		return nil, fmt.Errorf("describing instance for arn %q", arn)
	}

	if len(instances.Reservations) <= 0 || len(instances.Reservations[0].Instances) <= 0 {
		return nil, fmt.Errorf("missing instance id: %s", instanceID)
	}
	if len(instances.Reservations[0].Instances) > 1 {
		return nil, fmt.Errorf("found multiple instances with instance id: %s", instanceID)
	}

	instance := instances.Reservations[0].Instances[0]

	addrs, err := GetInstanceCertificateNames(instances)
	if err != nil {
		return nil, err
	}

	var challengeEndpoints []string
	for _, nic := range instance.NetworkInterfaces {

View on GitHub (pinned to 4c8573c808)

Solutions

1. Check the kOps controller/API server logs for the underlying AWS error; fix the specific cause (throttling, auth, endpoint).
2. Ensure the verifier's IAM policy includes ec2:DescribeInstances (kopsInstanceRole / kops-controller policy).
3. Retry the bootstrap request if the cause was transient throttling or an AWS outage; consider backoff on the node side.
4. Verify EC2 endpoint connectivity from the API server (VPC endpoints, DNS, proxy settings).

Example fix

// before: policy missing EC2 read
// after: attach to the API-server/kops-controller role
{ "Effect": "Allow", "Action": ["ec2:DescribeInstances"], "Resource": "*" }

// Pre-check the verifier's permissions before running nodes:
aws iam simulate-principal-policy --policy-source-arn <apiserver-role-arn> --action-names ec2:DescribeInstances

instances, err := a.ec2.DescribeInstances(ctx, input)
if err != nil {
	var ae smithy.APIError
	if errors.As(err, &ae) && (ae.ErrorCode() == "RequestLimitExceeded" || ae.ErrorCode() == "ThrottlingException") {
		// retry with backoff
	}
	return nil, fmt.Errorf("describing instance for arn %q: %w", arn, err) // wrap, don't discard cause
}

When it happens

Trigger: a.ec2.DescribeInstances returns an error: EC2 API outage/throttling (RequestLimitExceeded), credential permissions missing ec2:DescribeInstances on the verifier's role, network failure to the EC2 endpoint, invalid instance-ID format, or context cancellation.

Common situations: API server's IAM role missing the ec2:DescribeInstances permission after manual policy edits; EC2 API throttling during large cluster scale-ups; regional endpoint misconfiguration; transient AWS outages.

Related errors

• getting primary MAC address from ec2 metadata: %w
• failed to get region from ec2 metadata: %w
• error terminating instances: %v
• error describing instances: %v
• error describing addresses: %v

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