kubernetes/kops · error

building full cluster spec

Error message

building full cluster spec: %w

What it means

GetFullCluster calls cloudup.PopulateClusterSpec to fully populate/validate the cluster spec (defaults, cloud-specific fields) and wraps any failure. This means the cluster spec from the state store could not be reconciled against the cloud and instance groups.

Solutions

1. Read the wrapped root cause (%w chain) — it names the specific spec field or cloud error
2. Validate the cluster: kops replace/apply with --dry-run or `kops toolbox template` to surface spec errors
3. Refresh cloud credentials and confirm the cloud API is reachable
4. Upgrade/align the cluster spec (kops upgrade cluster) if versions are mismatched

Example fix

// before
fullCluster, err := b.GetFullCluster(ctx) // opaque spec error
// after
if err != nil {
    var root error
    for errors.Unwrap(err) != nil { root = errors.Unwrap(err) }
    log.Printf("populate failed, root cause: %v", root)
}

// validate spec before populating
if err := cluster.Validate(false); err != nil { return fmt.Errorf("invalid cluster spec: %w", err) }

func isSpecPopulationError(err error) bool {
    return err != nil && strings.Contains(err.Error(), "building full cluster spec")
}

full, err := b.GetFullCluster(ctx)
if isSpecPopulationError(err) {
    return fmt.Errorf("fix cluster spec / cloud access (see wrapped cause): %w", err)
}

When it happens

Trigger: PopulateClusterSpec returns an error: invalid or missing fields in the cluster manifest, cloud API failures (auth, quota, region), unsupported kubernetes version, or inconsistent instance groups.

Common situations: Cluster spec edited by hand with invalid values; cloud credentials expired/missing; kops version newer than the spec supports; deleting cloud resources referenced by the cluster (subnets/VPC).

Related errors

• cannot mix egress values in private or IPv6-capable subnets
• classic networking not supported
• configuration must include Subnets
• DNSZone not set
• error populating configuration

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

Appendix: source

Thrown at pkg/commands/toolbox_enroll.go:535

	assetBuilder, err := b.GetAssetBuilder(ctx)
	if err != nil {
		return nil, err
	}

	instanceGroupList, err := b.GetInstanceGroups(ctx)
	if err != nil {
		return nil, err
	}

	var instanceGroups []*kops.InstanceGroup
	for i := range instanceGroupList.Items {
		instanceGroup := &instanceGroupList.Items[i]
		instanceGroups = append(instanceGroups, instanceGroup)
	}

	fullCluster, err := cloudup.PopulateClusterSpec(ctx, clientset, cluster, instanceGroups, cloud, assetBuilder)
	if err != nil {
		return nil, fmt.Errorf("building full cluster spec: %w", err)
	}
	b.fullCluster = fullCluster
	return fullCluster, nil
}

func (b *ConfigBuilder) GetInstanceGroup(ctx context.Context) (*kops.InstanceGroup, error) {
	if b.InstanceGroup != nil {
		return b.InstanceGroup, nil
	}

	instanceGroups, err := b.GetInstanceGroups(ctx)
	if err != nil {
		return nil, err
	}

	if b.InstanceGroupName == "" {
		return nil, fmt.Errorf("InstanceGroup name is missing")
	}

View on GitHub (pinned to 4c8573c808)