[PROPOSAL] Migrate template string constants to embedded files using embed.FS

[vitorfloriano]

Note

The go:embed feature was suggested in #2067, but then the following thread took another direction and this enhancement seems to never have been properly discussed.

Summary

Migrate Kubebuilder's scaffolding templates from inline Go string constants to separate template files using Go's embed package. This improves maintainability, enables better tooling, and lowers the barrier for community contributions.

Motivation

Current State

Templates are currently defined as large string constants within Go files:

// pkg/plugins/golang/v4/scaffolds/internal/templates/dockerfile.go
const dockerfileTemplate = `# Build the manager binary
FROM golang:1.25 AS builder
...  70+ lines of Dockerfile ...

Problems

1. Poor Editing Experience

• No syntax highlighting for template content (Dockerfile, Makefile, YAML, etc.)
• Can't use language-specific linters (hadolint, yamllint, shellcheck)
• Can't use formatters (prettier, gofmt on generated code)
• Large Go files mixing templates and logic

2. Difficult Code Review

• Template changes mixed with Go code changes in diffs
• Hard to review template content without proper syntax highlighting
• Easy to miss errors (missing quotes, incorrect indentation, whitespace problems)

3. Scalability Issues

• Adding templates requires modifying Go files
• No hierarchical organization of templates
• Template discovery requires grepping through Go code

4. Community Contribution Barriers

• Contributors must understand Go syntax and escaping rules
• Can't preview templates without compiling
• Non-Go developers can't easily contribute template improvements

5. Limited Testing

• Can't use external validation tools on templates
• Difficult to test template syntax independently
• No easy way to discover and validate all templates

Goals

• Improve Maintainability - Separate templates from Go code
• Enable Better Tooling - Use language-specific linters and formatters
• Enhance Testability - Validate templates with external tools
• Lower Contribution Barrier - Allow non-Go developers to improve templates

Proposal

Embedded Filesystem with Helper Functions

All templates will be embedded into the binary using Go's embed.FS and accessed through a centralized loader with helper functions. This provides a clean separation between template content and Go logic while maintaining the single-binary distribution model.

Architecture

Template Loader (loader.go)

A single package-level embed.FS variable holds all templates, with helper functions providing convenient access:

// pkg/plugins/golang/v4/scaffolds/internal/templates/loader.go
package templates

import (
    "embed"
    "fmt"
    "io/fs"
    "path/filepath"
    "strings"
)

//go:embed embedded/*      <-- Embed entire template directory into binary at compile time
var templateFS embed. FS

// Load reads a template file by name (relative to embedded/)
func Load(name string) (string, error) {
    path := filepath.Join("embedded", name)
    content, err := templateFS.ReadFile(path)
    if err != nil {
        return "", fmt.Errorf("template %s not found: %w", name, err)
    }
    return string(content), nil
}

// MustLoad is like Load but panics if the template cannot be loaded. 
// Use this when template absence indicates a programming error.
func MustLoad(name string) string {
   ...
}

// Exists checks if a template file exists
func Exists(name string) bool {
    ...
}

// List returns all template files matching a pattern
func List(pattern string) ([]string, error) {
   ...
}

// ListAll returns all embedded template files
func ListAll() ([]string, error) {
   ...
}

Usage Patterns

• Simple Template (Single File)

For templates that are always used exactly as-is:

// pkg/plugins/golang/v4/scaffolds/internal/templates/dockerfile.go

var _ machinery.Template = &Dockerfile{}

type Dockerfile struct {
    machinery.TemplateMixin
}

func (f *Dockerfile) SetTemplateDefaults() error {
    if f.Path == "" {
        f.Path = "Dockerfile"
    }
    
    // Load template from embedded filesystem
    f.TemplateBody = templates.MustLoad("Dockerfile.tmpl")
    
    return nil
}

• Complex Template (Dynamic Composition)

For templates that need to be assembled from multiple parts based on configuration:

// pkg/plugins/golang/v4/scaffolds/internal/templates/webhooks/webhook.go

var _ machinery.Template = &Webhook{}

type Webhook struct {
    machinery.TemplateMixin
    machinery.MultiGroupMixin
    machinery.ResourceMixin
    
    QualifiedGroupWithDash  string
    AdmissionReviewVersions string
    Force                   bool
}

func (f *Webhook) SetTemplateDefaults() error {
    if f.Path == "" {
        if f.MultiGroup && f.Resource.Group != "" {
            f.Path = filepath.Join("internal", "webhook", "%[group]", "%[version]", "%[kind]_webhook.go")
        } else {
            f.Path = filepath. Join("internal", "webhook", "%[version]", "%[kind]_webhook.go")
        }
    }
    
    f.Path = f.Resource. Replacer().Replace(f.Path)
    
    // Load base template
    base := templates.MustLoad("webhooks/base. go.tmpl")
    parts := []string{base}
    
    // Conditionally add optional templates based on resource configuration
    if f.Resource.HasDefaultingWebhook() {
        defaulting := templates.MustLoad("webhooks/defaulting.go. tmpl")
        parts = append(parts, defaulting)
    }
    
    if f. Resource.HasValidationWebhook() {
        validating := templates.MustLoad("webhooks/validating.go. tmpl")
        parts = append(parts, validating)
    }
    
    if f.Resource.HasConversionWebhook() {
        conversion := templates.MustLoad("webhooks/conversion.go.tmpl")
        parts = append(parts, conversion)
    }
    
    // Combine all parts into final template body
    f.TemplateBody = strings.Join(parts, "\n")
    
    if f.Force {
        f.IfExistsAction = machinery.OverwriteFile
    } else {
        f.IfExistsAction = machinery.Error
    }
    
    f.AdmissionReviewVersions = "v1"
    f.QualifiedGroupWithDash = strings.ReplaceAll(f. Resource.QualifiedGroup(), ".", "-")
    
    return nil
}

Key Design Decisions

1. Centralized Loader

All template access goes through a single loader package. This provides:

• Consistent interface - Same API for all templates
• Single source of truth - One place to manage template access
• Easy debugging - All loads can be traced through one function
• Future extensibility - Can add features (caching, preprocessing, metrics) in one place

2. Hierarchical Organization

Templates are organized in subdirectories by domain:

• api/ - API-related templates (types, groups, conversions)
• webhooks/ - Webhook-related templates
• controllers/ - Controller-related templates
• config/ - Configuration templates (kustomize, RBAC, etc.)

This mirrors the project structure and makes templates easy to locate.

3. Template File Extensions

All templates use .tmpl extension:

• Clear distinction - Easy to identify template files
• Go convention - Follows standard Go template naming
• Tool compatibility - Many editors recognize .tmpl extension
• Glob patterns - Easy to filter: *.tmpl

Directory Structure

pkg/plugins/golang/v4/scaffolds/internal/templates/
├── loader.go                         # Template loader with embed.FS
├── loader_test.go                    # Comprehensive template tests
├── dockerfile.go                     # Dockerfile scaffolder
├── makefile.go                       # Makefile scaffolder
├── gitignore.go                      # . gitignore scaffolder 
├── embedded/                         # All template files
│   ├── Dockerfile. tmpl               # Dockerfile template
│   ├── Makefile.tmpl                 # Makefile template
│   ├── . gitignore.tmpl               # .gitignore template
│   ├── README.md.tmpl                # README template
│   ├── . golangci.yml.tmpl            # Linter config template
│   ├── api/                          # API templates
│   │   ├── types.go.tmpl
│   │   ├── group.go.tmpl
│   │   ├── hub.go.tmpl
│   │   └── spoke.go.tmpl
│   ├── webhooks/                     # Webhook templates
│   │   ├── base.go.tmpl
│   │   ├── defaulting.go.tmpl
│   │   ├── validating.go.tmpl
│   │   └── conversion.go.tmpl
│   ├── controllers/                  # Controller templates
│   │   ├── controller.go.tmpl
│   │   ├── suite_test.go.tmpl
│   │   └── controller_test.go.tmpl
│   └── config/                       # Config templates
│       ├── kustomize/
│       │   └── kustomization.yaml.tmpl
│       └── rbac/
│           ├── role.yaml.tmpl
│           └── rolebinding.yaml.tmpl

Benefits

1. Better Developer Experience

• Before:

// Edit in Go file, no syntax highlighting
const makefileTemplate = `
. PHONY: manifests
manifests:  controller-gen
	$(CONTROLLER_GEN) rbac:roleName=manager-role crd webhook paths="./..."
`

• After:

# embedded/Makefile.tmpl - Full Makefile syntax highlighting! 
.PHONY: manifests
manifests: controller-gen
	$(CONTROLLER_GEN) rbac:roleName=manager-role crd webhook paths="./..."

2. Enable External Tooling

 .github/workflows/validate-templates.yml
- name: Lint Dockerfiles
  run: find embedded -name "Dockerfile.tmpl" | xargs hadolint

- name: Lint YAML
  run: find embedded -name "*.yaml. tmpl" | xargs yamllint

- name: Lint Shell Scripts
  run: find embedded -name "*.sh.tmpl" | xargs shellcheck

3. Better Code Reviews

# Template changes are clear and isolated
diff --git a/embedded/Dockerfile.tmpl b/embedded/Dockerfile.tmpl
@@ -1,4 +1,4 @@
-FROM golang:1.25 AS builder
+FROM golang:1.26 AS builder

# Go logic changes are separate
diff --git a/dockerfile. go b/dockerfile.go
@@ -12,6 +12,7 @@
 func (f *Dockerfile) SetTemplateDefaults() error {
     f.Path = "Dockerfile"
+    f.IfExistsAction = machinery.OverwriteFile
     return nil
 }

4. Lower Contribution Barrier

Non-Go developers can now contribute template improvements:

# Before:  Must edit Go files, understand escaping
vim pkg/plugins/golang/v4/scaffolds/internal/templates/dockerfile.go

# After: Just edit the template
vim embedded/Dockerfile.tmpl

5. Separation of Concerns

Template content lives in dedicated .tmpl files with proper file extensions:

• Dockerfiles get full Docker syntax highlighting
• Makefiles get Makefile syntax highlighting
• YAML files get YAML validation
• Go templates get Go template syntax checking
• Go logic lives in .go files focused purely on scaffolding behavior.

6. Scalability

Adding new templates is straightforward:

# Create new template file
touch embedded/new-feature/component.yaml.tmpl

# Use in scaffolder
content := templates.MustLoad("new-feature/component.yaml.tmpl")

Conclusion

Migrating to go:embed improves Kubebuilder's maintainability, testability, and accessibility to contributors.

The implementation is straightforward, well-supported by Go's standard library, and aligns with Go best practices.

References

Go embed package documentation
Go 1.16 Release Notes (embed feature)

Discussion

Please share your thoughts, concerns, or suggestions.

[camilamacedo86]

Thanks a lot for the proposal — I appreciate the intent (better DX, cleaner diffs, easier editing).

After looking at how Kubebuilder scaffolding works today (Machinery + plugins), I’m not in favor of moving templates to embed.FS.

Why this is not just “template files”

Kubebuilder scaffolding is built on the Machinery library. In practice we don’t only “render a file” — we run a pipeline:

• Builders (Machinery Builder): everything that generates/updates a file has:

  • GetPath()
  • GetIfExistsAction() (overwrite/skip/error/etc.)

• Templates (Machinery Template): usually a Go struct that:

  • embeds mixins (TemplateMixin + project/resource mixins)
  • implements SetTemplateDefaults() (sets Path, TemplateBody, IfExistsAction, etc.)
  • uses text/template over the struct fields

• Mixins + injection interfaces: templates can implement HasRepository, HasProjectName, HasDomain, HasResource, HasMultiGroup, etc.
  The Scaffold engine injects values into templates via these interfaces (ex: repository, project name, resource GVK, boilerplate, config).

• Inserters / Updaters (Machinery Inserter): we also modify existing files by inserting code fragments at markers:

  • markers like +kubebuilder:scaffold:*
  • GetMarkers() declares valid insertion points
  • GetCodeFragments() returns the code to inject per marker
    This is how we keep adding controllers/webhooks/CRD bits over time without rewriting user code.

Key point: Kubebuilder scaffolding is a combination of:

1. template content,
2. injected context (config + resource),
3. conditional logic / composition,
4. insertions into existing files via markers.

That coupling is why Kubebuilder has stayed maintainable and extensible.

Why embed.FS is a bad fit for this model

embed.FS is nice when templates are small and mostly static. But for Kubebuilder’s Machinery-driven approach, it tends to create more problems:

• We lose co-location of “what” and “why”
  Today, the template body is close to SetTemplateDefaults() and the mixins/injection expectations.
  When templates move to embedded files, reviewers must jump between:

  • Go logic (mixins, defaults, conditions, insertion rules)
  • template file(s)
  • loader/lookup layer (paths/strings)
    That makes it harder to answer: “What gets generated for this option/resource?”

• Markers + inserters become harder to maintain
  Inserters depend on marker lines existing exactly as expected.
  When templates are external and spread out, it’s easier to accidentally:

  • rename/remove a marker line
  • move content around and break insertion behavior
    Keeping markers near the Go logic that uses them reduces mistakes.

• Indirection grows over time
  With embed.FS, you introduce string-based names/paths for templates.
  Refactors become more fragile (rename/move files, update paths, ensure no runtime lookup errors).
  It also becomes harder to search from “generated output line” back to the source.

• File explosion + variants
  In real projects, once you have many conditionals and variants, embed.FS usually leads to:

  • many template files (sometimes hundreds)
  • duplicated/near-duplicated templates for small differences
  • more “where is this defined?” time during debugging and reviews
    That’s not simpler — it’s just complexity in a different place.

• No real simplification of the hard parts
  We still need the Machinery pipeline (mixins/injection, config/resource context, inserters, markers).
  embed.FS only moves where the text lives; it does not remove the complex parts of scaffolding.

Cost / ROI

This would be an XXXXLLL sized migration effort across a mature system.
In my opinion the ROI is low and we would likely lose maintainability, not win it.

That time is better spent bringing value to end users, for example:

• make the CLI smarter (including exploring how AI can help common workflows)
• improve docs and onboarding
• bug fixes and reliability improvements
• new features that solve real user issues

So overall: I truly appreciate the proposal, but I’m not in favor of switching Kubebuilder templates to embed.FS.

[vitorfloriano]

Thanks for the detailed feedback!

I'll close this proposal and shift my focus to contributing in areas that better align with the roadmap, like the AI workflows or CLI improvements you mentioned.

Thanks again for the class on Machinery!

[camilamacedo86]

Thank you a lot for raising this one and for all your help and commitment to make things better
Please, continue doing this amazing collabs !!!