Fleet Management (OneAgent & ActiveGate)

# User Story: Fleet Management (OneAgent & ActiveGate)

## Story Overview

**As a** Platform Engineer, SRE, or Migration Specialist  
**I want to** manage OneAgent and ActiveGate fleet updates in Dynatrace Managed environments through natural language interactions with the MCP server  
**So that** I can maintain version consistency, coordinate safe phased rollouts, identify migration blockers, and ensure fleet health—especially during Managed-to-SaaS transitions where version parity reduces risk

---

## 🔍 Scope & Architecture

### What This MCP Server Does
This is a **Dynatrace Managed MCP Server**. It:
- ✅ Connects to one or more **Dynatrace Managed** environments
- ✅ Reads OneAgent and ActiveGate versions from **Managed clusters** only
- ✅ Configures auto-update settings for **Managed environments** via Settings 2.0
- ✅ Returns fleet status and version data to the NLM (Natural Language Model)
- ✅ Identifies migration readiness issues (version outliers, compatibility problems)

### What This MCP Server Does NOT Do
- ❌ Connect to Dynatrace SaaS environments directly
- ❌ Communicate with SaaS MCP Server directly
- ❌ Read or configure fleet settings in SaaS environments
- ❌ Perform cross-environment version comparisons directly (NLM orchestrates this)

### Cross-Environment Operations (Managed ↔ SaaS)
**Version Compatibility Checks (NLM-orchestrated):**
When user needs to compare Managed vs. SaaS fleet versions:
1. **User** makes request to **NLM** (e.g., "Compare OneAgent versions between Managed and SaaS")
2. **NLM** calls **this Managed MCP** to get Managed fleet status
3. **NLM** calls **separate SaaS MCP** to get SaaS fleet status (if available)
4. **NLM** analyzes both responses, identifies version gaps, and suggests remediation
5. **NLM** presents unified compatibility report to user

**Migration Readiness (NLM-orchestrated):**
1. **User** asks "Is my fleet ready for migration?"
2. **NLM** calls **this Managed MCP** to validate:
   - Minimum versions for migration assistant tool
   - Outlier detection (agents >6 months old)
   - Version distribution analysis
3. **NLM** optionally calls **SaaS MCP** to check SaaS cluster's `earliestAgentVersion` property
4. **NLM** correlates data and reports migration readiness

This user story describes the **complete end-to-end workflow** to show business value, but this MCP Server only implements fleet management in **Dynatrace Managed environments**.

---

## ⚙️ OneAgent vs ActiveGate Auto-Update Capabilities

### OneAgent Auto-Update (Full Settings 2.0 Support)
✅ **Supported via Settings 2.0 API** (`builtin:deployment.oneagent.updates`):
- **Version pinning** - Enforce specific version (e.g., "1.285.0")
- **Update windows** - Schedule updates during maintenance windows
- **Scope hierarchy** - Configure at environment, host group, process group, or host level
- **Update modes**:
  - Automatic updates during maintenance window
  - Automatic updates at earliest convenience  
  - Manual updates only
- **Update strategies** - Phased rollouts with health checks

### ActiveGate Auto-Update (Limited Capabilities)
⚠️ **Simple On/Off Configuration Only**:
- ✅ Enable auto-update (update at earliest convenience)
- ✅ Disable auto-update (manual only)
- ❌ **NO version pinning** - Always updates to latest
- ❌ **NO scheduled update windows** - Updates immediately when enabled
- ❌ **NO phased rollout support** - All-or-nothing approach
- ❌ **NO scope hierarchy** - Per-ActiveGate configuration only

**Workaround for ActiveGate Update Control:**
1. Create maintenance window to suppress alerts during update
2. Enable auto-update temporarily
3. Monitor update completion
4. Disable auto-update if you want manual control going forward

---

## User Value Proposition

### 1. Centralized Fleet Visibility
- **Single pane of glass** - view all OneAgent and ActiveGate versions across entire Managed environment
- **Version distribution analysis** - see how many agents are on each version, identify outliers
- **Outlier detection** - instantly identify agents older than 6 months that could block migrations
- **Multi-environment comparison** - NLM can query multiple MCP servers (Managed + SaaS) to compare fleet versions
- **Natural language queries** - "Show me all hosts with OneAgent older than 6 months"

### 2. Automated Safe Updates
- **Phased rollout coordination** - update hostgroup1 today, hostgroup2 next Monday if hostgroup1 is healthy
- **Maintenance window alignment** - automatically align update schedules with existing maintenance windows
- **Scope-specific configuration** - set different auto-update policies for environment, host groups, individual hosts (OneAgent only)
- **Version pinning** - enforce specific OneAgent versions across fleet (ActiveGate only supports on/off)
- **Natural language control** - "Update all OneAgents in Production to version 1.285 next Tuesday during maintenance window"

### 3. Multi-Environment Consistency (via NLM Orchestration)
- **Version parity validation** - NLM orchestrates comparison between Managed MCP and SaaS MCP to validate compatible agent versions
- **Migration readiness check** - this MCP verifies Managed fleet meets minimum version requirements; NLM coordinates with SaaS MCP for target environment validation
- **Risk reduction** - identical versions eliminate bugs caused by version differences during migration
- **Compliance tracking** - maintain audit trail of fleet version changes in Managed environments

### 4. Auto-Align with Maintenance Windows
- **Intelligent scheduling** - suggest update schedules based on existing maintenance windows
- **Zero-alert updates** - coordinate agent updates to happen during maintenance windows (no false alerts)
- **Automatic window creation** - offer to create maintenance windows when scheduling fleet updates
- **Conflict avoidance** - prevent scheduling updates when no maintenance window exists

### 5. Migration Assistant Compatibility
- **Version requirement validation** - check if fleet meets Dynatrace migration assistant minimum versions
- **Blockers identification** - highlight agents that would be rejected by target environment (too old)
- **Remediation guidance** - provide actionable steps to bring outliers up to required versions
- **Pre-migration health check** - comprehensive fleet readiness assessment before migration waves

---

## Acceptance Criteria

### Core Capabilities

#### 1. Query Fleet Status (OneAgent & ActiveGate)
**Given** a user wants to understand their fleet's current state  
**When** they ask about fleet versions or health  
**Then** the MCP server should:
- Query Dynatrace APIs to retrieve:
  - All OneAgent versions across hosts (via Entities API or Deployment API)
  - All ActiveGate versions (via ActiveGates API)
  - Auto-update configuration at each scope level (environment, host group, host)
- Aggregate and present:
  - Version distribution (how many on each version)
  - Outliers (agents older than specified threshold, default 6 months)
  - Latest available version from Deployment API
  - Auto-update status (enabled/disabled, update windows)
- Support filtering by:
  - Host group
  - Management zone
  - Tags
  - Specific hosts

**Example interactions:**
```
User: "Show me the OneAgent version distribution across my Production environment."

MCP: Querying OneAgent fleet status in Production...
     
     Fleet Overview (Production Management Zone):
     ✓ Total hosts: 127
     ✓ Latest available version: 1.285.0
     
     Version Distribution:
     1. v1.285.0 - 45 hosts (35.4%) ✅ Latest
     2. v1.283.2 - 62 hosts (48.8%) ⚠️ 1 version behind
     3. v1.280.1 - 15 hosts (11.8%) ⚠️ 4 versions behind
     4. v1.275.0 - 3 hosts (2.4%) 🔴 10 versions behind (>6 months old)
     5. v1.268.3 - 2 hosts (1.6%) 🔴 17 versions behind (>6 months old)
     
     ⚠️ Outliers Detected: 5 hosts with agents older than 6 months
        - prod-legacy-01 (HOST-ABC001): v1.275.0
        - prod-legacy-02 (HOST-ABC002): v1.275.0
        - prod-db-archive-01 (HOST-ABC003): v1.275.0
        - prod-analytics-03 (HOST-ABC004): v1.268.3
        - prod-backup-01 (HOST-ABC005): v1.268.3
     
     Auto-Update Configuration:
     ✓ Environment level: Automatic updates during maintenance window
     ✓ Host Group "Production-Critical": Manual updates only (override)
     ✓ Host Group "Production-Standard": Inherit environment settings
     
     Recommendation: Update outliers to v1.285.0 before migration.
```

#### 2. Identify Migration Blockers
**Given** a Managed-to-SaaS migration is planned  
**When** a user asks to validate fleet readiness  
**Then** the MCP server should:
- **⚠️ Limitation:** Cannot directly query cluster's `earliestAgentVersion` and `earliestActiveGateVersion` (cluster-level properties, requires cluster admin API)
- **Workaround:** Use known minimum version thresholds (e.g., versions released within last 6 months)
- Compare current fleet versions against migration assistant tool requirements (documented constants)
- Compare against target SaaS environment's minimum versions (if NLM provides SaaS data via SaaS MCP)
- Identify agents that would be rejected by target environment
- Check Dynatrace migration assistant version requirements
- Highlight outliers (agents older than 6 months)
- Provide remediation steps

**Example interaction:**
```
User: "Check if our fleet is ready for migration to SaaS. 
       We're migrating Production hosts tagged migration:wave1"

MCP: Running fleet readiness assessment for migration...
     
     Scope: Production hosts with tag migration:wave1
     Total hosts in scope: 23
     
     OneAgent Analysis:
     ✓ Managed cluster earliest supported version: 1.260.0
     ✓ Target SaaS earliest supported version: 1.265.0 (from NLM context)
     ✓ Migration assistant minimum version: 1.275.0
     
     Fleet Status:
     ✓ 20 hosts have OneAgent >= 1.275.0 (87%) ✅ Ready
     ⚠️ 3 hosts have OneAgent < 1.275.0 (13%) 🔴 BLOCKERS
     
     Migration Blockers:
     1. prod-payment-03 (HOST-ABC101)
        Current: v1.268.3
        Required: v1.275.0
        Gap: 7 versions behind
        Action: Update to v1.285.0 (latest)
     
     2. prod-payment-07 (HOST-ABC105)
        Current: v1.270.1
        Required: v1.275.0
        Gap: 5 versions behind
        Action: Update to v1.285.0 (latest)
     
     3. prod-payment-12 (HOST-ABC110)
        Current: v1.272.0
        Required: v1.275.0
        Gap: 3 versions behind
        Action: Update to v1.285.0 (latest)
     
     ActiveGate Analysis:
     ✓ All 4 ActiveGates are on v1.283.0 ✅ Ready
     
     Risk Assessment:
     🔴 HIGH RISK - 3 hosts will be rejected by migration assistant
     
     Recommendation:
     1. Update 3 blocker hosts to v1.285.0 immediately
     2. Re-run readiness check after updates
     3. Proceed with migration wave 1
     
     Would you like me to create update jobs for these 3 hosts?
```

#### 3. Configure OneAgent Auto-Update Settings
**Given** a user wants to control OneAgent update behavior  
**When** they specify auto-update configuration  
**Then** the MCP server should:
- Use Settings 2.0 API with OneAgent auto-update schema
- Support all configuration scopes:
  - Environment level (applies to all hosts)
  - Host Group level (overrides environment)
  - Individual Host level (overrides host group)
- Support all update modes:
  - **Automatic updates at earliest convenience** (immediate)
  - **Automatic updates during maintenance window** (scheduled)
  - **Manual updates only** (disabled)
  - **Pin to specific version**
- Create or update maintenance windows if needed
- Validate configuration before applying
- Show affected hosts count

**Example interaction:**
```
User: "Configure OneAgent auto-update for Production. 
       Update hostgroup-standard automatically during Tuesday maintenance window. 
       Keep hostgroup-critical on manual updates only."

MCP: Configuring OneAgent auto-update settings...
     
     Configuration Plan:
     
     1. Host Group: hostgroup-standard (87 hosts)
        ✓ Update Mode: Automatic updates during maintenance window
        ✓ Maintenance Window: Tuesdays 18:00-20:00 UTC (mw-recurring-prod-deploy)
        ✓ Target Version: Latest (currently 1.285.0)
     
     2. Host Group: hostgroup-critical (12 hosts)
        ✓ Update Mode: Manual updates only
        ✓ Reason: Critical systems require explicit approval
     
     Applying configuration via Settings 2.0 API...
     
     ✓ Schema: builtin:deployment.oneagent.updates
     ✓ Scope: Host Group hostgroup-standard (settings-obj-001)
     ✓ Scope: Host Group hostgroup-critical (settings-obj-002)
     
     Configuration applied successfully.
     
     Summary:
     - 87 hosts will auto-update during Tuesday maintenance window
     - 12 hosts require manual updates (no auto-update)
     - Next auto-update window: Tuesday 2026-02-06 18:00 UTC
     
     Affected hosts will update to v1.285.0 during next window.
```

#### 4. Enforce Immediate Update ("Update Now")
**Given** a user needs to force an immediate update  
**When** they request "update now" for specific agents  
**Then** the MCP server should:
- Change auto-update settings to "Automatic updates at earliest convenience"
- Apply to specified scope (individual hosts, host groups, or environment)
- Warn if no maintenance window exists (risk of alerts)
- Offer to create emergency maintenance window
- Confirm scope and affected host count
- Require explicit confirmation for production

**Example interaction:**
```
User: "Update OneAgent to latest version NOW on all hosts in hostgroup-dev."

MCP: Preparing immediate OneAgent update...
     
     Scope: Host Group hostgroup-dev
     Affected hosts: 15
     Current versions: v1.280.1 (12 hosts), v1.283.2 (3 hosts)
     Target version: v1.285.0 (latest)
     
     Update Mode: Automatic updates at earliest convenience
     
     ⚠️ WARNING: No maintenance window exists for this host group.
     Expected impact during update:
     - Brief agent disconnection (~30 seconds per host)
     - Process group restarts
     - Temporary monitoring gaps
     - Possible AVAILABILITY problems
     
     Options:
     1. Create emergency maintenance window (recommended)
     2. Proceed without maintenance window
     
     Which option?

User: "Create maintenance window for next 2 hours."

MCP: Creating emergency maintenance window...
     ✓ Window: mw-emergency-oneagent-dev
     ✓ Schedule: 2026-02-04 15:22-17:22 UTC (2 hours)
     ✓ Scope: Host Group hostgroup-dev (15 hosts)
     
     Applying auto-update configuration...
     ✓ Update Mode: Automatic at earliest convenience
     ✓ Target Version: 1.285.0
     ✓ Scope: hostgroup-dev (15 hosts)
     
     OneAgent updates will begin immediately.
     
     Expected timeline:
     - Updates start: Within 5 minutes
     - Completion: 15-30 minutes (15 hosts)
     - Maintenance window ends: 17:22 UTC
     
     Monitor progress: I'll track agent versions and report when complete.
```

#### 5. Pin OneAgent to Specific Version
**Given** a user wants to control exact OneAgent versions  
**When** they specify a version to pin  
**Then** the MCP server should:
- Validate version exists in available versions (via Deployment API)
- Configure auto-update to pin to specified version
- Apply to specified scope
- Prevent automatic upgrades beyond pinned version
- Show affected hosts and their current versions

**Example interaction:**
```
User: "Pin OneAgent to version 1.283.2 for all hosts in Production. 
       We need to stay on this version for compliance testing."

MCP: Configuring OneAgent version pinning...
     
     Target version: 1.283.2
     Validating version availability...
     ✓ Version 1.283.2 is available for deployment
     
     Scope: Management Zone "Production"
     Affected hosts: 127
     
     Current version distribution:
     - v1.285.0: 45 hosts → will downgrade to 1.283.2 ❌ NOT SUPPORTED
     - v1.283.2: 62 hosts → no change ✅
     - v1.280.1: 15 hosts → will upgrade to 1.283.2 ✅
     - v1.275.0: 3 hosts → will upgrade to 1.283.2 ✅
     - v1.268.3: 2 hosts → will upgrade to 1.283.2 ✅
     
     ⚠️ WARNING: 45 hosts are on newer version (v1.285.0).
     OneAgent does NOT support downgrade.
     
     These 45 hosts will remain on v1.285.0 and skip auto-updates.
     Only hosts on older versions will update to v1.283.2.
     
     Options:
     1. Proceed (pin 1.283.2 for all, 45 hosts stay on 1.285.0)
     2. Pin only hosts on <= 1.283.2 (exclude the 45 hosts)
     3. Cancel
     
     Which option?

User: "Option 2 - pin only hosts on 1.283.2 or older."

MCP: Applying version pin configuration...
     
     ✓ Scope: Production hosts with OneAgent <= 1.283.2 (82 hosts)
     ✓ Pinned version: 1.283.2
     ✓ Update mode: Automatic updates to 1.283.2
     
     Configuration applied via Settings 2.0 API.
     
     Summary:
     - 62 hosts on v1.283.2: No change (already on target)
     - 20 hosts on older versions: Will update to v1.283.2
     - 45 hosts on v1.285.0: Excluded from pin (continue normal updates)
     
     Version 1.283.2 pinned for compliance testing.
```

#### 6. Configure ActiveGate Auto-Update (Simple On/Off Only)
**Given** a user wants to control ActiveGate updates  
**When** they configure ActiveGate auto-update  
**Then** the MCP server should:
- Use ActiveGate auto-update API to enable/disable (on/off only)
- **⚠️ Limitation:** ActiveGate does NOT support version pinning, scheduled windows, or phased rollouts
- ActiveGate always updates to latest version when auto-update is enabled
- Support enabling/disabling per ActiveGate or all ActiveGates
- Recommend creating maintenance window to suppress alerts during updates
- Show affected ActiveGates and current versions

**Example interaction:**
```
User: "Enable auto-update for all ActiveGates."

MCP: ⚠️  Note: ActiveGate auto-update limitations:
     - Always updates to LATEST version (no version pinning)
     - Updates immediately when enabled (no scheduled windows)
     - Consider creating maintenance window to suppress alerts
     
     Querying ActiveGates in environment...
     Found 4 ActiveGates:
     1. ag-prod-us-01 (AG-123ABC) - v1.283.0 - Auto-update: OFF
     2. ag-prod-us-02 (AG-124DEF) - v1.283.0 - Auto-update: OFF
     3. ag-prod-eu-01 (AG-125GHI) - v1.280.5 - Auto-update: OFF
     4. ag-prod-eu-02 (AG-126JKL) - v1.280.5 - Auto-update: OFF
     
     Latest available ActiveGate version: 1.285.0
     
     Enabling auto-update for all 4 ActiveGates...
     ✓ ag-prod-us-01: Auto-update enabled (will update immediately)
     ✓ ag-prod-us-02: Auto-update enabled (will update immediately)
     ✓ ag-prod-eu-01: Auto-update enabled (will update immediately)
     ✓ ag-prod-eu-02: Auto-update enabled (will update immediately)
     
     Configuration applied.
     
     Expected updates (immediate):
     - ag-prod-eu-01: v1.280.5 → v1.285.0 (within 10 minutes)
     - ag-prod-eu-02: v1.280.5 → v1.285.0 (within 10 minutes)
     - ag-prod-us-01: v1.283.0 → v1.285.0 (within 10 minutes)
     - ag-prod-us-02: v1.283.0 → v1.285.0 (within 10 minutes)
     
     💡 Tip: Disable auto-update after completion if you want manual control.
     
     💡 Suggestion: Create maintenance window?
     ActiveGate updates may cause brief monitoring gaps (~2-3 minutes per AG).
     
     Create 30-minute maintenance window for ActiveGates?

User: "Yes."

MCP: ✓ Maintenance window created: mw-emergency-activegate-update
     ✓ Duration: 30 minutes (15:22-15:52 UTC)
     ✓ Scope: All 4 ActiveGates
     
     ActiveGate updates will proceed with alert suppression.
```

#### 7. List Available Versions (Deployment API)
**Given** a user wants to know what versions are available  
**When** they query available versions  
**Then** the MCP server should:
- Use Deployment API v1 endpoints:
  - `/deployment/installer/agent/versions` for OneAgent
  - `/deployment/installer/gateway/versions` for ActiveGate
- Show available versions with metadata (release date, EOL status)
- Highlight recommended versions
- Support filtering by OS, architecture, etc.

**Example interaction:**
```
User: "What OneAgent versions are available for deployment?"

MCP: Querying available OneAgent versions from Deployment API...
     
     Available OneAgent Versions (Linux x64):
     
     Latest (Recommended):
     ✅ v1.285.0 - Released: 2026-02-01 - Status: Latest stable
     
     Recent Versions:
     1. v1.283.2 - Released: 2026-01-25 - Status: Stable
     2. v1.283.0 - Released: 2026-01-22 - Status: Stable
     3. v1.280.1 - Released: 2026-01-15 - Status: Stable
     4. v1.278.0 - Released: 2026-01-08 - Status: Stable
     5. v1.275.0 - Released: 2025-12-20 - Status: Stable (aging)
     
     Older Versions (>6 months):
     6. v1.268.3 - Released: 2025-08-15 - Status: ⚠️ Deprecated (>6mo)
     7. v1.260.0 - Released: 2025-07-01 - Status: 🔴 End of life
     
     ⚠️ Versions older than v1.275.0 may not be supported by migration assistant.
     
     Recommendation: Update all agents to v1.285.0 (latest stable).
```

#### 8. Phased Rollout Coordination
**Given** a user wants to update fleet in controlled phases  
**When** they describe a phased rollout plan  
**Then** the MCP server should:
- Parse phased rollout intent (phase 1 today, phase 2 after validation, etc.)
- Configure auto-update settings for each phase/scope
- Align phases with maintenance windows
- Support conditional progression (phase 2 only if phase 1 healthy)
- Provide rollout timeline and affected hosts per phase

**Example interaction:**
```
User: "Update all OneAgents to v1.285.0 in phases. 
       Phase 1: hostgroup-canary today during maintenance window.
       Phase 2: hostgroup-standard next Tuesday if canary looks good."

MCP: Planning phased OneAgent rollout to v1.285.0...
     
     Phase 1: Canary Group
     ✓ Scope: Host Group hostgroup-canary (5 hosts)
     ✓ Current versions: v1.283.2
     ✓ Target version: v1.285.0
     ✓ Schedule: Today during maintenance window
     ✓ Maintenance window: mw-emergency-canary (creating...)
     ✓ Window: Today 16:00-18:00 UTC (2 hours)
     
     Phase 2: Standard Group (conditional)
     ✓ Scope: Host Group hostgroup-standard (87 hosts)
     ✓ Current versions: v1.280.1 (62), v1.283.2 (25)
     ✓ Target version: v1.285.0
     ✓ Schedule: Tuesday 2026-02-06 18:00-20:00 UTC
     ✓ Maintenance window: mw-recurring-prod-deploy (existing)
     ✓ Condition: Proceed only if Phase 1 hosts are healthy (no open problems)
     
     Rollout Timeline:
     - Today 16:00 UTC: Phase 1 starts (5 canary hosts)
     - Today ~16:30 UTC: Phase 1 completes
     - Today 18:00-Mon: Monitor canary health (48 hours)
     - Tuesday 18:00 UTC: Phase 2 starts (if canary healthy)
     - Tuesday ~20:00 UTC: Phase 2 completes
     
     Total fleet: 92 hosts updating to v1.285.0
     
     Applying Phase 1 configuration now...
     ✓ Phase 1: Configured for immediate update during window
     ✓ Phase 2: Scheduled (conditional on Phase 1 health)
     
     Phase 1 will begin at 16:00 UTC today.
     
     💡 Reminder: I'll check Phase 1 health before Phase 2. You can also:
     - Ask me: "Are canary hosts healthy?" anytime
     - Manually approve Phase 2: "Proceed with Phase 2"
     - Cancel Phase 2: "Cancel Phase 2 rollout"
```

#### 9. Compare Fleet Versions Across Environments
**Given** NLM is connected to multiple MCP servers (Managed + SaaS)  
**When** user asks to compare fleet versions  
**Then** each MCP server should:
- Report fleet version status for its environment
- NLM aggregates and compares results
- Highlight version differences that could cause migration issues
- Recommend version alignment actions

**Example interaction (NLM orchestrates, each MCP responds):**
```
User (to NLM): "Compare OneAgent versions between Managed and SaaS. 
                Are they compatible for migration?"

NLM: Querying fleet status from both environments...

[NLM calls Managed MCP]
Managed MCP Response:
     Environment: Managed Cluster (managed-prod-us)
     OneAgent Fleet:
     - Total hosts: 127
     - v1.285.0: 45 hosts (35%)
     - v1.283.2: 62 hosts (49%)
     - v1.280.1: 15 hosts (12%)
     - v1.275.0 or older: 5 hosts (4%) ⚠️ Outliers

[NLM calls SaaS MCP]
SaaS MCP Response:
     Environment: SaaS Tenant (abc123.live.dynatrace.com)
     OneAgent Fleet:
     - Total hosts: 89
     - v1.285.0: 89 hosts (100%)
     - Earliest supported version: 1.265.0

NLM Analysis:
     ✅ Majority compatible: 122/127 Managed hosts meet SaaS minimum (v1.265.0)
     ⚠️ 5 Managed hosts too old (< v1.265.0)
     
     Version Parity:
     - SaaS is fully on v1.285.0 (latest)
     - Managed has mixed versions (v1.268 to v1.285)
     
     Risk Assessment:
     🟡 MEDIUM RISK - Version disparity exists
     
     Recommendation:
     1. Update 5 Managed outliers to v1.285.0 (blocks migration)
     2. Consider updating all Managed to v1.285.0 for version parity
     3. This eliminates version-related bugs during migration
     
     Would you like Managed MCP to update the outliers?
```

#### 10. Monitor Update Progress
**Given** a fleet update is in progress  
**When** a user asks for update status  
**Then** the MCP server should:
- Query current agent versions across affected hosts
- Compare against expected target version
- Calculate completion percentage
- Report any failures or stuck updates
- Show estimated time to completion

**Example interaction:**
```
User: "What's the status of the canary OneAgent update?"

MCP: Checking OneAgent update progress for hostgroup-canary...
     
     Phase 1: Canary Group Update
     Target version: v1.285.0
     Started: 16:03 UTC (15 minutes ago)
     
     Update Status:
     ✅ 4/5 hosts completed (80%)
     ⏳ 1/5 hosts in progress (20%)
     
     Completed Hosts:
     1. canary-01 (HOST-ABC201) - v1.283.2 → v1.285.0 ✅ Success (4 min)
     2. canary-02 (HOST-ABC202) - v1.283.2 → v1.285.0 ✅ Success (5 min)
     3. canary-03 (HOST-ABC203) - v1.283.2 → v1.285.0 ✅ Success (6 min)
     4. canary-04 (HOST-ABC204) - v1.283.2 → v1.285.0 ✅ Success (7 min)
     
     In Progress:
     5. canary-05 (HOST-ABC205) - v1.283.2 → updating... ⏳ (10 min elapsed)
     
     Estimated completion: 5 minutes
     
     Health Check:
     ✅ No open problems on updated hosts
     ✅ All agents connected and reporting
     ✅ Process groups restarted successfully
     
     Canary update is progressing normally.
     Will perform final health check after all hosts complete.
```

#### 11. Generate Fleet Readiness Report
**Given** a migration is planned  
**When** a user requests a comprehensive fleet assessment  
**Then** the MCP server should:
- Analyze entire fleet (OneAgent + ActiveGate)
- Identify all blockers and risks
- Generate actionable remediation plan
- Provide version compatibility matrix
- Export report for stakeholders

**Example interaction:**
```
User: "Generate a comprehensive fleet readiness report for our Managed-to-SaaS migration."

MCP: Generating Fleet Readiness Report...
     
     ═══════════════════════════════════════════════════════════
     FLEET READINESS REPORT - Managed to SaaS Migration
     Generated: 2026-02-04 15:22 UTC
     Environment: managed-prod-us
     Migration Target: SaaS tenant abc123.live.dynatrace.com
     ═══════════════════════════════════════════════════════════
     
     EXECUTIVE SUMMARY
     ─────────────────────────────────────────────────────────
     Overall Readiness: 🟡 MEDIUM RISK (96% ready)
     
     Critical Blockers: 5 hosts with outdated OneAgent
     Warnings: 15 hosts 1-3 versions behind (low risk)
     Ready: 107 hosts (84%)
     
     
     ONEAGENT FLEET ANALYSIS
     ─────────────────────────────────────────────────────────
     Total Hosts: 127
     
     Version Distribution:
     ✅ v1.285.0 (Latest): 45 hosts (35.4%)
     ✅ v1.283.2: 62 hosts (48.8%)
     ⚠️ v1.280.1: 15 hosts (11.8%)
     🔴 v1.275.0: 3 hosts (2.4%) - BLOCKER
     🔴 v1.268.3: 2 hosts (1.6%) - BLOCKER
     
     Requirements:
     ✓ SaaS earliest supported: v1.265.0
     ✓ Migration assistant minimum: v1.275.0
     ✓ Recommended: v1.285.0 (version parity with SaaS)
     
     Blockers (5 hosts):
     1. prod-legacy-01 (v1.275.0) - 10 versions behind
     2. prod-legacy-02 (v1.275.0) - 10 versions behind
     3. prod-db-archive-01 (v1.275.0) - 10 versions behind
     4. prod-analytics-03 (v1.268.3) - 17 versions behind ⚠️ REJECTED BY SAAS
     5. prod-backup-01 (v1.268.3) - 17 versions behind ⚠️ REJECTED BY SAAS
     
     
     ACTIVEGATE FLEET ANALYSIS
     ─────────────────────────────────────────────────────────
     Total ActiveGates: 4
     
     Version Distribution:
     ✅ v1.283.0: 2 ActiveGates (50%)
     ⚠️ v1.280.5: 2 ActiveGates (50%)
     
     Requirements:
     ✓ SaaS earliest supported: v1.270.0
     ✓ Recommended: v1.285.0 (version parity)
     
     Status: ✅ All ActiveGates meet minimum requirements
     Recommendation: Update all to v1.285.0 for parity
     
     
     REMEDIATION PLAN
     ─────────────────────────────────────────────────────────
     Phase 1: Critical Blockers (Immediate)
     - Update 5 hosts with v1.275.0 or older to v1.285.0
     - Priority: HIGH - blocks migration assistant
     - Estimated time: 30 minutes
     - Action: "Update blocker hosts to v1.285.0 now"
     
     Phase 2: Version Alignment (Before Migration)
     - Update 15 hosts on v1.280.1 to v1.285.0
     - Update 62 hosts on v1.283.2 to v1.285.0
     - Priority: MEDIUM - reduces migration risk
     - Estimated time: 2 hours (phased rollout recommended)
     - Action: "Update all hosts to v1.285.0 during maintenance window"
     
     Phase 3: ActiveGate Alignment (Optional)
     - Update 4 ActiveGates to v1.285.0
     - Priority: LOW - current versions are compatible
     - Estimated time: 15 minutes
     - Action: "Update all ActiveGates to v1.285.0"
     
     
     RISK ASSESSMENT
     ─────────────────────────────────────────────────────────
     🔴 HIGH RISK: 2 hosts will be REJECTED by SaaS (v1.268.3)
     🟡 MEDIUM RISK: 3 hosts will FAIL migration assistant (v1.275.0)
     🟢 LOW RISK: Version parity not achieved (mixed versions)
     
     
     MIGRATION TIMELINE
     ─────────────────────────────────────────────────────────
     Today: Fix critical blockers (5 hosts)
     Tomorrow-Friday: Update remaining fleet (phased)
     Saturday: Re-run readiness check
     Sunday: Proceed with migration (if all green)
     
     
     COMPLIANCE & AUDIT
     ─────────────────────────────────────────────────────────
     Managed Cluster Info:
     - Earliest supported OneAgent: v1.260.0
     - Earliest supported ActiveGate: v1.260.0
     - Current cluster version: 1.283.0
     
     Target SaaS Tenant Info:
     - Earliest supported OneAgent: v1.265.0
     - Earliest supported ActiveGate: v1.270.0
     - Current cluster version: 1.285.0
     
     Version Gap: Managed is 2 versions behind SaaS
     Recommendation: Consider updating Managed cluster post-migration
     
     ═══════════════════════════════════════════════════════════
     END OF REPORT
     ═══════════════════════════════════════════════════════════
     
     Next Steps:
     1. Review and approve remediation plan
     2. Execute Phase 1 immediately (critical blockers)
     3. Schedule Phase 2 for this week
     4. Re-run readiness check before migration
     
     Would you like me to start Phase 1 now?
```

---

## Technical Implementation Requirements

### MCP Tools to Implement

#### Tool 1: `get-fleet-status`
**Purpose:** Query OneAgent and ActiveGate versions across fleet

**Inputs (Zod schema):**
```typescript
{
  environmentId: string,
  fleetType: "oneagent" | "activegate" | "both",
  filters?: {
    managementZone?: string,
    hostGroup?: string,
    tags?: string[],
    entitySelector?: string           // DQL selector
  },
  showOutliers?: boolean,             // Highlight agents older than threshold
  outlierThreshold?: number,          // Months (default: 6)
  includeAutoUpdateConfig?: boolean   // Show auto-update settings
}
```

**Implementation:**
- For OneAgent:
  - Query Entities API v2 for hosts with OneAgent version info
  - Alternative: Use Deployment API v1 to get agent versions
- For ActiveGate:
  - GET `/api/v2/activeGates` with version information
- Aggregate version distribution
- Identify outliers (versions older than threshold)
- Fetch auto-update configuration from Settings 2.0 if requested
- Return formatted summary

#### Tool 2: `check-migration-readiness`
**Purpose:** Validate fleet readiness for Managed-to-SaaS migration

**Inputs:**
```typescript
{
  environmentId: string,
  migrationScope?: {                  // Specific migration wave scope
    managementZone?: string,
    tags?: string[],
    hostGroups?: string[]
  },
  targetSaaSMinVersions?: {           // From NLM if available
    oneAgent?: string,
    activeGate?: string
  },
  migrationAssistantMinVersion?: string,  // Migration tool requirement
  generateReport?: boolean            // Full detailed report vs. summary
}
```

**Implementation:**
- Query fleet status for specified scope
- Get cluster's earliestAgentVersion and earliestActiveGateVersion properties
- Compare against target SaaS versions (if provided)
- Check migration assistant version requirements
- Identify blockers (too old, will be rejected)
- Generate remediation plan
- Return readiness assessment with risk level

#### Tool 3: `configure-oneagent-autoupdate`
**Purpose:** Configure OneAgent auto-update settings via Settings 2.0

**Inputs:**
```typescript
{
  environmentId: string,
  scope: {
    level: "environment" | "hostGroup" | "host",
    targetId?: string                 // Host group ID or host ID (if not environment)
  },
  configuration: {
    updateMode: "automatic_immediate" | "automatic_scheduled" | "manual",
    targetVersion?: string,           // Pin to specific version (optional)
    maintenanceWindow?: {
      windowId?: string,              // Existing maintenance window ID
      create?: {                      // Or create new window
        schedule: string,
        duration: number,
        recurrence?: object
      }
    }
  },
  validateOnly?: boolean              // Dry-run mode
}
```

**Implementation:**
- Construct Settings 2.0 payload for OneAgent auto-update schema
- Map updateMode to Dynatrace enums:
  - `automatic_immediate` → "Automatic updates at earliest convenience"
  - `automatic_scheduled` → "Automatic updates during maintenance window"
  - `manual` → "Manual updates only"
- If targetVersion specified, configure version pinning
- If maintenance window needed, create or link to existing
- POST to `/api/v2/settings/objects` with appropriate scope
- Return configuration summary and affected hosts count

#### Tool 4: `configure-activegate-autoupdate`
**Purpose:** Enable/disable ActiveGate auto-update (simple on/off only)

**Inputs:**
```typescript
{
  environmentId: string,
  activeGateIds?: string[],           // Specific AGs, or empty for all
  enabled: boolean,                   // Enable or disable auto-update
  warnAboutLimitations?: boolean      // Show limitations message (default: true)
}
```

**Implementation:**
- Query ActiveGates API to get all/specified ActiveGates
- For each ActiveGate, update auto-update configuration
  - API: ActiveGate auto-update settings (simple boolean)
  - Set: enabled = true (always updates to latest) or false (manual)
- Warn user about ActiveGate limitations:
  - No version pinning (always latest)
  - No scheduled windows (immediate update)
  - No phased rollout support
- Suggest creating maintenance window for alert suppression
- Return summary of updated ActiveGates

**API Limitations:**
- ❌ Cannot pin to specific version
- ❌ Cannot schedule update windows
- ❌ Cannot configure update strategies

#### Tool 5: `list-available-versions`
**Purpose:** Query available OneAgent/ActiveGate versions from Deployment API

**Inputs:**
```typescript
{
  environmentId: string,
  componentType: "oneagent" | "activegate",
  osType?: string,                    // "linux", "windows", "aix", etc.
  architecture?: string,              // "x64", "arm64", etc.
  includeOldVersions?: boolean,       // Show versions >6 months old
  maxResults?: number                 // Limit results (default: 20)
}
```

**Implementation:**
- Use Deployment API v1:
  - GET `/deployment/installer/agent/versions/{osType}/{architecture}` for OneAgent
  - GET `/deployment/installer/gateway/versions/{osType}` for ActiveGate
- Parse version list with metadata (release date, EOL status)
- Filter out old versions if includeOldVersions=false
- Highlight latest and recommended versions
- Return formatted version list

#### Tool 6: `create-phased-rollout`
**Purpose:** Configure multi-phase fleet update with health checks

**Inputs:**
```typescript
{
  environmentId: string,
  targetVersion: string,              // Target OneAgent version
  phases: [{
    name: string,                     // "Canary", "Phase 1", etc.
    scope: {
      hostGroups?: string[],
      tags?: string[],
      hosts?: string[]
    },
    schedule: string | "immediate",   // ISO timestamp or "immediate"
    maintenanceWindowId?: string,     // Link to existing MW
    condition?: {                     // Conditional progression
      requireHealthyHosts: boolean,   // Check for open problems
      waitMinutes: number             // Wait period between phases
    }
  }]
}
```

**Implementation:**
- For each phase:
  - Configure OneAgent auto-update settings with appropriate timing
  - Link to or create maintenance window
  - Set up conditional checks (if specified)
- Store phased rollout metadata for tracking
- Return rollout timeline and affected hosts per phase
- Support querying rollout status later

#### Tool 7: `monitor-update-progress`
**Purpose:** Track ongoing fleet update progress

**Inputs:**
```typescript
{
  environmentId: string,
  scope?: {                           // Track specific scope
    hostGroups?: string[],
    hosts?: string[]
  },
  expectedVersion: string,            // Target version
  checkHealth?: boolean               // Also check for problems on updated hosts
}
```

**Implementation:**
- Query current OneAgent versions for specified scope
- Compare against expectedVersion
- Calculate completion percentage
- Identify hosts still updating (version mismatch)
- If checkHealth=true, query Problems API for updated hosts
- Return progress summary with estimated completion time

#### Tool 8: `get-cluster-version-requirements`
**Purpose:** Get minimum supported versions from cluster

**Inputs:**
```typescript
{
  environmentId: string
}
```

**Implementation:**
- Query cluster configuration API to get:
  - earliestAgentVersion
  - earliestActiveGateVersion
  - Current cluster version
- Return version requirements
- Use this data in migration readiness checks

---

## MCP Resources

### Resource: `fleet-management-guide`
**Purpose:** Documentation on fleet management features

**Content:**
- OneAgent auto-update configuration guide
- ActiveGate auto-update guide
- Phased rollout best practices
- Migration readiness checklists
- Version compatibility matrix
- Troubleshooting update failures
- Integration with maintenance windows

### Resource: `oneagent-autoupdate-schema-reference`
**Purpose:** Technical reference for OneAgent auto-update Settings 2.0 schema

**Content:**
- Schema ID: `builtin:deployment.oneagent.updates`
- All configuration options and enums
- Scope hierarchy (environment → host group → host)
- Version pinning syntax
- Maintenance window integration
- Examples and common patterns

---

## Example User Interactions

### Scenario 1: Identify Outdated Agents
```
User: "Show me all hosts with OneAgent older than 6 months."

MCP: Querying fleet for outdated OneAgent instances...
     
     Outlier Detection: OneAgent older than 6 months
     
     Found 5 hosts with outdated agents:
     
     🔴 CRITICAL (>12 months):
     1. prod-analytics-03 (HOST-ABC004)
        Version: v1.268.3
        Age: 17 versions behind (>12 months)
        Last update: 2025-08-15
        Status: ⚠️ Will be REJECTED by SaaS (below minimum v1.265.0)
     
     2. prod-backup-01 (HOST-ABC005)
        Version: v1.268.3
        Age: 17 versions behind (>12 months)
        Last update: 2025-08-15
        Status: ⚠️ Will be REJECTED by SaaS
     
     🟡 HIGH RISK (6-12 months):
     3. prod-legacy-01 (HOST-ABC001)
        Version: v1.275.0
        Age: 10 versions behind (~6 months)
        Last update: 2025-12-20
        Status: ⚠️ Fails migration assistant requirement (min v1.275.0)
     
     4. prod-legacy-02 (HOST-ABC002)
        Version: v1.275.0
        Age: 10 versions behind (~6 months)
        Last update: 2025-12-20
     
     5. prod-db-archive-01 (HOST-ABC003)
        Version: v1.275.0
        Age: 10 versions behind (~6 months)
        Last update: 2025-12-20
     
     Latest available version: v1.285.0
     
     Recommendation: Update all 5 hosts to v1.285.0 immediately.
     
     Would you like me to create an update job for these hosts?
```

### Scenario 2: Phased Rollout with Conditional Progression
```
User: "Update all OneAgents in Production to v1.285.0. 
       Start with canary group today, then standard group next Tuesday 
       only if canary is healthy."

MCP: Planning phased rollout to OneAgent v1.285.0...
     
     Analyzing fleet in Production management zone...
     ✓ Total hosts: 92
     ✓ Current versions: v1.280.1 (62 hosts), v1.283.2 (30 hosts)
     ✓ Target version: v1.285.0
     
     Phase 1: Canary (Immediate)
     ─────────────────────────────────────────────────────
     Scope: Host Group "hostgroup-canary"
     Hosts: 5 (prod-canary-01 through prod-canary-05)
     Current: v1.283.2
     Schedule: Today 16:00-18:00 UTC
     Maintenance Window: Creating mw-canary-oneagent-update
     
     Phase 2: Standard (Conditional)
     ─────────────────────────────────────────────────────
     Scope: Host Group "hostgroup-standard"
     Hosts: 87
     Current: v1.280.1 (62), v1.283.2 (25)
     Schedule: Tuesday 2026-02-06 18:00-20:00 UTC
     Maintenance Window: mw-recurring-prod-deploy (existing)
     Condition: Canary hosts must have:
       - No open problems
       - Successful version update to v1.285.0
       - 48-hour monitoring period passed
     
     Rollout Timeline:
     ────────────────────────────────────────────────────
     Today 16:00 UTC    Phase 1 begins (5 canary hosts)
     Today ~16:30 UTC   Phase 1 completes
     Today-Monday       Monitor canary (48-hour soak period)
     Monday 16:00 UTC   Health check gate (automatic)
     Tuesday 18:00 UTC  Phase 2 begins (if gate passes)
     Tuesday ~20:00 UTC Phase 2 completes
     
     Total: 92 hosts → v1.285.0
     
     Creating phased rollout configuration...
     ✓ Phase 1: Configured (auto-update at earliest convenience during MW)
     ✓ Phase 2: Configured (conditional, awaits Phase 1 health check)
     ✓ Maintenance windows: Linked
     ✓ Health check gate: Registered
     
     Phased rollout configured successfully.
     
     Phase 1 will start at 16:00 UTC today.
     I'll monitor canary health and notify you before Phase 2.
     
     Commands you can use:
     - "What's the canary update status?"
     - "Are canary hosts healthy?"
     - "Proceed with Phase 2" (manual override)
     - "Cancel Phase 2"
```

### Scenario 3: Migration Readiness Check
```
User: "Check if our fleet is ready for migration. 
       We're migrating hosts tagged migration:wave1 this Saturday."

MCP: Running migration readiness assessment...
     
     Scope: Hosts tagged "migration:wave1"
     Found: 23 hosts
     
     ═══════════════════════════════════════════════════════
     MIGRATION READINESS CHECK - Wave 1
     ═══════════════════════════════════════════════════════
     
     OneAgent Analysis:
     ─────────────────────────────────────────────────────
     Total hosts: 23
     
     ✅ READY: 20 hosts (87%)
        - v1.285.0: 12 hosts
        - v1.283.2: 8 hosts
        - All meet minimum requirements
     
     🔴 BLOCKERS: 3 hosts (13%)
        1. prod-payment-03 (v1.268.3)
           Issue: Below SaaS minimum (v1.265.0)
           Action: Update to v1.285.0 immediately
        
        2. prod-payment-07 (v1.270.1)
           Issue: Below migration assistant minimum (v1.275.0)
           Action: Update to v1.285.0 immediately
        
        3. prod-payment-12 (v1.272.0)
           Issue: Below migration assistant minimum (v1.275.0)
           Action: Update to v1.285.0 immediately
     
     Version Requirements:
     ─────────────────────────────────────────────────────
     ✓ SaaS earliest supported: v1.265.0
     ✓ Migration assistant minimum: v1.275.0
     ✓ Recommended: v1.285.0 (version parity)
     
     ActiveGate Analysis:
     ─────────────────────────────────────────────────────
     ✅ All ActiveGates compatible (v1.283.0)
     
     Overall Readiness:
     ─────────────────────────────────────────────────────
     Status: 🔴 NOT READY
     Risk Level: HIGH
     Blockers: 3 hosts require immediate updates
     
     Remediation Plan:
     ─────────────────────────────────────────────────────
     IMMEDIATE (Today-Thursday):
     - Update 3 blocker hosts to v1.285.0
     - Estimated time: 15 minutes
     - Create emergency maintenance window (recommended)
     
     OPTIONAL (Before Saturday):
     - Update remaining 20 hosts to v1.285.0 for version parity
     - Reduces migration risk
     - Estimated time: 1 hour
     
     Timeline to Migration:
     ─────────────────────────────────────────────────────
     Today:    Fix 3 critical blockers
     Thursday: Optional - update remaining 20 hosts
     Friday:   Re-run readiness check (verification)
     Saturday: Proceed with migration ✅
     
     Would you like me to update the 3 blocker hosts now?

User: "Yes, update the blockers now."

MCP: Creating emergency update for 3 blocker hosts...
     
     ✓ Maintenance window: mw-emergency-wave1-blockers
     ✓ Schedule: Immediate (next 2 hours)
     ✓ Scope: 3 hosts (prod-payment-03, -07, -12)
     
     Applying OneAgent update configuration...
     ✓ Update mode: Automatic at earliest convenience
     ✓ Target version: v1.285.0
     
     Updates will begin within 5 minutes.
     Expected completion: 20 minutes
     
     I'll monitor progress and notify you when complete.
     You can also ask: "What's the blocker update status?"
```

---

## Non-Functional Requirements

### Performance
- Fleet status queries should complete within 5 seconds for 500 hosts
- Version distribution aggregation should be near-instant (use caching)
- Multi-environment queries (via NLM) should use parallel API calls
- Update configuration changes should apply within 2 seconds

### Security
- All API tokens remain server-side
- Validate user has appropriate Dynatrace permissions (`deployment.write`, `settings.write`)
- Audit all fleet configuration changes
- Prevent unauthorized version downgrades (not technically possible but validate)

### Error Handling
- If Deployment API unavailable, fall back to Entities API for version info
- If Settings 2.0 schema version differs, adjust payload to compatible version
- If maintenance window doesn't exist when needed, offer to create it
- If target version doesn't exist, suggest available versions
- Gracefully handle hosts that fail to update (report, don't fail entire operation)

### Observability
- Log all fleet configuration changes (who, what, when, why)
- Track metrics: updates triggered, success rate, average update time
- Monitor API latency and error rates
- Alert if update failure rate exceeds threshold

### Usability
- Natural language version specifications ("latest", "6 months old", "v1.285")
- Preview affected hosts before applying configuration
- Show estimated update duration and impact
- Provide clear remediation steps for blockers
- Support dry-run mode for all configuration changes

---

## Out of Scope (Future Stories)

1. **Dynatrace Managed Cluster Updates** - Server-side component updates
2. **Automatic Rollback on Failure** - Not supported by Dynatrace (no downgrade)
3. **Custom Update Scripts** - Pre/post-update hooks or custom automation
4. **Update Scheduling Optimization** - ML-based optimal update timing
5. **Fleet Cost Analysis** - Track costs of running outdated vs. latest agents
6. **Compliance Reporting** - Generate compliance reports for auditors
7. **Extension Updates** - Manage Extensions 2.0 alongside OneAgent/ActiveGate
8. **Network Zone Awareness** - Optimize updates based on network topology

---

## Dependencies

### Dynatrace APIs Required

**Environment API v2:**
- Entities API (`/api/v2/entities`) - Query hosts with OneAgent versions
- ActiveGates API (`/api/v2/activeGates`) - Query ActiveGate versions and configure updates
- Settings 2.0 API (`/api/v2/settings/...`)
  - Schema: `builtin:deployment.oneagent.updates` - OneAgent auto-update configuration
  - Schema: `builtin:deployment.activegate.updates` (if exists) - ActiveGate auto-update
- Problems API (`/api/v2/problems`) - Health checks after updates

**Environment API v1:**
- Deployment API (`/api/v1/deployment/...`)
  - `/deployment/installer/agent/versions/{osType}/{arch}` - Available OneAgent versions
  - `/deployment/installer/gateway/versions/{osType}` - Available ActiveGate versions
  - `/deployment/installer/agent/connectioninfo` - Agent connection details
  - Cluster version/requirements endpoints

### Existing MCP Server Capabilities
- Multi-environment connection management (already implemented)
- Authentication via API tokens (already implemented)
- NLM integration for natural language parsing
- Maintenance window management (from previous user story) - critical for coordinating updates
- Event ingestion (from earlier story) - for linking updates to governance events

### External Dependencies
- None (all operations via Dynatrace APIs)

---

## Success Metrics

### Fleet Health
- **Target:** 95% of fleet on latest or latest-1 version within 30 days
- **Measure:** Track version distribution over time

### Migration Support
- **Target:** Zero migration failures due to agent version incompatibility
- **Measure:** Track blocker detection and remediation before migrations

### Update Efficiency
- **Target:** Reduce time to update fleet by 70% compared to manual process
- **Measure:** Time from decision to 95% fleet updated

### Outlier Reduction
- **Target:** <5% of fleet older than 6 months at any time
- **Measure:** Track outlier percentage weekly

### User Adoption
- **Target:** 80% of users use MCP for fleet updates within first month
- **Measure:** Track fleet management tool usage

### Coordination Success
- **Target:** 90% of fleet updates occur during maintenance windows
- **Measure:** Track updates aligned with maintenance windows vs. ad-hoc

---

## Testing Strategy

### Unit Tests
- Validate version parsing and comparison logic
- Test outlier detection algorithm (age calculation)
- Verify Settings 2.0 payload construction for OneAgent updates
- Test phased rollout configuration logic
- Validate version compatibility checking

### Integration Tests
- E2E: Query fleet status, verify version distribution
- E2E: Configure OneAgent auto-update, verify Settings 2.0 object created
- E2E: Trigger immediate update, monitor progress, verify completion
- E2E: Create phased rollout, verify conditional progression
- E2E: Run migration readiness check, verify blockers identified
- Cross-environment: Compare fleet versions between Managed and SaaS (via NLM)

### Contract Tests
- Validate against Deployment API v1 schema (version lists)
- Validate against OneAgent auto-update Settings 2.0 schema
- Test with different Managed cluster versions
- Ensure backward compatibility with older API versions

### User Acceptance Tests
- Scenario: Platform engineer queries fleet status
- Scenario: SRE triggers immediate update for critical vulnerability
- Scenario: Migration specialist validates fleet readiness
- Scenario: DevOps engineer configures phased rollout
- Scenario: Team compares Managed and SaaS fleet versions

---

## Risks and Mitigations

| Risk | Impact | Mitigation |
|------|--------|-----------|
| Agent update failures causing monitoring gaps | High - loss of observability | Always coordinate with maintenance windows; monitor update progress; alert on failures |
| Downgrade attempts (not supported) | Medium - user frustration | Validate target version is >= current; warn users; prevent invalid configurations |
| Phased rollout health check false negatives | Medium - blocks legitimate updates | Use multiple health signals (problems, connectivity, metrics); allow manual override |
| Version incompatibility during migration | High - migration failure | Comprehensive readiness checks; require minimum versions; recommend version parity |
| Deployment API unavailable | Low - data temporarily unavailable | Fall back to Entities API for version info; cache version lists |
| Outlier detection false positives | Low - unnecessary updates | Allow configurable threshold; explain age calculation; let users override |
| Update configuration conflicts (multiple scopes) | Medium - unexpected behavior | Clearly show scope hierarchy; preview affected hosts; warn about overrides |

---

## Appendix: OneAgent Auto-Update Schema Reference

### builtin:deployment.oneagent.updates

**Scope Hierarchy:** `environment` → `hostGroup` → `processGroup` → `host`

**Key Properties:**
```typescript
{
  enabled: boolean,                   // Auto-update enabled
  updateMode: enum[
    "AUTOMATIC",                      // At earliest convenience
    "DURING_MAINTENANCE_WINDOW",      // Scheduled during MW
    "MANUAL"                          // No auto-update
  ],
  targetVersion?: string,             // Pin to specific version (optional)
  maintenanceWindow?: string,         // MW ID (if updateMode = DURING_MAINTENANCE_WINDOW)
  excludeVersions?: string[],         // Versions to skip (optional)
  rolloutStrategy?: {                 // Optional phased rollout
    percentage?: number,              // % of hosts to update initially
    waitMinutes?: number              // Wait between batches
  }
}
```

**Version Pinning:**
- If `targetVersion` is set, agents update UP TO that version
- No automatic updates beyond pinned version
- Downgrade NOT supported

**Scope Override:**
- Host-level config overrides host group
- Host group config overrides environment
- Most specific scope wins

Full schema: `GET /api/v2/settings/schemas/builtin:deployment.oneagent.updates`


Risk	Impact	Mitigation
Agent update failures causing monitoring gaps	High - loss of observability	Always coordinate with maintenance windows; monitor update progress; alert on failures
Downgrade attempts (not supported)	Medium - user frustration	Validate target version is >= current; warn users; prevent invalid configurations
Phased rollout health check false negatives	Medium - blocks legitimate updates	Use multiple health signals (problems, connectivity, metrics); allow manual override
Version incompatibility during migration	High - migration failure	Comprehensive readiness checks; require minimum versions; recommend version parity
Deployment API unavailable	Low - data temporarily unavailable	Fall back to Entities API for version info; cache version lists
Outlier detection false positives	Low - unnecessary updates	Allow configurable threshold; explain age calculation; let users override
Update configuration conflicts (multiple scopes)	Medium - unexpected behavior	Clearly show scope hierarchy; preview affected hosts; warn about overrides

Uh oh!

Fleet Management (OneAgent & ActiveGate) #64

Description

User Story: Fleet Management (OneAgent & ActiveGate)

Story Overview

🔍 Scope & Architecture

What This MCP Server Does

What This MCP Server Does NOT Do

Cross-Environment Operations (Managed ↔ SaaS)

⚙️ OneAgent vs ActiveGate Auto-Update Capabilities

OneAgent Auto-Update (Full Settings 2.0 Support)

ActiveGate Auto-Update (Limited Capabilities)

User Value Proposition

1. Centralized Fleet Visibility

2. Automated Safe Updates

3. Multi-Environment Consistency (via NLM Orchestration)

4. Auto-Align with Maintenance Windows

5. Migration Assistant Compatibility

Acceptance Criteria

Core Capabilities

1. Query Fleet Status (OneAgent & ActiveGate)

2. Identify Migration Blockers

3. Configure OneAgent Auto-Update Settings

4. Enforce Immediate Update ("Update Now")

5. Pin OneAgent to Specific Version

6. Configure ActiveGate Auto-Update (Simple On/Off Only)

7. List Available Versions (Deployment API)

8. Phased Rollout Coordination

9. Compare Fleet Versions Across Environments

10. Monitor Update Progress

11. Generate Fleet Readiness Report

Technical Implementation Requirements

MCP Tools to Implement

Tool 1: get-fleet-status

Tool 2: check-migration-readiness

Tool 3: configure-oneagent-autoupdate

Tool 4: configure-activegate-autoupdate

Tool 5: list-available-versions

Tool 6: create-phased-rollout

Tool 7: monitor-update-progress

Tool 8: get-cluster-version-requirements

MCP Resources

Resource: fleet-management-guide

Resource: oneagent-autoupdate-schema-reference

Example User Interactions

Scenario 1: Identify Outdated Agents

Scenario 2: Phased Rollout with Conditional Progression

Scenario 3: Migration Readiness Check

Non-Functional Requirements

Performance

Security

Error Handling

Observability

Usability

Out of Scope (Future Stories)

Dependencies

Dynatrace APIs Required

Existing MCP Server Capabilities

External Dependencies

Success Metrics

Fleet Health

Migration Support

Update Efficiency

Outlier Reduction

User Adoption

Coordination Success

Testing Strategy

Unit Tests

Integration Tests

Contract Tests

User Acceptance Tests

Risks and Mitigations

Appendix: OneAgent Auto-Update Schema Reference

builtin:deployment.oneagent.updates

Metadata

Metadata

Assignees

Labels

Type

Projects

Tool 1: `get-fleet-status`

Tool 2: `check-migration-readiness`

Tool 3: `configure-oneagent-autoupdate`

Tool 4: `configure-activegate-autoupdate`

Tool 5: `list-available-versions`

Tool 6: `create-phased-rollout`

Tool 7: `monitor-update-progress`

Tool 8: `get-cluster-version-requirements`

Resource: `fleet-management-guide`

Resource: `oneagent-autoupdate-schema-reference`