Skip to content
This repository was archived by the owner on Oct 10, 2025. It is now read-only.

Commit c96fd03

Browse files
committed
docs: replace 'provider context' with 'provider profile' terminology
- Replace all instances of 'provider_context' with 'provider_profile' across redesign documentation - Update directory structure references (provider_contexts/ → provider_profiles/) - Update YAML configuration examples and field names - Update section headers and terminology descriptions - Improve clarity and professionalism of cloud provider configuration concept - Affects: core concepts, environment naming, configuration management, deployment workflow, and project goals Resolves terminology inconsistency identified in Issue #31 redesign documentation.
1 parent 8acc177 commit c96fd03

File tree

5 files changed

+71
-72
lines changed

5 files changed

+71
-72
lines changed

docs/redesign/phase0-goals/project-goals-and-scope.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -111,7 +111,7 @@ visible and potentially accessible to each other within the provider account sco
111111

112112
- **Hetzner Cloud**: Use separate projects with project-specific API tokens for true isolation
113113
- **AWS**: Use separate accounts or strict IAM policies per environment
114-
- **Application Perspective**: The installer treats each provider context (token/credentials)
114+
- **Application Perspective**: The installer treats each provider profile (token/credentials)
115115
as a completely isolated infrastructure boundary, regardless of actual provider-level separation
116116

117117
**Alternative**: Manual provider account management and project separation by users who

docs/redesign/phase1-requirements/core-concepts-and-terminology.md

Lines changed: 27 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,8 @@
33
## Overview
44

55
This document defines the fundamental concepts used throughout the Torrust Tracker
6-
installer project. These definitions establish clear terminology for technical
6+
installer project. These definitions es1. **Create Environment**: Define new environment with goal and provider profile 2. **Configure Application**: Set tracker-specific settings for environment
7+
3. **Deploy Infrastructure**: Provision resources using provider profilelish clear terminology for technical
78
contributors and eliminate ambiguity in design discussions.
89

910
## Core Concepts
@@ -86,31 +87,29 @@ for deploying infrastructure.
8687
implementation details, allowing environments to be portable across different
8788
providers with minimal configuration changes.
8889

89-
### Provider Context
90+
### Provider Profile
9091

91-
**Definition**: The complete set of provider-specific configuration, credentials,
92-
and resource specifications needed to deploy to a specific provider account.
92+
A Provider Profile represents a complete set of provider-specific configuration,
93+
authentication credentials, and resource specifications for deploying
94+
infrastructure to a particular cloud provider or virtualization platform.
9395

94-
**Purpose**: Contains all provider-specific details required for actual
95-
deployment while keeping environment definitions provider-agnostic.
96+
**Key Components:**
9697

97-
**Components**:
98+
- **Authentication**: API tokens, service account keys, access credentials
99+
- **Configuration**: Provider-specific settings (regions, instance types, networking)
100+
- **Resource Specifications**: Default values for compute, storage, networking resources
101+
- **Account Boundaries**: Billing and access control scope
98102

99-
- **Authentication**: API tokens, credentials, access keys
100-
- **Resource Specifications**: VM sizes, storage types, network configurations
101-
- **Regional Settings**: Data center locations, availability zones
102-
- **Account-Specific**: Quotas, limits, billing preferences
103+
**Examples:**
103104

104-
**Examples**:
105-
106-
- `hetzner-personal` - Personal Hetzner account with CPX31 servers in Nuremberg
107-
- `hetzner-company` - Company Hetzner account with dedicated servers in Helsinki
108-
- `libvirt-workstation` - Local development machine with 8GB RAM allocation
105+
- `hetzner-staging`: Hetzner Cloud staging account with specific API tokens
106+
- `hetzner-production`: Hetzner Cloud production account with different credentials
107+
- `aws-development`: AWS development account with development-specific settings
108+
- `libvirt-local`: Local KVM/libvirt configuration for development testing
109109

110-
**Isolation Scope**: Provider contexts represent individual cloud accounts or
111-
infrastructure boundaries. Multiple environments can share a provider context,
112-
but isolation between environments within the same account is limited to
113-
resource naming and network separation.
110+
**Isolation Scope**: Provider profiles represent individual cloud accounts or
111+
infrastructure boundaries. Multiple environments can share a provider profile,
112+
but each profile maintains its own authentication and resource scope.
114113

115114
### Deployment Locality
116115

@@ -153,7 +152,7 @@ providers of both types.
153152
```text
154153
Environment
155154
├── Environment Goal (development|testing|staging|production)
156-
├── Provider Context
155+
├── Provider Profile
157156
│ ├── Provider (libvirt|hetzner|aws)
158157
│ ├── Authentication (API tokens, credentials)
159158
│ ├── Resource Specs (VM size, storage, network)
@@ -168,9 +167,9 @@ Environment
168167

169168
### Development Workflow
170169

171-
1. **Create Environment**: Define new environment with goal and provider context
170+
1. **Create Environment**: Define new environment with goal and provider profile
172171
2. **Configure Application**: Set tracker-specific settings for the environment
173-
3. **Deploy Infrastructure**: Provision resources using provider context
172+
3. **Deploy Infrastructure**: Provision resources using provider profile
174173
4. **Deploy Application**: Install and configure tracker software
175174
5. **Validate Deployment**: Test functionality and performance
176175
6. **Iterate**: Update configuration and redeploy as needed
@@ -192,7 +191,7 @@ Environment
192191

193192
1. Environment-specific configuration
194193
2. Environment goal defaults
195-
3. Provider context defaults
194+
3. Provider profile defaults
196195
4. Global system defaults
197196

198197
This hierarchy allows environments to inherit sensible defaults while
@@ -210,7 +209,7 @@ is implementation-dependent and not specified at this conceptual level.
210209
environment registries or namespacing to prevent conflicts and improve
211210
management.
212211

213-
### Provider Context Isolation
212+
### Provider Profile Isolation
214213

215214
**Current Limitation**: No built-in mechanism for isolating multiple
216215
environments within a single provider account beyond resource naming
@@ -222,16 +221,16 @@ considered for future versions.
222221

223222
### Security Considerations
224223

225-
**Credential Management**: Provider contexts contain sensitive authentication
224+
**Credential Management**: Provider profiles contain sensitive authentication
226225
information that must be handled securely:
227226

228227
- Never commit credentials to version control
229228
- Use environment variables or secure credential stores
230229
- Implement proper access controls and audit logging
231230
- Support credential rotation and expiration
232231

233-
**Environment Isolation**: While environments can share provider contexts,
234-
security-sensitive deployments should use dedicated provider contexts
232+
**Environment Isolation**: While environments can share provider profiles,
233+
security-sensitive deployments should use dedicated provider profiles
235234
to minimize blast radius and improve access control.
236235

237236
## Related Documentation

docs/redesign/phase1-requirements/deployment-stages-and-workflow.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -107,7 +107,7 @@ These stages execute for each individual environment with environment-specific c
107107
- Storage allocation and backup setup
108108
- DNS record creation (if applicable)
109109

110-
**Environment Variables**: Provider context, resource specifications, regional settings
110+
**Environment Variables**: Provider profile, resource specifications, regional settings
111111

112112
**Output**: Running virtual machine with base system ready for application deployment
113113

@@ -285,7 +285,7 @@ version infrastructure deployment validation
285285

286286
**Infrastructure Efficiency**:
287287

288-
- Shared provider contexts for cost optimization
288+
- Shared provider profiles for cost optimization
289289
- Resource scheduling for non-production environments
290290
- Automatic cleanup of temporary/expired environments
291291

docs/redesign/phase3-design/configuration-management-implementation.md

Lines changed: 28 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
## Overview
44

55
This document describes an advanced configuration management system implementation
6-
that can handle multi-environment, multi-provider_context deployments with proper defaults, validation,
6+
that can handle multi-environment, multi-provider_profile deployments with proper defaults, validation,
77
and secret management.
88

99
## Advanced Configuration Management System
@@ -28,11 +28,11 @@ config/
2828
│ ├── development.yaml # Development-specific defaults
2929
│ ├── staging.yaml # Staging-specific defaults
3030
│ └── production.yaml # Production-specific defaults
31-
├── provider_contexts/ # Provider context definitions
32-
│ ├── libvirt.yaml # Local development provider context
33-
│ ├── hetzner-staging.yaml # Hetzner Cloud staging provider context
34-
│ ├── hetzner-production.yaml # Hetzner Cloud production provider context
35-
│ └── aws.yaml # AWS provider context
31+
├── provider_profiles/ # Provider profile definitions
32+
│ ├── libvirt.yaml # Local development provider profile
33+
│ ├── hetzner-staging.yaml # Hetzner Cloud staging provider profile
34+
│ ├── hetzner-production.yaml # Hetzner Cloud production provider profile
35+
│ └── aws.yaml # AWS provider profile
3636
└── environments/ # User environment configurations
3737
├── dev-alice.yaml # Alice's personal dev environment
3838
├── staging-main.yaml # Main staging environment
@@ -46,7 +46,7 @@ config/
4646
```yaml
4747
# Environment identification
4848
environment_type: staging
49-
provider_context: hetzner
49+
provider_profile: hetzner
5050

5151
# General configuration
5252
general:
@@ -71,14 +71,14 @@ secrets:
7171
grafana_admin_password: ${GF_SECURITY_ADMIN_PASSWORD}
7272
```
7373
74-
**Provider Context** (`provider_contexts/hetzner-staging.yaml`):
74+
**Provider Profile** (`provider_profiles/hetzner-staging.yaml`):
7575

7676
```yaml
7777
# Provider identification
7878
provider_name: hetzner
7979
provider_type: cloud
8080
81-
# Concrete provisioning values for this provider context
81+
# Concrete provisioning values for this provider profile
8282
provisioning:
8383
server_type: cx31 # Hetzner-specific server type
8484
location: fsn1 # Hetzner datacenter location
@@ -99,14 +99,14 @@ api:
9999
dns_token_env_var: HDNS_TOKEN
100100
```
101101

102-
**Provider Context** (`provider_contexts/libvirt.yaml`):
102+
**Provider Profile** (`provider_profiles/libvirt.yaml`):
103103

104104
```yaml
105105
# Provider identification
106106
provider_name: libvirt
107107
provider_type: local
108108
109-
# Concrete provisioning values for this provider context
109+
# Concrete provisioning values for this provider profile
110110
provisioning:
111111
memory: 2048 # Memory in MB
112112
vcpus: 2 # Number of virtual CPUs
@@ -146,7 +146,7 @@ applies variable substitution with conditional logic.
146146
#### 4. File Merging with Priority System
147147

148148
A configuration merging system that combines multiple configuration layers (base,
149-
defaults, environment, provider_context) according to priority rules and inheritance
149+
defaults, environment, provider profiles) according to priority rules and inheritance
150150
patterns.
151151

152152
### Pros and Cons Analysis
@@ -158,7 +158,7 @@ patterns.
158158
- Supports complex nested configurations
159159
- Rich template system with conditional logic
160160
- Proper inheritance and composition patterns
161-
- Provider context abstraction enables multi-cloud
161+
- Provider profile abstraction enables multi-cloud
162162

163163
2. **Robust Validation**
164164

@@ -170,13 +170,13 @@ patterns.
170170
3. **Professional Configuration Management**
171171

172172
- Follows enterprise configuration management patterns
173-
- Separates concerns clearly (environment vs provider_context vs defaults)
173+
- Separates concerns clearly (environment vs provider_profile vs defaults)
174174
- Enables configuration reuse and DRY principles
175175
- Supports complex deployment scenarios
176176

177177
4. **Extensible Architecture**
178178

179-
- Easy to add new provider contexts
179+
- Easy to add new provider profiles
180180
- Template system supports custom logic
181181
- Schema-driven validation allows evolution
182182
- Plugin architecture for custom processors
@@ -228,7 +228,7 @@ patterns.
228228
#### 1. File Merging with Priorities
229229

230230
**Challenge**: Need to merge multiple YAML files with complex inheritance rules.
231-
**Reality**: No standard library exists that can handle conditional merging with provider context resolution.
231+
**Reality**: No standard library exists that can handle conditional merging with provider profile resolution.
232232

233233
#### 2. Secret Injection from Environment Variables
234234

@@ -238,17 +238,17 @@ patterns.
238238
#### 3. Multi-layer Validation
239239

240240
**Challenge**: Validate configurations across multiple file layers with
241-
provider_context-specific rules.
241+
provider_profile-specific rules.
242242

243243
#### 3. Multi-layer Validation
244244

245245
**Challenge**: Validate configurations that have common parts and conditional/extensible parts.
246246
**Reality**: JSON Schema with conditional validation becomes unwieldy and hard to maintain.
247247

248-
#### 4. Provider Context Resolution
248+
#### 4. Provider Profile Resolution
249249

250-
**Challenge**: Map abstract configuration to provider_context-specific implementations.
251-
**Reality**: Building abstraction layers that work across different cloud provider contexts
250+
**Challenge**: Map abstract configuration to provider_profile-specific implementations.
251+
**Reality**: Building abstraction layers that work across different cloud provider profiles
252252
is a massive undertaking.
253253

254254
### Conclusion
@@ -266,28 +266,28 @@ require significant development resources to implement properly.
266266

267267
### Phase 1: Core Configuration System
268268

269-
1. **Schema Definition**: Create base environment and provider context schemas
269+
1. **Schema Definition**: Create base environment and provider profile schemas
270270
2. **Configuration Parser**: Implement YAML loading and validation
271-
3. **Provider Context Resolution**: Build reference resolution system
271+
3. **Provider Profile Resolution**: Build reference resolution system
272272
4. **Basic Templates**: Implement simple template resolution
273273

274-
### Phase 2: Provider_context Integration
274+
### Phase 2: Provider Profile Integration
275275

276-
1. **Hetzner Provider Context**: Implement Hetzner-specific mappings and capabilities
277-
2. **Libvirt Provider Context**: Implement local development provider context
276+
1. **Hetzner Provider Profile**: Implement Hetzner-specific mappings and capabilities
277+
2. **Libvirt Provider Profile**: Implement local development provider profile
278278
3. **Validation Integration**: Add composite schema validation
279279
4. **Error Handling**: Comprehensive error reporting and validation messages
280280

281281
### Phase 3: Advanced Features
282282

283283
1. **Template Engine**: Full template resolution with conditional logic
284-
2. **Multiple Provider Contexts**: Support for multiple accounts per provider
284+
2. **Multiple Provider Profiles**: Support for multiple accounts per provider
285285
3. **Configuration Inheritance**: Implement goal-based defaults and inheritance
286286
4. **CLI Integration**: Command-line tools for configuration management
287287

288288
### Phase 4: Production Features
289289

290-
1. **Credential Management**: Secure handling of provider context authentication
290+
1. **Credential Management**: Secure handling of provider profile authentication
291291
2. **Configuration Validation**: Pre-deployment validation and dry-run capabilities
292-
3. **Migration Tools**: Tools for migrating between provider contexts
292+
3. **Migration Tools**: Tools for migrating between provider profiles
293293
4. **Documentation**: Complete configuration reference and examples

docs/redesign/phase3-design/environment-naming-and-configuration.md

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ This naming convention aligns with the core concepts defined in Phase 1:
88

99
- **Goal**: The Environment Goal (development, testing, staging, production)
1010
- **Provider**: The Provider type (libvirt, hetzner, aws)
11-
- **Identifier**: Unique identifier for the specific context or use case
11+
- **Identifier**: Unique identifier for the specific provider profile or use case
1212

1313
**Examples**:
1414

@@ -17,12 +17,12 @@ This naming convention aligns with the core concepts defined in Phase 1:
1717
- `prod-aws-primary` - Primary production environment on AWS
1818
- `e2e-libvirt-ci` - CI/CD end-to-end testing environment
1919

20-
### Provider Context Naming
20+
### Provider Profile Naming
2121

22-
Since multiple Provider Contexts can exist for each Provider type, provider
23-
contexts use a separate naming pattern:
22+
Since multiple Provider Profiles can exist for each Provider type, provider
23+
profiles use a separate naming pattern:
2424

25-
**Pattern**: `{provider}-{context-identifier}`
25+
**Pattern**: `{provider}-{profile-identifier}`
2626

2727
**Examples**:
2828

@@ -32,22 +32,22 @@ contexts use a separate naming pattern:
3232
- `aws-production` - Production AWS account
3333
- `aws-development` - Development AWS account
3434

35-
### Relationship Between Environment and Provider Context
35+
### Relationship Between Environment and Provider Profile
3636

37-
An Environment references a Provider Context by name:
37+
An Environment references a Provider Profile by name:
3838

3939
```yaml
4040
# environments/staging-hetzner-main.yaml
4141
environment:
4242
name: "staging-hetzner-main"
4343
goal: "staging"
44-
provider_context: "hetzner-company" # References providers/hetzner-company.yaml
44+
provider_profile: "hetzner-company" # References providers/hetzner-company.yaml
4545
```
4646
4747
This allows:
4848
49-
- **Multiple Environments per Provider Context**: Several environments can use the same provider account
50-
- **Provider Context Reuse**: Same provider context used across different environment goals
49+
- **Multiple Environments per Provider Profile**: Several environments can use the same provider account
50+
- **Provider Profile Reuse**: Same provider profile used across different environment goals
5151
- **Flexible Deployment**: Easy switching between personal and company accounts
5252
5353
## Configuration Inheritance
@@ -56,7 +56,7 @@ This allows:
5656
5757
1. Environment-specific configuration
5858
2. Environment goal defaults
59-
3. Provider context defaults
59+
3. Provider profile defaults
6060
4. Global system defaults
6161
6262
This hierarchy allows environments to inherit sensible defaults while
@@ -80,7 +80,7 @@ backup:
8080
retention_days: 7
8181
```
8282
83-
#### Provider Context Defaults
83+
#### Provider Profile Defaults
8484
8585
```yaml
8686
# providers/hetzner-company.yaml
@@ -98,7 +98,7 @@ defaults:
9898
#### Configuration Resolution Process
9999
100100
1. **Load Global Defaults**: System-wide default configuration
101-
2. **Apply Provider Context Defaults**: Merge provider-specific defaults
101+
2. **Apply Provider Profile Defaults**: Merge provider-specific defaults
102102
3. **Apply Goal Defaults**: Merge environment goal-specific defaults
103103
4. **Apply Environment Config**: Merge environment-specific configuration
104104
5. **Validate Final Config**: Ensure all required values are present

0 commit comments

Comments
 (0)