Skip to content

Commit 7d30add

Browse files
jbw976jbw976
committed
bump go function guide to latest function-sdk-go:v0.3.0 experience
Signed-off-by: Jared Watts <[email protected]>
1 parent 8ebeec1 commit 7d30add

File tree

2 files changed

+88
-44
lines changed

2 files changed

+88
-44
lines changed

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

Lines changed: 44 additions & 22 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,15 @@ 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
428+
The code uses the `v1beta1.Bucket` type from [Upbound's AWS S3
429+
provider](https://github.com/crossplane-contrib/provider-upjet-aws). One
422430
advantage of writing a function in Go is that you can compose resources using
423431
the same strongly typed structs Crossplane uses in its providers.
424432

425433
You must get the AWS Provider Go module to use this type:
426434

427435
```shell
428-
go get github.com/upbound/provider-aws@v0.43.0
436+
go get github.com/upbound/provider-aws@v1.14.0
429437
```
430438

431439
Crossplane provides a
@@ -447,7 +455,7 @@ command.
447455

448456
Go has rich support for unit testing. When you initialize a function from the
449457
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
458+
[recommendations](https://go.dev/wiki/TestComments). They use only
451459
[`pkg/testing`](https://pkg.go.dev/testing) from the Go standard library and
452460
[`google/go-cmp`](https://pkg.go.dev/github.com/google/go-cmp/cmp).
453461

@@ -532,6 +540,9 @@ func TestRunFunction(t *testing.T) {
532540
"forProvider": {
533541
"region": "us-east-2"
534542
}
543+
},
544+
"status": {
545+
"observedGeneration": 0
535546
}
536547
}`)},
537548
"xbuckets-test-bucket-b": {Resource: resource.MustStructJSON(`{
@@ -546,10 +557,21 @@ func TestRunFunction(t *testing.T) {
546557
"forProvider": {
547558
"region": "us-east-2"
548559
}
560+
},
561+
"status": {
562+
"observedGeneration": 0
549563
}
550564
}`)},
551565
},
552566
},
567+
Conditions: []*fnv1.Condition{
568+
{
569+
Type: "FunctionSuccess",
570+
Status: fnv1.Status_STATUS_CONDITION_TRUE,
571+
Reason: "Success",
572+
Target: fnv1.Target_TARGET_COMPOSITE_AND_CLAIM.Enum(),
573+
},
574+
},
553575
},
554576
},
555577
},
@@ -575,7 +597,7 @@ func TestRunFunction(t *testing.T) {
575597

576598
Run the unit tests using the `go test` command:
577599

578-
```shell
600+
```shell {copy-lines=1}
579601
go test -v -cover .
580602
=== RUN TestRunFunction
581603
=== RUN TestRunFunction/AddTwoBuckets
@@ -589,8 +611,8 @@ ok github.com/negz/function-xbuckets 0.016s coverage: 52.6% of state
589611
You can preview the output of a Composition that uses this function using
590612
the Crossplane CLI. You don't need a Crossplane control plane to do this.
591613

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

595617
Expand the following block to see example files.
596618

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

772794
Pushing your function to a registry allows you to use your function in a
773795
Crossplane control plane. See the
774-
[composition functions documentation]({{<ref "../concepts/compositions" >}}).
796+
[composition functions documentation]({{<ref "../concepts/compositions" >}})
775797
to learn how to use a function in a control plane.
776798

777799
Use Docker to build a runtime for each platform.

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

Lines changed: 44 additions & 22 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,15 @@ 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
428+
The code uses the `v1beta1.Bucket` type from [Upbound's AWS S3
429+
provider](https://github.com/crossplane-contrib/provider-upjet-aws). One
422430
advantage of writing a function in Go is that you can compose resources using
423431
the same strongly typed structs Crossplane uses in its providers.
424432

425433
You must get the AWS Provider Go module to use this type:
426434

427435
```shell
428-
go get github.com/upbound/provider-aws@v0.43.0
436+
go get github.com/upbound/provider-aws@v1.14.0
429437
```
430438

431439
Crossplane provides a
@@ -447,7 +455,7 @@ command.
447455

448456
Go has rich support for unit testing. When you initialize a function from the
449457
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
458+
[recommendations](https://go.dev/wiki/TestComments). They use only
451459
[`pkg/testing`](https://pkg.go.dev/testing) from the Go standard library and
452460
[`google/go-cmp`](https://pkg.go.dev/github.com/google/go-cmp/cmp).
453461

@@ -532,6 +540,9 @@ func TestRunFunction(t *testing.T) {
532540
"forProvider": {
533541
"region": "us-east-2"
534542
}
543+
},
544+
"status": {
545+
"observedGeneration": 0
535546
}
536547
}`)},
537548
"xbuckets-test-bucket-b": {Resource: resource.MustStructJSON(`{
@@ -546,10 +557,21 @@ func TestRunFunction(t *testing.T) {
546557
"forProvider": {
547558
"region": "us-east-2"
548559
}
560+
},
561+
"status": {
562+
"observedGeneration": 0
549563
}
550564
}`)},
551565
},
552566
},
567+
Conditions: []*fnv1.Condition{
568+
{
569+
Type: "FunctionSuccess",
570+
Status: fnv1.Status_STATUS_CONDITION_TRUE,
571+
Reason: "Success",
572+
Target: fnv1.Target_TARGET_COMPOSITE_AND_CLAIM.Enum(),
573+
},
574+
},
553575
},
554576
},
555577
},
@@ -575,7 +597,7 @@ func TestRunFunction(t *testing.T) {
575597

576598
Run the unit tests using the `go test` command:
577599

578-
```shell
600+
```shell {copy-lines=1}
579601
go test -v -cover .
580602
=== RUN TestRunFunction
581603
=== RUN TestRunFunction/AddTwoBuckets
@@ -589,8 +611,8 @@ ok github.com/negz/function-xbuckets 0.016s coverage: 52.6% of state
589611
You can preview the output of a Composition that uses this function using
590612
the Crossplane CLI. You don't need a Crossplane control plane to do this.
591613

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

595617
Expand the following block to see example files.
596618

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

772794
Pushing your function to a registry allows you to use your function in a
773795
Crossplane control plane. See the
774-
[composition functions documentation]({{<ref "../concepts/compositions" >}}).
796+
[composition functions documentation]({{<ref "../concepts/compositions" >}})
775797
to learn how to use a function in a control plane.
776798

777799
Use Docker to build a runtime for each platform.

0 commit comments

Comments
 (0)