Rearrange examples and update documentation (#8)

* Rearrange examples and update documentation * Sort examples by context dir * Provide render target specific for each use case * Avoid test file duplication, share as much as possible Signed-off-by: Yury Tsarev <[email protected]> * Update syntax highlighting Signed-off-by: Yury Tsarev <[email protected]> --------- Signed-off-by: Yury Tsarev <[email protected]>
upbound · Jan 10, 2025 · 8f2f705 · 8f2f705
1 parent 0ac31b7
commit 8f2f705
Show file tree

Hide file tree

Showing 21 changed files with 228 additions and 57 deletions.
diff --git a/README.md b/README.md
@@ -5,7 +5,7 @@ A function to query [Azure Resource Graph][azresourcegraph]
 
 ## Usage
 
-See [examples][examples]
+See the [examples][examples] for a variety of practical and testable use cases demonstrating this Function.
 
 Example pipeline step:
 
@@ -47,26 +47,14 @@ status:
     location: centralus
     name: us-vm-lzbpt-fgcds
     type: microsoft.compute/virtualmachines
-  - id: /subscriptions/f403a412-959c-4214-8c4d-ad5598f149cc/resourceGroups/us-vac-dr27h-ttsq5/providers/Microsoft.Compute/virtualMachines/us-vac-dr27h-t7dhd
-    location: centralus
-    name: us-vac-dr27h-t7dhd
-    type: microsoft.compute/virtualmachines
-  - id: /subscriptions/f403a412-959c-4214-8c4d-ad5598f149cc/resourceGroups/my-vm-mm59z/providers/Microsoft.Compute/virtualMachines/my-vm-jm8g2
-    location: swedencentral
-    name: my-vm-jm8g2
-    type: microsoft.compute/virtualmachines
-  - id: /subscriptions/f403a412-959c-4214-8c4d-ad5598f149cc/resourceGroups/javid-labs/providers/Microsoft.Compute/virtualMachines/devstack-test
-    location: westus2
-    name: devstack-test
-    type: microsoft.compute/virtualmachines
 ```
 
 ### QueryRef
 
 Rather than specifying a direct query string as shown in the example above,
 the function allows referencing a query from any arbitrary string within the Context or Status.
 
-#### Context
+#### Context Query Reference
 
 * Simple context field reference
 ```yaml
@@ -78,7 +66,7 @@ the function allows referencing a query from any arbitrary string within the Con
       queryRef: "context.[apiextensions.crossplane.io/environment].azResourceGraphQuery"
 ```
 
-#### XR Status
+#### XR Status Query Reference
 
 * Simple XR Status field reference
 ```yaml
@@ -94,7 +82,7 @@ the function allows referencing a query from any arbitrary string within the Con
 
 Function supports publishing Query Results to different locations.
 
-#### Context
+#### Context Target
 
 * Simple Context field target
 ```yaml
@@ -106,7 +94,7 @@ Function supports publishing Query Results to different locations.
       target: "context.[apiextensions.crossplane.io/environment].azResourceGraphQuery"
 ```
 
-#### XR Status
+#### XR Status Target
 
 * Simple XR status field target
 ```yaml

diff --git a/example/README.md b/example/README.md
@@ -1,43 +1,33 @@
 # Example manifests
 
-You can run your function locally and test it using `crossplane beta render`
-with these example manifests.
+This directory contains a collection of practical examples to demonstrate the functionality. Each example is organized into a directory with a self-descriptive name.
 
-```shell
-# Run the function locally
-$ go run . --insecure --debug
-```
+## Usage
+
+To render a specific example, navigate to its directory and run the `make` command.
+
+Each example provides a unique `composition.yaml` file that highlights a specific function usage scenario.
+
+The Makefile in the examples directory provides a simple `render` target to
+streamline rendering Crossplane compositions.
+
+To enable a successful query, update `secrets/azure-creds.yaml` with
+your valid Azure credentials.
+
+## Example
+
+For instance, the static-query-to-context-field directory demonstrates how to use a static query to populate a specific context field.
 
 ```shell
-# Then, in another terminal, call it with these example manifests
-$ crossplane render example/xr.yaml example/composition.yaml example/functions-dev.yaml --function-credentials=example/secrets/azure-creds.yaml -r
+$ cd queryref-from-environment
+$ make
+crossplane render ../xr.yaml composition.yaml ./functions.yaml --function-credentials=../secrets/azure-creds.yaml --extra-resources=envconfig.yaml  -rc
 ---
 apiVersion: example.crossplane.io/v1
 kind: XR
 metadata:
   name: example-xr
 status:
-  azResourceGraphQueryResult:
-  - id: /subscriptions/f403a412-959c-4214-8c4d-ad5598f149cc/resourceGroups/us-vm-zxqnj-s2jdb/providers/Microsoft.Compute/virtualMachines/us-vm-zxqnj-2h59v
-    location: centralus
-    name: us-vm-zxqnj-2h59v
-    type: microsoft.compute/virtualmachines
-  - id: /subscriptions/f403a412-959c-4214-8c4d-ad5598f149cc/resourceGroups/us-vm-lzbpt-tdv2h/providers/Microsoft.Compute/virtualMachines/us-vm-lzbpt-fgcds
-    location: centralus
-    name: us-vm-lzbpt-fgcds
-    type: microsoft.compute/virtualmachines
-  - id: /subscriptions/f403a412-959c-4214-8c4d-ad5598f149cc/resourceGroups/us-vac-dr27h-ttsq5/providers/Microsoft.Compute/virtualMachines/us-vac-dr27h-t7dhd
-    location: centralus
-    name: us-vac-dr27h-t7dhd
-    type: microsoft.compute/virtualmachines
-  - id: /subscriptions/f403a412-959c-4214-8c4d-ad5598f149cc/resourceGroups/my-vm-mm59z/providers/Microsoft.Compute/virtualMachines/my-vm-jm8g2
-    location: swedencentral
-    name: my-vm-jm8g2
-    type: microsoft.compute/virtualmachines
-  - id: /subscriptions/f403a412-959c-4214-8c4d-ad5598f149cc/resourceGroups/javid-labs/providers/Microsoft.Compute/virtualMachines/devstack-test
-    location: westus2
-    name: devstack-test
-    type: microsoft.compute/virtualmachines
   conditions:
   - lastTransitionTime: "2024-01-01T00:00:00Z"
     reason: Available
@@ -46,8 +36,19 @@ status:
 ---
 apiVersion: render.crossplane.io/v1beta1
 kind: Result
-message: 'Query: "Resources | project name, location, type, id| where type =~ ''Microsoft.Compute/virtualMachines''
-  | order by name desc"'
+message: 'Query: "Resources|count"'
 severity: SEVERITY_NORMAL
 step: query-azresourcegraph
+---
+apiVersion: render.crossplane.io/v1beta1
+fields:
+  apiextensions.crossplane.io/environment:
+    apiVersion: internal.crossplane.io/v1alpha1
+    azResourceGraphQuery: Resources|count
+    kind: Environment
+  azResourceGraphQueryResult:
+  - Count: 204
+kind: Context
 ```
+
+Explore the examples to better understand various use cases and integrations!
diff --git a/example/functions.yaml b/example/functions.yaml
@@ -3,12 +3,8 @@ apiVersion: pkg.crossplane.io/v1beta1
 kind: Function
 metadata:
   name: function-azresourcegraph
+  annotations:
+    # This tells crossplane beta render to connect to the function locally.
+    render.crossplane.io/runtime: Development
 spec:
   package: xpkg.upbound.io/upboundcare/function-azresourcegraph:v0.2.0
----
-apiVersion: pkg.crossplane.io/v1beta1
-kind: Function
-metadata:
-  name: function-environment-configs
-spec:
-  package: xpkg.upbound.io/crossplane-contrib/function-environment-configs:v0.2.0
diff --git a/example/query-with-mgmt-groups/Makefile b/example/query-with-mgmt-groups/Makefile
@@ -0,0 +1,3 @@
+.PHONY: render
+render:
+	crossplane render ../xr.yaml composition.yaml ../functions.yaml --function-credentials=../secrets/azure-creds.yaml  -rc
diff --git a/example/composition-with-mgmt-groups.yaml → ...e/query-with-mgmt-groups/composition.yaml b/example/composition-with-mgmt-groups.yaml → ...e/query-with-mgmt-groups/composition.yaml
diff --git a/example/definition.yaml → ...le/query-with-mgmt-groups/definition.yaml b/example/definition.yaml → ...le/query-with-mgmt-groups/definition.yaml
diff --git a/example/queryref-from-environment/Makefile b/example/queryref-from-environment/Makefile
@@ -0,0 +1,3 @@
+.PHONY: render
+render:
+	crossplane render ../xr.yaml composition.yaml ./functions.yaml --function-credentials=../secrets/azure-creds.yaml --extra-resources=envconfig.yaml  -rc
diff --git a/example/composition-queryref-context.yaml → ...ueryref-from-environment/composition.yaml b/example/composition-queryref-context.yaml → ...ueryref-from-environment/composition.yaml
diff --git a/example/queryref-from-environment/definition.yaml b/example/queryref-from-environment/definition.yaml
@@ -0,0 +1,43 @@
+apiVersion: apiextensions.crossplane.io/v1
+kind: CompositeResourceDefinition
+metadata:
+  name: xrs.example.crossplane.io
+spec:
+  group: example.crossplane.io
+  names:
+    categories:
+    - crossplane
+    kind: XR
+    plural: xrs
+  versions:
+  - name: v1
+    referenceable: true
+    schema:
+      openAPIV3Schema:
+        description: XR is the Schema for the XR API.
+        properties:
+          spec:
+            description: XRSpec defines the desired state of XR.
+            type: object
+          status:
+            description: XRStatus defines the observed state of XR.
+            type: object
+            properties:
+              azResourceGraphQueryResult:
+                description: Freeform field containing query results from function-azresourcegraph
+                type: array
+                items:
+                  type: object
+                x-kubernetes-preserve-unknown-fields: true
+        required:
+        - spec
+        type: object
+    served: true
+status:
+  controllers:
+    compositeResourceClaimType:
+      apiVersion: ""
+      kind: ""
+    compositeResourceType:
+      apiVersion: ""
+      kind: ""
diff --git a/example/envconfig.yaml → .../queryref-from-environment/envconfig.yaml b/example/envconfig.yaml → .../queryref-from-environment/envconfig.yaml
diff --git a/example/functions-dev.yaml → .../queryref-from-environment/functions.yaml b/example/functions-dev.yaml → .../queryref-from-environment/functions.yaml
@@ -7,8 +7,7 @@ metadata:
     # This tells crossplane beta render to connect to the function locally.
     render.crossplane.io/runtime: Development
 spec:
-  # This is ignored when using the Development runtime.
-  package: function-azresourcegraph
+  package: xpkg.upbound.io/upboundcare/function-azresourcegraph:v0.2.0
 ---
 apiVersion: pkg.crossplane.io/v1beta1
 kind: Function

diff --git a/example/queryref-from-xr-status/Makefile b/example/queryref-from-xr-status/Makefile
@@ -0,0 +1,3 @@
+.PHONY: render
+render:
+	crossplane render ./xr.yaml composition.yaml ../functions.yaml --function-credentials=../secrets/azure-creds.yaml  -rc
diff --git a/example/composition-queryref-status.yaml → .../queryref-from-xr-status/composition.yaml b/example/composition-queryref-status.yaml → .../queryref-from-xr-status/composition.yaml
diff --git a/example/queryref-from-xr-status/definition.yaml b/example/queryref-from-xr-status/definition.yaml
@@ -0,0 +1,43 @@
+apiVersion: apiextensions.crossplane.io/v1
+kind: CompositeResourceDefinition
+metadata:
+  name: xrs.example.crossplane.io
+spec:
+  group: example.crossplane.io
+  names:
+    categories:
+    - crossplane
+    kind: XR
+    plural: xrs
+  versions:
+  - name: v1
+    referenceable: true
+    schema:
+      openAPIV3Schema:
+        description: XR is the Schema for the XR API.
+        properties:
+          spec:
+            description: XRSpec defines the desired state of XR.
+            type: object
+          status:
+            description: XRStatus defines the observed state of XR.
+            type: object
+            properties:
+              azResourceGraphQueryResult:
+                description: Freeform field containing query results from function-azresourcegraph
+                type: array
+                items:
+                  type: object
+                x-kubernetes-preserve-unknown-fields: true
+        required:
+        - spec
+        type: object
+    served: true
+status:
+  controllers:
+    compositeResourceClaimType:
+      apiVersion: ""
+      kind: ""
+    compositeResourceType:
+      apiVersion: ""
+      kind: ""
diff --git a/example/xr-with-status.yaml → example/queryref-from-xr-status/xr.yaml b/example/xr-with-status.yaml → example/queryref-from-xr-status/xr.yaml
diff --git a/example/static-query-to-context-field/Makefile b/example/static-query-to-context-field/Makefile
@@ -0,0 +1,3 @@
+.PHONY: render
+render:
+	crossplane render ../xr.yaml composition.yaml ../functions.yaml --function-credentials=../secrets/azure-creds.yaml  -rc
diff --git a/example/composition-context.yaml → ...c-query-to-context-field/composition.yaml b/example/composition-context.yaml → ...c-query-to-context-field/composition.yaml
diff --git a/example/static-query-to-context-field/definition.yaml b/example/static-query-to-context-field/definition.yaml
@@ -0,0 +1,43 @@
+apiVersion: apiextensions.crossplane.io/v1
+kind: CompositeResourceDefinition
+metadata:
+  name: xrs.example.crossplane.io
+spec:
+  group: example.crossplane.io
+  names:
+    categories:
+    - crossplane
+    kind: XR
+    plural: xrs
+  versions:
+  - name: v1
+    referenceable: true
+    schema:
+      openAPIV3Schema:
+        description: XR is the Schema for the XR API.
+        properties:
+          spec:
+            description: XRSpec defines the desired state of XR.
+            type: object
+          status:
+            description: XRStatus defines the observed state of XR.
+            type: object
+            properties:
+              azResourceGraphQueryResult:
+                description: Freeform field containing query results from function-azresourcegraph
+                type: array
+                items:
+                  type: object
+                x-kubernetes-preserve-unknown-fields: true
+        required:
+        - spec
+        type: object
+    served: true
+status:
+  controllers:
+    compositeResourceClaimType:
+      apiVersion: ""
+      kind: ""
+    compositeResourceType:
+      apiVersion: ""
+      kind: ""
diff --git a/example/static-query-to-xr-status/Makefile b/example/static-query-to-xr-status/Makefile
@@ -0,0 +1,3 @@
+.PHONY: render
+render:
+	crossplane render ../xr.yaml composition.yaml ../functions.yaml --function-credentials=../secrets/azure-creds.yaml  -rc
diff --git a/example/composition.yaml → ...tatic-query-to-xr-status/composition.yaml b/example/composition.yaml → ...tatic-query-to-xr-status/composition.yaml
diff --git a/example/static-query-to-xr-status/definition.yaml b/example/static-query-to-xr-status/definition.yaml
@@ -0,0 +1,43 @@
+apiVersion: apiextensions.crossplane.io/v1
+kind: CompositeResourceDefinition
+metadata:
+  name: xrs.example.crossplane.io
+spec:
+  group: example.crossplane.io
+  names:
+    categories:
+    - crossplane
+    kind: XR
+    plural: xrs
+  versions:
+  - name: v1
+    referenceable: true
+    schema:
+      openAPIV3Schema:
+        description: XR is the Schema for the XR API.
+        properties:
+          spec:
+            description: XRSpec defines the desired state of XR.
+            type: object
+          status:
+            description: XRStatus defines the observed state of XR.
+            type: object
+            properties:
+              azResourceGraphQueryResult:
+                description: Freeform field containing query results from function-azresourcegraph
+                type: array
+                items:
+                  type: object
+                x-kubernetes-preserve-unknown-fields: true
+        required:
+        - spec
+        type: object
+    served: true
+status:
+  controllers:
+    compositeResourceClaimType:
+      apiVersion: ""
+      kind: ""
+    compositeResourceType:
+      apiVersion: ""
+      kind: ""