full walkthrough for get started with managed resources guide #900

jbw976 · 2025-03-27T23:40:46Z

This PR updates the "Get started with Managed Resources" guide to work with the v2 preview compatible AWS provider.

the provider version was updated to the latest build for v2
namespaced managed resources are used
a new section introduces the big change of namespaced managed resources and what they look like

Signed-off-by: Jared Watts <[email protected]>

netlify · 2025-03-27T23:41:02Z

✅ Deploy Preview for crossplane ready!

Name	Link
🔨 Latest commit	`3462331`
🔍 Latest deploy log	https://app.netlify.com/sites/crossplane/deploys/67e608d3c013db00082efe17
😎 Deploy Preview	https://deploy-preview-900--crossplane.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 71 (🟢 up 9 from production) Accessibility: 90 (🔴 down 2 from production) Best Practices: 83 (no change from production) SEO: 100 (no change from production) PWA: 70 (no change from production) View the detailed breakdown and full score reports

To edit notification comments on pull requests, go to your Netlify site configuration.

jbw976 · 2025-03-27T23:43:35Z

Just chatted with @negz about removing some additional details that aren't really necessary to be quickly successful in a getting started guide 🤓 - will take a pass through to streamline now

…ine grained details Signed-off-by: Jared Watts <[email protected]>

jbw976 · 2025-03-28T00:13:18Z

@negz pushed f78a611 to remove the fine grained details and streamline the guide 🤓

negz

Thanks @jbw976! This looks great - only blocker is my two comments WRT not specifically talking about v2 and how it's different in these getting started guides.

negz · 2025-03-28T00:31:42Z

content/v2.0-preview/get-started/get-started-with-managed-resources.md


+## About Managed Resources in Crossplane v2
+A _managed resource_ is anything Crossplane creates and manages outside of the
+Kubernetes cluster.


Should we say control plane instead of cluster?

I go back and forth. "Kubernetes cluster" is more common and likely to make more sense to most people.

On the other hand "control plane" fits more closely with our framing of what Crossplane is.

negz · 2025-03-28T00:36:47Z

content/v2.0-preview/get-started/get-started-with-managed-resources.md

+Crossplane v2 allows you to compose namespaced resources. To better support this
+new ability, managed resources (MRs) are now namespaced in Providers that have
+been updated for Crossplane v2.
+
+To support backwards compatibility while users are adopting Crossplane v2, each
+provider will offer the legacy cluster scoped MRs in addition to the new
+namespaced MRs.
+
+For example, when the AWS provider that has been upated to support Crossplane v2
+is installed during this guide, you will see two CRDs for each type of managed
+resource:
+
+1. A legacy cluster scoped MR in the `*.aws.upbound.io` API group
+1. A namespaced MR in the `*.aws.m.upbound.io` API group
+
+{{< hint type="tip" >}}
+More about namespaced managed resources can be read in the [Crossplane v2 proposal](https://github.com/crossplane/crossplane/pull/6255).
+{{< /hint >}}


I'd actually prefer to leave this detail out (in this guide at least).

Instead I'd like to completely ignore legacy topics, and just show a v2 style namespaced MR in this guide. That way folks who aren't coming from the legacy Crossplane v1 world won't need to worry about any of this.

Or another way to put it: write the v2 preview documentation as if Crossplane v1 never existed.

For folks who are coming from the legacy Crossplane v1 world I'd like to separately add a "What's new in Crossplane v2" page that explains things like this. I'm tentatively thinking we could add that under Guides, but (if possible) update the "This isn't the latest version" header to link to that guide if they're looking at a v2 page.

Got it, thanks for seeing that tone to follow here, will incorporate that.

negz · 2025-03-28T00:38:43Z

content/v2.0-preview/get-started/get-started-with-managed-resources.md

+{{< hover label="providerconfig" line="3">}}ProviderConfig{{</ hover >}}
 with the this Kubernetes configuration file:
 ```yaml {label="providerconfig",copy-lines="all"}
 cat <<EOF | kubectl apply -f -


I know this is subjective but per my rant about cat <<EOF in examples yesterday I've been omitting these here docs from the getting started with composition examples.

Instead I'm just saying (e.g.) "Save this as xrd.yaml" and showing the kubectl command to apply it.

I think we should be consistent, so I'll follow what you're doing, but I have realized when running through this guide multiple times that I do actually like the single step copy/paste that heredocs enable. As opposed to copying the content, saving it to a file, then having to get a terminal to that location too, which is more steps 😇

I made this update and when I ran through the guide to test, it definitely felt slower and more clumsy to have to save things to files and then apply them. I do prefer the zippy copy pasty heredocs! 😂

Long term I'd like to go back to a variant of what we used to do:

Add the YAML manifests as distinct files

Embed the YAML file in the examples (to avoid duplicates)

Provide a command that applies the file by URL - e.g. kubectl apply -f https://docs.crossplane.io/...

This is what Kubernetes does - e.g. https://kubernetes.io/docs/tutorials/configuration/updating-configuration-via-a-configmap/#rollout-configmap-volume

I find it to be a sweet spot. If you want to just run the example in your shell you can easily copy the command. If you want to copy the YAML and edit it in vim or YAML you don't have a weird here doc getting in the way.

negz · 2025-03-28T00:39:15Z

content/v2.0-preview/get-started/get-started-with-managed-resources.md

+## Create a namespace
+Before we can create our namespaced S3 bucket managed resource, we must create a
+namespace for it.


Can we omit this and just use the default namespace? That's what I'm doing in the Composition docs.

yes that's definitely a better approach, no need to create a new namespace 🤓

negz · 2025-03-28T00:40:50Z

content/v2.0-preview/get-started/get-started-with-managed-resources.md

+The {{< hover label="xr" line="6">}}metadata.generateName{{< /hover >}} gives a
+pattern that the provider will use to create a unique name for the bucket in S3.
+The generated name will look like `crossplane-bucket-<hash>`.


Suggested change

The {{< hover label="xr" line="6">}}metadata.generateName{{< /hover >}} gives a

pattern that the provider will use to create a unique name for the bucket in S3.

The generated name will look like `crossplane-bucket-<hash>`.

The {{< hover label="xr" line="6">}}metadata.generateName{{< /hover >}} gives a

pattern that Kubernetes will use to create a unique name for the bucket in S3.

The generated name will look like `crossplane-bucket-<hash>`.

Nit: this is more technically accurate. That said, I don't feel strongly if it feels less confusing to pretend it's the provider doing it in this context.

negz · 2025-03-28T00:44:10Z

content/v2.0-preview/get-started/get-started-with-managed-resources.md


 ## Delete the managed resource
-Before shutting down your Kubernetes cluster, delete the S3 bucket just created.
+Before shutting down your Kubernetes cluster, delete the S3 bucket that was just created.


Suggested change

Before shutting down your Kubernetes cluster, delete the S3 bucket that was just created.

Delete the S3 bucket that was just created.

Nit: Leading with "Before shutting down your Kubernetes cluster" feels weird to me for some reason here. What if they're using an existing cluster and not e.g. kind?

I'd suggest leaving it out. Maybe we could add a {{< hint >}} mentioning that it's important to delete the bucket before uninstalling Crossplane/deleting cluster/etc.

I'll remove this language from the mainline path and include it in a <hint> box.

negz · 2025-03-28T00:45:11Z

content/v2.0-preview/get-started/get-started-with-managed-resources.md

-Use `kubectl get buckets` to verify Crossplane created the bucket.
+Use `kubectl -n crossplane-aws-app get buckets.s3.aws.m.upbound.io` to verify Crossplane created the bucket.

 {{< hint type="tip" >}}


Suggested change

{{< hint type="tip" >}}

{{< hint "tip" >}}

This is an existing issue, but I noticed these aren't actually supposed to have a type=. It just happens that when you do type="tip" it doesn't know what it should be and defaults to tip. So if you do e.g. type="note" you'll get a tip instead. 🤔

ah good call out, there were 2 other "note" boxes on this page that were being displayed as tips. I'll update them all.

negz · 2025-03-28T00:45:47Z

content/v2.0-preview/get-started/get-started-with-managed-resources.md

+Crossplane v2 allows you to compose **any type of resource** into custom APIs
+for your users, which includes managed resources. Enjoy the freedom that
+Crossplane v2 gives you to compose the diverse set of resources your
+applications need for their unique environments, scenarios, and requirements.


I'd drop v2 here and just say "Crossplane".

jbw976

thanks @negz for the feedback! I'll push a commit with everything incorporated soon :)

jbw976 · 2025-03-28T01:50:00Z

content/v2.0-preview/get-started/get-started-with-managed-resources.md

+Crossplane v2 allows you to compose namespaced resources. To better support this
+new ability, managed resources (MRs) are now namespaced in Providers that have
+been updated for Crossplane v2.
+
+To support backwards compatibility while users are adopting Crossplane v2, each
+provider will offer the legacy cluster scoped MRs in addition to the new
+namespaced MRs.
+
+For example, when the AWS provider that has been upated to support Crossplane v2
+is installed during this guide, you will see two CRDs for each type of managed
+resource:
+
+1. A legacy cluster scoped MR in the `*.aws.upbound.io` API group
+1. A namespaced MR in the `*.aws.m.upbound.io` API group
+
+{{< hint type="tip" >}}
+More about namespaced managed resources can be read in the [Crossplane v2 proposal](https://github.com/crossplane/crossplane/pull/6255).
+{{< /hint >}}


Got it, thanks for seeing that tone to follow here, will incorporate that.

jbw976 · 2025-03-28T01:52:10Z

content/v2.0-preview/get-started/get-started-with-managed-resources.md

+{{< hover label="providerconfig" line="3">}}ProviderConfig{{</ hover >}}
 with the this Kubernetes configuration file:
 ```yaml {label="providerconfig",copy-lines="all"}
 cat <<EOF | kubectl apply -f -


I think we should be consistent, so I'll follow what you're doing, but I have realized when running through this guide multiple times that I do actually like the single step copy/paste that heredocs enable. As opposed to copying the content, saving it to a file, then having to get a terminal to that location too, which is more steps 😇

jbw976 · 2025-03-28T01:52:41Z

content/v2.0-preview/get-started/get-started-with-managed-resources.md

+## Create a namespace
+Before we can create our namespaced S3 bucket managed resource, we must create a
+namespace for it.


yes that's definitely a better approach, no need to create a new namespace 🤓

jbw976 · 2025-03-28T01:53:08Z

content/v2.0-preview/get-started/get-started-with-managed-resources.md

-Use `kubectl get buckets` to verify Crossplane created the bucket.
+Use `kubectl -n crossplane-aws-app get buckets.s3.aws.m.upbound.io` to verify Crossplane created the bucket.

 {{< hint type="tip" >}}


ah good call out, there were 2 other "note" boxes on this page that were being displayed as tips. I'll update them all.

jbw976 · 2025-03-28T01:53:32Z

content/v2.0-preview/get-started/get-started-with-managed-resources.md


 ## Delete the managed resource
-Before shutting down your Kubernetes cluster, delete the S3 bucket just created.
+Before shutting down your Kubernetes cluster, delete the S3 bucket that was just created.


I'll remove this language from the mainline path and include it in a <hint> box.

Signed-off-by: Jared Watts <[email protected]>

jbw976 · 2025-03-28T02:26:56Z

@negz your feedback has been incorporated in 3462331

negz · 2025-03-28T03:14:44Z

content/v2.0-preview/get-started/get-started-with-managed-resources.md

+{{< /hint >}}
+
+## Composing managed resources
+Crossplane allows you to compose **any type of resource** into custom APIs for


Vale hack: it thinks "type of" is too wordy but "kind of" is fine. 🙃

negz · 2025-03-28T03:15:26Z

content/v2.0-preview/get-started/get-started-with-managed-resources.md


-The Crossplane {{< hover label="provider" line="3" >}}Provider{{</hover>}}
+The Crossplane {{< hover label="provider" line="2" >}}Provider{{</hover>}}
 installs the Kubernetes _Custom Resource Definitions_ (CRDs) representing AWS S3
-services. These CRDs allow you to create AWS resources directly inside 
+services. These CRDs allow you to create AWS resources directly inside
 Kubernetes.


I'd like to drop all mentions of CRDs here - too much detail for this context IMO.

full walkthrough for get started with managed resources guide

0fd8146

Signed-off-by: Jared Watts <[email protected]>

Streamline getting started with managed resources guide by removing f…

f78a611

…ine grained details Signed-off-by: Jared Watts <[email protected]>

negz requested changes Mar 28, 2025

View reviewed changes

jbw976 commented Mar 28, 2025

View reviewed changes

incorporate PR feedback for get started with managed resources page

3462331

Signed-off-by: Jared Watts <[email protected]>

negz approved these changes Mar 28, 2025

View reviewed changes

negz reviewed Mar 28, 2025

View reviewed changes

negz merged commit 6a4cf06 into crossplane:master Mar 28, 2025
6 of 7 checks passed

jbw976 mentioned this pull request Apr 1, 2025

adds using secrets in a python function and cli --function-credentials #902

Closed

	Before shutting down your Kubernetes cluster, delete the S3 bucket that was just created.
	Delete the S3 bucket that was just created.

full walkthrough for get started with managed resources guide #900

full walkthrough for get started with managed resources guide #900

Uh oh!

Conversation

jbw976 commented Mar 27, 2025

Uh oh!

netlify bot commented Mar 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for crossplane ready!

Uh oh!

jbw976 commented Mar 27, 2025

Uh oh!

jbw976 commented Mar 28, 2025

Uh oh!

negz left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jbw976 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jbw976 commented Mar 28, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

netlify bot commented Mar 27, 2025 •

edited

Loading

negz left a comment •

edited

Loading