Add more details in helmchart spec doc
Details about the source reference, reconcile strategy and artifact revision value based on the reconcile strategy. Signed-off-by: Sunny <darkowlzz@protonmail.com>
This commit is contained in:
Sunny
parent
1e37d00a30
commit
bf694e1194
|
|
@ -472,8 +472,9 @@ func (r *HelmChartReconciler) buildFromHelmRepository(ctx context.Context, obj *
|
||||||
return sreconcile.ResultSuccess, nil
|
return sreconcile.ResultSuccess, nil
|
||||||
}
|
}
|
||||||
|
|
||||||
// buildFromHelmRepository attempts to pull and/or package a Helm chart with
|
// buildFromTarballArtifact attempts to pull and/or package a Helm chart with
|
||||||
// the specified data v1beta2.HelmChart object and the given v1beta2.Artifact.
|
// the specified data from the v1beta2.HelmChart object and the given
|
||||||
|
// v1beta2.Artifact.
|
||||||
// In case of a failure it records v1beta2.FetchFailedCondition on the chart
|
// In case of a failure it records v1beta2.FetchFailedCondition on the chart
|
||||||
// object, and returns early.
|
// object, and returns early.
|
||||||
func (r *HelmChartReconciler) buildFromTarballArtifact(ctx context.Context, obj *sourcev1.HelmChart, source sourcev1.Artifact, b *chart.Build) (sreconcile.Result, error) {
|
func (r *HelmChartReconciler) buildFromTarballArtifact(ctx context.Context, obj *sourcev1.HelmChart, source sourcev1.Artifact, b *chart.Build) (sreconcile.Result, error) {
|
||||||
|
|
|
||||||
|
|
@ -97,6 +97,120 @@ As with all other Kubernetes config, a HelmChart needs `apiVersion`, `kind`, and
|
||||||
A HelmChart also needs a
|
A HelmChart also needs a
|
||||||
[`.spec` section](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#spec-and-status).
|
[`.spec` section](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/api-conventions.md#spec-and-status).
|
||||||
|
|
||||||
|
### Source reference
|
||||||
|
|
||||||
|
`.spec.sourceRef` is a required field that specifies a reference to the Source
|
||||||
|
the chart is available at.
|
||||||
|
|
||||||
|
Supported references are:
|
||||||
|
- [`HelmRepository`](helmrepositories.md)
|
||||||
|
- [`GitRepository`](gitrepositories.md)
|
||||||
|
- [`Bucket`](buckets.md)
|
||||||
|
|
||||||
|
Although there are three kinds of source references, there are only two
|
||||||
|
underlying implementations. The artifact building process for `GitRepository`
|
||||||
|
and `Bucket` are the same as they are already built source artifacts. In case
|
||||||
|
of `HelmRepository`, a chart is fetched and/or packaged based on the
|
||||||
|
configuration of the Helm chart.
|
||||||
|
|
||||||
|
For a `HelmChart` to be reconciled, the associated artifact in the source
|
||||||
|
reference must be ready. If the source artifact is not ready, the `HelmChart`
|
||||||
|
reconciliation is retried.
|
||||||
|
|
||||||
|
When the `metadata.generation` of the `HelmChart` don't match with the
|
||||||
|
`status.observedGeneration`, the chart is fetched from source and/or packaged.
|
||||||
|
If there's no `.spec.valuesFiles` specified, the chart is only fetched from the
|
||||||
|
source, and not packaged. If `.spec.valuesFiles` are specified, the chart is
|
||||||
|
fetched and packaged with the values files. When the `metadata.generation`
|
||||||
|
matches the `status.observedGeneration`, the chart is only fetched from source
|
||||||
|
or from the cache if available, and not packaged.
|
||||||
|
|
||||||
|
When using a `HelmRepository` source reference, the secret reference defined in
|
||||||
|
the Helm repository is used to fetch the chart.
|
||||||
|
|
||||||
|
The HelmChart reconciliation behavior varies depending on the source reference
|
||||||
|
kind, see [reconcile strategy](#reconcile-strategy).
|
||||||
|
|
||||||
|
The attributes of the generated artifact also varies depending on the source
|
||||||
|
reference kind, see [artifact](#artifact).
|
||||||
|
|
||||||
|
### Chart
|
||||||
|
|
||||||
|
`.spec.chart` is a required field that specifies the name or path the Helm chart
|
||||||
|
is available at in the [Source reference](#source-reference).
|
||||||
|
|
||||||
|
For `HelmRepository` Source reference, it'll be just the name of the chart.
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
spec:
|
||||||
|
chart: podinfo
|
||||||
|
sourceRef:
|
||||||
|
name: podinfo
|
||||||
|
kind: HelmRepository
|
||||||
|
```
|
||||||
|
|
||||||
|
For `GitRepository` and `Bucket` Source reference, it'll be the path to the
|
||||||
|
Helm chart directory.
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
spec:
|
||||||
|
chart: ./charts/podinfo
|
||||||
|
sourceRef:
|
||||||
|
name: podinfo
|
||||||
|
kind: <GitRepository|Bucket>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Version
|
||||||
|
|
||||||
|
`.spec.version` is an optional field to specify the version of the chart in
|
||||||
|
semver. It is applicable only when the Source reference is a `HelmRepository`.
|
||||||
|
It is ignored for `GitRepository` and `Bucket` Source reference. It defaults to
|
||||||
|
the latest version of the chart with value `*`.
|
||||||
|
|
||||||
|
Version can be a fixed semver, minor or patch semver range of a specific
|
||||||
|
version (i.e. `4.0.x`) or any semver range (i.e. `>=4.0.0 <5.0.0`).
|
||||||
|
|
||||||
|
### Values files
|
||||||
|
|
||||||
|
`.spec.valuesFiles` is an optional field to specify an alternative list of
|
||||||
|
values files to use as the chart values (values.yaml). The file paths are
|
||||||
|
expected to be relative to the Source reference. Values files are merged in the
|
||||||
|
order of the list with the last file overriding the first. It is ignored when
|
||||||
|
omitted. When values files are specified, the chart is fetched and packaged
|
||||||
|
with the provided values.
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
spec:
|
||||||
|
chart:
|
||||||
|
spec:
|
||||||
|
chart: podinfo
|
||||||
|
...
|
||||||
|
valuesFiles:
|
||||||
|
- values.yaml
|
||||||
|
- values-production.yaml
|
||||||
|
```
|
||||||
|
|
||||||
|
Values files also affect the generated artifact revision, see
|
||||||
|
[artifact](#artifact).
|
||||||
|
|
||||||
|
### Reconcile strategy
|
||||||
|
|
||||||
|
`.spec.reconcileStrategy` is an optional field to specify what enables the
|
||||||
|
creation of a new Artifact. Valid values are `ChartVersion` and `Revision`.
|
||||||
|
`ChartVersion` is used for creating a new artifact when the chart version
|
||||||
|
changes in a `HelmRepository`. `Revision` is used for creating a new artifact
|
||||||
|
when the source revision changes in a `GitRepository` or a `Bucket` Source. It
|
||||||
|
defaults to `ChartVersion`.
|
||||||
|
|
||||||
|
**NOTE:** If the reconcile strategy is `ChartVersion` and the source reference
|
||||||
|
is a `GitRepository` or a `Bucket`, no new chart artifact is produced on updates
|
||||||
|
to the source unless the `version` in `Chart.yaml` is incremented. To produce
|
||||||
|
new chart artifact on change in source revision, set the reconcile strategy to
|
||||||
|
`Revision`.
|
||||||
|
|
||||||
|
Reconcile strategy also affects the artifact version, see [artifact](#artifact)
|
||||||
|
for more details.
|
||||||
|
|
||||||
### Interval
|
### Interval
|
||||||
|
|
||||||
`.spec.interval` is a required field that specifies the interval at which the
|
`.spec.interval` is a required field that specifies the interval at which the
|
||||||
|
|
@ -110,44 +224,6 @@ e.g. `10m0s` to look at the source for updates every 10 minutes.
|
||||||
If the `.metadata.generation` of a resource changes (due to e.g. applying a
|
If the `.metadata.generation` of a resource changes (due to e.g. applying a
|
||||||
change to the spec), this is handled instantly outside the interval window.
|
change to the spec), this is handled instantly outside the interval window.
|
||||||
|
|
||||||
### Source reference
|
|
||||||
|
|
||||||
`.spec.sourceRef` is a required field that specifies a reference to the Source
|
|
||||||
the chart is available at. `.spec.sourceRef.kind` must be one of
|
|
||||||
`HelmRepository`, `GitRepository` or `Bucket`. `.spec.sourceRef.name` is the
|
|
||||||
name of the referred kind.
|
|
||||||
|
|
||||||
### Chart
|
|
||||||
|
|
||||||
`.spec.chart` is a required field that specifies the name or path the Helm chart
|
|
||||||
is available at in the [Source reference](#source-reference). For HelmRepository
|
|
||||||
Source reference, it'll be just the name of the chart. For GitRepository and
|
|
||||||
Bucket Source reference, it'll be the path to the Helm chart directory.
|
|
||||||
|
|
||||||
### Version
|
|
||||||
|
|
||||||
`.spec.version` is an optional field to specify the version of the chart in
|
|
||||||
semver. It is applicable only when the Source reference is a HelmRepository. It
|
|
||||||
is ignored for GitRepository and Bucket Source reference. It defaults to the
|
|
||||||
latest version of the chart with value `*`.
|
|
||||||
|
|
||||||
### Values files
|
|
||||||
|
|
||||||
`.spec.valuesFiles` is an optional field to specify an alternative list of
|
|
||||||
values files to use as the chart values (values.yaml). The file paths are
|
|
||||||
expected to be relative to the Source reference. Values files are merged in the
|
|
||||||
order of the list with the last file overriding the first. It is ignored when
|
|
||||||
omitted.
|
|
||||||
|
|
||||||
### Reconcile strategy
|
|
||||||
|
|
||||||
`.spec.reconcileStrategy` is an optional field to specify what enables the
|
|
||||||
creation of a new Artifact. Valid values are `ChartVersion` and `Revision`.
|
|
||||||
`ChartVersion` is used for creating a new artifact when the chart version
|
|
||||||
changes in the HelmRepository. `Revision` is used for creating a new artifact
|
|
||||||
when the source revision changes in GitRepository or Bucket Source references.
|
|
||||||
It defaults to `ChartVersion`.
|
|
||||||
|
|
||||||
### Suspend
|
### Suspend
|
||||||
|
|
||||||
`.spec.suspend` is an optional field to suspend the reconciliation of a
|
`.spec.suspend` is an optional field to suspend the reconciliation of a
|
||||||
|
|
@ -317,7 +393,7 @@ The HelmChart reports the last built chart as an Artifact object in the
|
||||||
The Artifact file is a gzip compressed TAR archive (`<chart-name>-<chart-version>.tgz`),
|
The Artifact file is a gzip compressed TAR archive (`<chart-name>-<chart-version>.tgz`),
|
||||||
and can be retrieved in-cluster from the `.status.artifact.url` HTTP address.
|
and can be retrieved in-cluster from the `.status.artifact.url` HTTP address.
|
||||||
|
|
||||||
### Artifact example
|
#### Artifact example
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
---
|
---
|
||||||
|
|
@ -334,6 +410,51 @@ status:
|
||||||
url: http://source-controller.flux-system.svc.cluster.local./helmchart/<source-namespace>/<chart-name>/<chart-name>-<chart-version>.tgz
|
url: http://source-controller.flux-system.svc.cluster.local./helmchart/<source-namespace>/<chart-name>/<chart-name>-<chart-version>.tgz
|
||||||
```
|
```
|
||||||
|
|
||||||
|
When using a `HelmRepository` as the source reference and values files are
|
||||||
|
provided, the value of `status.artifact.revision` is the chart version combined
|
||||||
|
with the `HelmChart` object generation. For example, if the chart version is
|
||||||
|
`6.0.3` and the `HelmChart` object generation is `1`, the
|
||||||
|
`status.artifact.revision` value will be `6.0.3+1`.
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
---
|
||||||
|
apiVersion: source.toolkit.fluxcd.io/v1beta2
|
||||||
|
kind: HelmChart
|
||||||
|
metadata:
|
||||||
|
name: <chart-name>
|
||||||
|
status:
|
||||||
|
artifact:
|
||||||
|
checksum: ee68224ded207ebb18a8e9730cf3313fa6bc1f31e6d8d3943ab541113559bb52
|
||||||
|
lastUpdateTime: "2022-02-28T08:07:12Z"
|
||||||
|
path: helmchart/<source-namespace>/<chart-name>/<chart-name>-6.0.3+1.tgz
|
||||||
|
revision: 6.0.3+1
|
||||||
|
url: http://source-controller.flux-system.svc.cluster.local./helmchart/<source-namespace>/<chart-name>/<chart-name>-6.0.3+1.tgz
|
||||||
|
observedGeneration: 1
|
||||||
|
...
|
||||||
|
```
|
||||||
|
|
||||||
|
When using a `GitRepository` or a `Bucket` as the source reference and
|
||||||
|
`Revision` as the reconcile strategy, the value of `status.artifact.revision` is
|
||||||
|
the chart version combined with the first 12 characters of the revision of the
|
||||||
|
`GitRepository` or `Bucket`. For example if the chart version is `6.0.3` and the
|
||||||
|
revision of the `Bucket` is `4e5cbb7b97d00a8039b8810b90b922f4256fd3bd8f78b934b4892dae13f7ca87`,
|
||||||
|
the `status.artifact.revision` value will be `6.0.3+4e5cbb7b97d0`.
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
---
|
||||||
|
apiVersion: source.toolkit.fluxcd.io/v1beta2
|
||||||
|
kind: HelmChart
|
||||||
|
metadata:
|
||||||
|
name: <chart-name>
|
||||||
|
status:
|
||||||
|
artifact:
|
||||||
|
checksum: 8d1f0ac3f4b0e8759a32180086f17ac87ca04e5d46c356e67f97e97616ef4718
|
||||||
|
lastUpdateTime: "2022-02-28T08:07:12Z"
|
||||||
|
path: helmchart/<source-namespace>/<chart-name>/<chart-name>-6.0.3+4e5cbb7b97d0.tgz
|
||||||
|
revision: 6.0.3+4e5cbb7b97d0
|
||||||
|
url: http://source-controller.flux-system.svc.cluster.local./helmchart/<source-namespace>/<chart-name>/<chart-name>-6.0.3+4e5cbb7b97d0.tgz
|
||||||
|
```
|
||||||
|
|
||||||
### Conditions
|
### Conditions
|
||||||
|
|
||||||
A HelmChart enters various states during its lifecycle, reflected as [Kubernetes
|
A HelmChart enters various states during its lifecycle, reflected as [Kubernetes
|
||||||
|
|
@ -451,15 +572,18 @@ the spec is made.
|
||||||
|
|
||||||
### Observed Source Artifact Revision
|
### Observed Source Artifact Revision
|
||||||
|
|
||||||
The source-controller reports the revision of the
|
The source-controller reports the revision of the last
|
||||||
[Source reference's](#source-reference) Artifact the current chart was fetched
|
[Source reference's](#source-reference) Artifact the current chart was fetched
|
||||||
from in the HelmChart's `.status.observedSourceArtifactRevision`.
|
from in the HelmChart's `.status.observedSourceArtifactRevision`. It is used to
|
||||||
|
keep track of the source artifact revision and detect when a new source
|
||||||
|
artifact is available.
|
||||||
|
|
||||||
### Observed Chart Name
|
### Observed Chart Name
|
||||||
|
|
||||||
The source-controller reports the resolved chart name of the current Artifact
|
The source-controller reports the last resolved chart name of the Artifact
|
||||||
for the [`.spec.chart` field](#chart) in the HelmChart's
|
for the [`.spec.chart` field](#chart) in the HelmChart's
|
||||||
`.status.observedChartName`.
|
`.status.observedChartName`. It is used to keep track of the chart and detect
|
||||||
|
when a new chart is found.
|
||||||
|
|
||||||
### Observed Generation
|
### Observed Generation
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue