API reference — karpenter.dklesev.github.io/v1beta1

Three kinds. SSHHost is namespaced (the pool namespace, POOL_NAMESPACE); SSHNodeClass and SSHJoinProfile are cluster-scoped.

Karpenter's own NodePool/NodeClaim are documented upstream (https://karpenter.sh/docs/concepts/nodepools/); a NodePool joins this provider by referencing an SSHNodeClass in nodeClassRef:

nodeClassRef:
  group: karpenter.dklesev.github.io
  kind: SSHNodeClass
  name: my-pool

SSHHost (namespaced, kubectl get sshhosts)

One inventory entry per pre-existing host.

apiVersion: karpenter.dklesev.github.io/v1beta1
kind: SSHHost
metadata:
  name: host-a
  namespace: kpssh-system
  labels:
    karpenter.dklesev.github.io/host-class: big     # class membership (unset ⇒ "default")
spec:
  address: 10.0.0.11         # immutable
  port: 22
  user: ops
  sshKeySecretRef: {name: pool-ssh-key}
  nodeAddress: ""            # optional: IP literal the node advertises if != address
  capacity:                  # cpu and memory are mandatory
    cpu: "8"
    memory: 64Gi

spec

Labels and annotations

Well-known labels the provider advertises

These are what a NodePool's requirements can select on. Anything else matches nothing — a requirement the provider never advertises silently yields zero instance types, which surfaces only as pods that never schedule.

status

SSHNodeClass (cluster-scoped, kubectl get snc)

Karpenter node class: which hosts, how to join them, what they cost.

apiVersion: karpenter.dklesev.github.io/v1beta1
kind: SSHNodeClass
metadata:
  name: hybrid-pool
spec:
  hostSelector:
    matchLabels: {karpenter.dklesev.github.io/host-class: big}   # optional narrowing
  joinProfileRef: {name: nodeadm-ssm}
  providerIDSource: Adopt          # Static | Adopt
  pricePerCPUHour: "0.02"
  joinSecretRef: {name: eks-activation}   # optional
  cluster:                          # optional discovery override
    endpoint: https://ABC.gr7.eu-central-1.eks.amazonaws.com
    caBundle: LS0tLS1CRUdJTi…
  vars:                             # profile template variables
    clusterName: my-cluster
    region: eu-central-1
    k8sVersion: "1.34"

spec

status

conditions — operatorpkg readiness. Ready=True requires all of: the referenced SSHJoinProfile exists, it validates, hostSelector parses, and it matches at least one SSHHost. Referenced Secrets (sshKeySecretRef, joinSecretRef) are not checked here — a missing Secret surfaces as a join failure on the NodeClaim, not as a NotReady node class.

Karpenter refuses to launch NodeClaims against a node class that is not Ready (NodeClassNotReady), so these four are the first thing to check when nothing scales up.

SSHJoinProfile (cluster-scoped, kubectl get sjp)

A named, versioned join mechanism: four idempotent scripts. Full contract, environment table and authoring guide: join-profiles.md.

apiVersion: karpenter.dklesev.github.io/v1beta1
kind: SSHJoinProfile
metadata:
  name: tls-bootstrap
spec:
  version: "3"          # bump ⇒ invalidates every host's install cache
  scripts:
    install: |
      #!/usr/bin/env bash
      …
    join: |
      …
    leave: |
      …
    uninstall: |        # optional, manual/repair only
      …

spec

Timeouts are Go durations, pattern-validated as ^([0-9]+(s|m|h))+$ — 90s, 10m, 1h30m are accepted; 1.5h, 500ms and bare numbers are not. The pattern is load-bearing, not cosmetic: an undecodable duration on a single profile would break the typed List of every informer watching the kind and wedge the controller cluster-wide.

Scripts are Go text/templates rendered with the join context, transported over SSH and executed as sudo bash -s with the KPSSH_* environment exported in a preamble (sshd AcceptEnv is typically locked down, so env travels inside the script stream).

providerID forms