kubernetes/kops · error

unknown distro %v

Error message

unknown distro %v

What it means

Distribution.DefaultUsers in util/pkg/distributions returns the default SSH/admin username for a known Linux distribution. The Distribution value it receives is not one of the recognized distros (debian, ubuntu, centos, rhel, amazon-linux, rocky, flatcar, etc.), so the method has no mapping and returns this error. It is a guard against unvalidated Distribution values reaching user-selection logic.

Source

Thrown at util/pkg/distributions/distributions.go:142

}

// DefaultUsers returns the name of the system users for this distribution
func (d *Distribution) DefaultUsers() ([]string, error) {
	switch d.project {
	case "debian":
		return []string{"admin", "root"}, nil
	case "ubuntu":
		return []string{"ubuntu", "root"}, nil
	case "centos":
		return []string{"centos"}, nil
	case "rhel", "amazonlinux":
		return []string{"ec2-user"}, nil
	case "rocky":
		return []string{"rocky"}, nil
	case "flatcar":
		return []string{"core"}, nil
	default:
		return nil, fmt.Errorf("unknown distro %v", d)
	}
}

// HasLoopbackEtcResolvConf is true if systemd-resolved has put the loopback address 127.0.0.53 as a nameserver in /etc/resolv.conf
// See https://github.com/coredns/coredns/blob/master/plugin/loop/README.md#troubleshooting-loops-in-kubernetes-clusters
func (d *Distribution) HasLoopbackEtcResolvConf() bool {
	switch d.project {
	case "ubuntu", "flatcar":
		return true
	default:
		if _, err := os.Stat("/run/systemd/resolve/resolv.conf"); err == nil {
			return true
		}
		return false
	}
}

// Version returns the (project scoped) numeric version

View on GitHub (pinned to 4c8573c808)

Solutions

1. Use distributions.FindDistribution() to obtain the Distribution from /etc/os-release instead of constructing it manually
2. Pick a node image/AMI on a supported distro (debian, ubuntu, rocky, flatcar, amazon-linux, centos/rhel variants)
3. Add the missing distro case to DefaultUsers (and FindDistribution) if you genuinely need support for it
4. Print the value: the error includes the offending distribution string; verify spelling/casing against the constants in distributions.go

Example fix

// before
d := distributions.Distribution(osRelease["ID"])
users, err := d.DefaultUsers()
// after
d, err := distributions.FindDistribution("/")
if err != nil { return err }
users, err := d.DefaultUsers()

// validate the distro before asking for its users:
known := map[distributions.Distribution]bool{
    distributions.DistributionDebian9: true, /* ... all supported constants ... */
}
d, err := distributions.FindDistribution("/")
if err != nil { return err }
if !known[d] {
    return fmt.Errorf("distro %s not supported for node images", d)
}
users, err := d.DefaultUsers()

func isKnownDistro(d distributions.Distribution) bool {
    for _, supported := range distributions.GetSupported() { // if exported, else hardcode list
        if d == supported { return true }
    }
    return false
}

users, err := d.DefaultUsers()
if err != nil {
    return fmt.Errorf("cannot determine default SSH user for %v: %w; use a supported distro image", d, err)
}

When it happens

Trigger: Calling DefaultUsers() on a Distribution constructed from a string that FindDistribution never produced — e.g. &distributions.Distribution{"Fedora"}, an empty Distribution{}, or a hand-built value from cluster/config parsing that skipped the FindDistribution switch. The error prints the unknown value via %v.

Common situations: Parsing /etc/os-release yourself and feeding the raw ID into a Distribution without going through FindDistribution; a newly released distro (e.g. newer Fedora/Alma variant) whose image is used for nodes but is not in the supported list; typo'd distro names in custom tooling or tests; zero-value Distribution structs from failed earlier lookups.

Related errors

• unsupported distro %q
• method DeleteSSHCredential not supported in server-side clie
• method AddSSHPublicKey not supported in server-side client
• must specify %q label with cluster name to create SSHCredent
• spec.PublicKey is required

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