Infrastructure Labels and Tags

1. You are here:
2. Handbook
3. Infrastructure Standards
4. Infrastructure Labels and Tags

Maintained by:

On this page

• Quick Reference
  • Global Labels/Tags
  • Realm Labels/Tags
  • Design Decisions and Change Log
• Environment Realm (gl_realm)
  • Shared Services
  • Department Realms
• Environment Type (gl_env_type)
  • Expected values
• Environment Name (gl_env_name)
  • Realm Usage Guidelines
• Automated Infrastructure Environment ID (gl_env_id)
  • Realm Usage Guidelines
• Geographic Continent (Region) of Environment (gl_env_continent)
  • Expected Values
• Owner Email Handle (gl_owner_email_handle)
• Owner Timezone (gl_owner_timezone)
  • Example Values
• GitLab Entity (gl_entity)
  • Expected Values
  • Realm Usage Guidelines
  • BambooHR Mapping
• GitLab Department (gl_dept)
  • Expected Values
• GitLab Product Stage (gl_product_stage)
  • Expected Values
• GitLab Product Category (gl_product_category)
  • Expected Values
• GitLab Department Group (gl_dept_group)
  • Expected Values
  • Deprecated Group Names
• Resource Type (gl_resource_type)
  • Expected Values
• Resource Name (gl_resource_group)
• Resource Name (gl_resource_name)
• Resource Host (gl_resource_host)
• Data Classification (gl_data_classification)
  • Expected Values
• Accounting and Financial Reporting
• Impact to Business Owners and Infrastructure Team
• Impact to Users and Managers
• Footnotes

Quick Reference

We use the gl_ prefix for all labels and tags. All keys use underscores (snake_case). All values should use hyphens (alpha-dash for slug'd values), however underscores are allowed.

In labels and tags for specific realms should be prefixed with the realm prefix. You can learn more about the realm variables in the respective realm's documentation.

Global Labels/Tags

Realm Labels/Tags

Please see the realm label and tag handbook pages for labels and tags specific to the realm.

• infra-shared-services
• it
• saas
• sandbox
• security

Design Decisions and Change Log

Here is a summary of changes made during the design of these standards based on team feedback that should be preserved for historical reference.

• Based on feedback in the issue, we have revamped the list of departments and groups based on functional teams rather than people manager reporting structure.
• The GitLab Division has been deprecated since it is prefixed on the gl_department.
• We have renamed gl_department to gl_dept to allow it to be shorter as a prefix for gl_dept_group.
• We have renamed gl_team to gl_dept_group based on feedback about the ambiguity of team and the remapping that we did in the spreadsheet that most departments have groups/teams but none have sub-groups other than engineering which has the sub-department/stage (Ex. Dev - Plan) organizational hierarchy. The engineering sub-department is not used in our label/tag structure.
• We have added gl_product_stage. Earlier iterations used gl_stage however the term stage is ambiguous so we identify it as the product stage.
• We have abbreviated all values to allow for easier prefixing using industry recognizable abbreviations. We use full words where an abbreviation is not universally recognizable. For OKTA integration, we remap values from BambooHR to their short names that we use for infrastructure.
• We removed gl_owner_username since GitLab.com usernames can have characters not allowed cloud provider labels and tags.
• We renamed gl_owner_email to gl_owner_email_handle to provide clarity of the value that is expected.
• We have removed gl_owner_slack_id since we won't perform any action from a cloud resource and will use owner lookup in separate tools using gl_owner_email_handle.
• We added the allocate value to gl_entity for legacy parity with how we allocate global costs based on percentage of revenue for each entity.
• We added the gl_resource_type and gl_resource_name fields since GCP doesn't support easy reporting based on type of resource or name unless you use labels.
• We added gl_resource_host to help show aggregate costs of a parent resource for all resources (ex. disk, network, etc.)
• We added gl_resource_group to allow for infrastructure-as-code tools (ex. Ansible) to deploy resources to multiple instances of the same type and configuration.
• On 2021-07-22, we performed an audit and updated the gl_dept, gl_dept_group, and gl_product_stage tables with the latest values. A new table was added below gl_dept_group expected values with the list of renamed or removed department groups.
• The sales-cs realm was consolidated into the business-tech realm since the Demo Systems infrastructure is now managed by Business Technology.
• The infra-shared-services realm was added for top-level infrastructure management.
• We now allow short-term and long-term working groups to use the gl_dept_group label with the prefix of wg- and an easily understood name of their choice (no codenames).

Environment Realm (gl_realm)

This label/tag is required.

gl_realm: `eng-dev`

This is for the top-level identification of what type of resources reside here, and which infrastructure team has authoritative ownership of it.

Any custom labels or tags that are created should use the respective realm slug as the prefix for the label/tag key (Ex. gl_sandbox_keyname).

Shared Services

• The gitter realm was removed on 2021-07-22.

Department Realms

• The sales-cs realm was migrated to the business-tech realm on 2021-07-22.

Environment Type (gl_env_type)

This label/tag is required.

gl_env_type: 'experiment'

Expected values

New values can be added to this list and used without any other changes needed. This list was created for this label/tag and is not inherited from another source.

Environment Name (gl_env_name)

This label/tag is required.

gl_env_name: 'learning-kubernetes'

The environment name is a short name or description of the purpose of the environment or service. This is a sub-descriptor of gl_realm and gl_env_type. The standards and use of this label/tag vary based on the gl_realm that it is used in, and each team can use it however it makes sense to them.

Realm Usage Guidelines

Automated Infrastructure Environment ID (gl_env_id)

This label/tag is optional.

gl_env_id: 'a1b2c3d4'

The environment ID allows various inputs, but in general is a short UUID, long UUID, SHA or other alphanumeric identifier that is systematically generated. The use of this label/tag will vary based on the gl_realm that it is used in, and each team can use it however it makes sense to them.

Realm Usage Guidelines

Geographic Continent (Region) of Environment (gl_env_continent)

This label/tag is optional.

gl_env_continent: 'america'

We use continent to avoid confusion with region since that is an ambiguous word.

This is the continent where this environment's resources are consumed by users. This may not necessarily be where it is deployed or where the environment owner resides. This allows us to understand impact to users if infrastructure maintenance is needed or security incidents occur. This can also be used as meta data for global resources with autoscaling resources in specific continents/regions, however the gl_entity label/tag is needed for explicit cost allocation.

The abbreviation used by the business can change over time (Ex. APJ, APAC, Asia Pacific), and the cloud providers use different nomenclature, so we are standardizing using full names based on the prefix of programmatic timezones (Ex. America/Los_Angeles is america). For non-regional services, you can use the global value.

Expected Values

Some possible prefix values have been omitted from this list for brevity and unlikely applicability (Ex. brazil, hongkong, indian, etc.). They can be added at environment owner's discretion.

Owner Email Handle (gl_owner_email_handle)

This label/tag is required.

gl_owner_email_handle: 'jmartin'

The email handle before @gitlab.com. We only use the handle since labels and tags do not support @ and . symbols. Values can be individual users or Google Workspace group aliases. For people handles, this should be {firstinitial}{lastname} and not any username aliases (Ex. jeff) since user aliases cannot be looked up programatically with our current architecture.

This is used for association with OKTA account, infrastructure notifications, and identifying the user's account with additional meta data. Users may receive emails with security advisory notifications.

Owner Timezone (gl_owner_timezone)

This label/tag is optional.

gl_owner_timezone: 'america-los_angeles'

This is the timezone of the environment owner that is used for determining working hours. We assume that working hours are between 6am (06:00) and 6pm (18:00). This is usually only used when there is only one or two people who own a system. For systems with global coverage, you should not use this label/tag.

This is the based on the programmatic timezone ID that usually follows the format Continent/Locality. You can see the full list of examples in the GCP documentation.

Due to limitations with the allowed characters in labels, the / is not allowed and we use lowercase labels. Therefore, we replace the slash / with a hyphen - and use lowercase letters exclusively. This is the same reason that we chose not use UTC values since cannot use + symbols.

Example Values

• america-los_angeles
• america-denver
• america-chicago
• america-new_york
• asia-singapore
• asia-tokyo
• australia-sydney
• africa-johannesburg
• europe-amsterdam
• europe-berlin
• europe-london
• europe-paris
• europe-vienna

These are examples and not an exhaustive list. As part of our inclusive values, please know that all timezones are valued equally and this was created based on some of the localities on the team map with the largest number of team members per capita.

GitLab Entity (gl_entity)

This label/tag is optional.

gl_entity: 'allocate'

This allows us to allocate costs to the respective business entity in financial reports. If not set, we will assume allocate.

Expected Values

See the GitLab Mailing addresses for details about each entity.

Realm Usage Guidelines

BambooHR Mapping

During testing of OKTA integration, this field is populating additional values we did not expect (ex. safeguard-italy, federal). This is documented in www-data/data/entity_mapper.yml and we will map the respective entities to our cost center entities listed.

GitLab Department (gl_dept)

This label/tag is required.

gl_dept: eng-dev

We have abbreviated all values to allow for easier prefixing using industry recognizable abbreviations. We use full words where an abbreviation is not universally recognizable. For OKTA integration, we use YAML data file to remap values from BambooHR to their short names that we use for infrastructure. You can see a quick reference in the table below.

Expected Values

GitLab Product Stage (gl_product_stage)

This label/tag is optional.

gl_product_stage: eng-dev-manage

Since the eng-dev department has many groups, we use the Product sections, stages, groups and categories handbook page to define a parent group using the product stage. During the design discussion, we iterated with using product categories and sub-departments, and the stage made the most sense.

For GitLab SaaS and infrastructure cost allocation or attribution, the Engineering Infrastructure department team members can use the gl_product_stage label to attach to resources that should be attributed to a specific stage. You can optionally use the gl_dept_group if you need more granular attribution.

Expected Values

GitLab Product Category (gl_product_category)

This label/tag is required.

gl_product_category: gitaly

Expected Values

Product categories should match one of the categories defined in categories.yml in the handbook: https://gitlab.com/gitlab-com/www-gitlab-com/-/blob/master/data/categories.yml

By providing this value, costs can be directly mapped back to a specific set of features, as well as a set of owners within both Product and Engineering.

GitLab Department Group (gl_dept_group)

This label/tag is required.

gl_dept_group: eng-support-americas

For Engineering Development (eng-dev) department groups, the product stage slug (gl_product_stage) is used as the prefix for the gl_dept_group value. For all other departments, the gl_dept slug is used as the prefix.

All departments or stages have a default shared-infra label/tag/AWS account/GCP project that can be used when a separately distinguished/functional group is not needed. For groups with heavy infrastructure usage, we use the group name as a suffix and provide an isolated AWS account/GCP project for group team members to use.

For the groups that provide a shared service to other departments at GitLab, we also have a shared-services group value that can be used for shared cost attributions. We use shared-infra for our own team's resources and shared-services for everyone else's resources that we manage.

You can get an editable version of this table in the spreadsheet that we used to design this schema, however recent changes may not be reflected and this handbook page is the SSOT.

Expected Values

If a group listed below does not have a group documentation link, it is safe to assume that a AWS account or GCP project has not been created for that group yet. Please follow the instructions for provisioning the group (TODO).

The full list of groups was last audited and updated on 2021-07-22.

Footnotes:

1. If a group was renamed or removed, it appears in the Deprecated Group Names table below. Any renamed groups have a footnote indicator.
2. This was added after the initial list was created.
3. This is a special group that may not directly align with a team. For eng-dev, this usually appears under Other Functionality.

Deprecated Group Names

The following group names have been renamed or removed and may still be in use with legacy infrastructure and are preserved here for reference purposes.

Resource Type (gl_resource_type)

This label/tag is optional.

gl_resource_type: compute-instance

GCP doesn't support easy reporting based on type of resource and name unless you use labels. This is optional, but recommended for resources that cost a significant amount of money or are part of a production service. This is not recommended for sandbox and ephemeral use cases.

Expected Values

Resource Name (gl_resource_group)

This label/tag is optional.

gl_resource_group: prod-app

This is optional for using with Terraform, Ansible, and other related infrastructure-as-code or related tools.

The value of this key should match the name of the group in your infrastructure-as-code group definitions (ex. Ansible role/group naming)

Resource Name (gl_resource_name)

This label/tag is optional.

gl_resource_name: prod-app-web1

The value of this key should match the name of the resource in the cloud console.

GCP doesn't support easy reporting based on type of resource and name unless you use labels. This is optional, but recommended for resources that cost a significant amount of money or are part of a production service. This is not recommended for sandbox and ephemeral use cases.

Resource Host (gl_resource_host)

This label/tag is optional.

gl_resource_host: prod-app-web1

This is used for associating child resources (disks, snapshots, buckets, network IPs, etc) with the parent resource (ex. compute-instance) to show the aggregate costs of the resource.

The value of this key should match the name of the parent resource in the cloud console.

GCP doesn't support easy reporting based on type of resource and name unless you use labels. This is optional, but recommended for resources that cost a significant amount of money or are part of a production service. This is not recommended for sandbox and ephemeral use cases.

Data Classification (gl_data_classification)

This label/tag is required for resources that store data (databases, storage buckets, etc..).

gl_data_classification: red

Values should match the documented Data Classification Levels with all lowercase value (for cloud provider tag and label consistency).

Expected Values

Accounting and Financial Reporting

In alignment with our transparency value, financial information cannot be shared publicly. Team members can see the details of how labels and tags impact financial reporting in this issue. The cost allocation methodology for production environments that in this document.

Impact to Business Owners and Infrastructure Team

The largest impact of the label and tag schema is known owner and department identification for every resource provisioned in each cloud provider, and cross-reference to the Terraform configuration that can be referenced during infra/security review.

There are significant cost savings possible with the ability to set time limits on resources that solve the abandoned infrastructure problem. We can also save up to 65% of spending by implementing automation to power off infrastructure during non-working hours (overnight and weekends).

Impact to Users and Managers

With the label and tags, we can easily report on infrastructure and help you understand what's running and help you self manage the costs of the resources that you provision.

Since most labels and tags will be automatically added with Terraform and automation, or at the account/project level for sandbox accounts, there is not a significant burden on users to remember to add labels/tags to resources.

With future automation, we can also create frictionless experience for users with notification of system vulnerabilities, security incidents, and friendly reminders in Slack about upcoming expiration of infrastructure since your email, GitLab username, and Slack ID are automatically associated.

Footnotes