Merge pull request #2583 from replicatedhq/110902

paigecalvert · web-flow · commit 86017f87ce96 · 2024-08-22T09:58:37.000-06:00
Clarify EC template func limitation
diff --git a/docs/reference/embedded-config.mdx b/docs/reference/embedded-config.mdx
@@ -1,24 +1,30 @@
 # Embedded Cluster Config (Beta)
 
-This topic is a reference for the Replicated embedded cluster config custom resource. For more information about embedded cluster, see [Using Embedded Cluster](/vendor/embedded-overview).
+This topic is a reference for the Replicated Embedded Cluster Config custom resource. For more information about Embedded Cluster, see [Using Embedded Cluster](/vendor/embedded-overview).
 
 :::note
-Embedded cluster is in beta. If you are instead looking for information about creating Kubernetes Installers with Replicated kURL, see the [Replicated kURL](/vendor/packaging-embedded-kubernetes) section.
+Embedded Cluster is in beta. If you are instead looking for information about creating Kubernetes Installers with Replicated kURL, see the [Replicated kURL](/vendor/packaging-embedded-kubernetes) section.
 :::
 
 ## Overview
 
-To install your application in an embedded cluster, an embedded cluster config must be created in a release. Embedded cluster binaries are available only for releases that include an embedded cluster config.
+To install your application with Embedded Cluster, an Embedded Cluster Config must be created in a release. Embedded Cluster installation artifacts are available only for releases that include an Embedded Cluster Config.
 
-The embedded cluster config lets you define several aspects of the Kubernetes cluster that will be created.
+The Embedded Cluster Config lets you define several aspects of the Kubernetes cluster that will be created.
 
-**Example**:
+### Limitations
+
+* The Embedded Cluster Config does not support the use of Go template functions, including [KOTS template functions](/reference/template-functions-about).
+
+For additional property-specific limitations, see the sections below.
+
+### Example
 
 ```yaml
 apiVersion: embeddedcluster.replicated.com/v1beta1
 kind: Config
 spec:
-  version: 1.9.1+k8s-1.29
+  version: 1.10.0+k8s-1.29
   roles:
     controller:
       name: management
@@ -64,21 +70,21 @@ spec:
               service-node-port-range: 80-32767
 ```
 
-## Version
+## version
 
-You must specify which version of embedded cluster to install. Each version of embedded cluster includes particular versions of components like KOTS (admin console) and OpenEBS.
+You must specify which version of Embedded Cluster to install. Each version of Embedded Cluster includes particular versions of components like KOTS (Admin Console) and OpenEBS.
 
-For a full list of versions, see the embedded cluster [releases page](https://github.com/replicatedhq/embedded-cluster/releases) in GitHub. It's recommended to keep this version as up to date as possible because embedded cluster is changing rapidly.
+For a full list of versions, see the Embedded Cluster [releases page](https://github.com/replicatedhq/embedded-cluster/releases) in GitHub. It's recommended to keep this version as up to date as possible because Embedded Cluster is changing rapidly.
 
-## Roles
+## roles
 
-You can define node roles in the embedded cluster config. Roles are particularly useful for multi-node clusters. One or more roles can be selected and assigned to a node when it is joined to the cluster. Node roles can be used to determine which nodes run the Kubernetes control plane, and to assign application workloads to particular nodes.
+You can define node roles in the Embedded Cluster Config. Roles are particularly useful for multi-node clusters. One or more roles can be selected and assigned to a node when it is joined to the cluster. Node roles can be used to determine which nodes run the Kubernetes control plane, and to assign application workloads to particular nodes.
 
 :::note
 Roles are not updated or changed after a node is added. If you need to change a node’s role, reset the node and add it again.
 :::
 
-### Controller
+### controller
 
 The controller role is required in any cluster. Nodes with this role are “controller workers” because they run the control plane and can run other workloads too. The first node in a cluster will always have the controller role because a cluster needs a control plane. Any node that doesn't have the controller role is a worker node.
 
@@ -93,7 +99,7 @@ spec:
       name: management
 ```      
 
-### Custom
+### custom
 
 You can define custom roles for other purposes in the cluster. This is particularly useful when combined with labels.
 
@@ -108,7 +114,7 @@ spec:
     - name: app
 ```
 
-### Labels
+### labels
 
 Roles can have associated Kubernetes labels that are applied to any node in the cluster that is assigned that role. This is useful for things like assigning workloads to nodes.
 
@@ -129,19 +135,25 @@ spec:
         app: "true" # Label applied to "app" nodes
 ```
 
-## Helm Extensions
-
-If you need to install Helm charts before your application and as part of the embedded cluster itself, you can do this with Helm extensions. One situation where this is useful is if you want to ship an ingress controller, because embedded cluster does not yet include one.
+## extensions
 
-Helm extensions are updated when new versions of your application are deployed from the admin console. So, for example, you can change the values for a Helm extension from one release to another, and those changes will be applied to the cluster when the new release is deployed.
+If you need to install Helm charts before your application and as part of the Embedded Cluster itself, you can do this with Helm extensions. One situation where this is useful is if you want to ship an ingress controller, because Embedded Cluster does not yet include one.
 
-**Limitation**: If a Helm extension is removed from the embedded cluster config, the associated Helm chart is not removed from the cluster. This is a limitation that we intend to address in the future.
+Helm extensions are updated when new versions of your application are deployed from the Admin Console. So, for example, you can change the values for a Helm extension from one release to another, and those changes will be applied to the cluster when the new release is deployed.
 
 The format for specifying Helm extensions uses the same k0s Helm extensions format from the k0s configuration. For more information about these fields, see the [k0s documentation](https://docs.k0sproject.io/stable/helm-charts/#example).
 
-The `version` field is required. Failing to specify a chart version will cause problems for upgrades.
+### Limitation
+
+If a Helm extension is removed from the Embedded Cluster Config, the associated Helm chart is not removed from the cluster.
+
+### Requirements
+
+* The `version` field is required. Failing to specify a chart version will cause problems for upgrades.
 
-**Example**:
+* If you need to install multiple charts in a particular order, set the `order` field to a value greater than or equal to 10. Numbers below 10 are reserved for use by Embedded Cluster to deploy things like a storage provider and the Admin Console. If an `order` is not provided, Helm extensions are installed with order 10. 
+
+### Example
 
 ```yaml
 apiVersion: embeddedcluster.replicated.com/v1beta1
@@ -176,23 +188,19 @@ spec:
                     digest: ""
 ```
 
-:::note
-If an order is not provided, Helm extensions are installed with order 10. Numbers below 10 are reserved for use by embedded cluster to deploy things like a storage provider and the admin console. If you need to install multiple charts in a particular order, choose orders greater than or equal to 10.
-:::
-
-## Unsupported Overrides
+## unsupportedOverrides
 
 :::important
 This feature should be used with caution by advanced users who understand the risks and ramifications of changing the default configuration.
 :::
 
-Unsupported overrides allow you to override embedded cluster's default configuration, including the k0s config and the Helm values for extensions like KOTS and OpenEBS. This should be used with caution because changes here are untested and can disrupt or break embedded clusters. Any issues that are caused by unsupported overrides are not supported.
+Unsupported overrides allow you to override Embedded Cluster's default configuration, including the k0s config and the Helm values for extensions like KOTS and OpenEBS. This should be used with caution because changes here are untested and can disrupt or break Embedded Clusters. Any issues that are caused by unsupported overrides are not supported.
 
-While they should be used with caution, unsupported overrides are useful if you need to make changes that are not yet otherwise exposed by embedded cluster.
+While they should be used with caution, unsupported overrides are useful if you need to make changes that are not otherwise exposed by Embedded Cluster.
 
 ### Override the k0s Config
 
-By default, embedded cluster uses a k0s config that is tested and known to work for embedded clusters. In some circumstances, you might want to change the k0s config.
+By default, Embedded Cluster uses a k0s config that is tested and known to work for Embedded Clusters. In some circumstances, you might want to change the k0s config.
 
 For more information on the k0s config, see [Configuration options](https://docs.k0sproject.io/stable/configuration/#configuration-file-reference) in the k0s documentation.
 
@@ -211,19 +219,27 @@ spec:
               service-node-port-range: 80-32767
 ```
 
-Overrides overwrite the corresponding fields in the k0s configuration. They are not merged into embedded cluster’s default configuration. When using overrides to override a list, for example, ensure that you include other elements in the list that embedded cluster includes by default.
+#### Limtiations
+
+* The `spec.api` and `spec.storage` keys in the k0s config cannot be changed after installation. Whereas most keys in the k0s config apply to the whole cluster, these two keys are set for each node. Embedded Cluster cannot update these keys on each individual node during updates, so they cannot be changed after installation.
 
-**Limitation:** The `spec.api` and `spec.storage` keys in the k0s config cannot be changed after installation. Whereas most keys in the k0s config apply to the whole cluster, these two keys are set for each node. Embedded Cluster cannot update these keys on each individual node during updates, so they cannot be changed after installation.
+* Overrides overwrite the corresponding fields in the k0s configuration. They are not merged into Embedded Cluster’s default configuration. When using overrides to override a list, for example, ensure that you include other elements in the list that Embedded Cluster includes by default.
 
 ### Override the Helm Values for Built-In Extensions
 
-> Introduced in embedded cluster v1.2.0.
+Embedded Cluster deploys built-in extensions like KOTS and OpenEBS to provide capabilities like storage and application management. These extensions are deployed with Helm, and the Helm values for each can be modified if necessary.
+
+To modify these values, you can use the `unsupportedOverrides.builtInExtensions` key of the Embedded Cluster Config. Each chart you want to modify is an item in the array. The `name` key identifies the Helm chart that you want to modify, and the `values` key is a string where you specify your modified Helm values. Your modified values are merged into the values used by Embedded Cluster.
 
-Embedded cluster deploys built-in extensions like KOTS and OpenEBS to provide capabilities like storage and application management. These extensions are deployed with Helm, and the Helm values for each can be modified if necessary.
+The following are the built-in extensions available for modification:
 
-To modify these values, you can use the `unsupportedOverrides.builtInExtensions` key of the embedded cluster config. Each chart you want to modify is an item in the array. The `name` key identifies the Helm chart that you want to modify, and the `values` key is a string where you specify your modified Helm values. Your modified values are merged into the values used by embedded cluster.
+- `openebs`
+- `admin-console`
+- `velero`
+- `embedded-cluster-operator`
+
+#### Example
 
-Example:
 ```yaml
 apiVersion: embeddedcluster.replicated.com/v1beta1
 kind: Config
@@ -234,10 +250,3 @@ spec:
       values: |
         key: value
 ```
-
-The following are the built-in extensions available for modification:
-
-- `openebs`
-- `admin-console`
-- `velero`
-- `embedded-cluster-operator`
diff --git a/docs/reference/template-functions-about.mdx b/docs/reference/template-functions-about.mdx
@@ -14,15 +14,20 @@ All functionality of the Go templating language, including if statements, loops,
 
 ### Supported File Types
 
-You can use KOTS template functions in any Kubernetes manifest files for applications deployed by KOTS, such as:
+You can use KOTS template functions in Kubernetes manifest files for applications deployed by KOTS, such as:
 * Custom resources in the `kots.io` API group like Application, Config, or HelmChart
-  :::note
-  Not all fields in the Config custom resource support templating. For more information, see [Item Properties](/reference/custom-resource-config#item-properties) in _Config_.
-  :::
 * Custom resources in other API groups like Preflight, SupportBundle, or Backup
 * Kubernetes objects like Deployments, Services, Secrets, or ConfigMaps
 * Kubernetes Operators
 
+### Limitations
+
+* Not all fields in the Config and Application custom resources support templating. For more information, see [Application](/reference/custom-resource-application) and [Item Properties](/reference/custom-resource-config#item-properties) in _Config_.
+
+* Templating is not supported in the [Embedded Cluster Config](/reference/embedded-config) resource.
+
+* KOTS template functions are not directly supported in Helm charts. For more information, see [Helm Charts](#helm-charts) below.
+
 ### Helm Charts
 
 KOTS template functions are _not_ directly supported in Helm charts. However, the HelmChart custom resource provides a way to map values rendered by KOTS template functions to Helm chart values. This allows you to use KOTS template functions with Helm charts without making changes to those Helm charts.
diff --git a/docs/vendor/embedded-overview.mdx b/docs/vendor/embedded-overview.mdx
@@ -57,6 +57,8 @@ Embedded Cluster has the following limitations:
 
 * **Downgrading Kubernetes not supported**: Embedded Cluster does not support downgrading Kubernetes. The admin console will not prevent end-users from attempting to downgrade Kubernetes if a more recent version of your application specifies a previous Embedded Cluster version. You must ensure that you do not promote new versions with previous Embedded Cluster versions.
 
+* **Templating not supported in Embedded Cluster Config**: The [Embedded Cluster Config](/reference/embedded-config) resource does not support the use of Go template functions, including [KOTS template functions](/reference/template-functions-about).
+
 ## Quick Start
 
 You can use the following steps to get started quickly with Embedded Cluster. More detailed documentation is available below.
