using-kustomize.md

Get started using Kustomize

🛑 Upgrade Advisory

This documentation is for Helm Operator (v1) which has reached its end-of-life in November 2022.

We strongly recommend you familiarise yourself with the newest Flux and migrate as soon as possible.

For documentation regarding the latest Flux, please refer to this section.

This guide walks you through setting up the Helm Operator using Kustomize.

Prerequisites

• Kubernetes cluster >=1.13.0
• kustomize >=3.2.0
• Some knowledge of Kustomize
• (Optional) Tiller (secure setup)

Prepare the manifests for installation

Create a directory called helm-operator:

mkdir helm-operator

Create a kustomization.yaml file and use the Helm Operator deployment YAMLs as a base:

cat > helm-operator/kustomization.yaml <<EOF
bases:
- github.com/fluxcd/helm-operator//deploy
patchesJSON6902:
- target:
    group: apps
    version: v1
    kind: Deployment
    name: helm-operator
    namespace: flux
  patch: |-
    - op: replace
      path: /spec/template/spec/containers/0/args
      value:
        - --enabled-helm-versions=v3
EOF

The patchesJSON6902 target ensures only support for Helm 3 is enabled, to also enable support for Helm 2 and connect to Tiller, continue to read Helm 2 below.

{{% alert color="info" title="Tip" %}} If you want to install a specific Helm Operator release, add the version number to the base URL:

bases:
  - github.com/fluxcd/helm-operator//deploy?ref=1.4.4

{{% /alert %}}

Helm 2

To also enable support for Helm 2 and configure the Tiller settings, we need to make slight adjustment to the patchesJSON6902 target.

First, make sure your Tiller installation is secure, and add a secretGenerator entry of type kubernetes.io/tls for the client certificates:

# helm-operator/kustomization.yaml
namespace: flux   # ensures secret is generated in the right namespace
bases:
- github.com/fluxcd/helm-operator//deploy
secretGenerator:
- name: tiller-tls-cert
  type: kubernetes.io/tls
  files:
  - tls.crt
  - tls.key
patchesJSON6902:
...

Create a patch file for the Helm Operator to mount the tiller-tls-cert secret:

cat > helm-operator/patch-tiller-tls.yaml <<EOF
apiVersion: apps/v1
kind: Deployment
metadata:
  name: helm-operator
  namespace: flux
spec:
  template:
    spec:
      volumes:
        - name: tiller-tls-cert
          secret:
            secretName: tiller-tls-cert
            defaultMode: 0400
      containers:
        - name: helm-operator
          volumeMounts:
          - name: tiller-tls-cert
            mountPath: /etc/fluxd/helm
            readOnly: true
EOF

Adapt your kustomization.yaml to include the patch:

# helm-operator/kustomization.yaml
...
patchesStrategicMerge:
- patch-tiller-tls.yaml

Add (or replace) v2 to --enabled-helm-versions and configure the required Tiller option flags for your setup:

# helm-operator/kustomization.yaml
...
patchesJSON6902:
- target:
    group: apps
    version: v1
    kind: Deployment
    name: helm-operator
    namespace: flux
  patch: |-
    - op: replace
      path: /spec/template/spec/containers/0/args
      value:
        - --enabled-helm-versions=v2,v3     # enables Helm 2
        - --tiller-namespace=kube-system    # defines the Tiller namespace
        - --tiller-tls-enable=true          # enables TLS communication with Tiller
...

Install the Helm Operator using Kustomize

Deploy the Helm Operator to the cluster by applying the helm-operator folder with the kustomization.yaml file in it onto the cluster:

kustomize build helm-operator | kubectl apply -f -

Confirm the Helm Operator deployed successfully to the default flux namespace:

kubectl -n flux rollout status deployment/helm-operator

Customize the Helm Operator deployment

Configure a namespace

By default the Helm Operator is installed in the flux namespace when making use of the published deployment YAMLs as a base. It is possible to override this default namespace by creating a custom namespace definition and configuring a namespace in your kustomization.yaml file.

Create a custom namespace definition, this example uses team-ns:

cat > helm-operator/namespace.yaml <<EOF
apiVersion: v1
kind: Namespace
metadata:
  name: team-ns
EOF

Create a patch to remove the default namespace from the base:

cat > helm-operator/patch-default-ns.yaml <<EOF
apiVersion: v1
kind: Namespace
metadata:
  name: flux
\$patch: delete
EOF

Adapt your kustomization.yaml file to to include your own namespace resource and the patch file, and define the namespace:

# helm-operator/kustomization.yaml
namespace: team-ns
resources:
- namespace.yaml
bases:
- github.com/fluxcd/helm-operator//deploy
patchesJSON6902:
- target:
    group: apps
    version: v1
    kind: Deployment
    name: helm-operator
    namespace: flux
  patch: |-
    - op: replace
      path: /spec/template/spec/containers/0/args
      value:
        - --enabled-helm-versions=v3
patchesStrategicMerge:
- patch-default-ns.yaml

Apply the helm-operator folder with the kustomization.yaml file in it onto the cluster:

kubectl apply -k helm-operator

Confirm the Helm Operator deployed successfully to the teamn-ns namespace:

kubectl -n team-ns rollout status deployment/helm-operator

Provide Helm repository credentials

To mount a custom repositories.yaml file to e.g. provide credentials to a Helm chart repository as described in the HelmRelease guide, you can instruct Kustomize to create a secret from the repositories.yaml file.

First, create the repositores.yaml file with the credentials:

cat > helm-operator/repositories.yaml <<EOF
apiVersion: ""
generated: "0001-01-01T00:00:00Z"
repositories:
- caFile: ""
  certFile: ""
  keyFile: ""
  name: private-repository
  url: https://charts.example.com
  password: john
  username: s3cr3t!
EOF

Create a patch file for the Helm Operator to mount the flux-helm-repositories secret:

cat > helm-operator/patch-repositories-mount.yaml <<EOF
apiVersion: apps/v1
kind: Deployment
metadata:
  name: helm-operator
  namespace: flux
spec:
  template:
    spec:
      volumes:
        - name: repositories-yaml
          secret:
            secretName: flux-helm-repositories
            defaultMode: 0400
      containers:
        - name: helm-operator
          volumeMounts:
            - name: repositories-yaml
              mountPath: /root/.helm/repository/repositories.yaml
              readOnly: true
EOF

Adapt the kustomization.yaml file to instruct it to generate the secret and apply the patch file:

# helm-operator/kustomization.yaml
namespace: flux         # ensures secret is generated in the right namespace                            
bases:
 - github.com/fluxcd/helm-operator//deploy
patchesJSON6902:
- target:
    group: apps
    version: v1
    kind: Deployment
    name: helm-operator
    namespace: flux
  patch: |-
    - op: replace
      path: /spec/template/spec/containers/0/args
      value:
        - --enabled-helm-versions=v3
secretGenerator:
- name: flux-helm-repositories
  files:
  - repositories.yaml
patchesStrategicMerge:
- patch-repositories-mount.yaml

Apply the helm-operator folder with the kustomization.yaml file in it onto the cluster:

kustomize build helm-operator | kubectl apply -f -

Next

• Learn all about the available configuration options in the operator reference.
• Continue learning about HelmRelease resources in the guide.