Konvert

konvert renders Helm charts into Kustomize bases (or plain Kubernetes manifests).

konvert allows you to take advantage of the Helm chart ecosystem while:

• Expanding your ability to customize and configure your deployments in ways not supported by the underlying Helm chart
• Unifying your GitOps pipelines with plain Kubernetes manifests (instead of a hybrid mix of Helm charts and manifests)
• Facilitating maintainable and easily upgradable packages of deployment manifests

konvert is similar to the builtin Kustomize HelmChartInflationGenerator generator or the Kpt render-helm-chart function but with additional capabilities.

Features

• Render Helm charts to Kustomize bases
• Render Helm charts to plain Kubernetes manifests
• Set a namespace for all resources
• Render a chart into sub-directories
• Configured declaratively
• Enable easy configuration changes or upgrades, especially when used in conjunction with git
• Run as a standalone binary, docker image, or as a KRM function via Kpt

Usage

We will use the following konvert configuration for cert-manager in the following examples.

mkdir cert-manager

cat << EOF > cert-manager/konvert.yaml
apiVersion: konvert.kumorilabs.io/v1alpha1
kind: Konvert
metadata:
  name: cert-manager
  annotations:
    config.kubernetes.io/local-config: "true"
spec:
  kustomize: true
  repo: https://charts.jetstack.io
  chart: cert-manager
  version: v1.6.1
  namespace: cert-manager
  path: upstream
  values:
    installCRDs: true
    global:
      leaderElection:
        namespace: cert-manager
EOF

All of the examples below (except the Kustomize generator plugin) will produce the same result: the Helm chart with the specified configuration rendered to your local disk. You can use git to manage these manifests and use standard Kustomize to further modify them for your environments without worrying about changing the upstream source. Upgrading the chart is as simple as changing the version in the configuration and running konvert again. Since the manifests exist in your source code repository, reconciling upstream changes is easily accomplished with a pure git workflow.

The Kustomize generator plugin behaves slightly differently as the chart will render when running kustomize build and will not persist to disk.

• Binary
• Kpt Function
• Container Image
• Kustomize Generator Plugin

Binary

konvert -f cert-manager

Kpt Function

Because kpt currently does not allow network access when executing functions declaratively, you must use kpt fn eval if you are rendering a chart from a remote repository.

kpt fn eval cert-manager --image ghcr.io/kumorilabs/krm-fn-konvert:latest --network --fn-config cert-manager/konvert.yaml

If you don't wish to use the container image, you can also execute the konvert function using the binary.

kpt fn eval cert-manager --exec "konvert fn" --fn-config cert-manager/konvert.yaml

Container Image

Using docker:

docker run --rm -it -v "$(pwd)":/src ghcr.io/kumorilabs/konvert:latest -f src/cert-manager

Kustomize Generator Plugin

Using konvert in a Kustomize generator does require a small configuration change. We need to annotate the Konvert file to specify how to run the function. Add the following to the metadata section of the cert-manager Konvert file:

annotations:
  config.kubernetes.io/function: |
    container:
      network: true
      image: ghcr.io/kumorilabs/krm-fn-konvert:latest

You also need a kustomization.yaml that specifies the generator configuration.

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
metadata:
  name: kustomization
generators:
  - konvert.yaml

Finally, to render the chart with konvert, run:

kustomize build cert-manager

Environment Variables

konvert supports the following environment variables:

Variable	Description
KONVERT_FORCE_STANDALONE	When set (to any value), forces konvert to run in standalone mode even when stdin is not a TTY. Useful for automation, CI/CD pipelines, and tools that don't provide a TTY. Example: KONVERT_FORCE_STANDALONE= konvert -f cert-manager

Konvert schema

konvert uses a client-side KRM resource to configure how to find and render a Helm chart.

Example:

apiVersion: konvert.kumorilabs.io/v1alpha1
kind: Konvert
metadata:
  name: mysql
spec:
  repo: https://charts.bitnami.com/bitnami
  chart: mysql
  version: 8.6.2
  namespace: mysql
  kustomize: true
  values:
    auth:
      username: admin
      password: password
      rootPassword: password

Field	Description
apiVersion	konvert.kumorilabs.io/v1alpha1
kind	Konvert
metadata
name	The release name used when rendering the Helm chart.
spec
repo	The URL for the Helm chart repository.
chart	The name of the chart.
version	The version of the chart.
namespace	The namespace to use when rendering the chart. When kustomize is true, this will also configure the Kustomize namespace transformer.
path	The path (relative to the Konvert file) in which to render the chart.
kustomize	If true, konvert will write a kustomization.yaml for the generated chart resources. If path is configured, it will write a kustomization.yaml including the rendered chart subdirectory at the same level as the Konvert file.
values	The configuration values to use when rendering the chart.
skipHooks	If true, konvert will not render Helm hook resources.
skipTests	If true, konvert will not render Helm test resources.
skipCRDs	If true, konvert will not render CustomResourceDefinitions (CRDs).
kubeVersion	The Kubernetes version to use when rendering the chart. This allows templates to conditionally render based on the target Kubernetes version.
apiVersions	A list of Kubernetes API versions to make available during rendering. This allows templates to conditionally render resources based on available APIs (e.g., monitoring.coreos.com/v1/ServiceMonitor).

Contributing

Build

make build

Install

make install

Run Tests

make test