Slim down the README

negz · negz · commit ec96a6dfdc1e · 2023-11-01T17:14:56.000-07:00
Signed-off-by: Nic Cope &lt;nicc@rk0n.org&gt;
diff --git a/README.md b/README.md
@@ -1,38 +1,19 @@
 # function-patch-and-transform
+[![CI](https://github.com/crossplane-contrib/function-patch-and-transform/actions/workflows/ci.yml/badge.svg)](https://github.com/crossplane-contrib/function-patch-and-transform/actions/workflows/ci.yml) ![GitHub release (latest SemVer)](https://img.shields.io/github/release/crossplane-contrib/function-patch-and-transform)
 
-A [Crossplane] Composition Function that implements P&T-style Composition.
+This [composition function][docs-functions] does everything Crossplane's
+built-in [patch & transform][docs-pandt] (P&T) composition does. Instead of
+specifying `spec.resources` in your Composition, you can use this function.
 
-```yaml
-apiVersion: pkg.crossplane.io/v1beta1
-kind: Function
-metadata:
-  name: function-patch-and-transform
-spec:
-  package: xpkg.upbound.io/crossplane-contrib/function-patch-and-transform:v0.1.4
-```
-
-## What is this?
-
-This [Composition Function][function-design] does everything Crossplane's built-in Patch &
-Transform Composition does. Instead of specifying `spec.resources` in your
-Composition, you can use this Function.
-
-Note that this is a beta-style Function. It won't work with Crossplane v1.13 or
-earlier - it targets the [implementation of Functions][function-pr] coming with
-Crossplane v1.14 in late October.
-
-Take [this example][docs-composition] from https://docs.crossplane.io. Using
-this Function, it would look like this:
+Using this function, P&T looks like this:
 
 ```yaml
 apiVersion: apiextensions.crossplane.io/v1
 kind: Composition
 metadata:
-  name: dynamo-with-bucket
+  name: example
 spec:
-  compositeTypeRef:
-    apiVersion: database.example.com/v1alpha1
-    kind: NoSQL
+  # Omitted for brevity.
   mode: Pipeline
   pipeline:
   - step: patch-and-transform
@@ -42,40 +23,14 @@ spec:
       apiVersion: pt.fn.crossplane.io/v1beta1
       kind: Resources
       resources:
-      - name: s3Bucket
+      - name: bucket
         base:
           apiVersion: s3.aws.upbound.io/v1beta1
           kind: Bucket
-          metadata:
-            name: crossplane-quickstart-bucket
           spec:
             forProvider:
               region: us-east-2
         patches:
-        - type: FromCompositeFieldPath
-          fromFieldPath: "location"
-          toFieldPath: "spec.forProvider.region"
-          transforms:
-          - type: map
-            map: 
-              EU: "eu-north-1"
-              US: "us-east-2"
-      - name: dynamoDB
-        base:
-          apiVersion: dynamodb.aws.upbound.io/v1beta1
-          kind: Table
-          metadata:
-            name: crossplane-quickstart-database
-          spec:
-            forProvider:
-              region: "us-east-2"
-              writeCapacity: 1
-              readCapacity: 1
-              attribute:
-              - name: S3ID
-                type: S
-              hashKey: S3ID
-        patches:
         - type: FromCompositeFieldPath
           fromFieldPath: "spec.location"
           toFieldPath: "spec.forProvider.region"
@@ -86,168 +41,120 @@ spec:
               US: "us-east-2"
 ```
 
-Notice that it looks pretty much identical to the example from the Crossplane
-documentation. The key difference is that everything that used to be under
-`spec.resources` is now nested a little deeper. Specifically, it's under
-`spec.pipeline[0].input.resources` (i.e. in the Function's input).
+Notice that it looks very similar to native P&T. The difference is that
+everything is under `spec.pipeline[0].input.resources`, not `spec.resources`.
+This is the Function's input.
 
 ## Okay, but why?
 
-I think there are a _lot_ of good reasons to implement P&T Composition as a
-Function. In fact, I would go so far as to propose that once Functions are a GA
-feature we deprecate support for 'native' P&T (i.e. `spec.resources`). We can't
-remove it - that would be a breaking change - but we can freeze its API and
-suggest folks use the P&T Function instead.
+There are a lot of good reasons to use a function to use a function to do P&T
+composition. In fact, it's so compelling that the Crossplane maintainers are
+considering deprecating native P&T. See Crossplane issue [#4746] for details.
 
-### Run P&T anywhere in your pipeline
+### Mix and match P&T with other functions
 
-Native P&T can only run before the Composition Function pipeline. In the [draft
-beta implementation of Functions][function-pr] Crossplane does all the patching
-and transforming first, then sends the results through the Function pipeline.
+With this function you can use P&T with other functions. For example you can
+create a desired resource using the [Go Templating][fn-go-templating] function,
+then patch the result using this function.
 
-This is handy, but what if you wanted to run another Function (like rendering
-some Go templates) first, then pass the result of that Function to be patched
-and transformed? With this Function you can do that:
-
-```yaml
- apiVersion: apiextensions.crossplane.io/v1
-kind: Composition
-metadata:
-  name: dynamo-with-bucket
-spec:
-  compositeTypeRef:
-    apiVersion: database.example.com/v1alpha1
-    kind: NoSQL
-  # This pipeliene renders some Go templates, then passes them to P&T
-  pipeline:
-  - step: render-go-templates
-    functionRef:
-      name: function-go-templates
-    input: {} # Omitted for brevity :)
-  - step: patch-and-transform
-    functionRef:
-      name: function-patch-and-transform
-    input:
-      apiVersion: pt.fn.crossplane.io/v1beta1
-      kind: Resources
-      resources:
-        # Notice that my-cool-bucket doesn't have a base template. As long as
-        # the render-go-templates step above rendered a composed resource with
-        # this name, this Function will patch it.
-      - name: my-cool-bucket
-        patches:
-        - type: FromCompositeFieldPath
-          fromFieldPath: "location"
-          toFieldPath: "spec.forProvider.region"
-          transforms:
-          - type: map
-            map: 
-              EU: "eu-north-1"
-              US: "us-east-2"
-```
-
-It's not just patches either - you can use P&T to derive XR connection details
-from a resource produced by another Function too, or use it to determine whether
-a resource produced by another Function is ready
+It's not just patches either. You can use P&T to derive composite resource
+connection details from a resource produced by another function, or use it to
+determine whether a resource produced by another function is ready
 
 ### Decouple P&T development from Crossplane core
 
-When P&T development happens in a Function, it's not coupled to the Crossplane
-release cycle. The Function developers could cut releases more frequently to add
-new features to P&T.
-
-Plus, because it's just a Function, it becomes easier to fork. You could fork
-this Function, add a new kind of transform and try it out for a few weeks in
-your development environment before sending a PR upstream. Or, if your new
-feature is controversial, it's now a lot less work to maintain your own fork
-long term.
+When P&T development happens in a function, it's not coupled to the Crossplane
+release cycle. The maintainers of this function can cut releases more frequently
+to add new features to P&T.
 
-### Makes P&T code more portable
+It also becomes easier to fork. You could fork this function, add a new kind of
+transform and try it out for a few weeks before sending a PR upstream. Or, if
+your new feature is controversial, it's now a lot less work to maintain your own
+fork long term.
 
-A lot of building a better developer experience around Composition comes down to
-shifting left - letting you run and test your Compositions when you're
-developing them. Historically this has been tough. You need to spin up a `kind`
-cluster, install Crossplane, install providers, etc. 
-
-```bash
-$ xp composition render xr.yaml composition.yaml
-```
+### Test P&T locally using the Crossplane CLI
 
-You could imagine a CLI tool like the above helping a lot. The problem with
-building tools like this in the past has been that they need to share
-Crossplane's Composition logic. We could make Composition a library, but then
-you'd need to make sure that the version of `xp` on your laptop used the same
-Composition library as your control planes, or you might see different results
-than you expected in production.
+You can use the Crossplane CLI to run any function locally and see what composed
+resources it would create. This only works with functions - not native P&T.
 
-When all Composition logic is encapsulated in Functions - i.e. versioned OCI
-containers with a standard RPC - building a tool like this becomes much easier.
-Just tell the CLI what Function versions you're using in production and it can
-pull them down and use them to render your Composition.
+For example, using the files in the [example](example) directory:
 
-### Makes Crossplane's Composition implementation simpler
-
-If we can make the _native_ P&T implementation and Functions mutually exclusive,
-Crossplane's Composition implementation is dramatically less complex. This means 
-it's easier to maintain and much less likely to be buggy.
+```shell
+$ crossplane beta render xr.yaml composition.yaml functions.yaml
+```
+Produces the following output, showing what resources Crossplane would compose:
 
-Moving P&T inside a Function makes this possible - you can still use 'both' P&T
-and Functions, you'd just do it by... using Functions.
+```yaml
+---
+apiVersion: example.crossplane.io/v1
+kind: XR
+metadata:
+  name: example-xr
+---
+apiVersion: s3.aws.upbound.io/v1beta1
+kind: Bucket
+metadata:
+  annotations:
+    crossplane.io/composition-resource-name: bucket
+  generateName: example-xr-
+  labels:
+    crossplane.io/composite: example-xr
+  ownerReferences:
+    # Omitted for brevity
+spec:
+  forProvider:
+    region: us-east-2
+```
 
-Eventually, if enough P&T users switch to this Function we may be able to remove
-native support for P&T altogether.
+See the [composition functions documentation][docs-functions] to learn how to
+use `crossplane beta render`.
 
 ## Differences from the native implementation
 
-This Function has a few small, intentional breaking changes compared to the
-native implementation. Making the below fields required makes P&T configuration
-a lot more explicit and less ambiguous.
-
-* `resources[i].name` is now a required field.
-* `resources[i].connectionDetails[i].name` is now a required field
-* `resources[i].connectionDetails[i].type` is now a required field
-* `resources[i].patches[i].transforms[i].string.type` is now a required field
-* `resources[i].patches[i].transforms[i].math.type` is now a required field
-* `resources[i].patches[i].policy.mergeOptions` is no longer supported
+This function has a few small, intentional breaking changes compared to the
+native implementation.
 
-Functions use Kubernetes server-side apply, not `mergeOptions`, to intelligently
-merge arrays and objects. This requires merge configuration to be specified at
-the composed resource schema level (i.e. in CRDs) per [#4617].
+These fields are now required. This makes P&T configuration less ambiguous:
 
-## Known issues
+* `resources[i].name`
+* `resources[i].connectionDetails[i].name`
+* `resources[i].connectionDetails[i].type`
+* `resources[i].patches[i].transforms[i].string.type`
+* `resources[i].patches[i].transforms[i].math.type`
 
-The initial implementation has the following limitations:
+Also, the `resources[i].patches[i].policy.mergeOptions` field is no longer
+supported.
 
-* `EnvironmentConfig` and its associated patches aren't supported yet. This is
-  just because Crossplane doesn't yet send the `EnvironmentConfig` along with
-  the `RunFunctionRequest`. Once we do, these should be easy to (re)implement.
-  Adding support at the Functions level is tracked in [#4632].
+Composition functions use Kubernetes server-side apply to intelligently merge
+arrays and objects. This requires merge configuration to be specified at the
+composed resource schema level (i.e. in CRDs) per [#4617].
 
-## Developing
+## Developing this function
 
-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:
+This function uses [Go][go], [Docker][docker], and the [Crossplane CLI][cli] to
+build functions.
 
 ```shell
 # Run code generation - see input/generate.go
 $ go generate ./...
 
-# Run tests
-$ go test -cover ./...
-?       github.com/crossplane-contrib/function-patch-and-transform/input/v1beta1      [no test files]
-ok      github.com/crossplane-contrib/function-patch-and-transform    0.021s  coverage: 76.1% of statements
+# Run tests - see fn_test.go
+$ go test ./...
 
-# 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
+# Build the function's runtime image - see Dockerfile
+$ docker build . --tag=runtime
 
-# Build a Docker image - see Dockerfile
-$ docker build .
+# 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
-[docs-composition]: https://docs.crossplane.io/v1.13/getting-started/provider-aws-part-2/#create-a-deployment-template
+[docs-composition]: https://docs.crossplane.io/v1.14/getting-started/provider-aws-part-2/#create-a-deployment-template
+[docs-functions]: https://docs.crossplane.io/v1.14/concepts/composition-functions/
+[docs-pandt]: https://docs.crossplane.io/v1.14/concepts/patch-and-transform/
+[fn-go-templating]: https://github.com/crossplane-contrib/function-go-templating
 [#4617]: https://github.com/crossplane/crossplane/issues/4617
-[#4632]: https://github.com/crossplane/crossplane/pull/4632
+[#4746]: https://github.com/crossplane/crossplane/issues/4746
+[go]: https://go.dev
+[docker]: https://www.docker.com
+[cli]: https://docs.crossplane.io/latest/cli
diff --git a/example/composition.yaml b/example/composition.yaml
@@ -0,0 +1,33 @@
+apiVersion: apiextensions.crossplane.io/v1
+kind: Composition
+metadata:
+  name: function-patch-and-transform
+spec:
+  compositeTypeRef:
+    apiVersion: example.crossplane.io/v1
+    kind: XR
+  mode: Pipeline
+  pipeline:
+  - step: patch-and-transform
+    functionRef:
+      name: function-patch-and-transform
+    input:
+      apiVersion: pt.fn.crossplane.io/v1beta1
+      kind: Resources
+      resources:
+      - name: bucket
+        base:
+          apiVersion: s3.aws.upbound.io/v1beta1
+          kind: Bucket
+          spec:
+            forProvider:
+              region: us-east-2
+        patches:
+        - type: FromCompositeFieldPath
+          fromFieldPath: "location"
+          toFieldPath: "spec.forProvider.region"
+          transforms:
+          - type: map
+            map: 
+              EU: "eu-north-1"
+              US: "us-east-2"
diff --git a/example/functions.yaml b/example/functions.yaml
@@ -0,0 +1,7 @@
+---
+apiVersion: pkg.crossplane.io/v1beta1
+kind: Function
+metadata:
+  name: function-patch-and-transform
+spec:
+  package: xpkg.upbound.io/crossplane-contrib/function-patch-and-transform:v0.1.4
diff --git a/example/xr.yaml b/example/xr.yaml
@@ -0,0 +1,7 @@
+# Replace this with your XR!
+apiVersion: example.crossplane.io/v1
+kind: XR
+metadata:
+  name: example-xr
+spec:
+  location: US
