From b4bb9382cfdab4fda304a4a16174720fa58b0eaa Mon Sep 17 00:00:00 2001 From: Pete Lumbis Date: Sat, 11 Feb 2023 11:00:23 -0500 Subject: [PATCH] Fix AWS quickstart bugs (#357) Resolves https://github.com/crossplane/docs/issues/356 --- content/v1.10/reference/troubleshoot.md | 8 +- .../getting-started/provider-aws-part-2.md | 104 ++++++++++-------- .../getting-started/provider-aws-part-3.md | 26 ++--- content/v1.11/getting-started/provider-aws.md | 12 +- 4 files changed, 85 insertions(+), 65 deletions(-) diff --git a/content/v1.10/reference/troubleshoot.md b/content/v1.10/reference/troubleshoot.md index 51ba002d..88cf8b70 100644 --- a/content/v1.10/reference/troubleshoot.md +++ b/content/v1.10/reference/troubleshoot.md @@ -12,7 +12,9 @@ indicator that the kubectl Crossplane you're using is outdated. In other words some Crossplane API has been graduated from alpha to beta or stable and the old plugin is not aware of this change. -You can follow the [install Crossplane CLI] instructions to upgrade the plugin. +You can follow the +[install Crossplane CLI]({{}}) +instructions to upgrade the plugin. ## Resource Status and Conditions @@ -179,7 +181,7 @@ kubectl patch cloudsqlinstance my-db -p '{"metadata":{"finalizers": []}}' --type ## Installing Crossplane Package -After installing [Crossplane package], to verify the install results or +After installing [Crossplane package]({{}}), to verify the install results or troubleshoot any issue spotted during the installation, there are a few things you can do. @@ -260,7 +262,6 @@ spec: [Requested Resource Not Found]: #requested-resource-not-found -[install Crossplane CLI]: "../getting-started/install-configure" [Resource Status and Conditions]: #resource-status-and-conditions [Resource Events]: #resource-events [Crossplane Logs]: #crossplane-logs @@ -269,6 +270,5 @@ spec: [Pausing Providers]: #pausing-providers [Deleting When a Resource Hangs]: #deleting-when-a-resource-hangs [Installing Crossplane Package]: #installing-crossplane-package -[Crossplane package]: "../concepts/packages" [Handling Crossplane Package Dependency]: #handling-crossplane-package-dependency [semver spec]: https://github.com/Masterminds/semver#basic-comparisons diff --git a/content/v1.11/getting-started/provider-aws-part-2.md b/content/v1.11/getting-started/provider-aws-part-2.md index 277b95fd..cbf917bf 100644 --- a/content/v1.11/getting-started/provider-aws-part-2.md +++ b/content/v1.11/getting-started/provider-aws-part-2.md @@ -50,12 +50,14 @@ spec: EOF ``` -3. Create a file with your AWS keys -```ini +3. Create a file called `aws-credentials.txt` with your AWS keys +{{< editCode >}} +```ini {copy-lines="all"} [default] -aws_access_key_id = -aws_secret_access_key = +aws_access_key_id = $$$$ +aws_secret_access_key = $$$$ ``` +{{}} 4. Create a Kubernetes secret from the AWS keys ```shell {label="kube-create-secret",copy-lines="all"} @@ -100,6 +102,11 @@ To create a _composition_, first define each individual managed resource. ### Create an S3 bucket object Define a `bucket` resource using the configuration from the previous section: +{{< hint "note" >}} +Don't apply this configuration. This YAML is part of a larger +definition. +{{< /hint >}} + ```yaml apiVersion: s3.aws.upbound.io/v1beta1 kind: Bucket @@ -176,7 +183,7 @@ Create any {{}}name{{}} for this _comp apiVersion: apiextensions.crossplane.io/v1 kind: Composition metadata: - name: dynamodb-with-s3 + name: dynamodb-with-bucket ``` Add the resources to the @@ -193,7 +200,7 @@ key. apiVersion: apiextensions.crossplane.io/v1 kind: Composition metadata: - name: dynamodb-with-s3 + name: dynamodb-with-bucket spec: resources: - name: s3-bucket @@ -235,6 +242,10 @@ _Compositions_ do this with the {{}}spec.compositeTypeRef{{}} definition. +{{< hint "tip" >}} +Crossplane recommends prefacing the `kind` with an `X` to show it's a Composition. +{{< /hint >}} + ```yaml {label="compRef"} apiVersion: apiextensions.crossplane.io/v1 kind: Composition @@ -252,7 +263,7 @@ A _composite resource_ is actually a custom Kubernetes API type you define. The platform team controls the kind, API endpoint and version. - + With this {{}}spec.compositeTypeRef{{}} Crossplane only allows _composite resources_ from the API group {{}}custom-api.example.org{{}} @@ -269,7 +280,7 @@ cat <}}name{{}} is the new API endpoint. +{{< hint "tip" >}} +Crossplane recommends using a plural name for the _XRD_ +{{}}name{{}}. +{{< /hint >}} + ```yaml {label="xrdName"} apiVersion: apiextensions.crossplane.io/v1 kind: CompositeResourceDefinition @@ -364,17 +378,11 @@ spec: plural: xdatabases ``` -{{< hint "tip" >}} -This new API endpoint is a _Composite Resource_ (XR) API endpoint. It is -convention for Composite Resource kinds to start with `X`. For example -`XDatabase`. This is only convention and not required. -{{< /hint >}} - {{}} The _XRD_ {{}}group{{}} matches the _composition_ {{}}apiVersion{{}} and the _XRD_ {{}}kind{{}} matches the _composition_ -{{}}kind{{}} under the {{}}compositeTypeRef{{}}. +{{}}compositeTypeRef.kind{{}}. ```yaml {label="noteComp"} kind: Composition @@ -387,14 +395,13 @@ spec: {{< /hint >}} ### Set the API version -In Kubernetes, all API endpoints have a version to tell the stability of the API +In Kubernetes, all API endpoints have a version to show the stability of the API and track revisions. Apply a version to the _XRD_ with a {{}}versions.name{{}}. -This matches the {{}}apiVersion{{}} used in the _composition's_ -{{}}compositeTypeRef{{}}. +This matches the +{{}}compositeTypeRef.apiVersion{{}} _XRDs_ require both {{}}versions.served{{}} @@ -473,8 +480,8 @@ spec: ``` {{< hint "tip" >}} -For more information on the values allowed in the _XRD_ view its schema with -`kubectl explain compositeresourcedefinitions` +For more information on the values allowed in a _composite resource definition_ view its schema with +`kubectl explain compositeresourcedefinition` {{< /hint >}} Now, define the custom API. Your custom API continues under the last @@ -518,6 +525,13 @@ required: Tell this _XRD_ to offer a _claim_ by defining the _claim_ API endpoint under the _XRD_ {{}}spec{{< /hover >}}. +{{< hint "tip" >}} +Crossplane recommends a _Claim_ {{}}kind{{}} match the _Composite Resource_ (XR) +{{}}kind{{}}, +without the preceding `X`. +{{< /hint >}} + + ```yaml {label="XRDclaim"} apiVersion: apiextensions.crossplane.io/v1 kind: CompositeResourceDefinition @@ -532,13 +546,6 @@ spec: plural: databases ``` -{{< hint "tip" >}} -This new API endpoint is a _Composite Resource Claim_ (XRC) API endpoint. It is -convention for _Claim_ kinds to match their _Composite Resource_ (XR) kinds, -without the preceding `X`. For example `Database`. This is only convention and -not required. -{{< /hint >}} - {{}} The [Claims](#create-a-claim) section later in this guide discusses _claims_. {{< /hint >}} @@ -557,7 +564,7 @@ spec: group: custom-api.example.org names: kind: XDatabase - plural: databases + plural: xdatabases versions: - name: v1alpha1 served: true @@ -587,10 +594,9 @@ Verify Kubernetes created the XRD with `kubectl get xrd` ```shell {copy-lines="1",label="getXRD"} kubectl get xrd NAME ESTABLISHED OFFERED AGE -xdatabases.custom-api.example.org True True 9s +xdatabases.custom-api.example.org True True 10s ``` - ## Create a composite resource Creating an _XRD_ allows the creation _composite resources_. @@ -665,7 +671,7 @@ NAME SYNCED READY COMPOSITION AGE my-composite-resource True True dynamo-with-bucket 31s ``` -The output mentions the _composite_ template that the _composite resource_ used. +Both `SYNCED` and `READY` are `True` when Crossplane created the AWS resources. Now look at the S3 `bucket` and DynmoDB `table` _managed resources_ with `kubectl get bucket` and `kubectl get table`. @@ -741,12 +747,19 @@ my-second-composite-resource-nsz6j True True my-second-composite-resour Because the _composite resource_ is the `Owner` of the _managed resources_, when Crossplane deletes the _composite resource_, it also deletes the _managed resources_ automatically. -Delete the new _composite resource_ with `kubectl delete xdatabase`. +Delete the new _composite resource_ with `kubectl delete composition`. +Delete the first composition ```shell -kubectl delete xdatabase my-second-composite-resource +kubectl delete composition dynamodb-with-bucket ``` +And the second composition +```shell +kubectl delete composition my-second-composite-resource +``` + + {{}} There may a delay in deleting the _managed resources_. Crossplane is making API calls to AWS and waits for AWS to confirm they deleted the resources before @@ -792,7 +805,7 @@ Create a new namespace with `kubectl create namespace`. kubectl create namespace test ``` -A _claim_ uses the same {{}}group{{}} +A _claim_ uses the same {{}}group{{}} a _composite resource_ uses but a different {{}}kind{{}}. @@ -844,8 +857,8 @@ NAME SYNCED READY CONNECTION-SECRET AGE claimed-database True True 35s ``` -When Crossplane creates a _claim_ a unique _composite resource_ is automatically -created too. View the new _composite resource_ with `kubectl get xdatabase`. +When Crossplane creates a _claim_, a unique _composite resource_ is also +created. View the new _composite resource_ with `kubectl get xdatabase`. ```shell {copy-lines="1"} kubectl get xdatabase @@ -882,7 +895,7 @@ test2 claimed-database True True 43s Now look at the _composite resources_ at the cluster scope. -```shell +```shell {copy-lines="1"} kubectl get xdatabase NAME SYNCED READY COMPOSITION AGE claimed-database-6xsgq True True dynamo-with-bucket 8m37s @@ -921,7 +934,12 @@ Verify Crossplane removed all the _managed resources_. ```shell kubectl get bucket +No resources found +``` + +```shell kubectl get table +No resources found ``` Claims are powerful tools to give users resources in their own isolated diff --git a/content/v1.11/getting-started/provider-aws-part-3.md b/content/v1.11/getting-started/provider-aws-part-3.md index 74d9c62e..779915ce 100644 --- a/content/v1.11/getting-started/provider-aws-part-3.md +++ b/content/v1.11/getting-started/provider-aws-part-3.md @@ -50,12 +50,14 @@ spec: EOF ``` -3. Create a file with your AWS keys -```ini +3. Create a file called `aws-credentials.txt` with your AWS keys +{{< editCode >}} +```ini {copy-lines="all"} [default] -aws_access_key_id = -aws_secret_access_key = +aws_access_key_id = $$$$ +aws_secret_access_key = $$$$ ``` +{{}} 4. Create a Kubernetes secret from the AWS keys ```shell {label="kube-create-secret",copy-lines="all"} @@ -88,7 +90,7 @@ cat <}}bucket{{}} and a -{{}}table{{}}. +{{}}table{{}}. ```yaml {label="compResources"} apiVersion: apiextensions.crossplane.io/v1 @@ -289,7 +289,7 @@ cat <}} ```ini {copy-lines="all"} [default] -aws_access_key_id = -aws_secret_access_key = +aws_access_key_id = $$$$ +aws_secret_access_key = $$$$ ``` +{{}} Save this text file as `aws-credentials.txt`. @@ -1187,7 +1189,7 @@ Crossplane created the bucket when the values `READY` and `SYNCED` are `True`. This may take up to 5 minutes. {{< /hint >}} -```shell +```shell {copy-lines="1"} kubectl get buckets NAME READY SYNCED EXTERNAL-NAME AGE crossplane-bucket-lrxrf True True crossplane-bucket-lrxrf 61s @@ -1199,11 +1201,11 @@ Before shutting down your Kubernetes cluster, delete the S3 bucket just created. Use `kubectl delete bucket` to remove the bucket. {{}} -Use the `--label` flag to delete by label instead of by name. +Use `--selector` to delete a Kubernetes object by label instead of by name. {{}} ```shell {copy-lines="1"} -kubectl delete bucket --label docs.crossplane.io/example=provider-aws +kubectl delete bucket --selector=docs.crossplane.io/example=provider-aws bucket.s3.aws.upbound.io "crossplane-bucket-lrxrf" deleted ```