Merge pull request #3097 from replicatedhq/repl-config-functions-examples

Add HelmChart examples to Config template func page

Author: paigecalvert

docs/partials/template-functions/_config-context.mdx

@@ -0,0 +1 @@
+Template functions in the config context are available when rendering an application that includes the KOTS [Config](/reference/custom-resource-config) custom resource, which defines the KOTS Admin Console config screen. At execution time, template functions in the config context also can use the static context functions. For more information about configuring the Admin Console config screen, see [About the Configuration Screen](/vendor/config-screen-about).

docs/partials/template-functions/_identity-context.mdx

@@ -0,0 +1,5 @@
+:::note
+The KOTS identity service feature is deprecated and is not available to new users.
+:::
+
+Template functions in the Identity context have access to Replicated KOTS identity service information.

docs/partials/template-functions/_kurl-context.mdx

@@ -0,0 +1 @@
+Template functions in the kURL context have access to information about applications installed with Replicated kURL. For more information about kURL, see [Introduction to kURL](/vendor/kurl-about).

docs/partials/template-functions/_license-context.mdx

@@ -0,0 +1 @@
+Template functions in the license context have access to customer license and version data. For more information about managing customer licenses, see [About Customers and Licensing](/vendor/licenses-about).

docs/partials/template-functions/_static-context.mdx

@@ -0,0 +1,3 @@
+The context necessary to render the static template functions is always available.
+
+The static context also includes the Masterminds Sprig function library. For more information, see [Sprig Function Documentation](http://masterminds.github.io/sprig/) on the sprig website.

docs/reference/template-functions-about.mdx

@@ -1,4 +1,10 @@
 import UseCases from "../partials/template-functions/_use-cases.mdx"
+import StaticContext from "../partials/template-functions/_static-context.mdx"
+import ConfigContext from "../partials/template-functions/_config-context.mdx"
+import LicenseContext from "../partials/template-functions/_license-context.mdx"
+import KurlContext from "../partials/template-functions/_kurl-context.mdx"
+import IdentityContext from "../partials/template-functions/_identity-context.mdx"
+import KurlAvailability from "../partials/kurl/_kurl-availability.mdx"
 
 # About Template Functions
 
@@ -126,33 +132,32 @@ KOTS template functions are grouped into different contexts, depending on the ph
 
 ### Static Context
 
-The context necessary to render the static template functions is always available.
+<StaticContext/>
 
-The static context also includes the Masterminds Sprig function library. For more information, see [Sprig Function Documentation](http://masterminds.github.io/sprig/) on the sprig website.
-
-For a list of all KOTS template functions available in the static context, see [Static context](template-functions-static-context).
+For a list of all KOTS template functions available in the static context, see [Static Context](template-functions-static-context).
 
 ### Config Context
 
-Template functions in the config context are available when rendering an application that includes a Config custom resource.
-At execution time, template functions in the config context also can use the static context functions.
+<ConfigContext/>
 
-For a list of all KOTS template functions available in the config context, see [Config context](template-functions-config-context).
+For a list of all KOTS template functions available in the config context, see [Config Context](template-functions-config-context).
 
 ### License Context
 
-Template functions in the license context have access to customer license and version data.
+<LicenseContext/>
 
-For a list of all KOTS template functions available in the license context, see [License context](template-functions-license-context).
+For a list of all KOTS template functions available in the license context, see [License Context](template-functions-license-context).
 
 ### kURL Context
 
-Template functions in the kURL context have access to information about applications installed in embedded clusters created by Replicated kURL.
+<KurlAvailability/>
+
+<KurlContext/>
 
-For a list of all KOTS template functions available in the kURL context, see [kURL context](template-functions-kurl-context).
+For a list of all KOTS template functions available in the kURL context, see [kURL Context](template-functions-kurl-context).
 
 ### Identity Context
 
-Template functions in the Identity context have access to Replicated identity service information.
+<IdentityContext/>
 
-For a list of all KOTS template functions available in the identity context, see [Identity context](template-functions-identity-context).
+For a list of all KOTS template functions available in the identity context, see [Identity Context](template-functions-identity-context).

docs/reference/template-functions-config-context.md

@@ -1,64 +1,82 @@
+import ConfigContext from "../partials/template-functions/_config-context.mdx"
+
 # Config Context
 
+<ConfigContext/>
+
 ## ConfigOption
 
 ```go
 func ConfigOption(optionName string) string
 ```
 
-Returns the value of the config option as a string.
+Returns the value of the specified option from the KOTS Config custom resource as a string.
 
-For information about the config screen and associated options, see [Config](custom-resource-config) in the _Custom Resources_ section.
+For the `file` config option type, `ConfigOption` returns the base64 encoded file. To return the decoded contents of a file, use [ConfigOptionData](#configoptiondata) instead.
 
 ```yaml
 '{{repl ConfigOption "hostname" }}'
 ```
 
-`ConfigOption` returns the base64 **encoded** value of the `file` config option.
+#### Example
 
-```yaml
-'{{repl ConfigOption "ssl_key"}}'
-```
+The following KOTS [HelmChart](/reference/custom-resource-helmchart-v2) custom resource uses the ConfigOption template function to set the port, node port, and annotations for a LoadBalancer service using the values supplied by the user on the KOTS Admin Console config screen. These values are then mapped to the `values.yaml` file for the associated Helm chart during deployment.
 
-To use files in a Secret, use `ConfigOption`:
 ```yaml
-apiVersion: v1
-kind: Secret
+# KOTS HelmChart custom resource
+apiVersion: kots.io/v1beta2
+kind: HelmChart
 metadata:
-  name: tls-secret
-type: kubernetes.io/tls
-data:
-  tls.crt: '{{repl ConfigOption "tls_certificate_file" }}'
-  tls.key: '{{repl ConfigOption "tls_private_key_file" }}'
+  name: samplechart
+spec:
+  chart:
+    name: samplechart
+    chartVersion: 3.1.7
+  values:
+    myapp:
+      service:
+        type: LoadBalancer
+        port: repl{{ ConfigOption "myapp_load_balancer_port"}}
+        nodePort: repl{{ ConfigOption "myapp_load_balancer_node_port"}}
+        annotations: repl{{ ConfigOption `myapp_load_balancer_annotations` | nindent 14 }}
 ```
-
-For more information about using TLS certificates, see [Using TLS Certificates](../vendor/packaging-using-tls-certs).
+For more information, see [Setting Helm Values with KOTS](/vendor/helm-optional-value-keys).
 
 ## ConfigOptionData
 
 ```go
 func ConfigOptionData(optionName string) string
 ```
 
-`ConfigOptionData` returns the base64 **decoded** value of a `file` config option.
+For the `file` config option type,  `ConfigOptionData` returns the base64 decoded contents of the file. To return the base64 encoded file, use [ConfigOption](#configoption) instead.
 
 ```yaml
 '{{repl ConfigOptionData "ssl_key"}}'
 ```
 
-To use files in a ConfigMap, use `ConfigOptionData`:
+#### Example
+
+The following KOTS [HelmChart](/reference/custom-resource-helmchart-v2) custom resource uses the ConfigOptionData template function to set the TLS cert and key using the files supplied by the user on the KOTS Admin Console config screen. These values are then mapped to the `values.yaml` file for the associated Helm chart during deployment.
+
 ```yaml
-apiVersion: v1
-kind: ConfigMap
+# KOTS HelmChart custom resource
+apiVersion: kots.io/v1beta2
+kind: HelmChart
 metadata:
-  name: tls-config
-data:
-  tls.crt: |
-    repl{{- ConfigOptionData "tls_certificate_file" | nindent 4 }}
-
-  tls.key: |
-    repl{{- ConfigOptionData "tls_private_key_file" | nindent 4 }}
+  name: samplechart
+spec:
+  chart:
+    name: samplechart
+    chartVersion: 3.1.7
+  values:
+    myapp:
+      tls:
+        enabled: true
+        genSelfSignedCert: repl{{ ConfigOptionEquals "myapp_ingress_tls_type" "self_signed" }}
+        cert: repl{{ print `|`}}repl{{ ConfigOptionData `tls_certificate_file` | nindent 12 }}
+        key: repl{{ print `|`}}repl{{ ConfigOptionData `tls_private_key_file` | nindent 12 }}
 ```
+For more information, see [Setting Helm Values with KOTS](/vendor/helm-optional-value-keys).
 
 ## ConfigOptionFilename
 
@@ -73,7 +91,9 @@ It will return an empty string if used erroneously with other types.
 '{{repl ConfigOptionFilename "pom_file"}}'
 ```
 
-As an example, if you have the following Config Spec defined:
+#### Example
+
+For example, if you have the following KOTS Config defined:
 
 ```yaml
 apiVersion: kots.io/v1beta1
@@ -91,7 +111,8 @@ spec:
           required: true
 ```
 
-You can use `ConfigOptionFilename` in a Pod Spec to mount a file like so:
+The following example shows how to use `ConfigOptionFilename` in a Pod Spec to mount a file:
+
 ```yaml
 apiVersion: v1
 kind: Pod
@@ -137,6 +158,26 @@ Returns true if the configuration option value is equal to the supplied value.
 '{{repl ConfigOptionEquals "http_enabled" "1" }}'
 ```
 
+#### Example
+
+The following KOTS [HelmChart](/reference/custom-resource-helmchart-v2) custom resource uses the ConfigOptionEquals template function to set the `postgres.enabled` value depending on if the user selected the `embedded_postgres` option on the KOTS Admin Console config screen. This value is then mapped to the `values.yaml` file for the associated Helm chart during deployment.
+
+```yaml
+# KOTS HelmChart custom resource
+apiVersion: kots.io/v1beta2
+kind: HelmChart
+metadata:
+  name: samplechart
+spec:
+  chart:
+    name: samplechart
+    chartVersion: 3.1.7
+  values:
+    postgresql:
+      enabled: repl{{ ConfigOptionEquals `postgres_type` `embedded_postgres`}}
+```
+For more information, see [Setting Helm Values with KOTS](/vendor/helm-optional-value-keys).
+
 ## ConfigOptionNotEquals
 
 ```go
@@ -168,6 +209,29 @@ Returns the host of the local registry that the user configured. Alternatively,
 
 Includes the port if one is specified.
 
+#### Example
+
+The following KOTS [HelmChart](/reference/custom-resource-helmchart-v2) custom resource uses the HasLocalRegistry, LocalRegistryHost, and LocalRegistryNamespace template functions to conditionally rewrite an image registry and repository depending on if a local registry is used. These values are then mapped to the `values.yaml` file for the associated Helm chart during deployment.
+
+```yaml
+# KOTS HelmChart custom resource
+apiVersion: kots.io/v1beta2
+kind: HelmChart
+metadata:
+  name: samplechart
+spec:
+  chart:
+    name: samplechart
+    chartVersion: 3.1.7
+  values:
+    myapp:
+      image:
+        registry: '{{repl HasLocalRegistry | ternary LocalRegistryHost "images.mycompany.com" }}'
+        repository: '{{repl HasLocalRegistry | ternary LocalRegistryNamespace "proxy/myapp/quay.io/my-org" }}/nginx'
+        tag: v1.0.1
+```
+For more information, see [Setting Helm Values with KOTS](/vendor/helm-optional-value-keys).
+
 ## LocalRegistryNamespace
 
 ```go
@@ -176,6 +240,29 @@ func LocalRegistryNamespace() string
 
 Returns the namespace of the local registry that the user configured. Alternatively, for air gap installations with Embedded Cluster or kURL, LocalRegistryNamespace returns the namespace of the built-in registry.
 
+#### Example
+
+The following KOTS [HelmChart](/reference/custom-resource-helmchart-v2) custom resource uses the HasLocalRegistry, LocalRegistryHost, and LocalRegistryNamespace template functions to conditionally rewrite an image registry and repository depending on if a local registry is used. These values are then mapped to the `values.yaml` file for the associated Helm chart during deployment.
+
+```yaml
+# KOTS HelmChart custom resource
+apiVersion: kots.io/v1beta2
+kind: HelmChart
+metadata:
+  name: samplechart
+spec:
+  chart:
+    name: samplechart
+    chartVersion: 3.1.7
+  values:
+    myapp:
+      image:
+        registry: '{{repl HasLocalRegistry | ternary LocalRegistryHost "images.mycompany.com" }}'
+        repository: '{{repl HasLocalRegistry | ternary LocalRegistryNamespace "proxy/myapp/quay.io/my-org" }}/nginx'
+        tag: v1.0.1
+```
+For more information, see [Setting Helm Values with KOTS](/vendor/helm-optional-value-keys).
+
 ## LocalImageName
 
 ```go
@@ -206,6 +293,8 @@ Returns the base64 encoded local registry image pull secret value.
 This is often needed when an operator is deploying images to a namespace that is not managed by Replicated KOTS.
 Image pull secrets must be present in the namespace of the pod.
 
+#### Example
+
 ```yaml
 apiVersion: v1
 kind: Secret
@@ -239,6 +328,8 @@ Returns the name of the image pull secret that can be added to pod specs that us
 The secret will be automatically created in all application namespaces.
 It will contain authentication information for any private registry used with the application.
 
+#### Example
+
 ```yaml
 apiVersion: apps/v1
 kind: Deployment
@@ -258,4 +349,27 @@ func HasLocalRegistry() bool
 ```
 
 Returns true if the environment is configured to rewrite images to a local registry.
-HasLocalRegistry is always true for air gap installations. HasLocalRegistry is true in online installations if the user pushed images to a local registry.
+HasLocalRegistry is always true for air gap installations. HasLocalRegistry is true in online installations if the user pushed images to a local registry.
+
+#### Example
+
+The following KOTS [HelmChart](/reference/custom-resource-helmchart-v2) custom resource uses the HasLocalRegistry, LocalRegistryHost, and LocalRegistryNamespace template functions to conditionally rewrite an image registry and repository depending on if a local registry is used. These values are then mapped to the `values.yaml` file for the associated Helm chart during deployment.
+
+```yaml
+# KOTS HelmChart custom resource
+apiVersion: kots.io/v1beta2
+kind: HelmChart
+metadata:
+  name: samplechart
+spec:
+  chart:
+    name: samplechart
+    chartVersion: 3.1.7
+  values:
+    myapp:
+      image:
+        registry: '{{repl HasLocalRegistry | ternary LocalRegistryHost "images.mycompany.com" }}'
+        repository: '{{repl HasLocalRegistry | ternary LocalRegistryNamespace "proxy/myapp/quay.io/my-org" }}/nginx'
+        tag: v1.0.1
+```
+For more information, see [Setting Helm Values with KOTS](/vendor/helm-optional-value-keys).

docs/reference/template-functions-identity-context.md

@@ -1,5 +1,9 @@
+import IdentityContext from "../partials/template-functions/_identity-context.mdx"
+
 # Identity Context
 
+<IdentityContext/>
+
 ## IdentityServiceEnabled
 
 ```go

docs/reference/template-functions-kurl-context.md

@@ -1,22 +1,25 @@
+import KurlContext from "../partials/template-functions/_kurl-context.mdx"
+import KurlAvailability from "../partials/kurl/_kurl-availability.mdx"
+
 # kURL Context
 
-## kURL Context Functions
+<KurlAvailability/>
+
+## Overview
 
-For applications installed in embedded clusters created with Replicated kURL, you can use template functions to show all options the cluster was installed with.
+<KurlContext/>
 
-The creation of the Installer custom resource will reflect both install script changes made by posting YAML to the kURL API and changes made with -s flags at runtime. These functions are not available on the config page.
+The creation of the kURL Installer custom resource will reflect both install script changes made by posting YAML to the kURL API and changes made with -s flags at runtime. These functions are not available on the KOTS Admin Console config page.
 
 KurlBool, KurlInt, KurlString, and KurlOption all take a string yamlPath as a param.
-This path is the path from the manifest file, and is delineated between addon and subfield by a period ’.’.
+This is the path from the manifest file, and is delineated between add-on and subfield by a period ’.’.
 For example, the kURL Kubernetes version can be accessed as `{{repl KurlString "Kubernetes.Version" }}`.
 
 KurlBool, KurlInt, KurlString respectively return a bool, integer, and string value.
 If used on a valid field but with the wrong type these will return the falsy value for their type, false, 0, and “string respectively.
 The `KurlOption` function will convert all bool, int, and string fields to string.
 All functions will return falsy values if there is nothing at the yamlPath specified, or if these functions are run in a cluster with no installer custom resource (as in, not a cluster created by kURL).
 
-The following provides a complete list of the Installer custom resource with annotations:
-
 ## KurlBool
 
 ```go

docs/reference/template-functions-license-context.md

@@ -1,5 +1,9 @@
+import LicenseContext from "../partials/template-functions/_license-context.mdx"
+
 # License Context
 
+<LicenseContext/>
+
 ## LicenseFieldValue
 ```go
 func LicenseFieldValue(name string) string