Add a getting started guide for control plane projects#1110
Conversation
✅ Deploy Preview for crossplane ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
jbw976
left a comment
jbw976
left a comment
There was a problem hiding this comment.
nice guide! the new devex tooling really is powerful and smooth 💪
I found a couple issues while walking through it using go, let me know if you have any questions about the feedback! 🙇♂️
| @@ -0,0 +1,7 @@ | |||
| --- | |||
There was a problem hiding this comment.
would it make sense to link this new guide somehow from the core crossplane docs getting started section for more visibility? i.e. maybe a placeholder page so it shows up in that nav pane, but that page then just has a short intro and link to this content?
that may make things confusing, so feel free to disregard, just thinking of more ways to make this new guide discoverable
There was a problem hiding this comment.
Good idea. I thought about adding a note in the header of the existing "get started with compositions" page, but there's already a lot of frontmatter there so it kinda gets lost. I've taken your suggestion and added a stub page in that section that links to the CLI docs. Open to suggestions on where it sits in the nav and its content.
| @@ -0,0 +1,7 @@ | |||
| --- | |||
There was a problem hiding this comment.
will you add this to v2.3 also so it shows up in latest?
There was a problem hiding this comment.
Yep, I'll copy it to v2.3 and the new v2.4. Figured it would be easier to review and update in master first :-).
| ├── operations | ||
| └── tests | ||
|
|
||
| 6 directories, 1 file |
There was a problem hiding this comment.
mine says 5 dirs and 1 file, but i don't appear to be missing anything 🔍
maybe just a mac vs linux difference?
❯ tree example-project-webapp
example-project-webapp
├── apis
├── crossplane-project.yaml
├── examples
├── functions
├── operations
└── tests
5 directories, 1 file
There was a problem hiding this comment.
Huh, weird. Must be a Linux vs. BSD tree difference. I guess Linux counts the top-level directory?
|
|
||
| The command writes the generated XRD to `apis/webapps/definition.yaml`: | ||
|
|
||
| ```yaml |
There was a problem hiding this comment.
we can consider using {copy-lines="none"} for all of these blocks that are just showing what the tooling was expected to output. we aren't expecting folks to copy/paste this anywhere right? using copy none may reduce any potential confusion.
This comment applies to a few different blocks in this doc.
| can render and run the project against a realistic input. If you generated your | ||
| XRD from an example XR, you already have the example and can skip this step. | ||
|
|
||
| Create `examples/webapp/podinfo.yaml`: |
There was a problem hiding this comment.
the directory name under apis/ was webapps, but the directory here under examples/ is singular webapp. is that intentional?
There was a problem hiding this comment.
In the up tooling we had up example generate, which used the singular kind under examples/, so I had just followed that convention. But we don't have such a command in the upstream tooling (yet, at least), and I think the consistency of apis/webapps and examples/webapps is nice, so updated to use the plural.
| functions automatically, so you only pass the example XR and the composition: | ||
|
|
||
| ```shell | ||
| crossplane composition render examples/webapp/podinfo.yaml apis/webapps/composition.yaml |
There was a problem hiding this comment.
when i run this command for the go based function/composition, i get this error:
crossplane: error: cannot build embedded functions: failed to build function "compose-webapp": failed to build runtime images: failed to build function: build: go build: exit status 1: # example.com/my-org/example-project-webapp/compose-webapp
./fn.go:124:29: undefined: corev1.ServiceAPIVersionV1 (but have ServiceApiVersionV1)
Indeed, the same error is shown for that line in my IDE by the language server, and it looks correct that ServiceApiVersionV1 is the correct casing in schemas/go/io/k8s/core/v1/core.go.
Making that change seems to fix the error and the render is able to run.
There was a problem hiding this comment.
This is due to crossplane/cli#113, which is fixed now so uppercase API should always be generated. (I actually noticed the issue while testing this guide as well!)
| deployment.apps/podinfo 3/3 3 3 45s | ||
|
|
||
| NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE | ||
| service/podinfo ClusterIP 10.96.142.110 <none> 9898/TCP 45s |
There was a problem hiding this comment.
the service is not shown in my output, but it does seem to exist. Looks like it's missing the label, I think the go code is not applying that label to the Service object.
❯ kubectl get deployment,service -l app.kubernetes.io/name=podinfo
NAME READY UP-TO-DATE AVAILABLE AGE
deployment.apps/podinfo 3/3 3 3 20s
❯ k get service
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
kubernetes ClusterIP 10.96.0.1 <none> 443/TCP 106s
podinfo ClusterIP 10.96.109.136 <none> 9898/TCP 28s
❯ k get service podinfo -o json | jq '.metadata.labels'
{
"crossplane.io/composite": "podinfo"
}
There was a problem hiding this comment.
i think this issue affects templated yaml (function-go-templating) also, but python and KCL do correctly apply the label to the service.
There was a problem hiding this comment.
Good catch - added the labels to the Go and go-templating examples so the command works consistently now.
Signed-off-by: Adam Wolfe Gordon <awg@upbound.io>
Walk users through building their first control plane project using a simple WebApp example. Signed-off-by: Adam Wolfe Gordon <awg@upbound.io>
Signed-off-by: Adam Wolfe Gordon <awg@upbound.io>
This makes the composed resources consistent with the Python and KCL implementations. Signed-off-by: Adam Wolfe Gordon <awg@upbound.io>
The `up` tooling created examples in a directory named after the singular kind, even though compositions and XRDs go in a directory named after the plural. The upstream tooling doesn't generate examples (yet), so there's no reason to stick with this convention. Pluralize the example directory to make it consistent. Signed-off-by: Adam Wolfe Gordon <awg@upbound.io>
Signed-off-by: Adam Wolfe Gordon <awg@upbound.io>
Signed-off-by: Adam Wolfe Gordon <awg@upbound.io>
2 participants
Walk users through building their first control plane project using a simple WebApp example. This guide includes two "choose your own adventure" sections: