From c7f2097f373ed5fb05aba3fe241d18ce10388e23 Mon Sep 17 00:00:00 2001 From: djamaile Date: Tue, 16 May 2023 14:31:49 +0200 Subject: [PATCH 1/8] docs: add docs about Backstage Deploy Signed-off-by: djamaile --- docs/deployment/backstage-deploy/aws.md | 188 ++++++++++++++++++++++++ microsite/sidebars.json | 9 +- 2 files changed, 196 insertions(+), 1 deletion(-) create mode 100644 docs/deployment/backstage-deploy/aws.md diff --git a/docs/deployment/backstage-deploy/aws.md b/docs/deployment/backstage-deploy/aws.md new file mode 100644 index 0000000000..cac9ede624 --- /dev/null +++ b/docs/deployment/backstage-deploy/aws.md @@ -0,0 +1,188 @@ +--- +id: aws +title: Deploying Backstage on AWS Lightsail +sidebar_label: AWS +description: How to deploy Backstage on AWS Lightsail +--- + +> **DISCLAIMER: The `deploy` command is in alpha and still experimental. Do not use the `deploy` command for production deployments.** + +Getting started with Backstage often involves setting up an instance on a cloud provider and sharing it with your team so they can experiment. To make this cloud deployment easier, we've built a `deploy` command to stand up a proof-of-concept instance on AWS (using Lightsail). + +## What is AWS Lightsail + +:::tip + +AWS offers a free tier for up to three months on $10 USD/month Container service (Micro -1 node). By default we use the `nano` node, so if you are a new user this approach shouldn't cost you anything. For more information, refer to the [pricing](https://aws.amazon.com/lightsail/pricing/) documentation. + +::: + +AWS Lightsail offers a simple way to run containers in the cloud. To learn more about AWS Lightsail, please refer to the [official documentation](https://lightsail.aws.amazon.com/ls/docs/en_us/articles/amazon-lightsail-container-services-deployments). + +## Creating user in AWS + +- Open the AWS console and navigate to the IAM section +- In the left side menu click on `Users` and then click on `Add users` +- Specify a username and then click on `Next` +- Afterwards you can assign permissions, select `Attach policies directly` and then click on `Create policy`. + This should take you to a new window in which you can create a new policy based on `JSON`. + Copy over the following: + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "VisualEditor0", + "Effect": "Allow", + "Action": [ + "ecr:DescribeImageReplicationStatus", + "ecr:ListTagsForResource", + "ecr:UploadLayerPart", + "ecr:BatchGetRepositoryScanningConfiguration", + "ecr:DeleteRepository", + "ecr:GetRegistryScanningConfiguration", + "ecr:CompleteLayerUpload", + "ecr:TagResource", + "ecr:DescribeRepositories", + "ecr:DeleteRepositoryPolicy", + "ecr:BatchCheckLayerAvailability", + "ecr:GetLifecyclePolicy", + "ecr:GetRegistryPolicy", + "ecr:PutLifecyclePolicy", + "ecr:DescribeImageScanFindings", + "ecr:GetLifecyclePolicyPreview", + "ecr:CreateRepository", + "ecr:DescribeRegistry", + "ecr:GetDownloadUrlForLayer", + "ecr:GetAuthorizationToken", + "ecr:DeleteLifecyclePolicy", + "ecr:PutImage", + "ecr:UntagResource", + "ecr:SetRepositoryPolicy", + "ecr:BatchGetImage", + "ecr:InitiateLayerUpload", + "ecr:GetRepositoryPolicy", + "lightsail:CreateContainerService", + "lightsail:GetKeyPair", + "lightsail:GetContainerServiceDeployments", + "lightsail:CreateContainerServiceRegistryLogin", + "lightsail:GetContainerImages", + "lightsail:UntagResource", + "lightsail:RegisterContainerImage", + "lightsail:GetContainerServices", + "lightsail:GetContainerServicePowers", + "lightsail:GetKeyPairs", + "lightsail:CreateContainerServiceDeployment", + "lightsail:GetContainerServiceMetricData", + "lightsail:GetContainerAPIMetadata", + "lightsail:DeleteContainerService", + "lightsail:GetContainerLog", + "lightsail:TagResource" + ], + "Resource": "*" + }, + { + "Sid": "Statement1", + "Effect": "Allow", + "Action": [], + "Resource": [] + } + ] +} +``` + +Then click on `Next` and give the policy a name and a description of your liking. Afterwards, click on `Create policy`. + +- Navigate back to the user creation window and press on the refresh button and search for the policy you just created. Now, create the user. +- Now you will be redirected to all users, click on the user you just created and click on `Security credentials` +- Scroll below and click on `Create access key` +- Choose `Command Line Interface (CLI)` +- Now export the following values + +```bash +$ export AWS_ACCESS_KEY_ID=... (first value) +$ export AWS_SECRET_ACCESS_KEY=.... (second secret value) +``` + +## Configuring the Pulumi CLI + +Second, install the [Pulumi CLI](https://www.pulumi.com/docs/get-started/install/). + +Then we need to execute the following commands, to set Pulumi up: + +```bash +$ pulumi login --local +$ export PULUMI_CONFIG_PASSPHRASE="" +``` + +By using `pulumi login --local` we are making sure that Pulumi stores our state on the local file disk. The environment variable `PULUMI_CONFIG_PASSPHRASE` is used by Pulumi to generate a unique key for your stack + +## Deploying your instance on Lightsail + +:::warning + +Make sure that [Docker](https://docs.docker.com/) is running before you start with this section. + +::: + +After you have made your changes to your local instance, it's time to deploy it on Lightsail. + +First, we need to configure the `app-config.yaml` and update the `baseUrl`. + +```diff +app: +- baseUrl: http://localhost:3000 ++ baseUrl: ${BACKSTAGE_HOST} + +backend: +- baseUrl: http://localhost:7007 ++ baseUrl: ${BACKSTAGE_HOST} + listen: + port: 7007 +``` + +The environment variable `BACKSTAGE_HOST` will be set to the endpoint that AWS Lightsail creates. + +In addition, you should create a `app-config.local.yaml`: + +```bash +$ touch app-config.local.yaml +``` + +And then update the file with the following yaml: + +```yaml +app: + baseUrl: http://localhost:3000 + +backend: + baseUrl: http://localhost:7007 +``` + +Now we can deploy our instance! + +```bash +$ npx backstage-deploy aws --stack backstage-poc --create-dockerfile +``` + +In the first part of the command, we are specifying that we want to deploy our instance on AWS. With the [`--stack`](https://www.pulumi.com/docs/reference/cli/pulumi_stack/) option, we are providing Pulumi a reference to our container deployment. Furthermore, with the `--create-dockerfile` option, there will be a `Dockerfile` and `.dockerignore` created in the root of the project. + +After running the command, Pulumi will start creating the following resources for you in AWS: + +- ECR Repository +- Lightsail Container Service +- Lightsail Container Service Deployment +- Policy that allows Lightsail to pull from ECR + +If it's the first time building the Docker image, it might take a while for everything to be fully provisioned. After the command is finished running, your Backstage instance should be up and running on AWS Lightsail! 🎉 + +### Cleaning up resources + +Cleaning up the resources is also done with the deploy command. + +```bash +$ npx backstage-deploy aws --stack backstage-poc --destroy +``` + +This will delete everything that was originally created by the `deploy` command. \ No newline at end of file diff --git a/microsite/sidebars.json b/microsite/sidebars.json index 972a67f424..f697255539 100644 --- a/microsite/sidebars.json +++ b/microsite/sidebars.json @@ -325,7 +325,14 @@ "deployment/scaling", "deployment/docker", "deployment/k8s", - "deployment/heroku" + "deployment/heroku", + { + "type": "category", + "label": "Deploying on a cloud provider with Backstage Deploy", + "items": [ + "deployment/backstage-deploy/aws" + ] + } ], "Designing for Backstage": [ "dls/design", From ff7fe9abdd119a9b35ee3ffb1283b0a90ec6d553 Mon Sep 17 00:00:00 2001 From: djamaile Date: Tue, 16 May 2023 14:52:45 +0200 Subject: [PATCH 2/8] fix: add words to vale Signed-off-by: djamaile --- .github/vale/Vocab/Backstage/accept.txt | 2 ++ docs/deployment/backstage-deploy/aws.md | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/.github/vale/Vocab/Backstage/accept.txt b/.github/vale/Vocab/Backstage/accept.txt index e9fc74b874..2c50b55219 100644 --- a/.github/vale/Vocab/Backstage/accept.txt +++ b/.github/vale/Vocab/Backstage/accept.txt @@ -434,3 +434,5 @@ zod Zolotusky zoomable zsh +Pulumi +Lightsail diff --git a/docs/deployment/backstage-deploy/aws.md b/docs/deployment/backstage-deploy/aws.md index cac9ede624..e5309b8a83 100644 --- a/docs/deployment/backstage-deploy/aws.md +++ b/docs/deployment/backstage-deploy/aws.md @@ -185,4 +185,4 @@ Cleaning up the resources is also done with the deploy command. $ npx backstage-deploy aws --stack backstage-poc --destroy ``` -This will delete everything that was originally created by the `deploy` command. \ No newline at end of file +This will delete everything that was originally created by the `deploy` command. From 4dd8b4dea28fd91de945481f8516d3cbd4e3dfbd Mon Sep 17 00:00:00 2001 From: djamaile Date: Tue, 16 May 2023 16:07:25 +0200 Subject: [PATCH 3/8] fix: run prettier on sidebar Signed-off-by: djamaile --- microsite/sidebars.json | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/microsite/sidebars.json b/microsite/sidebars.json index f697255539..dc24a57737 100644 --- a/microsite/sidebars.json +++ b/microsite/sidebars.json @@ -329,9 +329,7 @@ { "type": "category", "label": "Deploying on a cloud provider with Backstage Deploy", - "items": [ - "deployment/backstage-deploy/aws" - ] + "items": ["deployment/backstage-deploy/aws"] } ], "Designing for Backstage": [ From 60f31ee9ea8b3e32829c056e18061eede35b077b Mon Sep 17 00:00:00 2001 From: Djam Date: Wed, 31 May 2023 21:37:19 +0200 Subject: [PATCH 4/8] Update docs/deployment/backstage-deploy/aws.md Co-authored-by: Patrik Oldsberg Signed-off-by: Djam --- docs/deployment/backstage-deploy/aws.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/deployment/backstage-deploy/aws.md b/docs/deployment/backstage-deploy/aws.md index e5309b8a83..897eb440c3 100644 --- a/docs/deployment/backstage-deploy/aws.md +++ b/docs/deployment/backstage-deploy/aws.md @@ -122,7 +122,7 @@ By using `pulumi login --local` we are making sure that Pulumi stores our state :::warning -Make sure that [Docker](https://docs.docker.com/) is running before you start with this section. +Make sure that [Docker](https://docs.docker.com/) is running before you start this section. ::: From 124ab2fd477129d7a234cf21bb0d1b020d7b7082 Mon Sep 17 00:00:00 2001 From: djamaile Date: Wed, 31 May 2023 21:59:50 +0200 Subject: [PATCH 5/8] chore: address feedback Signed-off-by: djamaile --- docs/deployment/backstage-deploy/aws.md | 10 ++++++++-- microsite/sidebars.json | 4 ++-- 2 files changed, 10 insertions(+), 4 deletions(-) diff --git a/docs/deployment/backstage-deploy/aws.md b/docs/deployment/backstage-deploy/aws.md index 897eb440c3..9d5fdc3ebb 100644 --- a/docs/deployment/backstage-deploy/aws.md +++ b/docs/deployment/backstage-deploy/aws.md @@ -1,7 +1,7 @@ --- -id: aws +id: aws-lightsail title: Deploying Backstage on AWS Lightsail -sidebar_label: AWS +sidebar_label: AWS Lightsail description: How to deploy Backstage on AWS Lightsail --- @@ -111,6 +111,12 @@ Second, install the [Pulumi CLI](https://www.pulumi.com/docs/get-started/install Then we need to execute the following commands, to set Pulumi up: +:::tip + +Make sure to store your passphrase somewhere save as it is used to encrypt/decrypt your Pulumi config. + +::: + ```bash $ pulumi login --local $ export PULUMI_CONFIG_PASSPHRASE="" diff --git a/microsite/sidebars.json b/microsite/sidebars.json index dc24a57737..f612e7b880 100644 --- a/microsite/sidebars.json +++ b/microsite/sidebars.json @@ -328,8 +328,8 @@ "deployment/heroku", { "type": "category", - "label": "Deploying on a cloud provider with Backstage Deploy", - "items": ["deployment/backstage-deploy/aws"] + "label": "Using Backstage Deploy (alpha)", + "items": ["deployment/backstage-deploy/aws-lightsail"] } ], "Designing for Backstage": [ From e939b298a527a776fe878034ad4a13d1f2ee000d Mon Sep 17 00:00:00 2001 From: djamaile Date: Thu, 1 Jun 2023 17:15:02 +0200 Subject: [PATCH 6/8] chore: rewrite app-config instructrions Signed-off-by: djamaile --- docs/deployment/backstage-deploy/aws.md | 26 ++++++------------------- 1 file changed, 6 insertions(+), 20 deletions(-) diff --git a/docs/deployment/backstage-deploy/aws.md b/docs/deployment/backstage-deploy/aws.md index 9d5fdc3ebb..93f38bcc3e 100644 --- a/docs/deployment/backstage-deploy/aws.md +++ b/docs/deployment/backstage-deploy/aws.md @@ -134,38 +134,24 @@ Make sure that [Docker](https://docs.docker.com/) is running before you start th After you have made your changes to your local instance, it's time to deploy it on Lightsail. -First, we need to configure the `app-config.yaml` and update the `baseUrl`. - -```diff -app: -- baseUrl: http://localhost:3000 -+ baseUrl: ${BACKSTAGE_HOST} - -backend: -- baseUrl: http://localhost:7007 -+ baseUrl: ${BACKSTAGE_HOST} - listen: - port: 7007 -``` - -The environment variable `BACKSTAGE_HOST` will be set to the endpoint that AWS Lightsail creates. - -In addition, you should create a `app-config.local.yaml`: +First, we need to configure a new `app-config` file and update the `baseUrl`. ```bash -$ touch app-config.local.yaml +$ touch app-config.deployment.yaml ``` And then update the file with the following yaml: ```yaml app: - baseUrl: http://localhost:3000 + baseUrl: ${BACKSTAGE_HOST} backend: - baseUrl: http://localhost:7007 + baseUrl: ${BACKSTAGE_HOST} ``` +The environment variable `BACKSTAGE_HOST` will be set to the endpoint that AWS Lightsail creates. + Now we can deploy our instance! ```bash From 705f31bb012b89ecd557190a2b1e873120b00836 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Wed, 7 Jun 2023 11:47:23 +0200 Subject: [PATCH 7/8] Update docs/deployment/backstage-deploy/aws.md Signed-off-by: Patrik Oldsberg --- docs/deployment/backstage-deploy/aws.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/deployment/backstage-deploy/aws.md b/docs/deployment/backstage-deploy/aws.md index 93f38bcc3e..957dc27437 100644 --- a/docs/deployment/backstage-deploy/aws.md +++ b/docs/deployment/backstage-deploy/aws.md @@ -113,7 +113,7 @@ Then we need to execute the following commands, to set Pulumi up: :::tip -Make sure to store your passphrase somewhere save as it is used to encrypt/decrypt your Pulumi config. +Make sure to store your passphrase somewhere safe as it is used to encrypt/decrypt your Pulumi config. ::: From e9c45927d5d549c580ffd9d6bc4bb68c1a328bd8 Mon Sep 17 00:00:00 2001 From: djamaile Date: Fri, 9 Jun 2023 01:38:08 +0200 Subject: [PATCH 8/8] chore: add docs reference back Signed-off-by: djamaile --- microsite/blog/2023-05-06-backstage-deploy-alpha.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/microsite/blog/2023-05-06-backstage-deploy-alpha.mdx b/microsite/blog/2023-05-06-backstage-deploy-alpha.mdx index cc0f3ee1a9..1a783b026a 100644 --- a/microsite/blog/2023-05-06-backstage-deploy-alpha.mdx +++ b/microsite/blog/2023-05-06-backstage-deploy-alpha.mdx @@ -38,7 +38,7 @@ It's now time to put the Deploy CLI into action and deploy a Backstage POC. The Deploy CLI makes use of [Pulumi](https://www.pulumi.com/docs/) which is an infrastructure-as-code tool that helps provision resources in the cloud. Before you get started, ensure you have the [Pulumi CLI](https://www.pulumi.com/docs/cli/) and [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) installed on your local machine. -You can find the step-by-step installation documentation for Pulumi under the [Deployment section](https://backstage.io/docs/deployment/pulumi/aws). +You can find the step-by-step installation documentation for Pulumi under the [Deployment section](https://backstage.io/docs/deployment/backstage-deploy/aws-lightsail). But we summarize the steps to deploy your POC here. You can invoke the the CLI you can use the following command: @@ -74,5 +74,6 @@ So, please try this new CLI out and let us know what you think on [Discord](http Useful links: - [Backstage Deploy](https://github.com/backstage/backstage-deploy) +- [Documentation](https://backstage.io/docs/deployment/backstage-deploy/aws-lightsail) - [Pulumi docs](https://www.pulumi.com/docs/) - [#deployment](https://discord.com/channels/687207715902193673/995973463208644678) channel in Discord