Merge pull request #12 from negz/release-prep

Update README, add a simpler example

README.md

@@ -1,103 +1,86 @@
 # function-auto-ready
+[![CI](https://github.com/crossplane-contrib/function-auto-ready/actions/workflows/ci.yml/badge.svg)](https://github.com/crossplane-contrib/function-auto-ready/actions/workflows/ci.yml) ![GitHub release (latest SemVer)](https://img.shields.io/github/release/crossplane-contrib/function-auto-ready)
 
-A Function that automatically detects when composed resources are ready. It
-considers a composed resource ready if:
+This [composition function][docs-functions] automatically detects composed
+resources that are ready. It considers a composed resource ready if:
 
-* The desired resource appears in the observed resources (i.e. it exists).
-* The observed resource has status condition `type: Ready`, `status: True`.
+* Another function added the composed resource to the desired state.
+* The composed resource appears in the observed state (i.e. it exists).
+* The composed resource has the status condition `type: Ready`, `status: True`.
 
-In future this Function may accept input to configure how it should determine
-that a composed resource is ready, but for now it's fixed.
+Crossplane considers a composite resource (XR) to be ready when all of its
+desired composed resources are ready.
 
-## Using this Function
-
-To use this Function, you must first install it:
-
-```yaml
-apiVersion: pkg.crossplane.io/v1beta1
-kind: Function
-metadata:
-  name: function-auto-ready
-spec:
-  package: xpkg.upbound.io/crossplane-contrib/function-auto-ready:v0.1.0
-```
-
-Remember that you need to [install a master build][install-master-docs] of
-Crossplane, since no released version of Crossplane supports beta Functions.
-
-To use this Function, write a Composition that uses it. Here we use
-[function-dummy] to return a "dummy" response, then run this Function.
+In this example, the [Go Templating][fn-go-templating] function is used to add
+a desired composed resource - an Amazon Web Services S3 Bucket. Once Crossplane
+has created the Bucket, the Auto Ready function will let Crossplane know when it
+is ready. Because this XR only has one composed resource, the XR will become
+ready when the Bucket becomes ready.
 
 ```yaml
 apiVersion: apiextensions.crossplane.io/v1
 kind: Composition
 metadata:
-  name: xnopresources.nop.example.org
+  name: example
 spec:
   compositeTypeRef:
-    apiVersion: nop.example.org/v1alpha1
-    kind: XNopResource
+    apiVersion: example.crossplane.io/v1beta1
+    kind: XR
   mode: Pipeline
   pipeline:
-  - step: be-a-dummy
+  - step: create-a-bucket
     functionRef:
-      name: function-dummy
+      name: function-go-templating
     input:
-      apiVersion: dummy.fn.crossplane.io/v1beta1
-      kind: Response
-      # This is a YAML-serialized RunFunctionResponse. function-dummy will
-      # overlay the desired state on any that was passed into it.
-      response:
-        desired:
-          resources:
-            nop-resource-1:
-              resource:
-                apiVersion: nop.crossplane.io/v1alpha1
-                kind: NopResource
-                spec:
-                  forProvider:
-                    conditionAfter:
-                    - conditionType: Ready
-                      conditionStatus: "False"
-                      time: 0s
-                    - conditionType: Ready
-                      conditionStatus: "True"
-                      time: 10s
+      apiVersion: gotemplating.fn.crossplane.io/v1beta1
+      kind: GoTemplate
+      source: Inline
+      inline:
+        template: |
+          apiVersion: s3.aws.upbound.io/v1beta1
+          kind: Bucket
+          metadata:
+            annotations:
+              gotemplating.fn.crossplane.io/composition-resource-name: bucket
+          spec:
+            forProvider:
+              region: {{ .observed.composite.resource.spec.region }}
   - step: automatically-detect-ready-composed-resources
     functionRef:
       name: function-auto-ready
 ```
 
-Check out `examples/` for a working example.
+See the [example](example) directory for an example you can run locally using
+the Crossplane CLI:
+
+```shell
+$ crossplane beta render xr.yaml composition.yaml functions.yaml
+```
 
-## Developing this Function
+See the [composition functions documentation][docs-functions] to learn more
+about `crossplane beta render`.
 
-This Function doesn't use the typical Crossplane build submodule and Makefile,
-since we'd like Functions to have a less heavyweight developer experience.
-It mostly relies on regular old Go tools:
+## Developing this function
+
+This function uses [Go][go], [Docker][docker], and the [Crossplane CLI][cli] to
+build functions.
 
 ```shell
-# Run tests
-$ go test -cover ./...
-?       github.com/crossplane/function-auto-ready/input/v1beta1      [no test files]
-ok      github.com/crossplane/function-auto-ready    0.006s  coverage: 25.8% of statements
+# Run code generation - see input/generate.go
+$ go generate ./...
 
-# Lint the code
-$ docker run --rm -v $(pwd):/app -v ~/.cache/golangci-lint/v1.54.2:/root/.cache -w /app golangci/golangci-lint:v1.54.2 golangci-lint run
+# Run tests - see fn_test.go
+$ go test ./...
 
-# Build a Docker image - see Dockerfile
-$ docker build .
-```
+# Build the function's runtime image - see Dockerfile
+$ docker build . --tag=runtime
 
-This Function can be pushed to any Docker registry. To push to xpkg.upbound.io
-use `docker push` and `docker-credential-up` from
-https://github.com/upbound/up/.
+# Build a function package - see package/crossplane.yaml
+$ crossplane xpkg build -f package --embed-runtime-image=runtime
+```
 
-[Crossplane]: https://crossplane.io
-[function-design]: https://github.com/crossplane/crossplane/blob/3996f20/design/design-doc-composition-functions.md
-[function-pr]: https://github.com/crossplane/crossplane/pull/4500
-[new-crossplane-issue]: https://github.com/crossplane/crossplane/issues/new?assignees=&labels=enhancement&projects=&template=feature_request.md
-[install-master-docs]: https://docs.crossplane.io/v1.13/software/install/#install-pre-release-crossplane-versions
-[proto-schema]: https://github.com/crossplane/function-sdk-go/blob/main/proto/v1beta1/run_function.proto
-[grpcurl]: https://github.com/fullstorydev/grpcurl
-[function-dummy]: https://github.com/crossplane-contrib/function-dummy/
+[docs-functions]: https://docs.crossplane.io/v1.14/concepts/composition-functions/
+[fn-go-templating]: https://github.com/crossplane-contrib/function-go-templating/tree/main
+[go]: https://go.dev
+[docker]: https://www.docker.com
+[cli]: https://docs.crossplane.io/latest/cli

example/composition.yaml

@@ -0,0 +1,34 @@
+apiVersion: apiextensions.crossplane.io/v1
+kind: Composition
+metadata:
+  name: example
+spec:
+  compositeTypeRef:
+    apiVersion: example.crossplane.io/v1beta1
+    kind: XR
+  mode: Pipeline
+  pipeline:
+  - step: create-a-bucket
+    functionRef:
+      name: function-go-templating
+    input:
+      apiVersion: gotemplating.fn.crossplane.io/v1beta1
+      kind: GoTemplate
+      source: Inline
+      inline:
+        template: |
+          apiVersion: s3.aws.upbound.io/v1beta1
+          kind: Bucket
+          metadata:
+            annotations:
+              gotemplating.fn.crossplane.io/composition-resource-name: bucket
+          spec:
+            forProvider:
+              region: {{ .observed.composite.resource.spec.region }}
+  # If the above Bucket becomes ready, this function will mark the XR as ready.
+  # crossplane beta render doesn't support showing whether an XR is ready, so
+  # unfortunately you'll have to trust that this is working.
+  # See https://github.com/crossplane/crossplane/issues/4810.
+  - step: automatically-detect-ready-composed-resources
+    functionRef:
+      name: function-auto-ready

examples/setup/functions.yaml → example/functions.yaml

@@ -2,13 +2,13 @@
 apiVersion: pkg.crossplane.io/v1beta1
 kind: Function
 metadata:
-  name: function-auto-ready
+  name: function-go-templating
 spec:
-  package: xpkg.upbound.io/crossplane-contrib/function-auto-ready:v0.1.0
+  package: xpkg.upbound.io/crossplane-contrib/function-go-templating:v0.0.0-20231101231317-cdb49945da4e
 ---
 apiVersion: pkg.crossplane.io/v1beta1
 kind: Function
 metadata:
-  name: function-dummy
+  name: function-auto-ready
 spec:
-  package: xpkg.upbound.io/crossplane-contrib/function-dummy:v0.2.0
+  package: xpkg.upbound.io/crossplane-contrib/function-auto-ready:v0.0.0-20231101225931-60aea09d94c8

example/xr.yaml

@@ -0,0 +1,7 @@
+# Replace this with your XR!
+apiVersion: example.crossplane.io/v1
+kind: XR
+metadata:
+  name: example-xr
+spec:
+  region: us-east-2