Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update HelmRelease documentation #389

Merged
merged 1 commit into from
Oct 29, 2020
Merged

Update HelmRelease documentation #389

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 1 addition & 2 deletions docs/faq/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,14 +55,13 @@ Support for custom commands and generators executed by fluxd in a POSIX shell |

Flux v1 | Toolkit component driven "Flux v2"
---------------------------------- | ----------------------------------
Declarative config in a single Helm custom resource | Declarative config through `HelmRepository`, `GitRepository`, `HelmChart` and `HelmRelease` custom resources
Declarative config in a single Helm custom resource | Declarative config through `HelmRepository`, `GitRepository`, `Bucket`, `HelmChart` and `HelmRelease` custom resources
Chart synchronisation embedded in the operator | Extensive release configuration options, and a reconciliation interval per source
Support for fixed SemVer versions from Helm repositories | Support for SemVer ranges for `HelmChart` resources
Git repository synchronisation on a global interval | Planned support for charts from GitRepository sources
Limited observability via the status object of the HelmRelease resource | Better observability via the HelmRelease status object, Kubernetes events, and notifications
Resource heavy, relatively slow | Better performance
Chart changes from Git sources are determined from Git metadata | Chart changes must be accompanied by a version bump in `Chart.yaml` to produce a new artifact
Chart dependencies for charts from Git sources are downloaded by the operator | Chart dependencies must be committed to Git

#### Notifications, webhooks, observability

Expand Down
92 changes: 68 additions & 24 deletions docs/guides/helmreleases.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ The [helm-controller](../components/helm/controller.md) allows you to
declaratively manage Helm chart releases with Kubernetes manifests.
It makes use of the artifacts produced by the
[source-controller](../components/source/controller.md) from
`HelmRepository`, `GitRepository`, and `HelmChart` resources.
`HelmRepository`, `GitRepository`, `Bucket` and `HelmChart` resources.
The helm-controller is part of the default toolkit installation.

## Prerequisites
Expand All @@ -17,8 +17,9 @@ or the [installation guide](installation.md).
## Define a chart source

To be able to release a Helm chart, the source that contains the chart
(either a `HelmRepository` or `GitRepository`) has to be known first to
the source-controller, so that the `HelmRelease` can reference to it.
(either a `HelmRepository`, `GitRepository`, or `Bucket`) has to be known
first to the source-controller, so that the `HelmRelease` can reference
to it.

A cluster administrator should register trusted sources by creating
the resources in the `gotk-system` namespace. By default, the
Expand Down Expand Up @@ -63,21 +64,16 @@ The `url` can be any HTTP/S Helm repository URL.
### Git repository

Charts from Git repositories can be released by declaring a
`GitRepository`, the source-controller will fetch the contents
of the repository on an interval and expose it as an artifact.
`GitRepository`, the source-controller will fetch the contents of the
repository on an interval and expose it as an artifact.

The source-controller can build and expose Helm charts as
artifacts from the contents of the `GitRepository` artifact
(more about this later on in the guide).
The source-controller can build and expose Helm charts as artifacts
from the contents of the `GitRepository` artifact (more about this
later on in the guide).

There are two caveats you should be aware of:

* To make the source-controller produce a new chart artifact,
the `version` in the `Chart.yaml` of the chart **must** be
bumped.
* Chart dependencies **must** be committed to Git, as the
source-controller does not attempt to download them. This
limitation may be removed in a future release.
**There is one caveat you should be aware of:** to make the
source-controller produce a new chart artifact, the `version` in the
`Chart.yaml` of the chart must be bumped.

An example `GitRepository`:

Expand Down Expand Up @@ -121,6 +117,52 @@ repository and omits all other files.
HTTP/S basic and SSH authentication can be configured for private
Git repositories. See the [`GitRepository` CRD docs](../components/source/gitrepositories.md)
for more details.

### Bucket

Charts from S3 compatible storage buckets can be released by declaring
a `Bucket`, the source-controller will fetch the contents of the bucket
on an interval and expose it as an artifact.

**There is one caveat you should be aware of:** to make the
source-controller produce a new chart artifact, the `version` in the
`Chart.yaml` of the chart must be bumped.

An example `Bucket`:

```yaml
apiVersion: source.toolkit.fluxcd.io/v1beta1
kind: Bucket
metadata:
name: podinfo
namespace: gotk-system
spec:
interval: 1m
provider: generic
bucketName: podinfo
endpoint: minio.minio.svc.cluster.local:9000
ignore: |
# exclude all
/*
# include charts directory
!/charts/
```

The `interval` defines at which interval the Git repository contents
are fetched, and should be at least `1m`. Setting this to a higher
value means newer chart versions will be detected at a slower pace,
a push-based fetch can be introduced using [webhook receivers](webhook-receivers.md)

The `provider`, `bucketName` and `endpoint` together define what
S3 compatible storage should be connected to. For more information,
see the [`Bucket` CRD docs](../components/source/buckets.md).


The `ignore` defines file and folder exclusion for the
artifact produced, and follows the [`.gitignore` pattern
format](https://git-scm.com/docs/gitignore#_pattern_format).
The above example only includes the `charts` directory of the
repository and omits all other files.

## Define a Helm release

Expand All @@ -140,7 +182,7 @@ spec:
chart: <name|path>
version: '4.0.x'
sourceRef:
kind: <HelmRepository|GitRepository>
kind: <HelmRepository|GitRepository|Bucket>
name: podinfo
namespace: gotk-system
interval: 1m
Expand All @@ -152,20 +194,22 @@ The `chart.spec` values are used by the helm-controller as a template
to create a new `HelmChart` resource in the same namespace as the
`sourceRef`. The source-controller will then lookup the chart in the
artifact of the referenced source, and either fetch the chart for a
`HelmRepository`, or build it from a `GitRepository`. It will then
make it available as a `HelmChart` artifact to be used by the
helm-controller.
`HelmRepository`, or build it from a `GitRepository` or `Bucket`.
It will then make it available as a `HelmChart` artifact to be used by
the helm-controller.

The `chart.spec.chart` can either contain:

* The name of the chart as made available by the `HelmRepository`
(without any aliases), for example: `podinfo`
* The relative path the chart can be found at in the `GitRepository`,
for example: `./charts/podinfo`
* The relative path the chart can be found at in the `GitRepository`
or `Bucket`, for example: `./charts/podinfo`
* The relative path the chart package can be found at in the
`GitRepository` or `Bucket`, for example: `./charts/podinfo-1.2.3.tgz`

The `chart.spec.version` can be a fixed semver, or any semver range
(i.e. `>=4.0.0 <5.0.0`). It is ignored for `HelmRelease` resources
that reference a `GitRepository` source.
(i.e. `>=4.0.0 <5.0.0`). It is only taken into account for `HelmRelease`
resources that reference a `HelmRepository` source.

!!! hint "Advanced configuration"
The `HelmRelease` offers an extensive set of configurable flags
Expand Down