refactor(config): rename startupTaintKeys to knownStartupTaintKeys (#19)

## Summary
- Renames `startupTaintKeys` to `knownStartupTaintKeys` across all
config, Go code, tests, Helm values, and docs
- Adds detailed documentation explaining that Vigil does NOT remove
these taints — they are managed by their respective controllers (CSI
drivers, CNI plugins, etc.)
- The setting is used solely for DaemonSet discovery: stripped during
scheduling predicate evaluation so DaemonSets that don't tolerate
temporary taints aren't incorrectly excluded

**Breaking change:** Config key renamed from `startupTaintKeys` to
`knownStartupTaintKeys`

## Test plan
- [x] All unit tests pass
- [x] Code compiles (including stress tests)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: diranged

charts/vigil-controller/values.yaml

@@ -154,7 +154,21 @@ skipConfig: false
 config:
   taintKey: "node.nextdoor.com/initializing"
   taintEffect: "NoSchedule"
-  startupTaintKeys:
+  # -- All known temporary startup taint keys used in the cluster.
+  # Vigil only removes the taint specified by taintKey. However, new nodes often
+  # have additional temporary taints set by other controllers (CSI drivers, CNI
+  # plugins, etc.). Those controllers remove their own taints — Vigil does not
+  # touch them.
+  #
+  # This list is used solely for DaemonSet discovery: when determining which
+  # DaemonSets should run on a node in steady state, Vigil strips these taints
+  # before evaluating scheduling predicates. Without this, DaemonSets that don't
+  # tolerate these temporary taints would be incorrectly excluded from Vigil's
+  # expected set, causing it to remove its taint too early.
+  #
+  # Must include taintKey itself. Add any other startup taints used by your
+  # infrastructure (CSI drivers, CNI plugins, GPU initializers, etc.).
+  knownStartupTaintKeys:
     - "node.nextdoor.com/initializing"
     - "cni.istio.io/not-ready"
     - "ebs.csi.aws.com/agent-not-ready"

config.example.yaml

@@ -7,11 +7,20 @@ taintKey: "node.nextdoor.com/initializing"
 # The taint effect to match
 taintEffect: "NoSchedule"
 
-# ALL startup taint keys present in this cluster.
-# These are stripped from the node's taint list when evaluating DaemonSet
-# tolerations, so that discovery answers "will this DS run in steady state?"
-# rather than "can this DS tolerate the node right now?"
-startupTaintKeys:
+# All known temporary startup taint keys used in the cluster.
+#
+# Vigil only removes the taint specified by taintKey above. However, new nodes
+# often have additional temporary taints set by other controllers (CSI drivers,
+# CNI plugins, etc.). Those taints are removed by their respective controllers,
+# not by Vigil.
+#
+# This list is used only for DaemonSet discovery: Vigil strips these taints
+# before evaluating which DaemonSets should run on a node in steady state.
+# Without this, DaemonSets that don't tolerate these temporary taints would be
+# incorrectly excluded from the expected set.
+#
+# Must include taintKey itself plus any other startup taints in the cluster.
+knownStartupTaintKeys:
   - "node.nextdoor.com/initializing"
   - "cni.istio.io/not-ready"
   - "ebs.csi.aws.com/agent-not-ready"

internal/controller/integration_test.go

@@ -57,7 +57,7 @@ func testConfig() *config.Config {
 	return &config.Config{
 		TaintKey:    "node.example.com/initializing",
 		TaintEffect: "NoSchedule",
-		StartupTaintKeys: []string{
+		KnownStartupTaintKeys: []string{
 			"node.example.com/initializing",
 		},
 		TimeoutSeconds: 120,

internal/discovery/discovery.go

@@ -48,7 +48,7 @@ func (d *DaemonSetDiscovery) ExpectedDaemonSets(ctx context.Context, node *corev
 	}
 
 	// Compute steady-state taints: node taints minus all configured startup taint keys.
-	steadyStateTaints := steadyStateTaints(node.Spec.Taints, d.config.StartupTaintKeys)
+	steadyStateTaints := steadyStateTaints(node.Spec.Taints, d.config.KnownStartupTaintKeys)
 
 	// Build exclusion lookup.
 	excludeByName := buildNameExclusionSet(d.config.ExcludeDaemonSets.ByName)

internal/discovery/discovery_test.go

@@ -28,7 +28,7 @@ func defaultConfig() *config.Config {
 	return &config.Config{
 		TaintKey:    "node.example.com/initializing",
 		TaintEffect: "NoSchedule",
-		StartupTaintKeys: []string{
+		KnownStartupTaintKeys: []string{
 			"node.example.com/initializing",
 			"cni.example.io/not-ready",
 		},
@@ -301,7 +301,7 @@ func TestExpectedDaemonSets_NoDaemonSets(t *testing.T) {
 func TestExpectedDaemonSets_NoStartupTaintsConfigured(t *testing.T) {
 	scheme := newScheme()
 	cfg := defaultConfig()
-	cfg.StartupTaintKeys = nil // No startup taints to strip.
+	cfg.KnownStartupTaintKeys = nil // No startup taints to strip.
 
 	// Node has a taint that the DS doesn't tolerate.
 	node := newNode(nil, []corev1.Taint{

pkg/config/config.go

@@ -15,10 +15,21 @@ type Config struct {
 	// TaintEffect is the taint effect to match.
 	TaintEffect string `mapstructure:"taintEffect"`
 
-	// StartupTaintKeys is the list of ALL startup taint keys present in this cluster.
-	// These are stripped from the node's taint list when evaluating DaemonSet
-	// tolerations, so that discovery answers "will this DS run in steady state?"
-	StartupTaintKeys []string `mapstructure:"startupTaintKeys"`
+	// KnownStartupTaintKeys lists ALL temporary startup taint keys used in the cluster.
+	//
+	// Vigil only removes the taint specified by TaintKey. However, new nodes often
+	// have additional temporary taints set by other controllers (e.g., CSI drivers,
+	// CNI plugins). These taints are removed by their respective controllers — not
+	// by Vigil.
+	//
+	// This list is used solely for DaemonSet discovery: when determining which
+	// DaemonSets should run on a node in steady state, Vigil strips these taints
+	// before evaluating scheduling predicates. Without this, DaemonSets that don't
+	// tolerate these temporary taints would be incorrectly excluded from the
+	// expected set.
+	//
+	// Must include TaintKey itself plus any other startup taints in the cluster.
+	KnownStartupTaintKeys []string `mapstructure:"knownStartupTaintKeys"`
 
 	// TimeoutSeconds is the maximum time to wait before removing the taint anyway.
 	TimeoutSeconds int `mapstructure:"timeoutSeconds"`
@@ -67,7 +78,7 @@ func NewDefault() *Config {
 	return &Config{
 		TaintKey:    "node.nextdoor.com/initializing",
 		TaintEffect: "NoSchedule",
-		StartupTaintKeys: []string{
+		KnownStartupTaintKeys: []string{
 			"node.nextdoor.com/initializing",
 		},
 		TimeoutSeconds:          120,

pkg/config/config_test.go

@@ -14,7 +14,7 @@ func TestNewDefault(t *testing.T) {
 	assert.Equal(t, "node.nextdoor.com/initializing", cfg.TaintKey)
 	assert.Equal(t, "NoSchedule", cfg.TaintEffect)
 	assert.Equal(t, 120, cfg.TimeoutSeconds)
-	assert.Len(t, cfg.StartupTaintKeys, 1)
+	assert.Len(t, cfg.KnownStartupTaintKeys, 1)
 }
 
 func TestLoad_FileNotFound(t *testing.T) {
@@ -30,7 +30,7 @@ func TestLoad_ValidConfig(t *testing.T) {
 taintKey: "custom.taint/key"
 taintEffect: "NoExecute"
 timeoutSeconds: 60
-startupTaintKeys:
+knownStartupTaintKeys:
   - "custom.taint/key"
   - "cni.istio.io/not-ready"
 excludeDaemonSets:
@@ -45,7 +45,7 @@ excludeDaemonSets:
 	assert.Equal(t, "custom.taint/key", cfg.TaintKey)
 	assert.Equal(t, "NoExecute", cfg.TaintEffect)
 	assert.Equal(t, 60, cfg.TimeoutSeconds)
-	assert.Len(t, cfg.StartupTaintKeys, 2)
+	assert.Len(t, cfg.KnownStartupTaintKeys, 2)
 	assert.Len(t, cfg.ExcludeDaemonSets.ByName, 1)
 	assert.Equal(t, "slow-ds", cfg.ExcludeDaemonSets.ByName[0].Name)
 }

test/stress/stress_test.go

@@ -103,7 +103,7 @@ func TestStress(t *testing.T) {
 	cfg := &config.Config{
 		TaintKey:    taintKey,
 		TaintEffect: "NoSchedule",
-		StartupTaintKeys: []string{
+		KnownStartupTaintKeys: []string{
 			taintKey,
 			"node.kubernetes.io/not-ready", // envtest adds this (no kubelet)
 		},

website/content/en/docs/reference/configuration.md

@@ -15,8 +15,10 @@ taintKey: "node.example.com/initializing"
 # The taint effect to match
 taintEffect: "NoSchedule"
 
-# ALL startup taint keys present in this cluster
-startupTaintKeys:
+# All known temporary startup taint keys in the cluster.
+# Used for DaemonSet discovery only — Vigil does not remove these taints.
+# Their respective controllers (CSI drivers, CNI plugins) handle removal.
+knownStartupTaintKeys:
   - "node.example.com/initializing"
   - "cni.istio.io/not-ready"
   - "ebs.csi.aws.com/agent-not-ready"
@@ -48,6 +50,6 @@ excludeDaemonSets:
 |-------|------|---------|-------------|
 | `taintKey` | string | `node.nextdoor.com/initializing` | The taint key to watch and remove |
 | `taintEffect` | string | `NoSchedule` | The taint effect to match |
-| `startupTaintKeys` | []string | `[taintKey]` | All startup taint keys in the cluster |
+| `knownStartupTaintKeys` | []string | `[taintKey]` | All temporary startup taint keys in the cluster (used for discovery only — Vigil does not remove these) |
 | `timeoutSeconds` | int | `120` | Max wait time before forced taint removal |
 | `excludeDaemonSets.byName` | []object | `[]` | DaemonSets to exclude by namespace/name |

website/content/en/docs/reference/helm-chart.md

@@ -26,7 +26,7 @@ helm install vigil vigil/vigil-controller \
 | `config.taintKey` | `node.nextdoor.com/initializing` | Taint key to watch |
 | `config.taintEffect` | `NoSchedule` | Taint effect |
 | `config.timeoutSeconds` | `120` | Timeout before forced removal |
-| `config.startupTaintKeys` | See values.yaml | All startup taint keys |
+| `config.knownStartupTaintKeys` | See values.yaml | Temporary startup taints to ignore during discovery |
 | `serviceMonitor.enabled` | `false` | Create ServiceMonitor |
 | `resources.requests.cpu` | `100m` | CPU request |
 | `resources.requests.memory` | `64Mi` | Memory request |