docs: non default ns eg

website/docs/gator.md

@@ -288,10 +288,10 @@ should include the resource(s) under test, the `ExpansionTemplate`(s), and
 optionally any Mutation CRs. The command will output a manifest containing the
 expanded resources.
 
-If the mutators use spec.match.namespaceSelector, the namespace the resource
+If the mutators or constraints use `spec.match.namespaceSelector`, the namespace the resource
 belongs to must be supplied in order to correctly evaluate the match criteria.
 If a resource is specified for expansion but its non-default namespace is not
-supplied, the command will exit 1.
+supplied, the command will exit 1. See the [non default namespace example](#non-default-namespace-example) below.
 
 ### Usage
 
@@ -324,6 +324,109 @@ gator expand --filename="manifest.yaml" –format="json"
 See `gator expand –help` for more details. `gator expand` will exit 1 if there
 is a problem parsing the configs or expanding the resources.
 
+#### Non default namespace example
+
+This is an example setup where we include a `namespace` in a `manifest.yaml` that we plan on passing to `gator expand`.
+
+```yaml
+apiVersion: expansion.gatekeeper.sh/v1alpha1
+kind: ExpansionTemplate
+metadata:
+  name: expand-deployments
+spec:
+  applyTo:
+  - groups: [ "apps" ]
+    kinds: [ "Deployment" ]
+    versions: [ "v1" ]
+  templateSource: "spec.template"
+  generatedGVK:
+    kind: "Pod"
+    group: ""
+    version: "v1"
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: nginx-deployment
+  namespace: my-ns
+  labels:
+    app: nginx
+spec:
+  replicas: 3
+  selector:
+    matchLabels:
+      app: nginx
+  template:
+    metadata:
+      labels:
+        app: nginx
+    spec:
+      containers:
+      - name: nginx
+        image: nginx:1.14.2
+        ports:
+        - containerPort: 80
+        args:
+        - "/bin/sh"
+---
+apiVersion: mutations.gatekeeper.sh/v1alpha1
+kind: Assign
+metadata:
+  name: always-pull-image
+spec:
+  applyTo:
+  - groups: [ "" ]
+    kinds: [ "Pod" ]
+    versions: [ "v1" ]
+  location: "spec.containers[name: *].imagePullPolicy"
+  parameters:
+    assign:
+      value: "Always"
+  match:
+    source: "Generated"
+    scope: Namespaced
+    kinds:
+    - apiGroups: [ ]
+      kinds: [ ]
+    namespaceSelector:
+      matchExpressions:
+        - key: admission.gatekeeper.sh/ignore
+          operator: DoesNotExist
+---
+# notice this file is providing the non default namespace `my-ns`
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: my-ns
+```
+
+Calling `gator expand --filename=manifest.yaml` will produce the following output:
+
+```yaml
+apiVersion: v1
+kind: Pod
+metadata:
+  labels:
+    app: nginx
+  name: nginx-deployment-pod
+  namespace: my-ns
+spec:
+  containers:
+  - args:
+    - /bin/sh
+    image: nginx:1.14.2
+    imagePullPolicy: Always
+    name: nginx
+    ports:
+    - containerPort: 80
+```
+
+However, not including the `namespace` definition in the call to `gator expand` will exit with a status code of 1 and error out with:
+
+```
+error expanding resources: error expanding resource nginx-deployment: failed to mutate resultant resource nginx-deployment-pod: matching for mutator Assign.mutations.gatekeeper.sh /always-pull-image failed for  Pod my-ns nginx-deployment-pod: failed to run Match criteria: namespace selector for namespace-scoped object but missing Namespace
+```
+
 ## Bundling Policy into OCI Artifacts
 
 It may be useful to bundle policy files into OCI Artifacts for ingestion during