From 63ee760669bbe6782f57fbc977550cd48b8b7cad Mon Sep 17 00:00:00 2001 From: Yannis Zarkadas Date: Fri, 9 Dec 2022 14:35:51 -0500 Subject: [PATCH] Document sortOptions field Kustomize has a new field called "sortOptions" to sort resources: https://github.com/kubernetes-sigs/kustomize/issues/3913 https://github.com/kubernetes-sigs/kustomize/pull/4019 Document what it does and how to use it. Signed-off-by: Yannis Zarkadas --- .../kustomization/sortoptions/_index.md | 118 ++++++++++++++++++ .../kustomize/kustomization/vars/_index.md | 28 ++--- 2 files changed, 132 insertions(+), 14 deletions(-) create mode 100644 site/content/en/references/kustomize/kustomization/sortoptions/_index.md diff --git a/site/content/en/references/kustomize/kustomization/sortoptions/_index.md b/site/content/en/references/kustomize/kustomization/sortoptions/_index.md new file mode 100644 index 000000000..a330ccaa0 --- /dev/null +++ b/site/content/en/references/kustomize/kustomization/sortoptions/_index.md @@ -0,0 +1,118 @@ +--- +title: "sortOptions" +linkTitle: "sortOptions" +type: docs +weight: 22 +description: > + Change the strategy used to sort resources at the end of the Kustomize build. +--- + +The `sortOptions` field is used to sort the resources kustomize outputs. It is +available in kustomize v5.0.0+. + +IMPORTANT: +- Currently, this field is respected only in the top-level Kustomization (that + is, the immediate target of `kustomize build`). Any instances of the field in + Kustomizations further down the build chain (for example, in bases included + through the `resources` field) will be ignored. +- This field is the endorsed way to sort resources. It should be used instead of + the `--reorder` CLI flag, which is deprecated. + +Currently, we support the following sort options: +- `legacy` +- `fifo` + +```yaml +kind: Kustomization +sortOptions: + order: legacy | fifo # "legacy" is the default +``` + +## FIFO Sorting + +In `fifo` order, kustomize does not change the order of resources. They appear +in the order they are loaded in `resources`. + +### Example 1: FIFO Sorting + +```yaml +kind: Kustomization +sortOptions: + order: fifo +``` + +## Legacy Sorting + +The `legacy` sort is the default order, and is used when the sortOrder field is +unspecified. + +In `legacy` order, kustomize sorts resources by using two priority lists: +- An `orderFirst` list for resources which should be first in the output. +- An `orderLast` list for resources which should be last in the output. +- Resources not on the lists will appear in between, sorted using their apiVersion and kind fields. + +### Example 2: Legacy Sorting with orderFirst / orderLast lists + +In this example, we use the `legacy` sort order to output `Namespace` objects +first and `Deployment` objects last. + +```yaml +kind: Kustomization +sortOptions: + order: legacy + legacySortOptions: + orderFirst: + - Namespace + orderLast: + - Deployment +``` + +### Example 3: Default Legacy Sorting + +If you specify `legacy` sort order without any arguments for the lists, +kustomize will fall back to the lists we were using before introducing this +feature. Since legacy sort is the default, this is also equivalent to not +specifying the field at all. + +These two configs are equivalent: + +```yaml +kind: Kustomization +sortOptions: + order: legacy +``` + +is equivalent to: + +```yaml +kind: Kustomization +sortOptions: + order: legacy + legacySortOptions: + orderFirst: + - Namespace + - ResourceQuota + - StorageClass + - CustomResourceDefinition + - ServiceAccount + - PodSecurityPolicy + - Role + - ClusterRole + - RoleBinding + - ClusterRoleBinding + - ConfigMap + - Secret + - Endpoints + - Service + - LimitRange + - PriorityClass + - PersistentVolume + - PersistentVolumeClaim + - Deployment + - StatefulSet + - CronJob + - PodDisruptionBudget + orderLast: + - MutatingWebhookConfiguration + - ValidatingWebhookConfiguration +``` diff --git a/site/content/en/references/kustomize/kustomization/vars/_index.md b/site/content/en/references/kustomize/kustomization/vars/_index.md index 20e4867bf..645c11ec3 100644 --- a/site/content/en/references/kustomize/kustomization/vars/_index.md +++ b/site/content/en/references/kustomize/kustomization/vars/_index.md @@ -2,7 +2,7 @@ title: "vars" linkTitle: "vars" type: docs -weight: 22 +weight: 23 description: > Substitute name references. --- @@ -11,7 +11,7 @@ description: > WARNING: There are plans to deprecate vars. For existing users of vars, we recommend migration to [replacements] as early as possible. There is a guide for convering vars to replacements at the bottom of this page under -"convert vars to replacements". For new users, we recommend never using vars, and starting with replacements +"convert vars to replacements". For new users, we recommend never using vars, and starting with replacements to avoid migration in the future. Vars are used to capture text from one resource's field @@ -134,7 +134,7 @@ vars: In order to convert `vars` to `replacements`, we have to: 1. Replace every instance of $(SOME_SECRET_NAME) with any arbitrary placeholder value. 2. Convert the vars `objref` field to a [replacements] `source` field. - 3. Replace the vars `name` fied with a [replacements] `targets` field that points to + 3. Replace the vars `name` fied with a [replacements] `targets` field that points to every instance of the placeholder value in step 1. In our simple example here, this would look like the following: @@ -169,7 +169,7 @@ replacements: name: my-secret version: v1 targets: - - select: + - select: kind: Pod name: my-pod fieldPaths: @@ -178,9 +178,9 @@ replacements: #### More complex migration example -Let's take a more complex usage of vars and convert it to [replacements]. We are going +Let's take a more complex usage of vars and convert it to [replacements]. We are going to convert the vars in the [wordpress example](https://github.com/kubernetes-sigs/kustomize/tree/master/examples/wordpress) -to replacements. +to replacements. The wordpress example has the following directory structure: @@ -228,7 +228,7 @@ spec: ``` and the top level `kustomization.yaml` has the following contents: - + ``` resources: - wordpress @@ -236,7 +236,7 @@ and the top level `kustomization.yaml` has the following contents: patchesStrategicMerge: - patch.yaml namePrefix: demo- - + vars: - name: WORDPRESS_SERVICE objref: @@ -255,7 +255,7 @@ In this example, the patch is used to: - Add environment variable that allow wordpress to find the mysql database We can convert vars to replacements in this more complex case too, by taking the same steps as -the previous example. To do this, we can change the contents of `patch.yaml` to: +the previous example. To do this, we can change the contents of `patch.yaml` to: ```yaml apiVersion: apps/v1 @@ -283,7 +283,7 @@ spec: ``` -Then, in our kustomization, we can have our replacements: +Then, in our kustomization, we can have our replacements: `kustomization.yaml` @@ -296,22 +296,22 @@ patchesStrategicMerge: namePrefix: demo- replacements: -- source: +- source: name: demo-wordpress kind: Service version: v1 targets: - - select: + - select: kind: Deployment name: demo-wordpress fieldPaths: - spec.template.spec.initContainers.[name=init-command].args.2 -- source: +- source: name: demo-mysql kind: Service version: v1 targets: - - select: + - select: kind: Deployment name: demo-wordpress fieldPaths: