From e17cdb7dd40dd37c64e59525113c6d02323853f9 Mon Sep 17 00:00:00 2001 From: Waldemar Hummer Date: Wed, 6 Sep 2023 08:59:00 +0200 Subject: [PATCH] Add tutorial on using Crossplane AWS provider with LocalStack (#804) --------- Co-authored-by: Osama M Co-authored-by: Harsh Mishra --- assets/scss/_styles_project.scss | 5 + .../integrations/crossplane/index.md | 230 +++++++++++++ .../crossplane/logo-crossplane.svg | 310 ++++++++++++++++++ .../integrations/terraform/index.md | 2 +- layouts/shortcodes/command.html | 8 + static/js/global-script.js | 1 + 6 files changed, 555 insertions(+), 1 deletion(-) create mode 100644 content/en/user-guide/integrations/crossplane/index.md create mode 100644 content/en/user-guide/integrations/crossplane/logo-crossplane.svg diff --git a/assets/scss/_styles_project.scss b/assets/scss/_styles_project.scss index 7933271624..0237770a32 100644 --- a/assets/scss/_styles_project.scss +++ b/assets/scss/_styles_project.scss @@ -559,5 +559,10 @@ table tfoot { } } } +.disable-copy-btn { + .code-copy-button{ + display: none !important; + } +} @import "modules/academy-styles.scss"; diff --git a/content/en/user-guide/integrations/crossplane/index.md b/content/en/user-guide/integrations/crossplane/index.md new file mode 100644 index 0000000000..8670881e11 --- /dev/null +++ b/content/en/user-guide/integrations/crossplane/index.md @@ -0,0 +1,230 @@ +--- +title: "Crossplane" +tags: ["crossplane", "kubernetes", "infrastructure-as-code"] +weight: 5 +description: > + Use the Crossplane cloud-native control plane framework with LocalStack +aliases: + - /integrations/crossplane/ +--- + +Crossplane logo + +## Overview + +[Crossplane](https://www.crossplane.io) is a cloud-native control plane framework, which offers an extensible backend that enables orchestrating applications and infrastructure via declarative APIs and resource definitions. + +Crossplane offers a native [AWS provider](https://github.com/upbound/provider-aws) which can be used to create and manage AWS cloud resources via the Crossplane platform. +For example, it can be used to create S3 buckets, SQS queues, Lambda functions, among many other resources. +Crossplane AWS provider supports a comprehensive set of some [900+ resource types](https://marketplace.upbound.io/providers/upbound/provider-aws). + +## Getting started + +In the following, we provide a step-by-step guide for installing Crossplane in a local test environment, and creating AWS resources (S3 bucket, SQS queue) in LocalStack via Crossplane. + +### Prerequisites +* LocalStack running in local Docker +* A local Kubernetes cluster: + * We can use the [embedded Kubernetes cluster](https://docs.docker.com/desktop/kubernetes) that ships with modern versions of Docker Desktop (can be easily enabled in the Docker settings) + * Alternatively, you can [create a local EKS cluster](https://docs.localstack.cloud/user-guide/aws/elastic-kubernetes-service/#create-an-embedded-kubernetes-cluster) in LocalStack directly, which will spin up a light-weight embedded `k3d` Kubernetes cluster in your Docker environment +* The [`helm`](https://helm.sh) and [`kubectl`](https://kubernetes.io/docs/tasks/tools/#kubectl) command-line clients installed + +## Installing Crossplane in local Kubernetes + +Once your `kubectl` is configured to point to the local Kubernetes cluster, we first install Crossplane via `helm`: +{{}} +$ helm repo add crossplane-stable https://charts.crossplane.io/stable +$ helm repo update +$ helm install crossplane crossplane-stable/crossplane --namespace crossplane-system --create-namespace +{{}} + +The installation may take a few minutes. In parallel, we can install the `crossplane` command-line extensions for `kubectl`: +{{}} +$ curl -sL https://raw.githubusercontent.com/crossplane/crossplane/master/install.sh | bash +... +$ sudo mv kubectl-crossplane /usr/local/bin +{{}} +To confirm that the installation was successful, we can run these `kubectl` commands, which should yield output similar to the following: +{{}} +$ kubectl crossplane --version +v1.13.2 + +$ kubectl get crds | grep crossplane +compositions.apiextensions.crossplane.io 2023-09-03T11:30:36Z +configurations.pkg.crossplane.io 2023-09-03T11:30:36Z +... +{{}} + +### Installing the Crossplane AWS Provider + +Once the basic Crossplane installation is running properly, we can proceed with installing the AWS provider. +Newer versions of Crossplane promote the use of [provider families](https://docs.upbound.io/providers/provider-families), which are collections of providers for different groups of resources. +For example, there is a separate provider for each individual AWS service (like S3, SQS, Lambda, etc), and in addition provider family provides shared resources for common configuration of all services (e.g., credentials, etc). + +In the following, we first install the AWS provider for S3. +Note that you can copy/paste the entire multi-line command below into your terminal: +{{}} +$ cat <}} + +We also install the AWS provider for SQS: +{{}} +$ cat <}} + +After some time, the providers should get into healthy state, which can be confirmed via `kubectl get providers`: +{{}} +$ kubectl get providers +NAME INSTALLED HEALTHY PACKAGE AGE +upbound-provider-family-aws True True xpkg.upbound.io/upbound/provider-family-aws:v0.40.0 2m +provider-aws-s3 True True xpkg.upbound.io/upbound/provider-aws-s3:v0.40.0 2m +provider-aws-sqs True True xpkg.upbound.io/upbound/provider-aws-sqs:v0.40.0 2m + +{{}} + +Next, we install a secret to define the test credentials for the AWS provider: +{{}} +$ cat <}} + +Finally, we create an AWS `ProviderConfig` that references the secret created above, and defines a static `endpoint` pointing to the LocalStack URL `http://host.docker.internal:4566`: +{{}} +$ cat <}} + +{{}} +The endpoint `http://host.docker.internal:4566` in the listing above assumes that you are running Kubernetes in the local Docker engine, and that LocalStack is up and running and available on default port `4566`. +{{}} + +{{}} +The Crossplane AWS provider currently requires us to specify the list of `services` for which the local `endpoint` is used as the target URL. Please make sure to extend this list accordingly if you're working with additional LocalStack services. +{{}} + +### Deploying sample resources in LocalStack + +After the Crossplane AWS provider is properly installed and configured, we can proceed with creating some local resources. + +First, we create an S3 bucket named `crossplane-test-bucket`: +{{}} +$ cat <}} + +If everything is wired up correctly, you should now see some activity in the LocalStack log outputs, where Crossplane starts deploying the S3 bucket against LocalStack. +After some time, the bucket should be transitioning into `ready` state within Crossplane: +{{}} +$ kubectl get buckets +NAME READY SYNCED EXTERNAL-NAME AGE +crossplane-test-bucket True True crossplane-test-bucket 30s + +{{}} + +... and the bucket it should also be visible when querying the local S3 buckets in LocalStack via [`awslocal`](https://github.com/localstack/awscli-local): +{{}} +$ awslocal s3 ls +2023-09-03 15:18:47 crossplane-test-bucket + +{{}} + +We can repeat the same exercise for creating a local SQS queue named `crossplane-test-queue`: +{{}} +$ cat <}} + +After some time, the queue should transition into `ready` state in Crossplane: +{{}} +$ kubectl get queues +NAME READY SYNCED EXTERNAL-NAME AGE +crossplane-test-queue True True http://host.docker.internal:4566/000000000000/crossplane-test-queue 40s + +{{}} + +... and the queue should be visible when listing the SQS queues in LocalStack: +{{}} +$ awslocal sqs list-queues +{ + "QueueUrls": [ + "http://localhost:4566/000000000000/crossplane-test-queue" + ] +} + +{{}} + +### Summary + +The Crossplane AWS provider is a great way to manage AWS resources, and by leveraging the `endpoint` configuration of the provider, we can seamlessly run resource deployments against LocalStack. + +In this tutorial, we have provided an end-to-end walkthrough of how to provision two simple resources - an S3 bucket, and an SQS queue. Crossplane supports a vast range of additional AWS resource types, as well as advanced operations like updating, deleting, or composing resources. +You can refer to the additional reading material to learn and explore more advanced features. + +## Further Reading + +* Kubernetes on Docker Desktop: https://docs.docker.com/desktop/kubernetes +* Kubernetes getting started guide: https://kubernetes.io/docs/setup +* EKS Kubernetes clusters on LocalStack: https://docs.localstack.cloud/user-guide/aws/elastic-kubernetes-service +* Crossplane user docs: https://docs.crossplane.io +* Crossplane AWS provider family: https://marketplace.upbound.io/providers/upbound/provider-family-aws +* Crossplane AWS provider source code: https://github.com/upbound/provider-aws diff --git a/content/en/user-guide/integrations/crossplane/logo-crossplane.svg b/content/en/user-guide/integrations/crossplane/logo-crossplane.svg new file mode 100644 index 0000000000..3af90369f7 --- /dev/null +++ b/content/en/user-guide/integrations/crossplane/logo-crossplane.svg @@ -0,0 +1,310 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/content/en/user-guide/integrations/terraform/index.md b/content/en/user-guide/integrations/terraform/index.md index d2a0365850..66abd2bdd9 100644 --- a/content/en/user-guide/integrations/terraform/index.md +++ b/content/en/user-guide/integrations/terraform/index.md @@ -8,7 +8,7 @@ aliases: - /integrations/terraform/ --- -terraform logo +Terraform logo ## Overview diff --git a/layouts/shortcodes/command.html b/layouts/shortcodes/command.html index d0499dac78..8019c9d0cd 100644 --- a/layouts/shortcodes/command.html +++ b/layouts/shortcodes/command.html @@ -3,11 +3,19 @@ {{ $inner := trim .Inner "\n " }} {{/* We encapsulate, for each line, the prefix (if present) in custom prefix tags so we find it after highlighting */}} {{ $inner = replaceRE `(?m)^ *((?:\$|#) )` "###CUSTOM_PREFIX###$1###CUSTOM_PREFIX_END###" $inner}} +{{ $inner := replaceRE `\(?s)(.*?)\<\/disable-copy\>` "###DISABLE_COPY###$1###DISABLE_COPY_END###" $inner }} {{/* We need to set a default for the highlighting options here */}} {{ $options := "" }} {{ with .Get 0 }} {{ $options = . }} {{ end }} {{ $highlighted := highlight $inner "text" $options }} +{{ $highlighted := replaceRE `###DISABLE_COPY###(?s)(.*?)###DISABLE_COPY_END###` "$1" $highlighted | safeHTML}} +{{ with .Get "wrapper" }} +
+{{ end }} {{/* Now we replace the custom prefixes with a span that contains the prefix, which is not selectable by users */}} {{- replaceRE `###CUSTOM_PREFIX###((?:\$|#)\s)###CUSTOM_PREFIX_END###` "$1" $highlighted | safeHTML -}} +{{ with .Get "wrapper" }} +
+{{ end }} diff --git a/static/js/global-script.js b/static/js/global-script.js index 3ef12d9900..96e61e6d6f 100644 --- a/static/js/global-script.js +++ b/static/js/global-script.js @@ -8,6 +8,7 @@ function setupCodeBlockCopyButton() { e.preventDefault(); const elem = $(this).closest('.code-container').find('code').clone(); elem.find('.command-prefix').remove(); // removing prefix + elem.find('.disable-copy').remove(); // removing text which shouldn't be copied navigator.clipboard.writeText(elem.text()); $(this).find('span').text('Copied!'); setTimeout(() => {