crossplane
/
docs
mirror of https://github.com/crossplane/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

AWS Quickstart Updates (#360)

This commit is contained in:
Pete Lumbis 2023-03-13 10:12:34 -04:00 committed by GitHub
parent 686070b8b4
commit 83e6e2e42d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 117 additions and 60 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

61
content/v1.11/getting-started/provider-aws-part-2.md
View File

@ -87,7 +87,7 @@ EOF
## Create a composition
[Part 1]({{<ref "provider-aws" >}}) 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
{{<hover label="specResources" line="20">}}apiVersion{{</ hover>}} and resource
settings under the
{{<hover label="specResources" line="19">}}base{{</ hover>}}.
_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 {{<hover label="xrdGroup" line="8" >}}kind{{</hover>}} 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`
{{<hint "tip" >}}
Use `kubectl get <kind>` 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`.
{{</hint >}}
```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
{{<hint "tip" >}}
Delete a specific _composite resource_ with `kubectl delete <kind>` 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
```
{{<hint "note">}}
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 {{<hover label="XRDclaim2" line="6" >}}group{{</hover>}}
a _composite resource_ uses but a different
{{<hover label="XRDclaim2" line="8" >}}kind{{</hover>}}.
@ -851,6 +857,11 @@ EOF
Verify Crossplane created the _claim_ with `kubectl get database` in the `test`
namespace.
{{<hint "tip" >}}
View claims with `kubectl get <kind>` or use `kubectl get claim` to view all
_claims_.
{{</hint >}}
```shell {copy-lines="1"}
kubectl get database -n test
NAME SYNCED READY CONNECTION-SECRET AGE

15
content/v1.11/getting-started/provider-aws-part-3.md
View File

@ -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
{{<hover label="compResources" line="8">}}bucket{{</hover>}} and a
{{<hover label="compResources" line="15">}}table{{</hover>}}.
@ -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 <<EOF > 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 <<EOF > 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
```

95
content/v1.11/getting-started/provider-aws.md
View File

@ -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 <<EOF | kubectl apply -f -
@ -1041,7 +1047,8 @@ spec:
EOF
```
The Crossplane {{< hover label="provider" line="3" >}}Provider{{</hover>}} Custom Resource Definition tells Kubernetes how to
The Crossplane {{< hover label="provider" line="3" >}}Provider{{</hover>}}
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 = $$<aws_secret_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{{</ 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.
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.
```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{{</ hover >}} with the command:
Apply the {{< hover label="providerconfig" line="2">}}ProviderConfig{{</ hover >}}
with the command:
```yaml {label="providerconfig",copy-lines="all"}
cat <<EOF | kubectl apply -f -
apiVersion: aws.upbound.io/v1beta1
@ -1148,13 +1174,18 @@ spec:
EOF
```
This attaches the AWS credentials, saved as a Kubernetes secret, as a {{< hover label="providerconfig" line="9">}}secretRef{{</ hover>}}.
This attaches the AWS credentials, saved as a Kubernetes secret, as a
{{< hover label="providerconfig" line="9">}}secretRef{{</ 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 >}}.
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{{</hover >}} are from the provider's CRDs.
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="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`.
{{</hint >}}
```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.
* **[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.

2
utils/vale/styles/Google/Headings.yml
View File

@ -14,7 +14,9 @@ exceptions:
- Cosmos
- Crossplane
- Docker
- DynamoDB
- Emmet
- Helm
- Hugo
- gRPC
- Helm

3
utils/vale/styles/Microsoft/HeadingAcronyms.yml
View File

@ -7,5 +7,6 @@ tokens:
- '[A-Z]{2,4}'
exceptions:
- API
- AWS
- GCP
- JSON
- JSON

1
utils/vale/styles/write-good/Weasel.yml
View File

@ -124,7 +124,6 @@ tokens:
- normally
- obediently
- occasionally
- only
- openly
- painfully
- particularly