kubernetes/kops · error

error describing VPC: %v

Error message

error describing VPC: %v

What it means

After loading the AWS client, getAWSZoneToSubnetProviderID calls awsCloud.FindVPCInfo(VPCID) to describe the VPC and enumerate its subnets. If the EC2 DescribeVpcs/DescribeSubnets API call fails (throttling, authz denial, network error), the SDK error is wrapped as "error describing VPC: %v" and returned to the caller (setupZones/setupTopology), aborting cluster creation.

Source

Thrown at upup/pkg/fi/cloudup/new_cluster.go:913

				cluster.Spec.Networking.Subnets = append(cluster.Spec.Networking.Subnets, *subnet)
			}
			zoneToSubnetsMap[zoneName] = append(zoneToSubnetsMap[zoneName], subnet)
		}
	}

	return zoneToSubnetsMap, nil
}

func getAWSZoneToSubnetProviderID(VPCID string, region string, subnetIDs []string) (map[string]string, error) {
	res := make(map[string]string)
	cloudTags := map[string]string{}
	awsCloud, err := awsup.NewAWSCloud(region, cloudTags)
	if err != nil {
		return res, fmt.Errorf("error loading cloud: %v", err)
	}
	vpcInfo, err := awsCloud.FindVPCInfo(VPCID)
	if err != nil {
		return res, fmt.Errorf("error describing VPC: %v", err)
	}
	if vpcInfo == nil {
		return res, fmt.Errorf("VPC %q not found", VPCID)
	}
	subnetByID := make(map[string]*fi.SubnetInfo)
	for _, subnetInfo := range vpcInfo.Subnets {
		subnetByID[subnetInfo.ID] = subnetInfo
	}
	for _, subnetID := range subnetIDs {
		subnet, ok := subnetByID[subnetID]
		if !ok {
			return res, fmt.Errorf("subnet %s not found in VPC %s", subnetID, VPCID)
		}
		if res[subnet.Zone] != "" {
			return res, fmt.Errorf("subnet %s and %s have the same zone", subnetID, res[subnet.Zone])
		}
		res[subnet.Zone] = subnetID
	}

View on GitHub (pinned to 4c8573c808)

Solutions

1. Grant the calling identity iam: ec2:DescribeVpcs and ec2:DescribeSubnets (check CloudTrail for the AccessDenied entry).
2. Retry on throttling errors; reduce parallel kOps invocations.
3. Verify network reachability to the regional EC2 endpoint (proxy/VPN/firewall).
4. Inspect the wrapped %v message for the exact AWS error code.

Example fix

// before (IAM policy missing describe permissions)
{"Effect": "Deny", "Action": ["ec2:Describe*"], "Resource": "*"}
// after
{"Effect": "Allow", "Action": ["ec2:DescribeVpcs", "ec2:DescribeSubnets"], "Resource": "*"}

out, err := exec.Command("aws", "ec2", "describe-vpcs", "--vpc-ids", vpcID, "--region", region).Output()
if err != nil {
    return fmt.Errorf("cannot describe VPC %s in %s: %w", vpcID, region, err)
}

if strings.Contains(err.Error(), "error describing VPC") {
    if strings.Contains(err.Error(), "Throttling") {
        time.Sleep(backoff); retry()
    } else if strings.Contains(err.Error(), "AccessDenied") {
        // surface IAM remediation to the operator
    }
}

When it happens

Trigger: `kops create cluster --cloud aws ... --vpc vpc-xxx --subnets subnet-...` where the EC2 API call errors: IAM policy missing ec2:DescribeVpcs/ec2:DescribeSubnets, API throttling, network timeout, or stale credentials revoked mid-call.

Common situations: Restricted IAM roles on CI runners; corporate proxy blocking EC2 endpoints; throttling when running many kOps operations in parallel; SCPs denying EC2 describe actions.

Related errors

• error modifying VPC attribute: %v
• VPC %q not found
• subnet %s not found in VPC %s
• IP version is incorrect
• provider ID cannot be empty

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