Skip to content

v1alpha2 conversion tool#698

Merged
wikkyk merged 11 commits intomainfrom
claude/api-migration-guide-rfDXE
Apr 9, 2026
Merged

v1alpha2 conversion tool#698
wikkyk merged 11 commits intomainfrom
claude/api-migration-guide-rfDXE

Conversation

@wikkyk
Copy link
Copy Markdown
Collaborator

@wikkyk wikkyk commented Apr 7, 2026

Issue #
fixes #534

Description of changes:

Migration tool that converts v1alpha1 templates etc to v1alpha2.
It uses the conversion routines in conversion.go, CAPI, etc to make sure that the conversions are consistent with in-cluster conversions.

It tries its best to maintain the original file structure, namely:

  • envsubst variables are handled with sentinel values that get converted back to the original shell variables on output
  • indentation is detected in input and set to the same on output
  • comments are retained where possible
  • any non-capmox/non-capi content is preserved where possible.

Default and null values get stripped. Status fields get stripped. Helpful warnings are emitted when the conversion is lossy.

It should be compatible with clusterctl.

Testing performed:

Comprehensive tests have been added, including an 'end-to-end' full-conversion test.
I have tested this converter on all examples and templates in the repo and it results in almost identical files, with the exception of the manual changes that were applied that cannot be done automatically.

Comment thread pkg/convert/convert.go Outdated
wikkyk pushed a commit that referenced this pull request Apr 7, 2026
wikkyk pushed a commit that referenced this pull request Apr 7, 2026
- Extract testFilename constant to deduplicate "test.yaml" literals
- Merge duplicate DocumentNode/SequenceNode switch cases in defaults.go
- Merge duplicate typeString/typeBool switch cases in sentinel.go Restore()
- Extract runStdin, processFile, writeInPlace from run() to reduce
  cognitive complexity from 31 to under 15
- Extract generateUnique helper to reduce generateSentinel complexity
  from 16 to under 15

https://claude.ai/code/session_015FdS7SaR8zLrDVCqqKXTTT
Comment thread pkg/convert/comments.go Outdated
@wikkyk wikkyk added the e2e/none skip all e2e tests (documentation etc) - overrides all e2e/* labels label Apr 7, 2026
@wikkyk wikkyk changed the base branch from main to v1alpha2/migration-doc April 7, 2026 10:18
wikkyk pushed a commit that referenced this pull request Apr 7, 2026
wikkyk pushed a commit that referenced this pull request Apr 7, 2026
- Extract testFilename constant to deduplicate "test.yaml" literals
- Merge duplicate DocumentNode/SequenceNode switch cases in defaults.go
- Merge duplicate typeString/typeBool switch cases in sentinel.go Restore()
- Extract runStdin, processFile, writeInPlace from run() to reduce
  cognitive complexity from 31 to under 15
- Extract generateUnique helper to reduce generateSentinel complexity
  from 16 to under 15

https://claude.ai/code/session_015FdS7SaR8zLrDVCqqKXTTT
@wikkyk wikkyk force-pushed the claude/api-migration-guide-rfDXE branch from 0e3b218 to 42a9181 Compare April 7, 2026 10:26
Comment thread docs/migration-v0.8-v1alpha2.md Outdated
Comment thread docs/migration-v0.8-v1alpha2.md Outdated
Comment thread docs/migration-v0.8-v1alpha2.md Outdated
Comment thread docs/migration-v0.8-v1alpha2.md Outdated
Base automatically changed from v1alpha2/migration-doc to main April 7, 2026 11:07
@wikkyk wikkyk force-pushed the claude/api-migration-guide-rfDXE branch 5 times, most recently from b864da6 to 4e7c901 Compare April 7, 2026 12:13
@wikkyk wikkyk marked this pull request as ready for review April 7, 2026 12:24
@wikkyk
Copy link
Copy Markdown
Collaborator Author

wikkyk commented Apr 7, 2026

e2e not required because this PR doesn't touch anything that would be tested by e2e.

@wikkyk
Copy link
Copy Markdown
Collaborator Author

wikkyk commented Apr 7, 2026

The 11 accepted issues in SonarQube are all about string constant duplications in places where we actually want to keep the naked string, so it's just a case of the tool being too eager.

@wikkyk wikkyk force-pushed the claude/api-migration-guide-rfDXE branch from 4e7c901 to 0282e42 Compare April 8, 2026 08:32
@wikkyk
Copy link
Copy Markdown
Collaborator Author

wikkyk commented Apr 8, 2026

Minor tweaks: added copyright headers, component name to commit messages; renamed the binary to just convert.

@wikkyk wikkyk force-pushed the claude/api-migration-guide-rfDXE branch from 0282e42 to 16b79c7 Compare April 8, 2026 08:38
@wikkyk
Copy link
Copy Markdown
Collaborator Author

wikkyk commented Apr 8, 2026

TODO: in k8s 34, add an option to output kyaml.

wikkyk and others added 9 commits April 9, 2026 11:11
Introduce the convert CLI tool and the pkg/convert library for
migrating CAPMOX v1alpha1 resources to v1alpha2, and CAPI v1beta1
resources to v1beta2. The tool detects resource types, routes to typed
converters using controller-runtime's conversion interface, and outputs
re-indented YAML.

Co-authored-by: Claude <noreply@anthropic.com>
…ment

Add sentinel scan/replace/restore so that ${VAR} expressions survive
the Go struct round-trip during conversion. Each expression is replaced
with a type-appropriate placeholder before unmarshalling, then restored
in the final YAML output.

Co-authored-by: Claude <noreply@anthropic.com>
Remove null scalars, empty mappings, and known-default values (like
zoneConfigs, externalManagedControlPlane) that the typed conversion
injects but were absent in the original v1alpha1 manifest.

Co-authored-by: Claude <noreply@anthropic.com>
Remove the top-level status key when it contains only zero/null values.
If a status block has real data, it is kept and a warning is emitted so
the operator can review it manually.

Co-authored-by: Claude <noreply@anthropic.com>
Copy head, line, and foot comments from the original YAML tree to the
converted output by matching node structure. Warnings are emitted for
comments on fields that no longer exist in the target schema.

Co-authored-by: Claude <noreply@anthropic.com>
Document the convert CLI tool usage, supported resource types,
and post-conversion review steps in the v0.8 to v1alpha2 migration guide.

Co-authored-by: Claude <noreply@anthropic.com>
Fix missing newline before --- separator for passthrough documents.
splitYAMLDocuments strips trailing newlines when flushing document
chunks before a separator, causing them to concatenate directly.

Co-authored-by: Claude <noreply@anthropic.com>
…calar quotes

Text-based Restore stripped " around sentinels, treating them as YAML quoting.
Inside block scalars (e.g. shell scripts) those chars are literal content.

Introduce RestoreNode, which replaces sentinels in scalar node Values directly —
surrounding " are left intact. typeInt nodes get their !!int tag cleared so
go-yaml re-infers the type. Array sentinels still go through text-based Restore
after serialisation. The top-level Restore call in convertDocument is removed.

Co-Authored-By: Claude <noreply@anthropic.com>
…replacement

Fix gofmt: double space before inline comment in sentinel.go.

Co-authored-by: Claude <noreply@anthropic.com>
@wikkyk wikkyk force-pushed the claude/api-migration-guide-rfDXE branch from 6f4dad0 to 2037e30 Compare April 9, 2026 09:11
claude and others added 2 commits April 9, 2026 11:09
…tput

Preserve block scalar style (literal |, folded >) from source nodes
during GraftComments. k8syaml.Marshal always emits literal style, so
folded (>) scalars were silently converted to literal (|).

Rename copyComments → copyMetadata and add Style copying restricted to
block scalar styles (LiteralStyle, FoldedStyle). Non-block styles like
DoubleQuotedStyle are intentionally not copied.

Co-authored-by: Claude <noreply@anthropic.com>

https://claude.ai/code/session_015FdS7SaR8zLrDVCqqKXTTT
…ng documents

bytes.TrimSpace treated "  ---" (indented) the same as "---", splitting
KubeadmControlPlane manifests mid-block-scalar when embedded YAML used
"---" separators. Document separators in YAML are always at column 0, so
a plain bytes.Equal check is sufficient and correct.

Co-Authored-By: Claude <noreply@anthropic.com>
@sonarqubecloud
Copy link
Copy Markdown

sonarqubecloud Bot commented Apr 9, 2026

Copy link
Copy Markdown
Collaborator

@65278 65278 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tool works for a complex test case. I've specifically not reviewed the code in depth because it's supposed to be used at your own risk. It doesn't run any infrastructure.

@wikkyk wikkyk merged commit adf1f01 into main Apr 9, 2026
13 checks passed
@wikkyk wikkyk deleted the claude/api-migration-guide-rfDXE branch April 9, 2026 12:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

e2e/none skip all e2e tests (documentation etc) - overrides all e2e/* labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

v1alpha1 to v1alpha2 migration tool

3 participants