Import an existing Collector configuration

Configuration migration converts an existing OpenTelemetry Collector configuration into a governed FleetAMP group configuration version. It does not deploy the imported configuration automatically.

Before you begin

• Create or identify the destination ownership group.
• Confirm you can create configuration versions for that group.
• Remove literal passwords and tokens from the source YAML. Use group-secret references instead.
• Keep a copy of the original configuration for comparison.

Workflow

Stage	What FleetAMP does	What the user checks
Import	Accepts pasted or uploaded Collector YAML	Correct source configuration
Parse	Reads the Collector document and component sections	YAML syntax and recognized sections
Normalize	Produces a consistent internal representation	No intended behavior was lost
Standardize	Applies governed recommendations and reports changes	Every added, changed, or retained item
Pattern match	Compares the configuration with reusable patterns	Suggested pattern is appropriate
Validate	Runs FleetAMP policy and optional Collector validation	No blocking errors remain
Preview	Shows final content before persistence	Preview matches the intended result
Save	Creates an immutable group configuration version	Group, version identity, and content
History	Preserves earlier migration results	Actor, time, and result are traceable
Optional approval	Submits the exact saved version	Reviewer and comment are correct

Step by step

1. Open Migration.
2. Select the target group.
3. Paste or upload the existing Collector YAML.
4. Parse and normalize it.
5. Review standardization findings and recognized governed patterns.
6. Run Validate and resolve blocking findings.
7. Compare the final Preview with the source configuration.
8. Save it as a new immutable group configuration version.
9. Confirm the result in Migration History.
10. When ready, submit that exact version to the normal approval workflow.

Validation

FleetAMP validates YAML and its governance rules. When FLEETAMP_OTELCOL_BINARY points to the target Collector executable, it can also validate distribution-specific components and pipeline settings.

A previously valid configuration can be rejected at approval time if policy or the validation binary changed. This prevents stale evidence from authorizing deployment.

Safety properties

• Saving creates a new immutable version.
• Preview occurs before persistence.
• Deployment still requires authorization and applicable approval.
• Migration history remains traceable.
• Literal credentials should never be stored in imported YAML.
• Group Owners remain limited to assigned groups.