Skip to content

Commit 09d1a64

Browse files
jbw976jbw976
authored
Merge pull request #814 from jbw976/bump-xfn-go-guide
bump go function guide to latest function-sdk-go:v0.3.0 experience
2 parents 8ebeec1 + 91e03f2 commit 09d1a64

File tree

2 files changed

+90
-48
lines changed

2 files changed

+90
-48
lines changed

‎content/master/guides/write-a-composition-function-in-go.md

Lines changed: 45 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -64,10 +64,10 @@ This guide covers each of these steps in detail.
6464

6565
To write a function in Go you need:
6666

67-
* [Go](https://go.dev/dl/) v1.21 or newer. The guide uses Go v1.21.
67+
* [Go](https://go.dev/dl/) v1.23 or newer. The guide uses Go v1.23.
6868
* [Docker Engine](https://docs.docker.com/engine/). This guide uses Engine v24.
69-
* The [Crossplane CLI]({{<ref "../cli" >}}) v1.14 or newer. This guide uses Crossplane
70-
CLI v1.14.
69+
* The [Crossplane CLI]({{<ref "../cli" >}}) v1.17 or newer. This guide uses Crossplane
70+
CLI v1.17.
7171

7272
{{<hint "note">}}
7373
You don't need access to a Kubernetes cluster or a Crossplane control plane to
@@ -84,6 +84,20 @@ as a template.
8484
```shell {copy-lines=1}
8585
crossplane xpkg init function-xbuckets function-template-go -d function-xbuckets
8686
Initialized package "function-xbuckets" in directory "/home/negz/control/negz/function-xbuckets" from https://github.com/crossplane/function-template-go/tree/91a1a5eed21964ff98966d72cc6db6f089ad63f4 (main)
87+
88+
To get started:
89+
90+
1. Replace `function-template-go` with your function in `go.mod`,
91+
`package/crossplane.yaml`, and any Go imports. (You can also do this
92+
automatically by running the `./init.sh <function-name>` script.)
93+
2. Update `input/v1beta1/` to reflect your desired input (and run `go generate`)
94+
3. Add your logic to `RunFunction` in `fn.go`
95+
4. Add tests for your logic in `fn_test.go`
96+
5. Update `README.md`, to be about your function!
97+
98+
Found init.sh script!
99+
Do you want to run it? [y]es/[n]o/[v]iew: y
100+
Function function-xbuckets has been initialised successfully
87101
```
88102

89103
The `crossplane xpkg init` command creates a directory named
@@ -92,7 +106,7 @@ this:
92106

93107
```shell {copy-lines=1}
94108
ls function-xbuckets
95-
Dockerfile fn.go fn_test.go go.mod go.sum input/ LICENSE main.go package/ README.md renovate.json
109+
Dockerfile LICENSE NOTES.txt README.md example fn.go fn_test.go go.mod go.sum init.sh input main.go package renovate.json
96110
```
97111

98112
The `fn.go` file is where you add the function's code. It's useful to know about
@@ -104,15 +118,9 @@ some other files in the template:
104118
* The `package` directory contains metadata used to build the function package.
105119

106120
{{<hint "tip">}}
107-
<!-- vale gitlab.FutureTense = NO -->
108-
<!--
109-
This tip talks about future plans for Crossplane.
110-
-->
111-
In v1.14 of the Crossplane CLI `crossplane xpkg init` just clones a
112-
template GitHub repository. A future CLI release will automate tasks like
113-
replacing the template name with the new function's name. See Crossplane issue
114-
[#4941](https://github.com/crossplane/crossplane/issues/4941) for details.
115-
<!-- vale gitlab.FutureTense = YES -->
121+
Starting with v1.15 of the Crossplane CLI, `crossplane xpkg init` gives you the
122+
option of running an initialization script to automate tasks like replacing the
123+
template name with the new function's name.
116124
{{</hint>}}
117125

118126
You must make some changes before you start adding code:
@@ -131,7 +139,7 @@ should delete the `input` and `package/input` directories.
131139

132140
The `input` directory defines a Go struct that a function can use to take input,
133141
using the `input` field from a Composition. The
134-
[composition functions]({{<ref "../concepts/compositions" >}})
142+
[composition functions]({{<ref "../concepts/compositions/#function-input" >}})
135143
documentation explains how to pass an input to a composition function.
136144

137145
The `package/input` directory contains an OpenAPI schema generated from the
@@ -417,15 +425,14 @@ This code:
417425
1. Adds one desired S3 bucket for each bucket name.
418426
1. Returns the desired S3 buckets in a `RunFunctionResponse`.
419427

420-
The code uses the `v1beta1.Bucket` type from
421-
[Upbound's AWS S3 provider](https://github.com/upbound/provider-aws). One
422-
advantage of writing a function in Go is that you can compose resources using
423-
the same strongly typed structs Crossplane uses in its providers.
428+
The code uses the `v1beta1.Bucket` type from [Upbound's AWS S3 provider](https://github.com/crossplane-contrib/provider-upjet-aws).
429+
One advantage of writing a function in Go is that you can compose resources
430+
using the same strongly typed structs Crossplane uses in its providers.
424431

425432
You must get the AWS Provider Go module to use this type:
426433

427434
```shell
428-
go get github.com/upbound/provider-aws@v0.43.0
435+
go get github.com/upbound/provider-aws@v1.14.0
429436
```
430437

431438
Crossplane provides a
@@ -447,7 +454,7 @@ command.
447454

448455
Go has rich support for unit testing. When you initialize a function from the
449456
template it adds some unit tests to `fn_test.go`. These tests follow Go's
450-
[recommendations](https://github.com/golang/go/wiki/TestComments). They use only
457+
[recommendations](https://go.dev/wiki/TestComments). They use only
451458
[`pkg/testing`](https://pkg.go.dev/testing) from the Go standard library and
452459
[`google/go-cmp`](https://pkg.go.dev/github.com/google/go-cmp/cmp).
453460

@@ -532,6 +539,9 @@ func TestRunFunction(t *testing.T) {
532539
"forProvider": {
533540
"region": "us-east-2"
534541
}
542+
},
543+
"status": {
544+
"observedGeneration": 0
535545
}
536546
}`)},
537547
"xbuckets-test-bucket-b": {Resource: resource.MustStructJSON(`{
@@ -546,10 +556,21 @@ func TestRunFunction(t *testing.T) {
546556
"forProvider": {
547557
"region": "us-east-2"
548558
}
559+
},
560+
"status": {
561+
"observedGeneration": 0
549562
}
550563
}`)},
551564
},
552565
},
566+
Conditions: []*fnv1.Condition{
567+
{
568+
Type: "FunctionSuccess",
569+
Status: fnv1.Status_STATUS_CONDITION_TRUE,
570+
Reason: "Success",
571+
Target: fnv1.Target_TARGET_COMPOSITE_AND_CLAIM.Enum(),
572+
},
573+
},
553574
},
554575
},
555576
},
@@ -575,7 +596,7 @@ func TestRunFunction(t *testing.T) {
575596

576597
Run the unit tests using the `go test` command:
577598

578-
```shell
599+
```shell {copy-lines=1}
579600
go test -v -cover .
580601
=== RUN TestRunFunction
581602
=== RUN TestRunFunction/AddTwoBuckets
@@ -589,8 +610,8 @@ ok github.com/negz/function-xbuckets 0.016s coverage: 52.6% of state
589610
You can preview the output of a Composition that uses this function using
590611
the Crossplane CLI. You don't need a Crossplane control plane to do this.
591612

592-
Create a directory under `function-xbuckets` named `example` and create
593-
Composite Resource, Composition and Function YAML files.
613+
Under `function-xbuckets`, there is a directory named `example` with Composite
614+
Resource, Composition and Function YAML files.
594615

595616
Expand the following block to see example files.
596617

@@ -771,7 +792,7 @@ then pushing all the packages to a single tag in the registry.
771792

772793
Pushing your function to a registry allows you to use your function in a
773794
Crossplane control plane. See the
774-
[composition functions documentation]({{<ref "../concepts/compositions" >}}).
795+
[composition functions documentation]({{<ref "../concepts/compositions" >}})
775796
to learn how to use a function in a control plane.
776797

777798
Use Docker to build a runtime for each platform.

‎content/v1.17/guides/write-a-composition-function-in-go.md

Lines changed: 45 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -64,10 +64,10 @@ This guide covers each of these steps in detail.
6464

6565
To write a function in Go you need:
6666

67-
* [Go](https://go.dev/dl/) v1.21 or newer. The guide uses Go v1.21.
67+
* [Go](https://go.dev/dl/) v1.23 or newer. The guide uses Go v1.23.
6868
* [Docker Engine](https://docs.docker.com/engine/). This guide uses Engine v24.
69-
* The [Crossplane CLI]({{<ref "../cli" >}}) v1.14 or newer. This guide uses Crossplane
70-
CLI v1.14.
69+
* The [Crossplane CLI]({{<ref "../cli" >}}) v1.17 or newer. This guide uses Crossplane
70+
CLI v1.17.
7171

7272
{{<hint "note">}}
7373
You don't need access to a Kubernetes cluster or a Crossplane control plane to
@@ -84,6 +84,20 @@ as a template.
8484
```shell {copy-lines=1}
8585
crossplane xpkg init function-xbuckets function-template-go -d function-xbuckets
8686
Initialized package "function-xbuckets" in directory "/home/negz/control/negz/function-xbuckets" from https://github.com/crossplane/function-template-go/tree/91a1a5eed21964ff98966d72cc6db6f089ad63f4 (main)
87+
88+
To get started:
89+
90+
1. Replace `function-template-go` with your function in `go.mod`,
91+
`package/crossplane.yaml`, and any Go imports. (You can also do this
92+
automatically by running the `./init.sh <function-name>` script.)
93+
2. Update `input/v1beta1/` to reflect your desired input (and run `go generate`)
94+
3. Add your logic to `RunFunction` in `fn.go`
95+
4. Add tests for your logic in `fn_test.go`
96+
5. Update `README.md`, to be about your function!
97+
98+
Found init.sh script!
99+
Do you want to run it? [y]es/[n]o/[v]iew: y
100+
Function function-xbuckets has been initialised successfully
87101
```
88102

89103
The `crossplane xpkg init` command creates a directory named
@@ -92,7 +106,7 @@ this:
92106

93107
```shell {copy-lines=1}
94108
ls function-xbuckets
95-
Dockerfile fn.go fn_test.go go.mod go.sum input/ LICENSE main.go package/ README.md renovate.json
109+
Dockerfile LICENSE NOTES.txt README.md example fn.go fn_test.go go.mod go.sum init.sh input main.go package renovate.json
96110
```
97111

98112
The `fn.go` file is where you add the function's code. It's useful to know about
@@ -104,15 +118,9 @@ some other files in the template:
104118
* The `package` directory contains metadata used to build the function package.
105119

106120
{{<hint "tip">}}
107-
<!-- vale gitlab.FutureTense = NO -->
108-
<!--
109-
This tip talks about future plans for Crossplane.
110-
-->
111-
In v1.14 of the Crossplane CLI `crossplane xpkg init` just clones a
112-
template GitHub repository. A future CLI release will automate tasks like
113-
replacing the template name with the new function's name. See Crossplane issue
114-
[#4941](https://github.com/crossplane/crossplane/issues/4941) for details.
115-
<!-- vale gitlab.FutureTense = YES -->
121+
Starting with v1.15 of the Crossplane CLI, `crossplane xpkg init` gives you the
122+
option of running an initialization script to automate tasks like replacing the
123+
template name with the new function's name.
116124
{{</hint>}}
117125

118126
You must make some changes before you start adding code:
@@ -131,7 +139,7 @@ should delete the `input` and `package/input` directories.
131139

132140
The `input` directory defines a Go struct that a function can use to take input,
133141
using the `input` field from a Composition. The
134-
[composition functions]({{<ref "../concepts/compositions" >}})
142+
[composition functions]({{<ref "../concepts/compositions/#function-input" >}})
135143
documentation explains how to pass an input to a composition function.
136144

137145
The `package/input` directory contains an OpenAPI schema generated from the
@@ -417,15 +425,14 @@ This code:
417425
1. Adds one desired S3 bucket for each bucket name.
418426
1. Returns the desired S3 buckets in a `RunFunctionResponse`.
419427

420-
The code uses the `v1beta1.Bucket` type from
421-
[Upbound's AWS S3 provider](https://github.com/upbound/provider-aws). One
422-
advantage of writing a function in Go is that you can compose resources using
423-
the same strongly typed structs Crossplane uses in its providers.
428+
The code uses the `v1beta1.Bucket` type from [Upbound's AWS S3 provider](https://github.com/crossplane-contrib/provider-upjet-aws).
429+
One advantage of writing a function in Go is that you can compose resources
430+
using the same strongly typed structs Crossplane uses in its providers.
424431

425432
You must get the AWS Provider Go module to use this type:
426433

427434
```shell
428-
go get github.com/upbound/provider-aws@v0.43.0
435+
go get github.com/upbound/provider-aws@v1.14.0
429436
```
430437

431438
Crossplane provides a
@@ -447,7 +454,7 @@ command.
447454

448455
Go has rich support for unit testing. When you initialize a function from the
449456
template it adds some unit tests to `fn_test.go`. These tests follow Go's
450-
[recommendations](https://github.com/golang/go/wiki/TestComments). They use only
457+
[recommendations](https://go.dev/wiki/TestComments). They use only
451458
[`pkg/testing`](https://pkg.go.dev/testing) from the Go standard library and
452459
[`google/go-cmp`](https://pkg.go.dev/github.com/google/go-cmp/cmp).
453460

@@ -532,6 +539,9 @@ func TestRunFunction(t *testing.T) {
532539
"forProvider": {
533540
"region": "us-east-2"
534541
}
542+
},
543+
"status": {
544+
"observedGeneration": 0
535545
}
536546
}`)},
537547
"xbuckets-test-bucket-b": {Resource: resource.MustStructJSON(`{
@@ -546,10 +556,21 @@ func TestRunFunction(t *testing.T) {
546556
"forProvider": {
547557
"region": "us-east-2"
548558
}
559+
},
560+
"status": {
561+
"observedGeneration": 0
549562
}
550563
}`)},
551564
},
552565
},
566+
Conditions: []*fnv1.Condition{
567+
{
568+
Type: "FunctionSuccess",
569+
Status: fnv1.Status_STATUS_CONDITION_TRUE,
570+
Reason: "Success",
571+
Target: fnv1.Target_TARGET_COMPOSITE_AND_CLAIM.Enum(),
572+
},
573+
},
553574
},
554575
},
555576
},
@@ -575,7 +596,7 @@ func TestRunFunction(t *testing.T) {
575596

576597
Run the unit tests using the `go test` command:
577598

578-
```shell
599+
```shell {copy-lines=1}
579600
go test -v -cover .
580601
=== RUN TestRunFunction
581602
=== RUN TestRunFunction/AddTwoBuckets
@@ -589,8 +610,8 @@ ok github.com/negz/function-xbuckets 0.016s coverage: 52.6% of state
589610
You can preview the output of a Composition that uses this function using
590611
the Crossplane CLI. You don't need a Crossplane control plane to do this.
591612

592-
Create a directory under `function-xbuckets` named `example` and create
593-
Composite Resource, Composition and Function YAML files.
613+
Under `function-xbuckets`, there is a directory named `example` with Composite
614+
Resource, Composition and Function YAML files.
594615

595616
Expand the following block to see example files.
596617

@@ -771,7 +792,7 @@ then pushing all the packages to a single tag in the registry.
771792

772793
Pushing your function to a registry allows you to use your function in a
773794
Crossplane control plane. See the
774-
[composition functions documentation]({{<ref "../concepts/compositions" >}}).
795+
[composition functions documentation]({{<ref "../concepts/compositions" >}})
775796
to learn how to use a function in a control plane.
776797

777798
Use Docker to build a runtime for each platform.

0 commit comments

Comments
 (0)