with-backstage

AWS reference architecture with Backstage

Provisions the AWS reference architecture connected to Humanitec and installs Backstage.

Prerequisites

• The same prerequisites as the base reference architecture, plus the following items.
• A GitHub organization and permission to create new repositories in it. Go to https://github.com/account/organizations/new to create a new org (the "Free" option is fine). Note: is has to be an organization, a free account is not sufficient.
• Create a classic github personal access token with repo, workflow, delete_repo and admin:org scope here.
• Set the GITHUB_TOKEN environment variable to your token.

  export GITHUB_TOKEN="my-github-token"
  

• Set the GITHUB_ORG_ID environment variable to your GitHub organization ID.

  export GITHUB_ORG_ID="my-github-org-id"
  

• Node.js installed locally.
• Install the GitHub App for Backstage into your GitHub organization using node create-gh-app/index.js. Follow the instructions.
  • “All repositories” ~> Install
  • “Okay, […] was installed on the […] account.” ~> You can close the window and server.

Usage

Follow the same steps as for the base layer, applying these modifications:

• Execute cd ./examples/with-backstage after cloning the repo. Execute all subsequent commands in this directory.
• In particular, use the ./examples/with-backstage/terraform.tfvars.example file as the basis for your terraform.tfvars file. It defines additional variables needed to setup and configure Backstage.

Verify your result

Check for the existence of key elements of the backstage module. This is a subset of all elements only. For a complete list of what was installed, review the Terraform code.

1. Perform the verification steps of the base installation if you have not already done so.

2. Verify the existence of the Backstage Application in your Humanitec Organization:

   curl -s https://api.humanitec.io/orgs/${HUMANITEC_ORG}/apps/backstage \
     --header "Authorization: Bearer ${HUMANITEC_TOKEN}"
   

   This should output a JSON formatted representation of the Application like so:

   {"id":"backstage","name":"backstage","created_at":"2023-10-02T13:44:27Z","created_by":"s-d3e94a0e-8b53-29f9-b666-27548b7e06e0","envs":[{"id":"development","name":"Development","type":"development"}]}
   

   You can also check for the Application in the Humanitec Platform Orchestrator UI.

3. Connect to your EKS cluster via kubectl. See the AWS documentation or use this command:

   aws eks update-kubeconfig --region <my-aws-region> --name ref-arch
   

4. Get the elements in the newly created Kubernetes namespace:

   kubectl get all -n backstage-development
   

   You should see

   • a deployment, replicaset, running pod, and service for Backstage
   • a statefulset, running pod, and service for PostgreSQL database used by Backstage.

   Note: it may take up to ten minutes after the terraform apply completed until you actually see those resources. The Backstage application needs to built and deployed via a GitHub action out of the newly created repository in your GitHub organization.

Cleaning up

Once you are finished with the reference architecture, you can remove all provisioned infrastrcuture and the resource definitions created in Humanitec with the following:

1. Delete all Humanitec applications scaffolded using Backstage, but not the backstage app itself.

2. Follow the base reference architecture cleanup instructions.

Terraform docs

Requirements

Name	Version
terraform	>= 1.3.0
aws	~> 5.17
github	~> 5.38
humanitec	~> 0.13

Providers

Name	Version
aws	~> 5.17
github	~> 5.38
humanitec	~> 0.13

Modules

Name	Source	Version
backstage_ecr	terraform-aws-modules/ecr/aws	~> 1.6
backstage_iam_policy_ecr_create_repository	git::https://github.com/humanitec-architecture/resource-packs-aws.git//humanitec-resource-defs/iam-policy/ecr-create-repository	n/a
backstage_iam_role_service_account	git::https://github.com/humanitec-architecture/resource-packs-aws.git//humanitec-resource-defs/iam-role/service-account	n/a
backstage_k8s_service_account	git::https://github.com/humanitec-architecture/resource-packs-aws.git//humanitec-resource-defs/k8s/service-account	n/a
backstage_mysql	git::https://github.com/humanitec-architecture/resource-packs-in-cluster.git//humanitec-resource-defs/mysql/basic	n/a
backstage_postgres	git::https://github.com/humanitec-architecture/resource-packs-in-cluster.git//humanitec-resource-defs/postgres/basic	n/a
backstage_workload	git::https://github.com/humanitec-architecture/resource-packs-aws.git//humanitec-resource-defs/workload/service-account	n/a
base	../../modules/base	n/a
iam_github_oidc_provider	terraform-aws-modules/iam/aws//modules/iam-github-oidc-provider	~> 5.30
iam_github_oidc_role	terraform-aws-modules/iam/aws//modules/iam-github-oidc-role	~> 5.30

Resources

Name	Type
aws_iam_policy.ecr_push_policy	resource
github_actions_organization_secret.backstage_humanitec_token	resource
github_actions_organization_variable.backstage_aws_region	resource
github_actions_organization_variable.backstage_aws_role_arn	resource
github_actions_organization_variable.backstage_cloud_provider	resource
github_actions_organization_variable.backstage_humanitec_org_id	resource
github_repository.backstage	resource
humanitec_application.backstage	resource
humanitec_resource_definition_criteria.backstage_iam_policy_ecr_create_repository	resource
humanitec_resource_definition_criteria.backstage_iam_role_service_account	resource
humanitec_resource_definition_criteria.backstage_k8s_service_account	resource
humanitec_resource_definition_criteria.backstage_mysql	resource
humanitec_resource_definition_criteria.backstage_postgres	resource
humanitec_resource_definition_criteria.backstage_workload	resource
humanitec_value.aws_default_region	resource
humanitec_value.backstage_cloud_provider	resource
humanitec_value.backstage_github_app_client_id	resource
humanitec_value.backstage_github_app_client_secret	resource
humanitec_value.backstage_github_app_id	resource
humanitec_value.backstage_github_app_private_key	resource
humanitec_value.backstage_github_app_webhook_secret	resource
humanitec_value.backstage_github_org_id	resource
humanitec_value.backstage_humanitec_org	resource
humanitec_value.backstage_humanitec_token	resource

Inputs

Name	Description	Type	Default	Required
aws_account_id	AWS Account (ID) to use	string	n/a	yes
aws_region	AWS region	string	n/a	yes
github_org_id	GitHub org id	string	n/a	yes
humanitec_ci_service_user_token	Humanitec CI Service User Token	string	n/a	yes
humanitec_org_id	Humanitec Organization ID	string	n/a	yes
resource_packs_aws_rev	Revision of the resource-packs-aws repository to use	string	"refs/heads/main"	no