{"id":22585427,"url":"https://github.com/silthus/terraform-backstage-metadata-module","last_synced_at":"2025-04-15T06:49:06.071Z","repository":{"id":266058597,"uuid":"897263037","full_name":"Silthus/terraform-backstage-metadata-module","owner":"Silthus","description":"A metadata wrapper module around the Terraform Backstage provider to compile a list of resource labels as output.","archived":false,"fork":false,"pushed_at":"2025-03-10T15:44:03.000Z","size":46,"stargazers_count":8,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-15T06:49:01.259Z","etag":null,"topics":["backstage","terraform","terraform-module"],"latest_commit_sha":null,"homepage":"","language":"HCL","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Silthus.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"silthus"}},"created_at":"2024-12-02T10:26:56.000Z","updated_at":"2025-02-27T08:02:37.000Z","dependencies_parsed_at":"2025-02-25T14:26:20.886Z","dependency_job_id":null,"html_url":"https://github.com/Silthus/terraform-backstage-metadata-module","commit_stats":null,"previous_names":["silthus/terraform-backstage-metadata-module"],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Silthus%2Fterraform-backstage-metadata-module","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Silthus%2Fterraform-backstage-metadata-module/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Silthus%2Fterraform-backstage-metadata-module/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Silthus%2Fterraform-backstage-metadata-module/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Silthus","download_url":"https://codeload.github.com/Silthus/terraform-backstage-metadata-module/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249023707,"owners_count":21199958,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["backstage","terraform","terraform-module"],"created_at":"2024-12-08T07:08:39.917Z","updated_at":"2025-04-15T06:49:06.047Z","avatar_url":"https://github.com/Silthus.png","language":"HCL","funding_links":["https://github.com/sponsors/silthus","https://github.com/sponsors/Silthus"],"categories":[],"sub_categories":[],"readme":"# terraform-backstage-metadata-module\n\n[![GitHub release (latest by date)](https://img.shields.io/github/v/release/silthus/terraform-backstage-metadata-module)](https://github.com/Silthus/terraform-backstage-metadata-module/releases)\n[![⚙️ CI](https://github.com/Silthus/terraform-backstage-metadata-module/actions/workflows/ci.yaml/badge.svg)](https://github.com/Silthus/terraform-backstage-metadata-module/actions/workflows/ci.yaml)\n[![🚀 Release Please](https://github.com/Silthus/terraform-backstage-metadata-module/actions/workflows/release.yaml/badge.svg)](https://github.com/Silthus/terraform-backstage-metadata-module/actions/workflows/release.yaml)\n[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--versioning-e10079.svg)](https://semver.org/)\n[![GitHub License](https://img.shields.io/github/license/silthus/terraform-backstage-metadata-module)](https://github.com/Silthus/terraform-backstage-metadata-module/blob/main/LICENSE)\n[![GitHub Sponsors](https://img.shields.io/github/sponsors/silthus)](https://github.com/sponsors/Silthus)\n![GitHub Repo stars](https://img.shields.io/github/stars/silthus/terraform-backstage-metadata-module)\n\nA metadata wrapper module around the [Terraform Backstage provider](https://registry.terraform.io/providers/datolabs-io/backstage/latest) to fetch metadata for an entity from Backstage and compile a list of resource labels as output.\n\n## Features\n\n- Fetch metadata for a Backstage entity\n- Compile a list of resource labels from the metadata\n- Fallback to a provided metadata object if the Backstage API is not reachable\n- Retry the request to the Backstage API a configurable number of times\n\n## Fallback Mechanism\n\nIn general, tying infrastructure to a third-party API is not recommended. However, in some cases, it is necessary to fetch metadata from a third-party API to configure infrastructure. In such cases, it is important to have a fallback mechanism in place to ensure that the infrastructure can still be configured even if the third-party API is not reachable.\n\nThis module provides multiple fallback mechanisms ensuring that the infrastructure can still be configured even if the Backstage API is not reachable.\n\n### Retry API Requests\n\nIf configured the [datolabs-io/backstage](https://registry.terraform.io/providers/datolabs-io/backstage/latest) provider will retry the request to the Backstage API a configurable number of times before failing. This ensures that the request is retried multiple times before falling back to the next fallback mechanism.\n\n```hcl\nprovider \"backstage\" {\n  ...\n  # After failing the `fallback` input of the module kicks in.\n  retries = 3\n}\n```\n\n### Remote State Fallback\n\nIf the `fallback` input is provided, the module will use the provided metadata object as a fallback if the Backstage API is not reachable. This allows you to provide a known good metadata object as a fallback in case the Backstage API is not reachable.  \nIt is recommended to use the [`terraform_remote_state`](https://developer.hashicorp.com/terraform/language/state/remote-state-data) data source to fetch the last known metadata object from the remote state backend.\n\n```hcl\nmodule \"metadata\" {\n  source = \"github.com/silthus/terraform-backstage-metadata-module?ref=v1.0.0\" # x-release-please-version\n\n  name = var.entity_name\n  # This loops back the last metadata in the state\n  # as a fallback if the Backstage API is not reachable.\n  # By design the terraform_remote_state data source will return null if no state is found.\n  # And the metadata module will simply treat a null fallback as no fallback, and will return an error if the Backstage API is not reachable.\n  fallback = data.terraform_remote_state.metadata.outputs.metadata.entity\n}\n\ndata \"terraform_remote_state\" \"metadata\" {\n  backend = \"gcs\" // TODO: replace this with the actual backend and config you are using\n  config = {\n    bucket = \"some-bucket\"\n    prefix = \"some-prefix\"\n  }\n}\n```\n\n### Fallback Sub-Module\n\nAs a last resort, or if you don't want to use the remote state fallback, you can manually switch the `modules/fallback` submodule, which acks as a mock Backstage API and returns a predefined object with empty and dummy labels and metadata.\n\n```hcl\nmodule \"metadata\" {\n  source = \"github.com/silthus/terraform-backstage-metadata-module//modules/fallback?ref=v1.0.0\" # x-release-please-version\n\n  name = var.entity_name\n}\n```\n\n\u003c!-- BEGIN_TF_DOCS --\u003e\n\n\n## Usage\n\n```hcl\nmodule \"metadata\" {\n  source = \"github.com/silthus/terraform-backstage-metadata-module?ref=v1.0.0\" # x-release-please-version\n\n  name = var.entity_name\n  # This loops back the last metadata in the state\n  # as a fallback if the Backstage API is not reachable.\n  # By design the terraform_remote_state data source will return null if no state is found.\n  # And the metadata module will simply treat a null fallback as no fallback, and will return an error if the Backstage API is not reachable.\n  fallback = data.terraform_remote_state.metadata.outputs.metadata.entity\n}\n\ndata \"terraform_remote_state\" \"metadata\" {\n  backend = \"gcs\" // TODO: replace this with the actual backend and config you are using\n  config = {\n    bucket = \"some-bucket\"\n    prefix = \"some-prefix\"\n  }\n}\n\nprovider \"backstage\" {\n  base_url = \"https://backstage.io/\" # TODO: provide your own Backstage URL\n  headers = {\n    \"Authorization\" = \"Bearer \u003csome-token\u003e\" # TODO: provide your own Backstage API token. See https://backstage.io/docs/auth/service-to-service-auth/#static-tokens for more information.\n  }\n  # This configures the fallback capabilities of the provider itself to retry the request 3 times before failing.\n  # After failing the above `fallback` kicks in and provides the last known metadata from the terraform state.\n  retries = 3\n}\n```\n\n## Required Inputs\n\nThe following input variables are required:\n\n### \u003ca name=\"input_name\"\u003e\u003c/a\u003e [name](#input\\_name)\n\nDescription: The name of the entity you need metadata for.\n\nType: `string`\n\n## Optional Inputs\n\nThe following input variables are optional (have default values):\n\n### \u003ca name=\"input_environment\"\u003e\u003c/a\u003e [environment](#input\\_environment)\n\nDescription: The name of the environment you are deploying to.\n\nType: `string`\n\nDefault: `\"unknown\"`\n\n### \u003ca name=\"input_fallback\"\u003e\u003c/a\u003e [fallback](#input\\_fallback)\n\nDescription: The fallback data to use if the Backstage API returns an error or is not reachable. It is recommended to use the terraform\\_remote\\_state data source to fetch the data from the remote state backend.\n\nType:\n\n```hcl\nobject({\n    api_version = string\n    kind        = string\n    metadata = object({\n      annotations = optional(map(string))\n      description = optional(string)\n      etag        = optional(string)\n      labels      = optional(map(string))\n      links = optional(list(object({\n        icon  = optional(string)\n        title = string\n        type  = optional(string)\n        url   = string\n      })))\n      name      = string\n      namespace = string\n      tags      = optional(list(string))\n      title     = optional(string)\n    })\n    relations = optional(list(object({\n      target = object({\n        kind      = string\n        name      = string\n        namespace = string\n      })\n      target_ref = string\n      type       = string\n    })))\n    spec = optional(string)\n  })\n```\n\nDefault: `null`\n\n### \u003ca name=\"input_kind\"\u003e\u003c/a\u003e [kind](#input\\_kind)\n\nDescription: The kind of Backstage entity you are fetch metadata for.\n\nType: `string`\n\nDefault: `\"Component\"`\n\n### \u003ca name=\"input_namespace\"\u003e\u003c/a\u003e [namespace](#input\\_namespace)\n\nDescription: The namespace of the entity you need metadata for.\n\nType: `string`\n\nDefault: `\"default\"`\n\n## Outputs\n\nThe following outputs are exported:\n\n### \u003ca name=\"output_entity\"\u003e\u003c/a\u003e [entity](#output\\_entity)\n\nDescription: The full component object as defined by the Backstage API.\n\n### \u003ca name=\"output_labels\"\u003e\u003c/a\u003e [labels](#output\\_labels)\n\nDescription: A common set of labels to attach to cloud resources.\n\n### \u003ca name=\"output_metadata\"\u003e\u003c/a\u003e [metadata](#output\\_metadata)\n\nDescription: A flattened filtered set of metadata from the component object.\n\n## Requirements\n\nThe following requirements are needed by this module:\n\n- \u003ca name=\"requirement_terraform\"\u003e\u003c/a\u003e [terraform](#requirement\\_terraform) (\u003e= 1.9.6, \u003c 2)\n\n- \u003ca name=\"requirement_backstage\"\u003e\u003c/a\u003e [backstage](#requirement\\_backstage) (\u003e= 3.1.0)\n\n## Providers\n\nThe following providers are used by this module:\n\n- \u003ca name=\"provider_backstage\"\u003e\u003c/a\u003e [backstage](#provider\\_backstage) (3.1.0)\n\n## Modules\n\nNo modules.\n\n## Resources\n\nThe following resources are used by this module:\n\n- [backstage_entities.entity](https://registry.terraform.io/providers/datolabs-io/backstage/latest/docs/data-sources/entities) (data source)\n\u003c!-- END_TF_DOCS --\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsilthus%2Fterraform-backstage-metadata-module","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsilthus%2Fterraform-backstage-metadata-module","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsilthus%2Fterraform-backstage-metadata-module/lists"}