cli/bpmetadata/doc.go

// Package bpmetadata generates and validates metadata for Terraform blueprint packages.
//
// bpmetadata is a tool that generates metadata for Terraform packages that are structured based
// on the
// [CFT Module Template]. Executing the cli at the root of a Terraform blueprint package or pointing
// to one with a "path" flag will generate "metadata.yaml". Additionally a UI-display specific
// metadata file can also be generated by providing the cli with a "display" flag.
//
// # Downloading the CFT CLI
//
// Download the CFT CLI as:
//
//	curl https://storage.googleapis.com/cft-cli/<VERSION>/cft-<PLATFORM>-amd64 --output cft
//
// Where:
//   - VERSION can be set to "latest" or to a specific semver e.g. "v0.5.0". It is recommended to
//     use the "latest" version.
//   - PLATFORM can be set as "linux", "windows" or "darwin".
//
// e.g. the latest version of the CLI for linux can be downloaded as:
//
//	curl https://storage.googleapis.com/cft-cli/latest/cft-linux-amd64 --output cft
//
// This will download the CLI binary to the current working directory.
//
// # Generating metadata for a Terraform package
//
// Prerequisite: The Terraform package should conform to the folder structure defined by the
// [CFT Module Template]. A vanilla package can be generated using `cookiecutter` as explained in
// the CFT Module Template's documentation.
//
// Generate metadata using the CLI by pointing the CLI to the root of the Terraform package as:
//
//	cft blueprint metadata -p <SOLUTION_ROOT_PATH> -d
//
// This will generate two files i.e. "metadata.yaml" and "metadata.display.yaml" for each root and
// sub-modules available in the Terraform Blueprint. "metadata.yaml" is mostly auto generated while
// "metadata.display.yaml" is expected to be hand-authored.
//
// All fields (auto generated and manually authored) supported by the metadata schema can be found
// under the top-level struct type [BlueprintMetadata].
//
// Refer to sample versions of [metadata.yaml] and [metadata.display.yaml] for the [canonical]
// Terraform package.
//
// For all available flags for the CLI, use help for cft as:
//
//	cft blueprint metadata -h
//
// # Validating metadata for schema consistencies
//
// Validate metadata for your root and sub modules with the CFT CLI as:
//
//	cft blueprint metadata -v
//
// This will output a success message i.e. "metadata is valid" if all fields in all metadata files
// are consistent with the [BlueprintMetadata] schema. Otherwise, error messages for invalid field
// names, types or values will be shown.
//
// [BlueprintMetadata]: https://pkg.go.dev/github.com/GoogleCloudPlatform/cloud-foundation-toolkit/cli/bpmetadata#BlueprintMetadata
// [metadata.yaml]: https://github.com/g-awmalik/terraform-google-canonical-mp/blob/main/metadata.yaml
// [metadata.display.yaml]: https://github.com/g-awmalik/terraform-google-canonical-mp/blob/main/metadata.display.yaml
// [CFT Module Template]: https://github.com/terraform-google-modules/terraform-google-module-template
// [canonical]: https://github.com/g-awmalik/terraform-google-canonical-mp/tree/main
package bpmetadata