Skip to content

Commit 1a1dd04

Browse files
AmberAlstonclaude
AmberAlston
and
claude
committed
Clarify when kots.io/installer-only annotation is needed
Adds critical context about when the annotation is actually required vs when exclusion is automatic: - New section: "When to Use This Annotation" explaining 3 scenarios - Updated example: Shows resource INSIDE Helm chart template (where annotation matters) - Improved image handling section: Table format with concrete examples - New section: "Common Use Cases" with real-world scenarios Key clarification: Resources OUTSIDE Helm charts are auto-excluded from Helm CLI. The annotation is primarily for resources INSIDE Helm chart templates that should only deploy with Replicated installers. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
1 parent aa5bf0a commit 1a1dd04

File tree

1 file changed

+140
-17
lines changed

1 file changed

+140
-17
lines changed

‎docs/partials/helm/_helmchart-installer-only-annotation.mdx‎

Lines changed: 140 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,31 @@ Charts with `kots.io/installer-only: "true"` are still deployed when using Repli
88

99
This annotation is useful for charts that are required for Replicated installer-based deployments but should not be visible or installed when customers use the Helm CLI.
1010

11+
### When to Use This Annotation
12+
13+
The `kots.io/installer-only` annotation is needed in these scenarios:
14+
15+
**Scenario 1: Resources Inside Helm Chart Templates**
16+
17+
If you have Kubernetes resources (Deployments, Jobs, Services, etc.) **inside a Helm chart's templates** that should only deploy with Replicated installers:
18+
19+
- Without annotation: Resource deploys with BOTH Helm CLI and Replicated installers
20+
- With annotation: Resource only deploys with Replicated installers
21+
22+
**Scenario 2: Entire Helm Charts**
23+
24+
If you have a HelmChart custom resource that references a chart needed only for Replicated installers:
25+
26+
- The annotation on the HelmChart CR excludes the entire chart from Helm CLI installations
27+
28+
**Scenario 3: Standalone Manifests**
29+
30+
Standard Kubernetes resources that are NOT part of any Helm chart are **automatically excluded** from Helm CLI installations. You do not need to add this annotation to standalone manifests.
31+
32+
:::note
33+
HelmChart custom resources are Replicated-specific and never deployed by Helm CLI. The annotation controls whether the chart they reference is included in Helm installation instructions.
34+
:::
35+
1136
### Example: HelmChart Custom Resource
1237

1338
```yaml
@@ -23,35 +48,133 @@ spec:
2348
chartVersion: 1.0.0
2449
```
2550
26-
### Example: Standard Kubernetes Resource
51+
### Example: Resource Inside a Helm Chart
52+
53+
This example shows a Kubernetes Job inside a Helm chart's templates that should only run during Replicated installer deployments:
54+
55+
**File:** `your-chart/templates/preflight-job.yaml`
2756

2857
```yaml
58+
apiVersion: batch/v1
59+
kind: Job
60+
metadata:
61+
name: {{ .Release.Name }}-preflight
62+
annotations:
63+
kots.io/installer-only: "true"
64+
spec:
65+
template:
66+
spec:
67+
containers:
68+
- name: preflight-checks
69+
image: replicated/preflight:latest
70+
command: ["/bin/sh"]
71+
args: ["-c", "echo Running Replicated-specific preflight checks"]
72+
restartPolicy: Never
73+
```
74+
75+
**Why the annotation is needed:** Without it, this Job would run during both Helm CLI and Replicated installer deployments. The annotation ensures it only runs with Replicated installers where the preflight tooling is available.
76+
77+
**Standalone manifests:** If this Job were a standalone manifest in your release (not inside a Helm chart), it would automatically be excluded from Helm CLI installations without needing the annotation.
78+
79+
### Container Image Handling in Airgap Bundles
80+
81+
When determining which container images to include in Helm airgap bundles, the system uses intelligent many-to-many tracking. An image is **only excluded from Helm airgap bundles if ALL resources that reference it are marked as installer-only**.
82+
83+
**Example scenarios:**
84+
85+
| Scenario | Result | Why |
86+
|----------|--------|-----|
87+
| Image referenced only by installer-only resources | Excluded from Helm | All sources are installer-only |
88+
| Image referenced by installer-only AND regular resources | Included in Helm | At least one source is not installer-only |
89+
| Image referenced by multiple installer-only resources | Excluded from Helm | All sources are installer-only |
90+
91+
**Example:**
92+
93+
```yaml
94+
# In your-chart/templates/cache.yaml
2995
apiVersion: apps/v1
30-
kind: Deployment
96+
kind: StatefulSet
3197
metadata:
32-
name: installer-setup-job
98+
name: installer-cache
3399
annotations:
34100
kots.io/installer-only: "true"
35101
spec:
36-
replicas: 1
37-
selector:
38-
matchLabels:
39-
app: installer-setup
40102
template:
41-
metadata:
42-
labels:
43-
app: installer-setup
44103
spec:
45104
containers:
46-
- name: setup-container
47-
image: myregistry/installer-tool:v1.0
105+
- image: redis:7.2 # Still in Helm airgap if used elsewhere
106+
---
107+
# In your-chart/templates/app-cache.yaml
108+
apiVersion: apps/v1
109+
kind: Deployment
110+
metadata:
111+
name: app-cache
112+
# No annotation - regular deployment
113+
spec:
114+
template:
115+
spec:
116+
containers:
117+
- image: redis:7.2 # Same image, non-installer-only source
118+
```
119+
120+
In this example, `redis:7.2` is **included in Helm airgap bundles** because it's referenced by the `app-cache` Deployment which is NOT marked as installer-only, even though it's also used by an installer-only StatefulSet.
121+
122+
### Common Use Cases
123+
124+
**1. Preflight Checks and Validation**
125+
126+
Jobs that perform Replicated-specific preflight checks or validation:
127+
128+
```yaml
129+
# Inside your-chart/templates/preflight.yaml
130+
apiVersion: batch/v1
131+
kind: Job
132+
metadata:
133+
name: preflight-validator
134+
annotations:
135+
kots.io/installer-only: "true"
136+
```
137+
138+
**2. KOTS Admin Console Dependencies**
139+
140+
Charts or resources needed to support the KOTS Admin Console:
141+
142+
```yaml
143+
apiVersion: kots.io/v1beta2
144+
kind: HelmChart
145+
metadata:
146+
name: kots-postgres
147+
annotations:
148+
kots.io/installer-only: "true"
149+
spec:
150+
chart:
151+
name: postgresql
48152
```
49153

50-
### Troubleshooting
154+
**3. Database Migration Jobs**
155+
156+
Migration scripts that run during Replicated installer upgrades:
157+
158+
```yaml
159+
# Inside your-chart/templates/migrations.yaml
160+
apiVersion: batch/v1
161+
kind: Job
162+
metadata:
163+
name: db-migration
164+
annotations:
165+
kots.io/installer-only: "true"
166+
```
51167

52-
This annotation capability uses intelligent many-to-many tracking for container images. An image is **only excluded from Helm airgap bundles if ALL resources that reference it are marked as installer-only**. Example scenarios:
53-
* Annotated image only in installer-only Deployment → Excluded from Helm
54-
* Annotated image in both installer-only Job AND regular Deployment → Still included in Helm (because at least one source is not installer-only)
55-
* Image in multiple installer-only resources → Excluded from Helm
168+
**4. Cluster Preparation**
56169

170+
DaemonSets or init containers that prepare the cluster environment:
57171

172+
```yaml
173+
# Inside your-chart/templates/cluster-prep.yaml
174+
apiVersion: apps/v1
175+
kind: DaemonSet
176+
metadata:
177+
name: node-configurator
178+
annotations:
179+
kots.io/installer-only: "true"
180+
```

0 commit comments

Comments
 (0)