Tag Governance¶

Overview¶

Cloud resources accumulate tags differently across every team, every provider, and every account — "environment", "env", "ENV", and "Env" all mean the same thing but count as four separate tags. Without a unified standard, cost attribution becomes guesswork and compliance is invisible.

CloudPi Tag Governance solves this with two capabilities working together:

• Virtual Tags & Discovery — define org-wide standard tag keys (virtual tags), automatically discover every tag that exists across your cloud estate, and link real cloud tags to your standards
• Compliance Dashboard — see at a glance how well each project follows those standards, with KPI cards, trend indicators, and a per-project breakdown you can export or action directly

Tag Governance today is read-only: you define standards, link tags, and measure compliance. Automatically rewriting or pushing tags back to cloud providers is on our roadmap and not part of the current release.

Sidebar → Tag Governance
              ├── Virtual Tags & Discovery   — define standards + link tags
              └── Compliance Dashboard       — measure and report

Who Is This For?¶

The short forms (WS Admin, WS User, Proj Admin) are used in the rest of this guide.

What each user sees is scoped to their access:

• WS Admin sees tags and compliance across the entire organization
• WS User sees tags and compliance for resources in their assigned project group(s)
• Proj Admin, Proj User, and Viewer see tags and compliance only for their assigned project(s)

Before You Begin¶

• Your workspace has at least one cloud project with billing data already syncing into CloudPi
• Your cloud billing data feeds into CloudPi normally (tag discovery reads from this same data — no separate integration required)
• You know which tags your organization intends to standardize (e.g., "Environment", "Owner", "CostCenter")
• You have WS Admin access if you need to create or edit virtual tags

Feature Overview¶

Tag Governance works in three stages:

A time-range toggle in the top-right corner of both pages (Current Month / Last 2 Months / Last 3 Months) controls the period that tag occurrence counts and total costs are calculated against.

How Auto-Matching Works¶

When you create a virtual tag and give it one or more Auto-Match Patterns, CloudPi immediately evaluates all cloud tags and links any that match.

Patterns use a simple wildcard syntax with *:

You can enter multiple patterns separated by commas. Allowed characters: letters, numbers, -, _, *, :, |. Maximum 100 patterns per virtual tag, 100 characters each.

You can always override an auto-link or manually link tags that don't match any pattern.

How Coverage Is Calculated¶

In plain English: the percentage of your resources that have all your required virtual tags filled in.

A resource counts as tagged for a virtual tag if it has any cloud tag linked to that virtual tag. The coverage score only considers required virtual tags:

Coverage Score = (tagged resources across all required virtual tags)
                 ───────────────────────────────────────────────────── × 100
                 (total resources × count of required virtual tags)

Optional virtual tags are tracked but do not affect the coverage score.

Step-by-Step Guides¶

Guide 1: Define a Virtual Tag (Standard Key)¶

Goal: Create an org-wide standard tag key that cloud tags can be linked to.

Requires: WS Admin

1. Navigate to Tag Governance → Virtual Tags & Discovery.
2. In the Virtual Tags section at the top of the page, click + Add Virtual Tag.
3. Fill in the form:

1. Click Save.

The system immediately evaluates all existing cloud tags against the new patterns and links any matches. The Matched Tags count and Total Cost in the virtual tags table reflect the number of cloud tags linked and their billed cost.

What you see after saving:

• The virtual tag appears in the Virtual Tags table with its Requirement (Required / Optional), Matching Patterns, Matched Tags count, and Total Cost
• Use the row-per-page selector at the bottom of the table to control how many virtual tags are shown at once

Guide 2: Edit or Delete a Virtual Tag¶

Goal: Update a virtual tag's definition, or remove one that is no longer needed.

Requires: WS Admin

To edit:

1. In the Virtual Tags table, click the edit icon on the row you want to change.
2. Update any fields (name, description, Required on all resources checkbox, or Auto-Match Patterns).

3. Click Save Changes.

4. Existing tag links remain intact after editing

5. If you update the patterns, CloudPi immediately re-evaluates all unlinked tags and auto-links any new matches
6. Toggling "Required on all resources" on or off changes the tag from Required to Optional (or vice versa) and updates compliance calculations on the next dashboard load
7. Renaming a virtual tag updates the "Linked Virtual Tags" column everywhere the old name appeared

The dialog shows a Currently matching N tags line that updates as you adjust the patterns, and a Requirement Change warning if you toggle the requirement off.

To delete:

1. Click the delete icon on the virtual tag row.
2. A confirmation dialog appears explaining that deleting the tag will unlink all associated cloud tags.
3. Click Delete to confirm. All linked cloud tags revert to Unmapped status.

Guide 3: Discover and Link Cloud Tags¶

Goal: View all tags that exist across your cloud resources and link them to your virtual tags.

1. Navigate to Tag Governance → Virtual Tags & Discovery.
2. Scroll down to the Cloud Tags section.
3. The table shows every tag key discovered in your cloud billing data:

1. Use the search bar to filter by tag name, the All Statuses dropdown to filter by status, the All Providers dropdown to filter by cloud (AWS / Azure / GCP), or the Top 10 toggle to focus on the highest-occurrence tags.

!!! note "Top 10 is applied after other filters" If you search for "env" and then toggle Top 10, you see the 10 highest-occurrence tags that contain "env" — not the top 10 across all tags.

To link a cloud tag:

1. Click the Link icon in the Actions column for the tag you want to link.
2. The Link Tag to Virtual Tag modal opens, showing the cloud tag's name, occurrence count, total cost, and current status.
3. Choose an action:
4. Link to Virtual Tag — assign this tag to an organization-wide virtual tag; status becomes Mapped and the "Linked Virtual Tags" column shows the virtual tag name
5. Mark as Deprecated — flag this tag for future removal; status becomes Deprecated
6. Mark as Ignored — hide from compliance reports and scoring; status becomes Ignored
7. Click Save.

System tags (e.g., aws:createdBy, microsoft.*) appear in the table like any other tag. You can link or ignore them like any other tag. Marking them Ignored excludes them from compliance calculations.

Empty state: If no virtual tags have been defined yet, the "Linked Virtual Tags" column shows "—" with a link to create your first virtual tag. The Cloud Tags table is still fully functional without virtual tags defined.

Guide 4: Resolve a Tag Conflict¶

Goal: Identify and address resources that have multiple cloud tags linked to the same virtual tag.

A conflict occurs when a single resource has both "env" and "environment" tags — and both are linked to the "Environment" virtual tag. CloudPi counts the resource as tagged, but redundant tags can cause reporting confusion.

1. Navigate to Tag Governance → Virtual Tags & Discovery.
2. If conflicts exist, a yellow warning panel appears above the Cloud Tags table showing the number of affected resources, e.g., "2 resources have tag conflicts — Multiple tags linked to the same virtual tag".
3. Click View Details → on the warning panel to expand the conflict detail.
4. Decide how to resolve each conflict:
5. Re-link one of the conflicting cloud tags to a different virtual tag
6. Mark one of the tags as Deprecated to flag it for future cleanup
7. Leave both linked — the resource still counts as tagged; the conflict is informational only in Phase 1

Guide 5: Review the Compliance Dashboard¶

Goal: See high-level tagging compliance KPIs and identify which projects need attention.

1. Navigate to Tag Governance → Compliance Dashboard.
2. The page loads five KPI cards at the top:

1. A "Last updated" timestamp in the top-right shows when compliance data was last calculated. The time-range toggle (Current Month / Last 2 Months / Last 3 Months) changes the period the metrics are calculated against.

Guide 6: Analyze Compliance by Project¶

Goal: See per-project, per-tag compliance detail and create tasks or tickets for non-compliant projects.

1. On the Compliance Dashboard, scroll to the Tag Compliance by Dimension table.
2. Use the By Project dropdown (top right of the table) to switch the grouping. The default groups by project; you can also filter by All Standards to narrow to specific virtual tags.
3. Each row in the grouped table shows:

1. Coverage indicators on each row:
2. 🟢 Green ≥80% coverage

3. 🔴 Red <80% coverage

4. Click Export (top right of the table) to download the current view as a CSV.

To create a task for a non-compliant project:

1. Click the Create Task icon (clipboard) on the project row.
2. The Create Task drawer opens pre-filled with: project name, project owner, and a description listing which required tags are missing and their coverage percentages.
3. Review and submit.

To raise a support ticket:

1. Click the Raise Ticket icon (ticket) on the project row.
2. The Raise Ticket drawer opens with the same pre-filled compliance context.

Guide 7: Export Compliance Data to CSV¶

Goal: Download a copy of the compliance dimension table for offline analysis or reporting.

1. Navigate to Tag Governance → Compliance Dashboard.
2. Adjust the dimension grouping and any filters you need — the export reflects your current view.
3. Click Export (top right of the Tag Compliance by Dimension table).
4. The server generates the file and downloads it to your browser. All columns visible in the table are included.

Behavior Reference¶

Tag Status Values¶

Permission Quick Reference¶

"(group)" and "(project)" mean the user has permission, but only within their assigned project group or project. They do not see other groups or projects.

Auto-Match Trigger Rules¶

Coverage Score Formula¶

In plain English: the percentage of your resources that have all required virtual tags filled in.

Coverage Score = (sum of tagged resources across all required virtual tags)
                 ───────────────────────────────────────────────────────── × 100
                 (total resources × number of required virtual tags)

• A resource is tagged for a virtual tag if it has any cloud tag with Mapped status linked to it
• Resources with no resource ID (e.g., AWS support charges) are excluded from resource counts but included in cost totals
• Optional virtual tags have no effect on the coverage score

Troubleshooting & FAQs¶

My virtual tag is not auto-linking any cloud tags¶

Cause: No cloud tags currently match any of the patterns, or there are no Unmapped tags in your scope.

Fix:

1. Test your patterns against your known tag keys. Patterns are case-sensitive — env does not match "Env" or "ENV". Use a comma-separated list to cover variations: env, ENV, Env.
2. In the Cloud Tags table, filter by Status: Unmapped to confirm there are tags available to be linked. If all tags are already Mapped to other virtual tags, auto-matching will not override them.
3. If tags are present in your cloud accounts but not appearing in the Cloud Tags table, ask your CloudPi administrator to confirm that billing data is currently syncing for the affected accounts.

A tag is Mapped when I expected it to be Unmapped¶

Cause: A previously created virtual tag has a pattern that matched this tag key.

Fix: Click the link icon on the cloud tag row and either re-link it to the correct virtual tag or mark it as Deprecated/Ignored. Your manual assignment takes permanent precedence and will not be overridden by future auto-match runs.

A tag I know exists is not in the Cloud Tags table¶

Cause: The Cloud Tags table reads from billing data. Tags attached to resources that have not appeared in a billing line item yet will not be discovered.

Fix: Wait for the next billing data refresh. If the tag is critical, ask your CloudPi administrator to confirm that billing data is currently syncing for the affected account.

The Coverage Score seems lower than expected¶

Cause: Coverage only counts resources that have a Mapped cloud tag linked to a required virtual tag. Tags with Unmapped, Deprecated, or Ignored status do not count toward coverage.

Fix:

1. Check the Unlinked Tags KPI card — a high count means many cloud tags are not yet linked.
2. Navigate to Virtual Tags & Discovery and link Unmapped tags to the appropriate virtual tag.
3. Compliance metrics are refreshed on the next calculation cycle (typically within 24 hours of billing data changes).

A Deprecated tag is still showing in the table¶

Cause: Deprecated status means the tag is flagged for cleanup but remains visible in the table. It is not deleted.

Fix: If you want to fully exclude the tag from compliance calculations, change its status to Ignored via the Link Tag to Virtual Tag modal. The tag will remain visible in the Cloud Tags table but will no longer affect compliance scores.

Two admins linked the same tag at the same time¶

Cause: Concurrent edits are handled with last-write-wins — the most recent save overwrites the earlier one.

Fix: Refresh the page to see the current state. If the wrong link is now active, re-link the tag to the correct virtual tag. Both operations are recorded in the audit log so you can trace what happened and when.

Action icons are missing on the compliance table¶

Cause: Action icons only appear for roles with write access (WS Admin, WS User, Proj Admin). Proj User and Viewer roles do not have write access.

Fix: If your role should have write access, contact your workspace administrator to request a role elevation.

Release & Security Notes¶

Organization isolation: All tag governance data — virtual tags, links, and compliance snapshots — is scoped to your organization. Other organizations using CloudPi cannot see your tags, links, or compliance metrics.

Role-based data scoping: Discovery and compliance data are scoped by role (org / project group / project). A Proj User cannot see discovery data outside their assigned projects, even if they know the tag key names.

Tag links are org-wide: When a WS User or Proj Admin links a cloud tag to a virtual tag, that link applies across the entire organization — not just their project scope. Role scoping controls which tags you can see and initiate linking for, but the resulting link is global once saved.

Audit trail (SOC 2): Every write operation on virtual tags and tag links is logged with timestamp, user identity, action type, entity, and before/after values. Audit logs are append-only and retained for a minimum of 1 year. CSV export actions are also logged with filter criteria and row count.

Input validation: Virtual tag names and Auto-Match Patterns are validated server-side before saving. Invalid characters are rejected with a clear error message before any data is stored.

Glossary¶

Related Documentation¶

• Cost Assignment — Assign cloud costs to projects using rules
• VM Scheduler — Automate VM power management with schedules
• Tag Management — Apply, edit, and review tags on individual resources