A metadata wrapper module around the Terraform Backstage provider to fetch metadata for an entity from Backstage and compile a list of resource labels as output.
- Fetch metadata for a Backstage entity
- Compile a list of resource labels from the metadata
- Fallback to a provided metadata object if the Backstage API is not reachable
- Retry the request to the Backstage API a configurable number of times
In 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.
This module provides multiple fallback mechanisms ensuring that the infrastructure can still be configured even if the Backstage API is not reachable.
If configured the datolabs-io/backstage 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.
provider "backstage" {
...
# After failing the `fallback` input of the module kicks in.
retries = 3
}If 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.
It is recommended to use the terraform_remote_state data source to fetch the last known metadata object from the remote state backend.
module "metadata" {
source = "github.com/silthus/terraform-backstage-metadata-module?ref=v1.0.0" # x-release-please-version
name = var.entity_name
# This loops back the last metadata in the state
# as a fallback if the Backstage API is not reachable.
# By design the terraform_remote_state data source will return null if no state is found.
# 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.
fallback = data.terraform_remote_state.metadata.outputs.metadata.entity
}
data "terraform_remote_state" "metadata" {
backend = "gcs" // TODO: replace this with the actual backend and config you are using
config = {
bucket = "some-bucket"
prefix = "some-prefix"
}
}As 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.
module "metadata" {
source = "github.com/silthus/terraform-backstage-metadata-module//modules/fallback?ref=v1.0.0" # x-release-please-version
name = var.entity_name
}module "metadata" {
source = "github.com/silthus/terraform-backstage-metadata-module?ref=v1.0.0" # x-release-please-version
name = var.entity_name
# This loops back the last metadata in the state
# as a fallback if the Backstage API is not reachable.
# By design the terraform_remote_state data source will return null if no state is found.
# 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.
fallback = data.terraform_remote_state.metadata.outputs.metadata.entity
}
data "terraform_remote_state" "metadata" {
backend = "gcs" // TODO: replace this with the actual backend and config you are using
config = {
bucket = "some-bucket"
prefix = "some-prefix"
}
}
provider "backstage" {
base_url = "https://backstage.io/" # TODO: provide your own Backstage URL
headers = {
"Authorization" = "Bearer <some-token>" # TODO: provide your own Backstage API token. See https://backstage.io/docs/auth/service-to-service-auth/#static-tokens for more information.
}
# This configures the fallback capabilities of the provider itself to retry the request 3 times before failing.
# After failing the above `fallback` kicks in and provides the last known metadata from the terraform state.
retries = 3
}The following input variables are required:
Description: The name of the entity you need metadata for.
Type: string
The following input variables are optional (have default values):
Description: The name of the environment you are deploying to.
Type: string
Default: "unknown"
Description: 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.
Type:
object({
api_version = string
kind = string
metadata = object({
annotations = optional(map(string))
description = optional(string)
etag = optional(string)
labels = optional(map(string))
links = optional(list(object({
icon = optional(string)
title = string
type = optional(string)
url = string
})))
name = string
namespace = string
tags = optional(list(string))
title = optional(string)
})
relations = optional(list(object({
target = object({
kind = string
name = string
namespace = string
})
target_ref = string
type = string
})))
spec = optional(string)
})Default: null
Description: The kind of Backstage entity you are fetch metadata for.
Type: string
Default: "Component"
Description: The namespace of the entity you need metadata for.
Type: string
Default: "default"
The following outputs are exported:
Description: The full component object as defined by the Backstage API.
Description: A common set of labels to attach to cloud resources.
Description: A flattened filtered set of metadata from the component object.
The following requirements are needed by this module:
The following providers are used by this module:
- backstage (3.1.0)
No modules.
The following resources are used by this module:
- backstage_entities.entity (data source)