Merge pull request #900 from jbw976/mr-go

full walkthrough for get started with managed resources guide

Author: negz

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

@@ -3,10 +3,13 @@ title: Get Started With Managed Resources
 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).
+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:
@@ -17,66 +20,67 @@ This quickstart requires:
 * AWS [access keys](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html#cli-configure-quickstart-creds)
 
 ## Install the AWS provider
-
-Install the AWS S3 provider into the Kubernetes cluster with a Kubernetes 
-configuration file. 
+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.21.1
-EOF
+  package: xpkg.crossplane.io/crossplane-contrib/provider-aws-s3:v1.22.0-crossplane-v2-preview.0
+```
+
+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="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.
 
-Verify the provider installed with `kubectl get providers`. 
+Verify the provider installed with `kubectl get providers`.
 
 
 ```shell {copy-lines="1",label="getProvider"}
 kubectl get providers
-NAME                                     INSTALLED   HEALTHY   PACKAGE                                                             AGE
-crossplane-contrib-provider-family-aws   True        True      xpkg.crossplane.io/crossplane-contrib/provider-family-aws:v1.21.1   30s
-provider-aws-s3                          True        True      xpkg.crossplane.io/crossplane-contrib/provider-aws-s3:v1.21.1       34s
+NAME                                     INSTALLED   HEALTHY   PACKAGE                                                                                     AGE
+crossplane-contrib-provider-family-aws   True        True      xpkg.crossplane.io/crossplane-contrib/provider-family-aws:v1.22.0-crossplane-v2-preview.0   27s
+provider-aws-s3                          True        True      xpkg.crossplane.io/crossplane-contrib/provider-aws-s3:v1.22.0-crossplane-v2-preview.0       31s
 ```
 
 The S3 Provider installs a second Provider, the
-{{<hover label="getProvider" line="4">}}crossplane-contrib-provider-family-aws{{</hover >}}.   
+{{<hover label="getProvider" line="4">}}crossplane-contrib-provider-family-aws{{</hover >}}.
 The family provider manages authentication to AWS across all AWS family
-Providers. 
+Providers.
 
-
-You can view the new CRDs with `kubectl get crds`.  
+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" >}}
-See details about all the supported CRDs in the 
+{{< 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 >}}
 
 ## Create a Kubernetes secret for AWS
-The provider requires credentials to create and manage AWS resources.  
+The provider requires credentials to create and manage AWS resources.
 Providers use a Kubernetes _Secret_ to connect the credentials to the provider.
 
-Generate a Kubernetes _Secret_ from your AWS key-pair and 
+Generate a Kubernetes _Secret_ from your AWS key-pair and
 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. 
+For basic user authentication, use an AWS Access keys key-pair file.
 
-{{< hint type="tip" >}}
-The [AWS documentation](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html#cli-configure-quickstart-creds) 
+{{< 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 >}}
 
-Create a text file containing the AWS account `aws_access_key_id` and `aws_secret_access_key`.  
+Create a text file containing the AWS account `aws_access_key_id` and `aws_secret_access_key`.
 
 {{< editCode >}}
 ```ini {copy-lines="all"}
@@ -88,17 +92,17 @@ 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 >}}
 
 ### Create a Kubernetes secret with the AWS credentials
-A Kubernetes generic secret has a name and contents.  
-Use 
-{{< hover label="kube-create-secret" line="1">}}kubectl create secret{{</hover >}}  
-to generate the secret object named 
-{{< hover label="kube-create-secret" line="2">}}aws-secret{{< /hover >}}  
-in the {{< hover label="kube-create-secret" line="3">}}crossplane-system{{</ hover >}} namespace.  
+A Kubernetes generic secret has a name and contents.
+Use
+{{< hover label="kube-create-secret" line="1">}}kubectl create secret{{</hover >}}
+to generate the secret object named
+{{< hover label="kube-create-secret" line="2">}}aws-secret{{< /hover >}}
+in the {{< hover label="kube-create-secret" line="3">}}crossplane-system{{</ hover >}} namespace.
 
 Use the {{< hover label="kube-create-secret" line="4">}}--from-file={{</hover>}} argument to set the value to the contents of the  {{< hover label="kube-create-secret" line="4">}}aws-credentials.txt{{< /hover >}} file.
 
@@ -109,35 +113,11 @@ generic aws-secret \
 --from-file=creds=./aws-credentials.txt
 ```
 
-View the secret with `kubectl describe secret`
-
-{{< hint type="note" >}}
-The size may be larger if there are extra blank spaces in your text file.
-{{< /hint >}}
-
-```shell {copy-lines="1"}
-kubectl describe secret aws-secret -n crossplane-system
-Name:         aws-secret
-Namespace:    crossplane-system
-Labels:       <none>
-Annotations:  <none>
-
-Type:  Opaque
-
-Data
-====
-creds:  114 bytes
-```
-
 ## 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:
@@ -149,83 +129,83 @@ 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>}}.
+Save this to a file called `providerconfig.yaml`, then apply it with:
 
-The 
-{{< hover label="providerconfig" line="11">}}spec.credentials.secretRef.name{{< /hover >}} 
-value is the name of the Kubernetes secret containing the AWS credentials in the 
-{{< hover label="providerconfig" line="10">}}spec.credentials.secretRef.namespace{{< /hover >}}.
+```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
-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_.
-
-{{< hint type="note" >}}
-AWS S3 bucket names must be globally unique. To generate a unique name the example uses a random hash. 
+{{< 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 -
-apiVersion: s3.aws.upbound.io/v1beta1
+```yaml {label="bucket"}
+apiVersion: s3.aws.m.upbound.io/v1beta1
 kind: Bucket
 metadata:
+  namespace: default
   generateName: crossplane-bucket-
 spec:
   forProvider:
     region: us-east-2
   providerConfigRef:
     name: default
-EOF
 ```
 
-The {{< hover label="xr" line="2">}}apiVersion{{< /hover >}} and 
-{{< hover label="xr" line="3">}}kind{{</hover >}} are from the provider's CRDs.
-
-
-The {{< hover label="xr" line="5">}}metadata.generateName{{< /hover >}} value is the 
-name of the created S3 bucket in AWS.  
-This example uses the generated name `crossplane-bucket-<hash>` in the 
-{{< hover label="xr" line="5">}}$bucket{{</hover >}} variable.
+Save this to a file called `bucket.yaml`, then apply it with:
 
-The {{< hover label="xr" line="8">}}spec.forProvider.region{{< /hover >}} tells 
-AWS which AWS region to use when deploying resources.  
+```shell {label="kube-create-bucket",copy-lines="all"}
+kubectl create -f bucket.yaml
+```
 
-The region can be any 
-[AWS Regional endpoint](https://docs.aws.amazon.com/general/latest/gr/rande.html#regional-endpoints) code.
+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 get buckets` 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" >}}
-Crossplane created the bucket when the values `READY` and `SYNCED` are `True`.  
-This may take up to 5 minutes.  
+{{< 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 get buckets
-NAME                      READY   SYNCED   EXTERNAL-NAME             AGE
-crossplane-bucket-hhdzh   True    True     crossplane-bucket-hhdzh   5s
+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 just created.
-
-Use `kubectl delete bucket <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 delete bucket crossplane-bucket-hhdzh
-bucket.s3.aws.upbound.io "crossplane-bucket-hhdzh" deleted
+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 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.
+
 ## Next steps
-* Join the [Crossplane Slack](https://slack.crossplane.io/) and connect with 
+* Join the [Crossplane Slack](https://slack.crossplane.io/) and connect with
   Crossplane users and contributors.