kubernetes/kops · error

error creating Instance: %v

Error message

error creating Instance: %v

What it means

Instance.RenderAWS calls EC2 RunInstances to create the instance; any API error from AWS is wrapped as 'error creating Instance: %v'. This is the generic failure point for instance creation: invalid parameters (AMI, subnet, SG, key, IAM profile), quota/capacity limits, or authorization problems. No instance ID is assigned, so the task fails.

Source

Thrown at upup/pkg/fi/cloudup/awstasks/instance.go:294

				// But it exposes some bugs in the AWS console, so if we can avoid it, we should
				//d, err = fi.GzipBytes(d)
				//if err != nil {
				//	return fmt.Errorf("error while gzipping UserData: %v", err)
				//}
				return fmt.Errorf("Instance UserData was too large (%d bytes)", len(d))
			}
			request.UserData = aws.String(base64.StdEncoding.EncodeToString(d))
		}

		if e.IAMInstanceProfile != nil {
			request.IamInstanceProfile = &ec2types.IamInstanceProfileSpecification{
				Name: e.IAMInstanceProfile.Name,
			}
		}

		response, err := t.Cloud.EC2().RunInstances(ctx, request)
		if err != nil {
			return fmt.Errorf("error creating Instance: %v", err)
		}

		e.ID = response.Instances[0].InstanceId
	}

	return t.AddAWSTags(*e.ID, e.Tags)
}

func (e *Instance) TerraformLink() *terraformWriter.Literal {
	if fi.ValueOf(e.Shared) {
		if e.ID == nil {
			klog.Fatalf("ID must be set, if NAT Instance is shared: %s", e)
		}

		return terraformWriter.LiteralFromStringValue(*e.ID)
	}

	return terraformWriter.LiteralSelfLink("aws_instance", *e.Name)

View on GitHub (pinned to 4c8573c808)

Solutions

1. Read the wrapped AWS error after the colon (e.g. InvalidAMIID.NotFound) and fix the referenced resource ID.
2. Verify AMI, subnet, SGs, and keypair exist in the target region: `aws ec2 describe-images|describe-subnets|describe-security-groups|describe-key-pairs`.
3. Check EC2 service quotas (vCPU limit) in the region and request an increase if needed.
4. Confirm AWS credentials/IAM policy allow ec2:RunInstances for the task's role.
5. Retry if the error is InsufficientInstanceCapacity, possibly with a different instance type or AZ.

Example fix

# before
kops set cluster spec image: ami-0123456789abcdef0   # not present in eu-west-1
# after
aws ec2 describe-images --region eu-west-1 --owners amazon --filters Name=name,Values=amzn2-ami-hvm-*
kops edit cluster  # image: ami-<valid-in-region>
kops update cluster

// Pre-flight: validate referenced resources exist before RunInstances
func preflight(client *ec2.Client, imageID, subnetID, keyName string, sgIDs []string) error {
	if _, err := client.DescribeImages(ctx, &ec2.DescribeImagesInput{ImageIds: []string{imageID}}); err != nil {
		return fmt.Errorf("AMI %s invalid: %w", imageID, err)
	}
	if _, err := client.DescribeSubnets(ctx, &ec2.DescribeSubnetsInput{SubnetIds: []string{subnetID}}); err != nil {
		return fmt.Errorf("subnet %s invalid: %w", subnetID, err)
	}
	if _, err := client.DescribeSecurityGroups(ctx, &ec2.DescribeSecurityGroupsInput{GroupIds: sgIDs}); err != nil {
		return fmt.Errorf("security groups invalid: %w", err)
	}
	if keyName != "" {
		if _, err := client.DescribeKeyPairs(ctx, &ec2.DescribeKeyPairsInput{KeyNames: []string{keyName}}); err != nil {
			return fmt.Errorf("keypair %s missing: %w", keyName, err)
		}
	}
	return nil
}

err := applyCluster(ctx)
var retryable = []string{"InsufficientInstanceCapacity", "RequestLimitExceeded", "InternalError", "Throttling"}
if err != nil {
	for _, s := range retryable {
		if strings.Contains(err.Error(), "error creating Instance") && strings.Contains(err.Error(), s) {
			time.Sleep(30 * time.Second) // backoff, then retry kops update
			return applyCluster(ctx)
		}
	}
	return err
}
return nil

When it happens

Trigger: RunInstances returns an AWS error: InvalidAMIID.NotFound, InvalidSubnetID.NotFound, InvalidKeyPair.NotFound, InsufficientInstanceCapacity, VcpuLimitExceeded, UnauthorizedOperation, or invalid network-interface parameters (e.g. bad PrivateIpAddress in subnet).

Common situations: AMI not available in the target region; subnet or security group IDs deleted or from another VPC; EC2 vCPU service quota exhausted; spot/capacity constraints; IAM credentials lacking ec2:RunInstances; specifying a private IP already in use; SSH key name that does not exist in the region.

Related errors

• describing instance for arn %q
• error terminating instances: %v
• error describing 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/f89813c142846f6b. Report an issue: GitHub.