Skip to content

Latest commit

 

History

History
 
 

with-backstage

README.md

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
disk_size Disk size in GB to use for EKS nodes number 20 no
instance_types List of EC2 instances types to use for EKS nodes list(string) 
[
  "t3.large"
]
 no
resource_packs_aws_rev Revision of the resource-packs-aws repository to use string "refs/heads/main" no