Merge pull request #15 from htc-demo-00-azure/toggleable-backstage

feat: toggleable backstage

Author: johanneswuerbach

.github/workflows/ci.yaml

@@ -20,30 +20,22 @@ jobs:
       - name: Install terraform-docs
         run: |
           WORK_DIR=$(mktemp -d)
-          curl -Lo ${WORK_DIR}/terraform-docs.tar.gz https://github.com/terraform-docs/terraform-docs/releases/download/v0.16.0/terraform-docs-v0.16.0-$(uname)-amd64.tar.gz
+          curl -Lo ${WORK_DIR}/terraform-docs.tar.gz https://github.com/terraform-docs/terraform-docs/releases/download/v0.18.0/terraform-docs-v0.18.0-$(uname)-amd64.tar.gz
           cd ${WORK_DIR}
           tar -xzf terraform-docs.tar.gz
           chmod +x terraform-docs
           mv terraform-docs /usr/local/bin/terraform-docs
-
       - name: Generate docs
         run: make docs
 
       - name: Check git diff is clean (all files generated should be committed)
         run: git diff --exit-code
 
-      - name: Terraform Format Check
-        run: make fmt-check
-
-      - name: Stub GitHub App credentials (required for validation)
-        run: cd ./examples/with-backstage && STUB_FILE=1 node create-gh-app/index.js
-
-      - name: Terraform Validate
-        run: make validate
-
       - uses: terraform-linters/setup-tflint@v4
         with:
-          tflint_version: v0.49.0
-
-      - name: Lint
+          tflint_version: v0.51.1
+      - name: Terraform Lint
         run: make lint
+
+      - name: Terraform Validate
+        run: make validate

.tflint.hcl

@@ -5,6 +5,6 @@ plugin "terraform" {
 
 plugin "azurerm" {
   enabled = true
-  version = "0.25.1"
+  version = "0.26.0"
   source  = "github.com/terraform-linters/tflint-ruleset-azurerm"
 }

Makefile

@@ -1,15 +1,18 @@
 TF_DIRS = $(patsubst %/main.tf, %, $(shell find . -type d -name .terraform -prune -o -name 'main.tf' -print))
 VALIDATE_TF_DIRS = $(addprefix validate-,$(TF_DIRS))
 LINT_TF_DIRS = $(addprefix lint-,$(TF_DIRS))
+DOCS_TF_DIRS = $(addprefix docs-,$(TF_DIRS))
+
+# Generate docs for a terraform directories
+$(DOCS_TF_DIRS): docs-%:
+	@echo "Docs $*"
+	terraform-docs --config docs/.terraform-docs.yaml $*
+	terraform-docs --config docs/.terraform-docs-example.yaml $*
 
 # Generate docs
 .PHONY: docs
-docs:
-	terraform-docs --lockfile=false ./modules/base
-	terraform-docs --config docs/.terraform-docs.yaml .
-	terraform-docs --config docs/.terraform-docs-example.yaml .
-	terraform-docs --config docs/.terraform-docs.yaml ./examples/with-backstage
-	terraform-docs --config docs/.terraform-docs-example.yaml ./examples/with-backstage
+docs: $(DOCS_TF_DIRS)
+	@echo "All docs generated"
 
 # Format all terraform files
 fmt:
@@ -39,5 +42,5 @@ lint-init:
 	tflint --init
 
 # Lint all terraform directories
-lint: lint-init $(LINT_TF_DIRS)
+lint: lint-init $(LINT_TF_DIRS) fmt-check
 	@echo "All linted"

README.md

@@ -58,7 +58,7 @@ This plane is where the actual infrastructure exists including clusters, databas
 
 ## How to spin up your Humanitec Azure Reference Architecture
 
-This repo contains an implementation of part of the Humanitec Reference Architecture for an Internal Developer Platform.
+This repo contains an implementation of part of the Humanitec Reference Architecture for an Internal Developer Platform, including Backstage as optional Portal solution.
 
 This repo covers the base layer of the implementation for Azure.
 
@@ -98,21 +98,21 @@ This reference architecture implementation uses Terraform. You will need to do t
 
    For example:
 
-   ```
+   ```shell
    export HUMANITEC_TOKEN="my-humanitec-api-token"
    ```
 
 5. Run terraform:
 
-   ```
+   ```shell
    terraform init
    terraform plan
    terraform apply
    ```
 
    `terraform plan` and `apply` might output this message:
 
-   ```
+   ```shell
    │ Warning: Argument is deprecated
    │
    │   with module.base.module.azure_aks.azurerm_kubernetes_cluster.main,
@@ -136,34 +136,34 @@ Check for the existence of key elements of the reference architecture. This is a
 
 1. Set the `HUMANITEC_ORG` environment variable to the ID of your Humanitec Organization (must be all lowercase):
 
-   ```
+   ```shell
    export HUMANITEC_ORG="my-humanitec-org"
    ```
 
 2. Verify the existence of the Resource Definition for the AKS cluster in your Humanitec Organization:
 
-   ```
+   ```shell
    curl -s https://api.humanitec.io/orgs/${HUMANITEC_ORG}/resources/defs/ref-arch \
      --header "Authorization: Bearer ${HUMANITEC_TOKEN}" \
      | jq .id,.type
    ```
 
    This should output:
 
-   ```
+   ```shell
    "ref-arch"
    "k8s-cluster"
    ```
 
 3. Verify the existence of the newly created AKS cluster:
 
-   ```
+   ```shell
    az aks list --subscription <your-subscription>
    ```
 
    This should output:
 
-   ```
+   ```shell
    [
       {
          ... various properties ...
@@ -173,17 +173,56 @@ Check for the existence of key elements of the reference architecture. This is a
    ]
    ```
 
+### Enable a portal (optional)
+
+#### Portal Prerequisites
+
+Backstage requires a GitHub connection, which in turn needs:
+
+* 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](https://github.com/settings/tokens).
+* Set the `GITHUB_TOKEN` environment variable to your token.
+
+  ```shell
+  export GITHUB_TOKEN="my-github-token"
+  ```
+
+* Set the `GITHUB_ORG_ID` environment variable to your GitHub organization ID.
+
+  ```shell
+  export GITHUB_ORG_ID="my-github-org-id"
+  ```
+
+* Install the GitHub App for Backstage into your GitHub organization
+  * Run `docker run --rm -it -e GITHUB_ORG_ID -v $(pwd):/pwd -p 127.0.0.1:3000:3000 ghcr.io/humanitec-architecture/create-gh-app` ([image source](https://github.com/humanitec-architecture/create-gh-app/)) and follow the instructions:
+    * “All repositories” ~> Install
+    * “Okay, […] was installed on the […] account.” ~> You can close the window and server.
+
+#### Portal Usage
+
+* Enable `with_backstage` inside your `terraform.tfvars` and configure the additional variables that a required for Backstage.
+* Perform another `terraform apply`
+
+#### Verify portal setup
+
+* [Fetch the DNS entry](https://developer.humanitec.com/score/getting-started/get-dns/) of the Humanitec Application `backstage`, Environment `development`.
+* Open the host in your browser.
+* Click the "Create" button and scaffold your first application.
+
 ### Cleaning up
 
 Once you are finished with the reference architecture, you can remove all provisioned infrastructure and the resource definitions created in Humanitec with the following:
 
-1. Ensure you are (still) logged in with `az`.
+Once you are finished with the reference architecture, you can remove all provisioned infrastructure and the resource definitions created in Humanitec with the following:
+
+1. Delete all Humanitec Applications scaffolded using the Portal, if you used one, but not the `backstage` app itself.
+2. Ensure you are (still) logged in with `az`.
 
-2. Ensure you still have the `HUMANITEC_TOKEN` environment variable set to an appropriate Humanitec API token with the `Administrator` role on the Humanitec Organization.
+3. Ensure you still have the `HUMANITEC_TOKEN` environment variable set to an appropriate Humanitec API token with the `Administrator` role on the Humanitec Organization.
 
-3. Run terraform:
+4. Run terraform:
 
-   ```
+   ```shell
    terraform destroy
    ```
 
@@ -198,24 +237,44 @@ Once you are finished with the reference architecture, you can remove all provis
 | azapi | ~> 1.11 |
 | azuread | ~> 2.47 |
 | azurerm | ~> 3.87 |
+| github | ~> 5.38 |
 | helm | ~> 2.12 |
 | humanitec | ~> 1.0 |
 | kubernetes | ~> 2.25 |
+| random | ~> 3.5 |
+
+### Providers
+
+| Name | Version |
+|------|---------|
+| humanitec | ~> 1.0 |
 
 ### Modules
 
 | Name | Source | Version |
 |------|--------|---------|
 | base | ./modules/base | n/a |
+| github | ./modules/github | n/a |
+| github\_app | github.com/humanitec-architecture/shared-terraform-modules | v2024-06-12//modules/github-app |
+| portal\_backstage | ./modules/portal-backstage | n/a |
+
+### Resources
+
+| Name | Type |
+|------|------|
+| [humanitec_service_user_token.deployer](https://registry.terraform.io/providers/humanitec/humanitec/latest/docs/resources/service_user_token) | resource |
+| [humanitec_user.deployer](https://registry.terraform.io/providers/humanitec/humanitec/latest/docs/resources/user) | resource |
 
 ### Inputs
 
 | Name | Description | Type | Default | Required |
 |------|-------------|------|---------|:--------:|
-| humanitec\_org\_id | Humanitec Organization ID | `string` | n/a | yes |
 | location | Azure region to deploy into | `string` | n/a | yes |
 | subscription\_id | Azure Subscription (ID) to use | `string` | n/a | yes |
+| github\_org\_id | GitHub org id (required for Backstage) | `string` | `null` | no |
+| humanitec\_org\_id | Humanitec Organization ID (required for Backstage) | `string` | `null` | no |
 | vm\_size | The Azure VM instances type to use as "Agents" (aka Kubernetes Nodes) in AKS | `string` | `"Standard_D2_v2"` | no |
+| with\_backstage | Deploy Backstage | `bool` | `false` | no |
 
 ### Outputs