Skip to content

implementation_guide: add a cross-resource tagging strategy page to naming conventions #279

@dangrondahl

Description

@dangrondahl

Problem

The naming_conventions group under implementation_guide/phase_2/plan_organizational_structure covers naming for flows/trails, attestation types, and environments, but there is no guidance on tagging as a classification strategy across resource types. Tags now exist on resources (including via the Terraform provider), and tag-based filtering is on the roadmap, but there is no recommended taxonomy for what to tag or how. Without it, different teams invent divergent schemes, which undermines filtering, policy scoping, and reporting once the resource count grows.

Expected Behavior

A strategy-level page (e.g. naming_conventions/tagging_strategy.md, or a section in overview.md) that defines a recommended, cross-resource tag vocabulary, complementing the per-resource naming pages. Naming identifies a resource; tags classify it for filtering, policy, and reporting.

Current Behavior

No tagging guidance exists in the implementation guide. The current naming_conventions/ group contains only overview.md, flows_and_trails.md, and attestation_types.md.

Use Case

Organizations operating across multiple geographies, business units, and teams need a consistent way to classify environments and attestation types (and later repos) so they can filter, scope policy, and report consistently as the number of resources scales.

Suggested Approach

  • Recommended tag keys with example values: geo/region, business-unit, team, tier (criticality/lifecycle), cost-center, cloud.
  • key:value conventions: lowercase keys, consistent value formats, avoid redundancy with the resource name. Model the guidance on Kubernetes labels/annotations conventions.
  • When to tag vs encode in the name: stable identity goes in the name; filterable, mutable metadata goes in a tag.
  • Note on managing tags as code via the Terraform provider.
  • Keep this page strategy-only and cross-link the environments naming page (Add environment naming conventions to implementation guide #135) and the tags reference (Add documentation for tags #169) to avoid duplication.
  • Add the page to docs.json navigation under the naming conventions group.

Related

Metadata

Metadata

Assignees

No one assigned

    Labels

    contentWriting, adding, or updating doc pagesenhancementNew feature or request

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions