kubernetes/kops · error

converting cluster object: %w

Error message

converting cluster object: %w

What it means

Thrown by buildBootstrapData when the kops scheme codec (kopscodecs.Scheme.Convert) cannot convert the external v1alpha2 kops Cluster object into the internal kops.Cluster representation. Conversion failures mean the external object contains fields/values that cannot be losslessly mapped to the internal API, typically because the object came from a different kops version than the controller binary.

Source

Thrown at pkg/controllers/clusterapi/kopsconfig_controller.go:192

func (r *KopsConfigReconciler) buildBootstrapData(ctx context.Context, cluster *kopsapi.Cluster, kopsControlPlane *capikops.KopsControlPlane) ([]byte, error) {
	wellKnownAddresses := model.WellKnownAddresses{}
	for _, systemEndpoint := range kopsControlPlane.Status.SystemEndpoints {
		switch systemEndpoint.Type {
		case capikops.SystemEndpointTypeKopsController:
			wellKnownAddresses[wellknownservices.KopsController] = append(wellKnownAddresses[wellknownservices.KopsController], systemEndpoint.Endpoint)
		case capikops.SystemEndpointTypeKubeAPIServer:
			wellKnownAddresses[wellknownservices.KubeAPIServer] = append(wellKnownAddresses[wellknownservices.KubeAPIServer], systemEndpoint.Endpoint)
		}
	}

	clusterInternal := &kops.Cluster{}

	configBuilder := &commands.ConfigBuilder{}
	configBuilder.Clientset = r.clientset

	{
		if err := kopscodecs.Scheme.Convert(cluster, clusterInternal, nil); err != nil {
			return nil, fmt.Errorf("converting cluster object: %w", err)
		}
		// TODO: Fix validation
		clusterInternal.Namespace = ""

		configBuilder.Cluster = clusterInternal
		configBuilder.ClusterName = clusterInternal.Name
	}

	ig := &kops.InstanceGroup{}
	{
		ig.SetName("placeholder-ig-name") // IG name is not used for nodeup config generation
		ig.Spec.Role = kops.InstanceGroupRoleNode
		// The machine image is chosen by the CAPI infrastructure provider and is not used for
		// nodeup config generation; the placeholder avoids resolving a default from the channel.
		ig.Spec.Image = "placeholder-image"

		configBuilder.InstanceGroup = ig
		configBuilder.InstanceGroupName = ig.Name

View on GitHub (pinned to 4c8573c808)

Solutions

1. Read the wrapped conversion error to identify the offending field/value.
2. Upgrade or downgrade the kops cluster-api controller binary to match the kops version used to create the Cluster object.
3. Re-apply the Cluster object using kubectl/kops from the controller's matching version so defaults and field formats are consistent.
4. If a replica set is running mixed versions, align all controller pods to one kops version (check image tags in the deployment).
5. As a last resort, recreate the Cluster object from the authoritative kops cluster configuration export.

Example fix

// before: controller image pinned to old kops version
image: ko.k8s.io/kops-clusterapi-controller:v3.1.0
// after: match controller version to the kops version that created the Cluster
image: ko.k8s.io/kops-clusterapi-controller:v3.2.0

// Validate the external Cluster converts cleanly before the controller does
clusterInternal := &kops.Cluster{}
if err := kopscodecs.Scheme.Convert(cluster, clusterInternal, nil); err != nil {
	return fmt.Errorf("cluster %s/%s not convertible with this controller version: %w", cluster.Namespace, cluster.Name, err)
}
// Also pin controller version to the kops version that created the object

When it happens

Trigger: The Cluster spec stored in the management cluster was created by a different kops version than the controller (field type changes, removed/renamed fields), the object is partially written or corrupted, or a round-trip conversion hook returns an error for an unrecognized field value.

Common situations: Upgrading the kops cluster-api controllers while old Cluster objects created by a previous version still exist; hand-edited Cluster YAML with invalid enum values; mixed controller replicas running different kops versions against the same management cluster.

Related errors

• building cloud: %w
• node identity is required
• did not find owner for node %q
• invalid InstanceGroup name: %v
• error building InstanceGroup from CAPI Machine: %w

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