kubernetes/kops · error

unknown instancegroup role %q

Error message

unknown instancegroup role %q

What it means

BuildNodeRoleSubject received an instance group role outside the known set (control-plane, api-server, node, bastion); a new or invalid role value reached the IAM builder.

Source

Thrown at pkg/model/iam/subject.go:104

}

// BuildNodeRoleSubject returns a Subject implementation for the specified InstanceGroupRole.
func BuildNodeRoleSubject(igRole kops.InstanceGroupRole, enableLifecycleHookPermissions bool) (Subject, error) {
	switch igRole {
	case kops.InstanceGroupRoleControlPlane:
		return &NodeRoleMaster{}, nil
	case kops.InstanceGroupRoleAPIServer:
		return &NodeRoleAPIServer{
			warmPool: enableLifecycleHookPermissions,
		}, nil
	case kops.InstanceGroupRoleNode:
		return &NodeRoleNode{
			enableLifecycleHookPermissions: enableLifecycleHookPermissions,
		}, nil
	case kops.InstanceGroupRoleBastion:
		return &NodeRoleBastion{}, nil
	default:
		return nil, fmt.Errorf("unknown instancegroup role %q", igRole)
	}
}

// AddServiceAccountRole adds the appropriate mounts / env vars to enable a pod to use a service-account role
func AddServiceAccountRole(context *IAMModelContext, podSpec *corev1.PodSpec, serviceAccountRole Subject) error {
	cloudProvider := context.Cluster.GetCloudProvider()

	switch cloudProvider {
	case kops.CloudProviderAWS:
		return addServiceAccountRoleForAWS(context, podSpec, serviceAccountRole)
	default:
		return fmt.Errorf("ServiceAccount-level IAM is not yet supported on cloud %T", cloudProvider)
	}
}

func addServiceAccountRoleForAWS(context *IAMModelContext, podSpec *corev1.PodSpec, serviceAccountRole Subject) error {
	roleName, err := context.IAMNameForServiceAccountRole(serviceAccountRole)
	if err != nil {

View on GitHub (pinned to 4c8573c808)

Solutions

1. Check the instance group's spec.role is a valid kOps role
2. Fix the instance group manifest
3. Report upstream if a legitimately new role is unsupported

When it happens

Trigger: Thrown at pkg/model/iam/subject.go:104 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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