diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 0000000..899b01d --- /dev/null +++ b/examples/README.md @@ -0,0 +1,4 @@ +# Examples + +* [Helm Generator](helm.md) +* [Jsonnet Generator](jsonnet.md) diff --git a/examples/helm.md b/examples/helm.md new file mode 100644 index 0000000..467e288 --- /dev/null +++ b/examples/helm.md @@ -0,0 +1,68 @@ +# Helm Generator + +The Helm Generator is used to generate manifests from a Helm chart, much like the [Kustomize chart example](https://github.com/kubernetes-sigs/kustomize/blob/master/examples/chart.md). + +## Prerequisites + +For this example, you will need Konjure, Kustomize, and Helm installed on your `PATH`. If you plan to use Konjure without Kustomize you can, however the Helm Generator requires the `helm` executable (you can specify an alternate location in your configuration if you like). + +```bash +which konjure +which kustomize +which helm +konjure kustomize init + +DEMO_HOME=$(mktemp -d) +mkdir -p "$DEMO_HOME" +``` + +## Configuration + +Create a configuration file for the Helm Generator, in this case we will generate manifests from the `stable/elasticsearch` chart, pinned to version 1.31.1. + +```bash +cat <<'EOF' >"$DEMO_HOME/elasticsearch.yaml" +apiVersion: konjure.carbonrelay.com/v1beta1 +kind: HelmGenerator +metadata: + name: currently-ignored-if-release-name-is-set + +releaseName: elasticsearch +chart: stable/elasticsearch +version: 1.31.1 +values: + - name: data.replicas + value: 3 +EOF +``` + +## Kustomize + +Create a kustomization the uses the Helm Generator configuration, for this example we are only including the resources generated by the Helm chart, however you can perform additional kustomizations on the resources if you like (though beware of using `commonLabels` on this example because this particular chart contains `apps/v1beta1` resources with implicit selectors!). + +```bash +cat <<'EOF' >"$DEMO_HOME/kustomization.yaml" +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization + +generators: + - elasticsearch.yaml +EOF +``` + +## Build + +Finally, build the manifests. Notice that there are no test hook pods present in the output as they are filtered out by default. + +```bash +kustomize build "$DEMO_HOME" --enable_alpha_plugins > "$DEMO_HOME/kustomized.yaml" +(! grep -q 'helm.sh/hook: test-success' "$DEMO_HOME/kustomized.yaml") +``` + +## Clean Up + +Remove your demo workspace: + +```bash +rm -rf "$DEMO_HOME" +``` \ No newline at end of file diff --git a/examples/jsonnet.md b/examples/jsonnet.md new file mode 100644 index 0000000..815bf5b --- /dev/null +++ b/examples/jsonnet.md @@ -0,0 +1,79 @@ +# Jsonnet Generator + +The Jsonnet Generator is used to run Jsonnet programs, this is useful when using projects that are built with Jsonnet. + +## Prerequisites + +For this example, you will need Konjure, Kustomize, and Jsonnet installed on your `PATH`. If you plan to use Konjure without Kustomize you can, however the Jsonnet Generator requires the `jsonnet` executable (you can specify an alternate location in your configuration if you like). + +```sh +which konjure +which kustomize +which jsonnet +konjure kustomize init + +DEMO_HOME=$(mktemp -d) +mkdir -p "$DEMO_HOME" +``` + +## Configuration + +Create a configuration file for the Jsonnet Generator, in this case we will generate an example NGINX manifest from a simple Jsonnet program specified in the configuration file itself. + +```bash +cat <<'EOF' >"$DEMO_HOME/nginx.yaml" +apiVersion: konjure.carbonrelay.com/v1beta1 +kind: JsonnetGenerator +metadata: + name: currently-ignored + +exec: | + local podName = "nginx-demo"; + local container = { + name: "nginx", + image: "nginx:1.7.9", + ports: [ { containerPort: 80 } ] + }; + + { + apiVersion: "v1", + kind: "Pod", + metadata: { + name: podName + }, + spec: { + containers: [ container ] + } + } +EOF +``` + +## Kustomize + +Create a kustomization the uses the Jsonnet Generator configuration, for this example we are only including the resources generated by the Jsonnet program, however you can perform additional kustomizations on the resources if you like. + +```bash +cat <<'EOF' >"$DEMO_HOME/kustomization.yaml" +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization + +generators: + - nginx.yaml +EOF +``` + +## Build + +Finally, build the manifests. Notice the output is already output as a YAML document stream. + +```bash +kustomize build "$DEMO_HOME" --enable_alpha_plugins +``` + +## Clean Up + +Remove your demo workspace: + +```bash +rm -rf "$DEMO_HOME" +``` \ No newline at end of file