Document helmfile and infra-mgmt onboarding process for component owners

Overview

Teams adopting the Component Ownership Model need to understand how to onboard their projects into infra-mgmt and gitlab-helmfiles to deploy their infrastructure. However, the current process has implicit dependencies and lacks clear documentation, requiring teams to seek SRE guidance. This issue tracks improvements needed to make the onboarding process self-service.

Current Challenges

1. Implicit Dependencies Not Documented

• There is an implicit dependency that a new cluster must first be given roles via infra-mgmt before it can be accessed by gitlab-helmfiles
• This dependency is not clearly documented anywhere
• Teams discover this requirement through trial and error or by asking SREs

2. Unclear Onboarding Sequence

• The exact sequence of steps for onboarding a project into infra-mgmt and gitlab-helmfiles is unclear
• Multiple repositories and configuration files are involved, but the order and relationships are not well explained
• Teams don't know which steps to take first or what the dependencies are between steps

3. Lack of Step-by-Step Guidance

• No clear runbook or guide exists for the complete onboarding process
• Teams must piece together information from multiple sources
• This creates friction and requires SRE involvement to clarify the process

Goals

Create clear, self-service documentation that enables teams to:

1. Understand the dependencies between infra-mgmt and gitlab-helmfiles
2. Follow a step-by-step process to onboard their project
3. Know what configuration changes are needed in each repository
4. Minimize SRE involvement in the onboarding process

Proposed Solutions

1. Document the Dependency Chain

   • Clearly explain that infra-mgmt must be configured before gitlab-helmfiles can access the cluster
   • Document why this dependency exists
   • Provide a visual diagram if helpful

2. Create Step-by-Step Onboarding Guide

   • Document the exact sequence of steps needed
   • Include which repository each step applies to
   • Provide examples of configuration changes needed
   • Include validation steps to confirm each step was successful

3. Document Configuration Requirements

   • What changes are needed in infra-mgmt?
   • What changes are needed in gitlab-helmfiles?
   • What other repositories or systems need to be updated?
   • Provide templates or examples for each

4. Create Troubleshooting Guide

   • Document common issues teams encounter during onboarding
   • Provide solutions for each common issue
   • Include how to validate that onboarding was successful

5. Update Component Ownership Model Handbook

   • Link to the new onboarding documentation from the handbook
   • Ensure the handbook reflects the current process

Related Issues

• Component Ownership Model feedback: #27175 (closed)
• Infrastructure Support for Usage Billing: gl-infra#1637 (closed)
• Component Ownership Model handbook: https://handbook.gitlab.com/handbook/engineering/infrastructure/production/component-ownership-model/

Success Criteria

• Clear documentation exists explaining the infra-mgmt and gitlab-helmfiles dependency
• Step-by-step onboarding guide is created and tested
• Guide includes examples of required configuration changes
• Troubleshooting guide covers common onboarding issues
• Component Ownership Model handbook is updated with links to new documentation
• Non-SRE teams can successfully onboard their projects with minimal SRE involvement
• Documentation is discoverable and easy to find