Merge pull request #97 from Peefy/docs-extract-data-from-composed-res…

…ources docs: add more ocds documents and examples
crossplane-contrib · May 8, 2024 · dacde80 · dacde80
2 parents b563f36 + 6d693c8
commit dacde80
Show file tree

Hide file tree

Showing 7 changed files with 242 additions and 43 deletions.
diff --git a/README.md b/README.md
@@ -21,9 +21,9 @@ spec:
     kind: XR
   mode: Pipeline
   pipeline:
-    - step: create-a-bucket
+    - step: basic
       functionRef:
-        name: function-go-templating
+        name: function-kcl
       input:
         apiVersion: krm.kcl.dev/v1alpha1
         kind: KCLRun
@@ -119,21 +119,25 @@ kind: KCLRun
 metadata:
   name: basic
 spec:
-  target: Resources
   source: ./path/to/kcl/file.k
 ```
 
 ### Read the Function Requests and Values through the `option` Function
 
-+ Read the `ObservedCompositeResource` from `option("params").oxr`.
-+ Read the `ObservedComposedResources` from `option("params").ocds`.
-+ Read the `DesiredCompositeResource` from `option("params").dxr`.
-+ Read the `DesiredComposedResources` from `option("params").dcds`.
-+ Read the function pipeline's context from `option("params").ctx`.
++ Read the [`ObservedCompositeResource`](https://docs.crossplane.io/latest/concepts/composition-functions/#observed-state) from `option("params").oxr`.
++ Read the [`ObservedComposedResources`](https://docs.crossplane.io/latest/concepts/composition-functions/#observed-state) from `option("params").ocds`.
++ Read the [`DesiredCompositeResource`](https://docs.crossplane.io/latest/concepts/composition-functions/#desired-state) from `option("params").dxr`.
++ Read the [`DesiredComposedResources`](https://docs.crossplane.io/latest/concepts/composition-functions/#desired-state) from `option("params").dcds`.
++ Read the [`function pipeline's context`](https://docs.crossplane.io/latest/concepts/composition-functions/#function-pipeline-context) from `option("params").ctx`.
 + Return an error using `assert {condition}, {error_message}`.
++ Log variable values using the function `print(variable)` and it will be output to the stdout of the function pod.
 + Read the PATH variables. e.g. `option("PATH")`.
 + Read the environment variables. e.g. `option("env")`.
 
+### oxr
+
+#### Custom Parameters
+
 You can define your custom parameters in the `params` field and use `option("params").custom_key` to get the `custom_value`.
 
 ```yaml
@@ -217,61 +221,113 @@ spec:
     ...
 ```
 
+### Extract Data from a Specific Composed Resource
+
+To extract data from a specific composed resource by using the resource name, we can use the `option("params").ocds` variable, `ocds` is a mapping that its key is the resource name and its value is the [`observed composed resource`](https://pkg.go.dev/github.com/crossplane/[email protected]/resource#ObservedComposed) like [the example](./examples/default/read_ocds_resource/composition.yaml).
+
+```yaml
+apiVersion: krm.kcl.dev/v1alpha1
+kind: KCLRun
+metadata:
+  name: show-ocds
+spec:
+  source: |
+    {
+        metadata.name = "ocds"
+        spec.ocds = option("params").ocds
+        spec.user_kind = option("params").ocds["test-user"]?.Resource.Kind
+        spec.user_metadata = option("params").ocds["test-user"]?.Resource.metadata
+        spec.user_status = option("params").ocds["test-user"]?.Resource.status
+    }
+```
+
 ### Composite Resource Connection Details
 
-To return desired composite resource connection details, include a KCL dict that produces the special CompositeConnectionDetails resource like [the example](./examples/default/connection_details/composition.yaml):
+To return desired composite resource connection details, include a KCL config that produces the special CompositeConnectionDetails resource like [the example](./examples/default/connection_details/composition.yaml):
 
-```kcl
-details = {
-    apiVersion: "meta.krm.kcl.dev/v1alpha1"
-    kind: "CompositeConnectionDetails"
-    data: {
-        "connection-secret-key": "connection-secret-value"
+```yaml
+apiVersion: krm.kcl.dev/v1alpha1
+kind: KCLRun
+metadata:
+  name: basic
+spec:
+  source: |
+    details = {
+        apiVersion: "meta.krm.kcl.dev/v1alpha1"
+        kind: "CompositeConnectionDetails"
+        data: {
+            "connection-secret-key": "connection-secret-value"
+        }
     }
-}
+    # Omit other composite logics.
+    # Input the details resource into the return resource list.
+    items = [
+        details
+        # Omit other return resources.
+    ]
 ```
 
 > Note: The value of the connection secret value must be base64 encoded. This is already the case if you are referencing a key from a managed resource's connectionDetails field. However, if you want to include a connection secret value from somewhere else, you will need to use the `base64.encode` function:
 
-```kcl
-import base64
-
-ocds = option("params").ocds
-details = {
-    apiVersion: "meta.krm.kcl.dev/v1alpha1"
-    kind: "CompositeConnectionDetails"
-    data: {
-        "server-endpoint" = base64.encode(ocds["my-server"].Resource.status.atProvider.endpoint)
+```yaml
+apiVersion: krm.kcl.dev/v1alpha1
+kind: KCLRun
+metadata:
+  name: basic
+spec:
+  source: |
+    import base64
+    
+    # Omit other logic
+    ocds = option("params").ocds
+    details = {
+        apiVersion: "meta.krm.kcl.dev/v1alpha1"
+        kind: "CompositeConnectionDetails"
+        data: {
+            "server-endpoint" = base64.encode(ocds["my-server"].Resource.status.    atProvider.endpoint)
+        }
     }
-}
 ```
 
 To mark a desired composed resource as ready, use the `krm.kcl.dev/ready` annotation:
 
-```kcl
-user = {
-    apiVersion: "iam.aws.upbound.io/v1beta1"
-    kind: "User"
-    metadata.name = "test-user"
-    metadata.annotations: {
-        "krm.kcl.dev/ready": "True"
+```yaml
+apiVersion: krm.kcl.dev/v1alpha1
+kind: KCLRun
+metadata:
+  name: basic
+spec:
+  source: |
+    # Omit other logic
+    user = {
+        apiVersion: "iam.aws.upbound.io/v1beta1"
+        kind: "User"
+        metadata.name = "test-user"
+        metadata.annotations: {
+            "krm.kcl.dev/ready": "True"
+        }
     }
-}
 ```
 
 ### Patching the XR status field
 
 You can read the XR, patch it with the status field and return the new patched XR in the `item` result like this
 
-```
-# Read the XR
-oxr = option("params").oxr
-# Patch the XR with the status field
-dxr = {
-    **oxr
-    status.dummy = "cool-status"
-}
-items = [dxr] # Omit other resources
+```yaml
+apiVersion: krm.kcl.dev/v1alpha1
+kind: KCLRun
+metadata:
+  name: basic
+spec:
+  source: |
+    # Read the XR
+    oxr = option("params").oxr
+    # Patch the XR with the status field
+    dxr = {
+        **oxr
+        status.dummy = "cool-status"
+    }
+    items = [dxr] # Omit other resources
 ```
 
 ## Library

diff --git a/examples/default/read_ocds_resource/Makefile b/examples/default/read_ocds_resource/Makefile
@@ -0,0 +1,3 @@
+render:
+	crossplane beta render xr.yaml composition.yaml functions.yaml \
+      --observed-resources=existing-observed-resources.yaml
diff --git a/examples/default/read_ocds_resource/README.md b/examples/default/read_ocds_resource/README.md
@@ -0,0 +1,76 @@
+# Example Manifests
+
+You can run your function locally and test it using `crossplane beta render`
+with these example manifests.
+
+```shell
+# Run the function locally
+$ go run . --insecure --debug
+```
+
+```shell
+# Then, in another terminal, call it with these example manifests
+$ crossplane beta render xr.yaml composition.yaml functions.yaml \
+      --observed-resources=existing-observed-resources.yaml
+---
+apiVersion: example.crossplane.io/v1beta1
+kind: XR
+metadata:
+  name: example
+---
+metadata:
+  annotations:
+    crossplane.io/composition-resource-name: ocds
+  generateName: example-
+  labels:
+    crossplane.io/composite: example
+  name: ocds
+  ownerReferences:
+  - apiVersion: example.crossplane.io/v1beta1
+    blockOwnerDeletion: true
+    controller: true
+    kind: XR
+    name: example
+    uid: ""
+spec:
+  ocds:
+    test-user:
+      ConnectionDetails: {}
+      Resource:
+        apiVersion: iam.aws.upbound.io/v1beta1
+        kind: User
+        metadata:
+          annotations:
+            crossplane.io/composition-resource-name: test-user
+          generateName: example-
+          labels:
+            crossplane.io/composite: example
+            dummy: foo
+            testing.upbound.io/example-name: test-user
+          name: test-user
+          ownerReferences:
+          - apiVersion: example.crossplane.io/v1beta1
+            blockOwnerDeletion: true
+            controller: true
+            kind: XR
+            name: example
+            uid: ""
+        spec:
+          forProvider: {}
+  user_metadata:
+    annotations:
+      crossplane.io/composition-resource-name: test-user
+    generateName: example-
+    labels:
+      crossplane.io/composite: example
+      dummy: foo
+      testing.upbound.io/example-name: test-user
+    name: test-user
+    ownerReferences:
+    - apiVersion: example.crossplane.io/v1beta1
+      blockOwnerDeletion: true
+      controller: true
+      kind: XR
+      name: example
+      uid: ""
+```
diff --git a/examples/default/read_ocds_resource/composition.yaml b/examples/default/read_ocds_resource/composition.yaml
@@ -0,0 +1,29 @@
+apiVersion: apiextensions.crossplane.io/v1
+kind: Composition
+metadata:
+  name: function-template-go
+spec:
+  compositeTypeRef:
+    apiVersion: example.crossplane.io/v1
+    kind: XR
+  mode: Pipeline
+  pipeline:
+
+  # Just for test
+  - step: normal
+    functionRef:
+      name: kcl-function
+    input:
+      apiVersion: krm.kcl.dev/v1alpha1
+      kind: KCLRun
+      metadata:
+        name: show-ocds
+      spec:
+        source: |
+          {
+              metadata.name = "ocds"
+              spec.ocds = option("params").ocds
+              spec.user_kind = option("params").ocds["test-user"]?.Resource.Kind
+              spec.user_metadata = option("params").ocds["test-user"]?.Resource.metadata
+              spec.user_status = option("params").ocds["test-user"]?.Resource.status
+          }
diff --git a/examples/default/read_ocds_resource/existing-observed-resources.yaml b/examples/default/read_ocds_resource/existing-observed-resources.yaml
@@ -0,0 +1,20 @@
+apiVersion: iam.aws.upbound.io/v1beta1
+kind: User
+metadata:
+  annotations:
+    crossplane.io/composition-resource-name: test-user
+  generateName: example-
+  labels:
+    crossplane.io/composite: example
+    dummy: foo
+    testing.upbound.io/example-name: test-user
+  name: test-user
+  ownerReferences:
+  - apiVersion: example.crossplane.io/v1beta1
+    blockOwnerDeletion: true
+    controller: true
+    kind: XR
+    name: example
+    uid: ""
+spec:
+  forProvider: {}
diff --git a/examples/default/read_ocds_resource/functions.yaml b/examples/default/read_ocds_resource/functions.yaml
@@ -0,0 +1,9 @@
+apiVersion: pkg.crossplane.io/v1beta1
+kind: Function
+metadata:
+  name: kcl-function
+  annotations:
+    # This tells crossplane beta render to connect to the function locally.
+    render.crossplane.io/runtime: Development
+spec:
+  package: xpkg.upbound.io/crossplane-contrib/function-kcl:latest
diff --git a/examples/default/read_ocds_resource/xr.yaml b/examples/default/read_ocds_resource/xr.yaml
@@ -0,0 +1,6 @@
+apiVersion: example.crossplane.io/v1beta1
+kind: XR
+metadata:
+  name: example
+spec:
+  count: 1