incorporate PR feedback for get started with managed resources page

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

Author: jbw976

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

@@ -6,6 +6,10 @@ weight: 200
 Connect Crossplane to AWS to create and manage cloud resources from Kubernetes
 with [provider-upjet-aws](https://github.com/crossplane-contrib/provider-upjet-aws).
 
+A _managed resource_ is anything Crossplane creates and manages outside of the
+control plane.
+
+This guide creates an AWS S3 bucket with Crossplane. The S3 bucket is a _managed resource_.
 
 ## Prerequisites
 This quickstart requires:
@@ -15,50 +19,25 @@ This quickstart requires:
 * An AWS account with permissions to create an S3 storage bucket
 * AWS [access keys](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html#cli-configure-quickstart-creds)
 
-## About Managed Resources in Crossplane v2
-A _managed resource_ is anything Crossplane creates and manages outside of the
-Kubernetes cluster.
-
-This guide creates an AWS S3 bucket with Crossplane.
-
-The S3 bucket is a _managed resource_.
-
-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 >}}
-
 ## Install the AWS provider
-
 Install the AWS S3 provider into the Kubernetes cluster with a Kubernetes
 configuration file.
 
 ```yaml {label="provider",copy-lines="all"}
-cat <<EOF | kubectl apply -f -
 apiVersion: pkg.crossplane.io/v1
 kind: Provider
 metadata:
   name: provider-aws-s3
 spec:
   package: xpkg.crossplane.io/crossplane-contrib/provider-aws-s3:v1.22.0-crossplane-v2-preview.0
-EOF
 ```
 
-The Crossplane {{< hover label="provider" line="3" >}}Provider{{</hover>}}
+Save this to a file called `provider.yaml`, then apply it with:
+```shell {label="kube-apply-provider",copy-lines="all"}
+kubectl apply -f provider.yaml
+```
+
+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
 Kubernetes.
@@ -81,7 +60,7 @@ Providers.
 You can view the new CRDs with `kubectl get crds`.
 Every CRD maps to a unique AWS service Crossplane can provision and manage.
 
-{{< hint type="tip" >}}
+{{< hint "tip" >}}
 See details about all the supported CRDs in the
 [provider examples](https://github.com/crossplane-contrib/provider-upjet-aws/tree/main/examples).
 {{< /hint >}}
@@ -96,7 +75,7 @@ then configure the Provider to use it.
 ### Generate an AWS key-pair file
 For basic user authentication, use an AWS Access keys key-pair file.
 
-{{< hint type="tip" >}}
+{{< hint "tip" >}}
 The [AWS documentation](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html#cli-configure-quickstart-creds)
 provides information on how to generate AWS Access keys.
 {{< /hint >}}
@@ -113,7 +92,7 @@ aws_secret_access_key = $@<aws_secret_key>$@
 
 Save this text file as `aws-credentials.txt`.
 
-{{< hint type="note" >}}
+{{< hint "note" >}}
 The [Authentication](https://docs.upbound.io/providers/provider-aws/authentication/) section of the AWS Provider documentation describes other authentication methods.
 {{< /hint >}}
 
@@ -135,14 +114,10 @@ generic aws-secret \
 ```
 
 ## Create a ProviderConfig
-A {{< hover label="providerconfig" line="3">}}ProviderConfig{{</ hover >}}
-customizes the settings of the AWS Provider.
+A {{< hover label="providerconfig" line="2">}}ProviderConfig{{</ hover >}}
+customizes the settings of the AWS Provider:
 
-Apply the
-{{< hover label="providerconfig" line="3">}}ProviderConfig{{</ hover >}}
-with the this Kubernetes configuration file:
 ```yaml {label="providerconfig",copy-lines="all"}
-cat <<EOF | kubectl apply -f -
 apiVersion: aws.upbound.io/v1beta1
 kind: ProviderConfig
 metadata:
@@ -154,73 +129,79 @@ spec:
       namespace: crossplane-system
       name: aws-secret
       key: creds
-EOF
 ```
 
-This attaches the AWS credentials, saved as a Kubernetes secret, as a
-{{< hover label="providerconfig" line="9">}}secretRef{{</ hover>}}.
-
-## Create a namespace
-Before we can create our namespaced S3 bucket managed resource, we must create a
-namespace for it.
+Save this to a file called `providerconfig.yaml`, then apply it with:
 
-```shell {label="kube-create-namespace",copy-lines="all"}
-kubectl create namespace crossplane-aws-app
+```shell {label="kube-apply-providerconfig",copy-lines="all"}
+kubectl apply -f providerconfig.yaml
 ```
 
+This attaches the AWS credentials, saved as a Kubernetes secret, as a
+{{< hover label="providerconfig" line="8">}}secretRef{{</ hover>}}.
+
 ## Create a managed resource
-{{< hint type="note" >}}
+{{< hint "note" >}}
 AWS S3 bucket names must be globally unique. To generate a unique name the example uses a random hash.
 Any unique name is acceptable.
 {{< /hint >}}
 
-```yaml {label="xr"}
-cat <<EOF | kubectl create -f -
+```yaml {label="bucket"}
 apiVersion: s3.aws.m.upbound.io/v1beta1
 kind: Bucket
 metadata:
-  namespace: crossplane-aws-app
+  namespace: default
   generateName: crossplane-bucket-
 spec:
   forProvider:
     region: us-east-2
   providerConfigRef:
     name: default
-EOF
 ```
 
-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.
+Save this to a file called `bucket.yaml`, then apply it with:
+
+```shell {label="kube-create-bucket",copy-lines="all"}
+kubectl create -f bucket.yaml
+```
+
+The {{< hover label="bucket" line="5">}}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>`.
 
-Use `kubectl -n crossplane-aws-app get buckets.s3.aws.m.upbound.io` to verify Crossplane created the bucket.
+Use `kubectl -n default get buckets.s3.aws.m.upbound.io` to verify Crossplane created the bucket.
 
-{{< hint type="tip" >}}
+{{< hint "tip" >}}
 Crossplane created the bucket when the values `READY` and `SYNCED` are `True`.
 This may take up to 5 minutes.
 {{< /hint >}}
 
 ```shell {copy-lines="1"}
-kubectl -n crossplane-aws-app get buckets.s3.aws.m.upbound.io
+kubectl -n default get buckets.s3.aws.m.upbound.io
 NAME                      SYNCED   READY   EXTERNAL-NAME             AGE
 crossplane-bucket-7tfcj   True     True    crossplane-bucket-7tfcj   3m4s
 ```
 
 ## Delete the managed resource
-Before shutting down your Kubernetes cluster, delete the S3 bucket that was just created.
-
-Use `kubectl -n crossplane-aws-app delete buckets.s3.aws.m.upbound.io <bucketname>` to remove the bucket.
+When you are finished with your S3 bucket, use `kubectl -n default
+delete buckets.s3.aws.m.upbound.io <bucketname>` to remove the bucket.
 
 ```shell {copy-lines="1"}
-kubectl -n crossplane-aws-app delete buckets.s3.aws.m.upbound.io crossplane-bucket-7tfcj
+kubectl -n default delete buckets.s3.aws.m.upbound.io crossplane-bucket-7tfcj
 bucket.s3.aws.m.upbound.io "crossplane-bucket-7tfcj" deleted
 ```
 
+{{< hint "important" >}}
+Make sure to delete the S3 bucket before uninstalling the provider or shutting
+down your control plane. If those are no longer running, they can't clean up any
+managed resources and you would need to do so manually.
+{{< /hint >}}
+
 ## Composing managed resources
-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.
+Crossplane allows you to compose **any type of resource** into custom APIs for
+your users, which includes managed resources. Enjoy the freedom that Crossplane
+gives you to compose the diverse set of resources your applications need for
+their unique environments, scenarios, and requirements.
 
 Follow [Get Started with Composition]({{<ref "../get-started/get-started-with-composition">}})
 to learn more about how composition works.