Skip to content

Commit fcdaa90

Browse files
brandondbrandond
committed
Rework CRD generation to add docs and kubectl explain support
- Convert CRD generation to controller-gen - Add CRD docs Signed-off-by: Brad Davidson <[email protected]>
1 parent f4dd2a5 commit fcdaa90

File tree

24 files changed

+1317
-359
lines changed

24 files changed

+1317
-359
lines changed

‎Dockerfile

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ ARG ARCH
1818
ENV ARCH=$ARCH
1919
RUN apk add --no-cache bash git gcc musl-dev curl
2020
RUN GOPROXY=direct go install golang.org/x/tools/cmd/goimports@gopls/v0.18.1
21+
RUN GOPROXY=direct go install sigs.k8s.io/controller-tools/cmd/[email protected]
2122
RUN if [ "${ARCH}" != "arm" ]; then \
2223
curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s v1.64.7; \
2324
fi

‎README.md

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,7 @@
11
helm-controller
22
========
33

4-
_NOTE: this repository has been recently (2020-10-06) moved out of the github.com/rancher org to github.com/k3s-io
5-
supporting the [acceptance of K3s as a CNCF sandbox project](https://github.com/cncf/toc/pull/447)_.
6-
7-
---
8-
9-
A simple way to manage helm charts (v2 and v3) with Custom Resource Definitions in k8s.
4+
A simple way to manage helm charts with Custom Resource Definitions in k8s.
105

116
## Manifests and Deploying
127
The `./manifests` folder contains useful YAML manifests to use for deploying and developing the Helm Controller. This simple YAML deployment creates a HelmChart CRD + a Deployment using the `rancher/helm-controller` container. The YAML might need some modifications for your environment so read below for Namespaced vs Cluster deployments and how to use them properly.
@@ -17,6 +12,10 @@ Use the `deploy-namespaced.yaml` to create a namespace and add the Helm Controll
1712
#### Cluster Scoped Deploys
1813
If you'd like your helm controller to watch the entire cluster for HelmChart CRD changes use the `deploy-cluster-scoped.yaml` deploy manifest. By default it will add the helm-controller to the `kube-system` so update `metadata.namespace` for your needs.
1914

15+
## API Documentation
16+
17+
Autogenerated API docs for `helm.cattle.io/v1 HelmChart` and `HelmChartConfig` are available at [doc/helmchart.md](doc/helmchart.md#HelmChart)
18+
2019
## Uninstalling
2120
To remove the Helm Controller run `kubectl delete` and pass the deployment YAML used using to create the Deployment `-f` parameter.
2221

‎crd-ref-docs.yaml

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
processor:
2+
ignoreFields:
3+
- "TypeMeta$"
4+
render:
5+
kubernetesVersion: 1.32

‎doc/helmchart.md

Lines changed: 199 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,199 @@
1+
# API Reference
2+
3+
## Packages
4+
- [helm.cattle.io/v1](#helmcattleiov1)
5+
6+
7+
## helm.cattle.io/v1
8+
9+
10+
11+
12+
13+
14+
#### FailurePolicy
15+
16+
_Underlying type:_ _string_
17+
18+
19+
20+
_Validation:_
21+
- Enum: [abort reinstall]
22+
23+
_Appears in:_
24+
- [HelmChartConfigSpec](#helmchartconfigspec)
25+
- [HelmChartSpec](#helmchartspec)
26+
27+
28+
29+
#### HelmChart
30+
31+
32+
33+
HelmChart represents configuration and state for the deployment of a Helm chart.
34+
35+
36+
37+
_Appears in:_
38+
- [HelmChartList](#helmchartlist)
39+
40+
| Field | Description | Default | Validation |
41+
| --- | --- | --- | --- |
42+
| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | | |
43+
| `spec` _[HelmChartSpec](#helmchartspec)_ | | | |
44+
| `status` _[HelmChartStatus](#helmchartstatus)_ | | | |
45+
46+
47+
#### HelmChartCondition
48+
49+
50+
51+
52+
53+
54+
55+
_Appears in:_
56+
- [HelmChartStatus](#helmchartstatus)
57+
58+
| Field | Description | Default | Validation |
59+
| --- | --- | --- | --- |
60+
| `type` _[HelmChartConditionType](#helmchartconditiontype)_ | Type of job condition. | | |
61+
| `status` _[ConditionStatus](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#conditionstatus-v1-core)_ | Status of the condition, one of True, False, Unknown. | | |
62+
| `reason` _string_ | (brief) reason for the condition's last transition. | | |
63+
| `message` _string_ | Human readable message indicating details about last transition. | | |
64+
65+
66+
#### HelmChartConditionType
67+
68+
_Underlying type:_ _string_
69+
70+
71+
72+
73+
74+
_Appears in:_
75+
- [HelmChartCondition](#helmchartcondition)
76+
77+
| Field | Description |
78+
| --- | --- |
79+
| `JobCreated` | |
80+
| `Failed` | |
81+
82+
83+
#### HelmChartConfig
84+
85+
86+
87+
HelmChartConfig represents additional configuration for the installation of Helm chart release.
88+
This resource is intended for use when additional configuration needs to be passed to a HelmChart
89+
that is managed by an external system.
90+
91+
92+
93+
_Appears in:_
94+
- [HelmChartConfigList](#helmchartconfiglist)
95+
96+
| Field | Description | Default | Validation |
97+
| --- | --- | --- | --- |
98+
| `metadata` _[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#objectmeta-v1-meta)_ | Refer to Kubernetes API documentation for fields of `metadata`. | | |
99+
| `spec` _[HelmChartConfigSpec](#helmchartconfigspec)_ | | | |
100+
101+
102+
103+
104+
#### HelmChartConfigSpec
105+
106+
107+
108+
HelmChartConfigSpec represents additional user-configurable details of an installed and configured Helm chart release.
109+
These fields are merged with or override the corresponding fields on the related HelmChart resource.
110+
111+
112+
113+
_Appears in:_
114+
- [HelmChartConfig](#helmchartconfig)
115+
116+
| Field | Description | Default | Validation |
117+
| --- | --- | --- | --- |
118+
| `valuesContent` _string_ | Override complex Chart values via inline YAML content.<br />Helm CLI positional argument/flag: `--values` | | |
119+
| `valuesSecrets` _[SecretSpec](#secretspec) array_ | Override complex Chart values via references to external Secrets.<br />Helm CLI positional argument/flag: `--values` | | |
120+
| `failurePolicy` _[FailurePolicy](#failurepolicy)_ | Configures handling of failed chart installation or upgrades.<br />- `reinstall` will perform a clean uninstall and reinstall of the chart.<br />- `abort` will take no action and leave the chart in a failed state so that the administrator can manually resolve the error. | reinstall | Enum: [abort reinstall] <br /> |
121+
122+
123+
124+
125+
#### HelmChartSpec
126+
127+
128+
129+
HelmChartSpec represents the user-configurable details for installation and upgrade of a Helm chart release.
130+
131+
132+
133+
_Appears in:_
134+
- [HelmChart](#helmchart)
135+
136+
| Field | Description | Default | Validation |
137+
| --- | --- | --- | --- |
138+
| `targetNamespace` _string_ | Helm Chart target namespace.<br />Helm CLI positional argument/flag: `--namespace` | | |
139+
| `createNamespace` _boolean_ | Create target namespace if not present.<br />Helm CLI positional argument/flag: `--create-namespace` | | |
140+
| `chart` _string_ | Helm Chart name in repository, or complete HTTPS URL to chart archive (.tgz)<br />Helm CLI positional argument/flag: `CHART` | | |
141+
| `version` _string_ | Helm Chart version. Only used when installing from repository; ignored when .spec.chart or .spec.chartContent is used to install a specific chart archive.<br />Helm CLI positional argument/flag: `--version` | | |
142+
| `repo` _string_ | Helm Chart repository URL.<br />Helm CLI positional argument/flag: `--repo` | | |
143+
| `repoCA` _string_ | Verify certificates of HTTPS-enabled servers using this CA bundle. Should be a string containing one or more PEM-encoded CA Certificates.<br />Helm CLI positional argument/flag: `--ca-file` | | |
144+
| `repoCAConfigMap` _[LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#localobjectreference-v1-core)_ | Reference to a ConfigMap containing CA Certificates to be be trusted by Helm. Can be used along with or instead of `.spec.repoCA`<br />Helm CLI positional argument/flag: `--ca-file` | | |
145+
| `set` _object (keys:string, values:[IntOrString](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#intorstring-intstr-util))_ | Override simple Chart values. These take precedence over options set via valuesContent.<br />Helm CLI positional argument/flag: `--set`, `--set-string` | | |
146+
| `valuesContent` _string_ | Override complex Chart values via inline YAML content.<br />Helm CLI positional argument/flag: `--values` | | |
147+
| `valuesSecrets` _[SecretSpec](#secretspec) array_ | Override complex Chart values via references to external Secrets.<br />Helm CLI positional argument/flag: `--values` | | |
148+
| `helmVersion` _string_ | DEPRECATED. Helm version to use. Only v3 is currently supported. | | |
149+
| `bootstrap` _boolean_ | Set to True if this chart is needed to bootstrap the cluster (Cloud Controller Manager, CNI, etc) | | |
150+
| `chartContent` _string_ | Base64-encoded chart archive .tgz; overides `.spec.chart` and `.spec.version`<br />Helm CLI positional argument/flag: `CHART` | | |
151+
| `jobImage` _string_ | Specify the image to use for tht helm job pod when installing or upgrading the helm chart. | | |
152+
| `backOffLimit` _integer_ | Specify the number of retries before considering the helm job failed. | | |
153+
| `timeout` _[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#duration-v1-meta)_ | Timeout for Helm operations.<br />Helm CLI positional argument/flag: `--timeout` | | |
154+
| `failurePolicy` _[FailurePolicy](#failurepolicy)_ | Configures handling of failed chart installation or upgrades.<br />- `reinstall` will perform a clean uninstall and reinstall of the chart.<br />- `abort` will take no action and leave the chart in a failed state so that the administrator can manually resolve the error. | reinstall | Enum: [abort reinstall] <br /> |
155+
| `authSecret` _[LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#localobjectreference-v1-core)_ | Reference to Secret of type kubernetes.io/basic-auth holding Basic auth credentials for the Chart repo. | | |
156+
| `authPassCredentials` _boolean_ | Pass Basic auth credentials to all domains.<br />Helm CLI positional argument/flag: `--pass-credentials` | | |
157+
| `insecureSkipTLSVerify` _boolean_ | Skip TLS certificate checks for the chart download.<br />Helm CLI positional argument/flag: `--insecure-skip-tls-verify` | | |
158+
| `plainHTTP` _boolean_ | Use insecure HTTP connections for the chart download.<br />Helm CLI positional argument/flag: `--plain-http` | | |
159+
| `dockerRegistrySecret` _[LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#localobjectreference-v1-core)_ | Reference to Secret of type kubernetes.io/dockerconfigjson holding Docker auth credentials for the OCI-based registry acting as the Chart repo. | | |
160+
| `podSecurityContext` _[PodSecurityContext](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#podsecuritycontext-v1-core)_ | Custom PodSecurityContext for the helm job pod. | | |
161+
| `securityContext` _[SecurityContext](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#securitycontext-v1-core)_ | custom SecurityContext for the helm job pod. | | |
162+
163+
164+
#### HelmChartStatus
165+
166+
167+
168+
HelmChartStatus represents the resulting state from processing HelmChart events
169+
170+
171+
172+
_Appears in:_
173+
- [HelmChart](#helmchart)
174+
175+
| Field | Description | Default | Validation |
176+
| --- | --- | --- | --- |
177+
| `jobName` _string_ | The name of the job created to install or upgrade the chart. | | |
178+
| `conditions` _[HelmChartCondition](#helmchartcondition) array_ | `JobCreated` indicates that a job has been created to install or upgrade the chart.<br />`Failed` indicates that the helm job has failed and the failure policy is set to `abort`. | | |
179+
180+
181+
#### SecretSpec
182+
183+
184+
185+
SecretSpec describes a key in a secret to load chart values from.
186+
187+
188+
189+
_Appears in:_
190+
- [HelmChartConfigSpec](#helmchartconfigspec)
191+
- [HelmChartSpec](#helmchartspec)
192+
193+
| Field | Description | Default | Validation |
194+
| --- | --- | --- | --- |
195+
| `name` _string_ | Name of the secret. Must be in the same namespace as the HelmChart resource. | | |
196+
| `keys` _string array_ | Keys to read values content from. If no keys are specified, the secret is not used. | | |
197+
| `ignoreUpdates` _boolean_ | Ignore changes to the secret, and mark the secret as optional.<br />By default, the secret must exist, and changes to the secret will trigger an upgrade of the chart to apply the updated values.<br />If `ignoreUpdates` is true, the secret is optional, and changes to the secret will not trigger an upgrade of the chart. | | |
198+
199+

‎generate.go

Lines changed: 0 additions & 4 deletions
This file was deleted.

‎hack/crdgen.go

Lines changed: 0 additions & 13 deletions
This file was deleted.

‎main.go

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,9 @@
1+
//go:generate go run pkg/codegen/cleanup/main.go
2+
//go:generate rm -rf pkg/generated pkg/crds/yaml/generated
3+
//go:generate go run pkg/codegen/main.go
4+
//go:generate controller-gen crd:generateEmbeddedObjectMeta=true paths=./pkg/apis/... output:crd:dir=./pkg/crds/yaml/generated
5+
//go:generate crd-ref-docs --config=crd-ref-docs.yaml --renderer=markdown --output-path=doc/helmchart.md
6+
17
package main
28

39
import (

0 commit comments

Comments
 (0)