Skip to content

Commit aea859c

Browse files
update readme
Signed-off-by: Steven Borrelli <[email protected]>
1 parent 033c1b5 commit aea859c

File tree

5 files changed

+100
-122
lines changed

5 files changed

+100
-122
lines changed

README.md

Lines changed: 99 additions & 74 deletions
Original file line numberDiff line numberDiff line change
@@ -5,87 +5,132 @@ This composition function is a fork of the upstream [function-patch-and-transfor
55
that adds support for Conditional invocation of the function and the rendering
66
of individual resources.
77

8-
This [composition function][docs-functions] does everything Crossplane's
9-
built-in [patch & transform][docs-pandt] (P&T) composition does. Instead of
10-
specifying `spec.resources` in your Composition, you can use this function.
11-
12-
Using this function, P&T looks like this:
8+
## Installing this Function
139

1410
```yaml
15-
apiVersion: apiextensions.crossplane.io/v1
16-
kind: Composition
11+
apiVersion: pkg.crossplane.io/v1beta1
12+
kind: Function
1713
metadata:
18-
name: example
14+
name: function-conditional-patch-and-transform
15+
annotations:
16+
render.crossplane.io/runtime: Development
1917
spec:
20-
# Omitted for brevity.
21-
mode: Pipeline
18+
package: xpkg.upbound.io/borrelli-org/function-conditional-patch-and-transform:v0.3.0
19+
```
20+
21+
## What this function does
22+
23+
This function enables condition rendering of the entire function or select resources.
24+
25+
### Conditionally Running the Function
26+
27+
Composition authors express a CEL condition, and if it returns `true`, patch-and-transforms defined in the `input` will be processed.
28+
29+
```yaml
30+
mode: Pipeline
2231
pipeline:
2332
- step: patch-and-transform
2433
functionRef:
25-
name: function-conditional-patch-and-transform
34+
name: function-patch-and-transform
2635
input:
27-
apiVersion: pt.fn.crossplane.io/v1beta1
36+
apiVersion: conditional-pt.fn.crossplane.io/v1beta1
2837
kind: Resources
29-
resources:
30-
- name: bucket
31-
base:
32-
apiVersion: s3.aws.upbound.io/v1beta1
33-
kind: Bucket
34-
spec:
35-
forProvider:
36-
region: us-east-2
37-
patches:
38-
- type: FromCompositeFieldPath
39-
fromFieldPath: "spec.location"
40-
toFieldPath: "spec.forProvider.region"
41-
transforms:
42-
- type: map
43-
map:
44-
EU: "eu-north-1"
45-
US: "us-east-2"
38+
condition: observed.composite.resource.spec.env == "prod" && observed.composite.resource.spec.render == true
39+
resources: [...all your resources...]
4640
```
4741

48-
Notice that it looks very similar to native P&T. The difference is that
49-
everything is under `spec.pipeline[0].input.resources`, not `spec.resources`.
50-
This is the Function's input.
42+
Using the following XR and RunFunctionRequest inputs (click to expand):
43+
<details>
5144

52-
## Okay, but why?
45+
```yaml
46+
apiVersion: nopexample.org/v1alpha1
47+
kind: XNopResource
48+
metadata:
49+
name: test-resource
50+
spec:
51+
env: dev
52+
render: true
53+
```
5354

54-
There are a lot of good reasons to use a function to use a function to do P&T
55-
composition. In fact, it's so compelling that the Crossplane maintainers are
56-
considering deprecating native P&T. See Crossplane issue [#4746] for details.
55+
```json
56+
{
57+
"desired": {
58+
"composite": {
59+
"resource": {
60+
"apiVersion": "nopexample.org/v1alpha1",
61+
"kind": "XNopResource",
62+
"metadata": {
63+
"name": "test-resource"
64+
},
65+
"spec": {
66+
"env": "dev",
67+
"render": true
68+
}
69+
}
70+
},
71+
"resources": {
72+
"test": {
73+
"resource": {
74+
"apiVersion": "example.org/v1",
75+
"kind": "CD",
76+
"metadata": {
77+
"name": "cool-42",
78+
"namespace": "default"
79+
}
80+
}
81+
}
82+
}
83+
},
84+
"observed": {
85+
"composite": {
86+
"resource": {
87+
"apiVersion": "nopexample.org/v1alpha1",
88+
"kind": "XNopResource",
89+
"metadata": {
90+
"name": "test-resource"
91+
},
92+
"spec": {
93+
"env": "dev",
94+
"render": true
95+
},
96+
"status": {
97+
"id": "123",
98+
"ready": false
99+
}
100+
}
101+
}
102+
}
103+
}
104+
```
57105

58-
### Mix and match P&T with other functions
106+
</details>
59107

60-
With this function you can use P&T with other functions. For example you can
61-
create a desired resource using the [Go Templating][fn-go-templating] function,
62-
then patch the result using this function.
63108

64-
It's not just patches either. You can use P&T to derive composite resource
65-
connection details from a resource produced by another function, or use it to
66-
determine whether a resource produced by another function is ready
109+
You can use the [CEL Playground](https://playcel.undistro.io/?content=H4sIAAAAAAAAA%2B1UPW%2FDIBT8K4g5SeW0U9Z27tCh6sDyYl5aVAwIsNUq8n%2BvMY4dGxx16dYNuON93D04Uw4e6IGemSKEMMrRCYuc0QOJR%2F1pqSujnfA4O%2B8hi07XtkyQHgQjXtE6oVWAGVXa4BdURuJO2%2Fe7pgBpPqBgdLO8%2BSkUj3fenrV5GZMkxAo9hB4y%2BXtcQYUxkEfnt1O5c26bBHYGy7WgqJoYk2OT1DTIojjaQPK2xkWuq%2B24ngqYNHWp3KGJrNQ3fCA5K%2BY%2B5JuYTHh8yjNuq0%2FmBpRay%2B3DPhdpZDoDJV60PUEt%2FdKphYCrevaLQVVG9dGhbf4H%2B28HO83lwdfJGF9QMShR7O%2FXkgH%2FDpwTSPerVxRdZ6qlm27ETadKMKn74Fjn1BH4lU5EKDJ8d7vxxdH2B6myt7YTBQAA) to test various queries.
67110

68-
### Decouple P&T development from Crossplane core
69111

70-
When P&T development happens in a function, it's not coupled to the Crossplane
71-
release cycle. The maintainers of this function can cut releases more frequently
72-
to add new features to P&T.
112+
Here are some example queries on the XR and RunFunctionRequest:
73113

74-
It also becomes easier to fork. You could fork this function, add a new kind of
75-
transform and try it out for a few weeks before sending a PR upstream. Or, if
76-
your new feature is controversial, it's now a lot less work to maintain your own
77-
fork long term.
114+
- `desired.composite.resource.spec.env == "dev"` evaluates to `true`
115+
- `desired.composite.resource.spec.render == true,` evaluates to `true`
116+
- `desired.composite.resource.spec.render == false"` evaluates to `false`
117+
- `observed.composite.resource.status.ready == true"` evaluates to `false`
118+
- `size(desired.resources) == 0` evaluates to `false`
119+
- `"test" in desired.resources`evaluates to `true`
120+
- `"bad-resource" in desired.resources` evaluates to `false`
78121

79-
### Test P&T locally using the Crossplane CLI
122+
### Test this function locally using the Crossplane CLI
80123

81124
You can use the Crossplane CLI to run any function locally and see what composed
82125
resources it would create. This only works with functions - not native P&T.
83126

84-
For example, using the files in the [example](example) directory:
127+
For example, using the files in the [examples](examples) directory:
85128

86129
```shell
87-
$ crossplane beta render xr.yaml composition.yaml functions.yaml
130+
cd examples/conditional-rendering
131+
crossplane beta render xr.yaml composition.yaml functions.yaml
88132
```
133+
89134
Produces the following output, showing what resources Crossplane would compose:
90135

91136
```yaml
@@ -113,26 +158,6 @@ spec:
113158
See the [composition functions documentation][docs-functions] to learn how to
114159
use `crossplane beta render`.
115160

116-
## Differences from the native implementation
117-
118-
This function has a few small, intentional breaking changes compared to the
119-
native implementation.
120-
121-
These fields are now required. This makes P&T configuration less ambiguous:
122-
123-
* `resources[i].name`
124-
* `resources[i].connectionDetails[i].name`
125-
* `resources[i].connectionDetails[i].type`
126-
* `resources[i].patches[i].transforms[i].string.type`
127-
* `resources[i].patches[i].transforms[i].math.type`
128-
129-
Also, the `resources[i].patches[i].policy.mergeOptions` field is no longer
130-
supported.
131-
132-
Composition functions use Kubernetes server-side apply to intelligently merge
133-
arrays and objects. This requires merge configuration to be specified at the
134-
composed resource schema level (i.e. in CRDs) per [#4617].
135-
136161
## Developing this function
137162

138163
This function uses [Go][go], [Docker][docker], and the [Crossplane CLI][cli] to

example/composition.yaml

Lines changed: 0 additions & 33 deletions
This file was deleted.

example/functions.yaml

Lines changed: 0 additions & 7 deletions
This file was deleted.

example/xr.yaml

Lines changed: 0 additions & 7 deletions
This file was deleted.

examples/conditional-rendering/function.yaml renamed to examples/conditional-rendering/functions.yaml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,5 +5,5 @@ metadata:
55
annotations:
66
render.crossplane.io/runtime: Development
77
spec:
8-
package: index.docker.io/steve/function-conditional-patch-and-transform:v0.2.0
8+
package: xpkg.upbound.io/borrelli-org/function-conditional-patch-and-transform:v0.3.0
99
packagePullPolicy: Always

0 commit comments

Comments
 (0)