diff --git a/docs/basics/helm.md b/docs/basics/helm.md index ad809478cd..0585177978 100644 --- a/docs/basics/helm.md +++ b/docs/basics/helm.md @@ -3,9 +3,9 @@ You can use the `Helm` construct in order to include [Helm](https://helm.sh) charts. -In order to use this construct, you must have `helm` installed on your system. -See [Installing Helm](https://helm.sh/docs/intro/install/) in the Helm -documentation for details. +!!! note + You will need helm to be [installed](https://helm.sh/docs/intro/install/) locally for this feature. + For accessing private helm repositories, you must be authenticated to the repository in a way that the `helm pull` command recognizes. The following example adds the [bitnami/redis](https://github.com/bitnami/charts/tree/master/bitnami/redis) diff --git a/docs/cli/import.md b/docs/cli/import.md index 544da77f80..8d8d62e4f5 100644 --- a/docs/cli/import.md +++ b/docs/cli/import.md @@ -73,7 +73,8 @@ imports. You could use them in this fashion: The `import` command supports two types of imports: 1. `k8s`: generates constructs from the core Kubernetes API -2. CRDs: generates constructs from custom resource definitions +2. `CRDs`: generates constructs from custom resource definitions +3. `Helm Charts`: generates constructs from helm charts. This section describes specific behavior related to each type of import. @@ -152,3 +153,144 @@ kubectl get crds -o json | cdk8s import /dev/stdin ``` > Yes, this works! + +### Helm Charts + +You can import a helm chart and code generate a dedicated construct for it. To do this, pass either a url +or a local path to the helm chart. For example, running the following command would code +generate [bitnami's mysql](https://github.com/bitnami/charts/tree/main/bitnami/mysql) helm chart: + +``` +cdk8s import helm:https://charts.bitnami.com/bitnami/mysql@9.10.10 +``` + +> The format for the helm chart url is: `helm:/@`. + +You can use this generated construct in your cdk8s application, + +```typescript +import { Construct } from 'constructs'; +import { App, Chart, ChartProps } from 'cdk8s'; +import { Mysql, MysqlArchitecture } from './imports/mysql'; + +export class MyChart extends Chart { + constructor(scope: Construct, id: string, props: ChartProps = { }) { + super(scope, id, props); + + new Mysql(this, 'MySql', { + values: { + architecture: MysqlArchitecture.STANDALONE, // <------- type safe property + } + }); + } +} + +const app = new App(); +new MyChart(app, 'Typescript-App'); +app.synth(); +``` + +!!! note + You would need `helm` to be installed on your machine for using this feature. + For accessing private helm repositories, you must be authenticated to the repository in a way that the `helm pull` command recognizes. + + This feature is an extension to [helm](../basics/helm.md) support in cdk8s and you will find similar properties of Helm construct in these generated constructs. + +#### Values Schema + +If the helm chart that you are importing contains a schema file (`values.schema.json`) within it, +then the `values` property of the construct properties will be typed according to that schema. + +For example: + +```typescript +import { Construct } from 'constructs'; +import { App, Chart, ChartProps } from 'cdk8s'; +import { Mysql, MysqlArchitecture } from './imports/mysql'; + +export class MyChart extends Chart { + constructor(scope: Construct, id: string, props: ChartProps = { }) { + super(scope, id, props); + + new Mysql(this, 'MySql', { + values: { + architecture: 'foo', // <------- This will give an error since this is not `MysqlArchitecture` type which is generated from Schema + } + }); + } +} + +const app = new App(); +new MyChart(app, 'Typescript-App'); +app.synth(); +``` + +If there is no schema present in the helm chart, then `values` will not have type support and you can pass in any values. + +#### Additional Values and Globals + +The generated construct's `values` property will also include following special properties: + +* `additionalValues`: If the imported helm chart has a schema but that schema does not cover all values accepted by the chart, then you can use this property to pass in those values to the chart. +* `global`: This property can be used to set global values. For more information, see [here](https://helm.sh/docs/chart_template_guide/subcharts_and_globals/#global-chart-values). + +For example: + +```typescript +import { Construct } from 'constructs'; +import { App, Chart, ChartProps } from 'cdk8s'; +import { Mysql, MysqlArchitecture } from './imports/mysql'; + +export class MyChart extends Chart { + constructor(scope: Construct, id: string, props: ChartProps = { }) { + super(scope, id, props); + + new Mysql(this, 'MySql', { + values: { + architecture: MysqlArchitecture.STANDALONE, + global: { // <------- global values + imageRegistry: 'bar', + }, + additionalValues: { // <------- values missing in schema which are not code generated + nameOverride: "baz" + }, + } + }); + } +} + +const app = new App(); +new MyChart(app, 'Typescript-App'); +app.synth(); +``` + +#### Dependencies + +If the imported helm chart has any dependencies mentioned in `Chart.yaml`, then you will find those as properties in the generated construct. You can use those to pass in values to the dependency. + +```typescript +import { Construct } from 'constructs'; +import { App, Chart, ChartProps } from 'cdk8s'; +import { Mysql, MysqlArchitecture } from './imports/mysql'; + +export class MyChart extends Chart { + constructor(scope: Construct, id: string, props: ChartProps = { }) { + super(scope, id, props); + + new Mysql(this, 'MySql', { + values: { + architecture: MysqlArchitecture.STANDALONE, + common: { // <------- `common` is a dependency for the MySql helm chart + names: { + namespace: 'foo', + } + }, + } + }); + } +} + +const app = new App(); +new MyChart(app, 'Typescript-App'); +app.synth(); +```