Document sortOptions field

Kustomize has a new field called "sortOptions" to sort resources:
kubernetes-sigs/kustomize#3913
kubernetes-sigs/kustomize#4019

Document what it does and how to use it.

Signed-off-by: Yannis Zarkadas <yanniszark@gmail.com>

site/content/en/references/kustomize/kustomization/sortoptions/_index.md

@@ -0,0 +1,114 @@
+---
+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 are 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
+```

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,15 +228,15 @@ spec:
  ```
 
 and the top level `kustomization.yaml` has the following contents:
- 
+
  ```
  resources:
  - wordpress
  - mysql
  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: