From 83e6e2e42d64232f432228ca9b66d03706895459 Mon Sep 17 00:00:00 2001 From: Pete Lumbis Date: Mon, 13 Mar 2023 10:12:34 -0400 Subject: [PATCH] AWS Quickstart Updates (#360) --- .../getting-started/provider-aws-part-2.md | 61 +++++++----- .../getting-started/provider-aws-part-3.md | 15 +-- content/v1.11/getting-started/provider-aws.md | 95 ++++++++++++++----- utils/vale/styles/Google/Headings.yml | 2 + .../vale/styles/Microsoft/HeadingAcronyms.yml | 3 +- utils/vale/styles/write-good/Weasel.yml | 1 - 6 files changed, 117 insertions(+), 60 deletions(-) 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 cbf917bf..343ac675 100644 --- a/content/v1.11/getting-started/provider-aws-part-2.md +++ b/content/v1.11/getting-started/provider-aws-part-2.md @@ -87,7 +87,7 @@ EOF ## Create a composition [Part 1]({{}}) created a single _managed resource_. -A _Composition_ is a template to create multiple _managed resources_ at the same time. +A _Composition_ is a template to create one or more _managed resource_ at the same time. This sample _composition_ creates an DynamoDB instance and associated S3 storage bucket. @@ -227,12 +227,7 @@ spec: hashKey: S3ID ``` -Put the entire resource definition including the -{{}}apiVersion{{}} and resource -settings under the -{{}}base{{}}. - -_Compositions_ are only a template for generating resources. A _composite +_Compositions_ are a template for generating resources. A _composite resource_ actually creates the resources. A _composition_ defines what _composite resources_ can use this @@ -353,7 +348,7 @@ Crossplane recommends using a plural name for the _XRD_ apiVersion: apiextensions.crossplane.io/v1 kind: CompositeResourceDefinition metadata: - name: databases.custom-api.example.org + name: xdatabases.custom-api.example.org ``` The _XRD's_ @@ -370,7 +365,7 @@ Next, create the API {{}}kind{{}} and apiVersion: apiextensions.crossplane.io/v1 kind: CompositeResourceDefinition metadata: - name: databases.custom-api.example.org + name: xdatabases.custom-api.example.org spec: group: custom-api.example.org names: @@ -412,12 +407,12 @@ and apiVersion: apiextensions.crossplane.io/v1 kind: CompositeResourceDefinition metadata: - name: custom-api-definition + name: xdatabases.custom-api.example.org spec: group: custom-api.example.org names: kind: XDatabase - plural: databases + plural: xdatabases versions: - name: v1alpha1 served: true @@ -481,7 +476,7 @@ spec: {{< hint "tip" >}} For more information on the values allowed in a _composite resource definition_ view its schema with -`kubectl explain compositeresourcedefinition` +`kubectl explain xrd` {{< /hint >}} Now, define the custom API. Your custom API continues under the last @@ -600,10 +595,11 @@ xdatabases.custom-api.example.org True True 10s ## Create a composite resource Creating an _XRD_ allows the creation _composite resources_. -_Composite resources_ are a convenient way to create multiple resources with a standard template. - A _composite resource_ uses the custom API created in the _XRD_. +The _XRD_ maps the _composite resource_ values to the _composition_ template and +creates new _managed resources_. + Looking at part of the _XRD_: ```yaml {label="xrdSnip"} @@ -665,6 +661,11 @@ EOF ### Verify the composite resource Verify Crossplane created the _composite resource_ with `kubectl get xdatabase` +{{}} +Use `kubectl get ` to view a specific `kind` of _composite resource_. +View all _composite resources_ with `kubectl get composite`. +{{< /hint >}} + ```shell {copy-lines="1"} kubectl get xdatabase NAME SYNCED READY COMPOSITION AGE @@ -676,6 +677,11 @@ 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`. +{{< hint "important" >}} +This guide uses Upbound AWS provider v0.27.0. AWS Provider v0.30.0 and later +requires the full CRD name `bucket.s3.aws.upbound.io` instead of `buckets`. +{{}} + ```shell {copy-lines="1"} kubectl get bucket NAME READY SYNCED EXTERNAL-NAME AGE @@ -747,19 +753,18 @@ 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 composition`. +Delete the new _composite resource_ with `kubectl delete xdatabase`. -Delete the first composition +{{}} +Delete a specific _composite resource_ with `kubectl delete ` or +`kubectl delete composite`. +{{< /hint >}} + +Delete the second composition ```shell -kubectl delete composition dynamodb-with-bucket +kubectl delete xdatabase my-second-composite-resource ``` -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 @@ -780,14 +785,14 @@ NAME READY SYNCED EXTERNAL-NAME my-composite-resource-m6vk6 True True my-composite-resource-m6vk6 7m37s ``` -Delete the second _composite resource_ to remove the last `bucket` and `table` +Delete the other _composite resource_ to remove the last `bucket` and `table` _managed resources_. ```shell kubectl delete xdatabase my-composite-resource ``` -_Composite resources_ are great for creating multiple related resources against +_Composite resources_ are great for creating one or more related resources against a template, but all _composite resources_ exist at the Kubernetes "cluster level." There's no isolation between _composite resources_. Crossplane uses _claims_ to create resources with namespace isolation. @@ -805,6 +810,7 @@ Create a new namespace with `kubectl create namespace`. kubectl create namespace test ``` +Look at the _XRD_ to see the parameters for the _claim_. A _claim_ uses the same {{}}group{{}} a _composite resource_ uses but a different {{}}kind{{}}. @@ -851,6 +857,11 @@ EOF Verify Crossplane created the _claim_ with `kubectl get database` in the `test` namespace. +{{}} +View claims with `kubectl get ` or use `kubectl get claim` to view all +_claims_. +{{}} + ```shell {copy-lines="1"} kubectl get database -n test NAME SYNCED READY CONNECTION-SECRET AGE 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 779915ce..57f80219 100644 --- a/content/v1.11/getting-started/provider-aws-part-3.md +++ b/content/v1.11/getting-started/provider-aws-part-3.md @@ -166,7 +166,7 @@ kubectl create namespace test In a _composition_ `patches` map fields in the custom API to fields inside the _managed resources_. -The _composition_ has two _managed resources_, a +The example _composition_ has two _managed resources_, a {{}}bucket{{}} and a {{}}table{{}}. @@ -354,7 +354,7 @@ EOF View the _claim_ with `kubectl get claim` ```shell {copy-lines="1"} -kubectl get claim -n test +kubectl get database -n test NAME SYNCED READY CONNECTION-SECRET AGE claimed-eu-database True True 18m ``` @@ -384,7 +384,7 @@ The _managed resources_ take up to 5 minutes to delete. {{< /hint >}} ```shell -kubectl delete claim claimed-eu-database -n test +kubectl delete database claimed-eu-database -n test ``` ## Create a Crossplane configuration package @@ -501,12 +501,12 @@ cat < crossplane-aws-quickstart/definition.yaml apiVersion: apiextensions.crossplane.io/v1 kind: CompositeResourceDefinition metadata: - name: databases.custom-api.example.org + name: xdatabases.custom-api.example.org spec: group: custom-api.example.org names: kind: XDatabase - plural: databases + plural: xdatabases versions: - name: v1alpha1 served: true @@ -547,7 +547,7 @@ cat < crossplane-aws-quickstart/composition.yaml apiVersion: apiextensions.crossplane.io/v1 kind: Composition metadata: - name: dynamo-with-bucket + name: dynamodb-with-bucket spec: compositeTypeRef: apiVersion: custom-api.example.org/v1alpha1 @@ -596,7 +596,8 @@ To build a configuration package install the Crossplane Kubernetes command-line extension. ```shell -curl "https://raw.githubusercontent.com/crossplane/crossplane/master/install.sh" +wget "https://raw.githubusercontent.com/crossplane/crossplane/master/install.sh" +chmod +x install.sh ./install.sh sudo mv kubectl-crossplane /usr/bin ``` diff --git a/content/v1.11/getting-started/provider-aws.md b/content/v1.11/getting-started/provider-aws.md index 9d2cf952..c2e9d9d8 100644 --- a/content/v1.11/getting-started/provider-aws.md +++ b/content/v1.11/getting-started/provider-aws.md @@ -3,7 +3,9 @@ title: AWS Quickstart weight: 100 --- -Connect Crossplane to AWS to create and manage cloud resources from Kubernetes with the [Upbound AWS Provider](https://marketplace.upbound.io/providers/upbound/provider-aws). +Connect Crossplane to AWS to create and manage cloud resources from Kubernetes +with the +[Upbound AWS Provider](https://marketplace.upbound.io/providers/upbound/provider-aws). This guide is in three parts: * Part 1 walks through installing Crossplane, configuring the provider to @@ -29,13 +31,15 @@ This quickstart requires: Crossplane installs into an existing Kubernetes cluster. {{< hint type="tip" >}} -If you don't have a Kubernetes cluster create one locally with [Kind](https://kind.sigs.k8s.io/). +If you don't have a Kubernetes cluster create one locally with +[Kind](https://kind.sigs.k8s.io/). {{< /hint >}} ### Install the Crossplane Helm chart -Helm enables Crossplane to install all its Kubernetes components through a _Helm Chart_. +Helm enables Crossplane to install all its Kubernetes components through a +_Helm Chart_. Enable the Crossplane Helm Chart repository: @@ -1010,7 +1014,8 @@ crossplane-d4cd8d784-ldcgb 1/1 Running 0 54s crossplane-rbac-manager-84769b574-6mw6f 1/1 Running 0 54s ``` -Installing Crossplane creates new Kubernetes API end-points. Look at the new API end-points with `kubectl api-resources | grep crossplane`. +Installing Crossplane creates new Kubernetes API end-points. Look at the new API +end-points with `kubectl api-resources | grep crossplane`. ```shell {label="grep",copy-lines="1"} kubectl api-resources | grep crossplane @@ -1028,7 +1033,8 @@ storeconfigs secrets.crossplane.io/v1alpha1 ## Install the AWS provider -Install the provider into the Kubernetes cluster with a Kubernetes configuration file. +Install the provider into the Kubernetes cluster with a Kubernetes configuration +file. ```yaml {label="provider",copy-lines="all"} cat <}}Provider{{}} Custom Resource Definition tells Kubernetes how to +The Crossplane {{< hover label="provider" line="3" >}}Provider{{}} +Custom Resource Definition tells Kubernetes how to connect to the provider. Verify the provider installed with `kubectl get providers`. @@ -1056,32 +1063,41 @@ NAME INSTALLED HEALTHY PACKAGE upbound-provider-aws True True xpkg.upbound.io/upbound/provider-aws:v0.27.0 12m ``` -A provider installs their own Kubernetes _Custom Resource Definitions_ (CRDs). These CRDs allow you to create AWS resources directly inside Kubernetes. +A provider installs their own Kubernetes _Custom Resource Definitions_ (CRDs). +These CRDs allow you to create AWS resources directly inside Kubernetes. -You can view the new CRDs with `kubectl get crds`. Every CRD maps to a unique AWS service Crossplane can provision and manage. +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 [Upbound Marketplace](https://marketplace.upbound.io/providers/upbound/provider-aws/v0.27.0/crds). +See details about all the supported CRDs in the +[Upbound Marketplace](https://marketplace.upbound.io/providers/upbound/provider-aws/v0.27.0/crds). {{< /hint >}} ## Create a Kubernetes secret for AWS -The provider requires credentials to create and manage AWS resources. Providers use a Kubernetes _Secret_ to connect the credentials to the provider. +The provider requires credentials to create and manage AWS resources. Providers +use a Kubernetes _Secret_ to connect the credentials to the provider. -First generate a Kubernetes _Secret_ from your AWS key-pair and then configure the Provider to use it. +First generate a Kubernetes _Secret_ from your AWS key-pair and then configure +the Provider to use it. {{< hint type="note" >}} -Other authentication methods exist and are beyond the scope of this guide. The [Provider documentation](https://marketplace.upbound.io/providers/upbound/provider-aws/latest/docs/configuration) contains information on alternative authentication methods. +Other authentication methods exist and are beyond the scope of this guide. The +[Provider documentation](https://marketplace.upbound.io/providers/upbound/provider-aws/latest/docs/configuration) +contains information on alternative authentication methods. {{< /hint >}} ### Generate an AWS 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) provides information on how to generate AWS Access keys. +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"} @@ -1094,12 +1110,21 @@ aws_secret_access_key = $$$$ Save this text file as `aws-credentials.txt`. {{< hint type="note" >}} -The [Configuration](https://marketplace.upbound.io/providers/upbound/provider-aws/latest/docs/configuration) section of the Provider documentation describes other authentication methods. +The [Configuration](https://marketplace.upbound.io/providers/upbound/provider-aws/latest/docs/configuration) +section of the 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{{}} namespace. -Use the {{< hover label="kube-create-secret" line="4">}}--from-file={{}} argument to set the value to the contents of the {{< hover label="kube-create-secret" line="4">}}aws-credentials.txt{{< /hover >}} file. +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{{}} +namespace. +Use the {{< hover label="kube-create-secret" line="4">}}--from-file={{}} +argument to set the value to the contents of the +{{< hover label="kube-create-secret" line="4">}}aws-credentials.txt{{< /hover >}} +file. ```shell {label="kube-create-secret",copy-lines="all"} kubectl create secret \ @@ -1131,7 +1156,8 @@ creds: 114 bytes ## Create a ProviderConfig A `ProviderConfig` customizes the settings of the AWS Provider. -Apply the {{< hover label="providerconfig" line="2">}}ProviderConfig{{}} with the command: +Apply the {{< hover label="providerconfig" line="2">}}ProviderConfig{{}} +with the command: ```yaml {label="providerconfig",copy-lines="all"} cat <}}secretRef{{}}. +This attaches the AWS credentials, saved as a Kubernetes secret, as a +{{< hover label="providerconfig" line="9">}}secretRef{{}}. -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 >}}. +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 >}}. ## Create a managed resource -A _managed resource_ is anything Crossplane creates and manages outside of the Kubernetes cluster. This creates an AWS S3 bucket with Crossplane. The S3 bucket is a _managed resource_. +A _managed resource_ is anything Crossplane creates and manages outside of the +Kubernetes cluster. This 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. Any unique name is acceptable. To @@ -1178,9 +1209,13 @@ spec: EOF ``` -The {{< hover label="xr" line="2">}}apiVersion{{< /hover >}} and {{< hover label="xr" line="3">}}kind{{}} are from the provider's CRDs. +The {{< hover label="xr" line="2">}}apiVersion{{< /hover >}} and +{{< hover label="xr" line="3">}}kind{{}} are from the provider's CRDs. -The {{< hover label="xr" line="10">}}spec.forProvider.region{{< /hover >}} tells AWS which AWS region to use when deploying resources. The region can be any [AWS Regional endpoint](https://docs.aws.amazon.com/general/latest/gr/rande.html#regional-endpoints) code. +The {{< hover label="xr" line="10">}}spec.forProvider.region{{< /hover >}} tells +AWS which AWS region to use when deploying resources. The region can be any +[AWS Regional endpoint](https://docs.aws.amazon.com/general/latest/gr/rande.html#regional-endpoints) +code. Use `kubectl get buckets` to verify Crossplane created the bucket. @@ -1189,6 +1224,11 @@ Crossplane created the bucket when the values `READY` and `SYNCED` are `True`. This may take up to 5 minutes. {{< /hint >}} +{{< hint "important" >}} +This guide uses Upbound AWS provider v0.27.0. AWS Provider v0.30.0 and later +requires the full CRD name `bucket.s3.aws.upbound.io` instead of `buckets`. +{{}} + ```shell {copy-lines="1"} kubectl get buckets NAME READY SYNCED EXTERNAL-NAME AGE @@ -1210,6 +1250,9 @@ bucket.s3.aws.upbound.io "crossplane-bucket-lrxrf" deleted ``` ## Next steps -* **[Continue to part 2]({{< ref "provider-aws-part-2">}})** to create a Crossplane _Composite Resource_ and _Claim_. -* Explore AWS resources that Crossplane can configure in the [Provider CRD reference](https://marketplace.upbound.io/providers/upbound/provider-aws/latest/crds). -* Join the [Crossplane Slack](https://slack.crossplane.io/) and connect with Crossplane users and contributors. \ No newline at end of file +* **[Continue to part 2]({{< ref "provider-aws-part-2">}})** to create a + Crossplane _Composite Resource_ and _Claim_. +* Explore AWS resources that Crossplane can configure in the + [Provider CRD reference](https://marketplace.upbound.io/providers/upbound/provider-aws/latest/crds). +* Join the [Crossplane Slack](https://slack.crossplane.io/) and connect with + Crossplane users and contributors. \ No newline at end of file diff --git a/utils/vale/styles/Google/Headings.yml b/utils/vale/styles/Google/Headings.yml index 858450c9..f12209c8 100644 --- a/utils/vale/styles/Google/Headings.yml +++ b/utils/vale/styles/Google/Headings.yml @@ -14,7 +14,9 @@ exceptions: - Cosmos - Crossplane - Docker + - DynamoDB - Emmet + - Helm - Hugo - gRPC - Helm diff --git a/utils/vale/styles/Microsoft/HeadingAcronyms.yml b/utils/vale/styles/Microsoft/HeadingAcronyms.yml index 8674cf6e..74d16e9b 100644 --- a/utils/vale/styles/Microsoft/HeadingAcronyms.yml +++ b/utils/vale/styles/Microsoft/HeadingAcronyms.yml @@ -7,5 +7,6 @@ tokens: - '[A-Z]{2,4}' exceptions: - API + - AWS - GCP - - JSON \ No newline at end of file + - JSON diff --git a/utils/vale/styles/write-good/Weasel.yml b/utils/vale/styles/write-good/Weasel.yml index e2939144..8218aa19 100644 --- a/utils/vale/styles/write-good/Weasel.yml +++ b/utils/vale/styles/write-good/Weasel.yml @@ -124,7 +124,6 @@ tokens: - normally - obediently - occasionally - - only - openly - painfully - particularly