helm-external-secrets/design/015-module-import-boundaries.md

Module Import Boundaries

Intent

https://github.com/external-secrets/external-secrets/issues/5494 introduced the split of our go module into multiple go modules.

The module structure has been exercised and can now be moved to a design document.

Principles

• Packages in apis are for CRDs and a limited set of interfaces. They may import the standard library, packages in the apis module and an explicit allowlist of API dependencies (for example, k8s.io modules).
• Packages in runtime are common utilities. They contain shared code (validation utilities, webhook helpers, metrics/logging tooling, ...). They may import the standard library, packages in apis or runtime, and an explicit allowlist of runtime dependencies. As the dependencies are included in provider modules, the addition of a module into a runtime package needs to be carefully analysed.
• Packages in pkg are for the core orchestration. It's where the controllers and binary reside. They can depend on apis and runtime.
• Packages in e2e are for the e2e testing, and can require any of the above packages. They are built in isolation, so they should not leak dependencies everywhere.
• Transitive dependencies are not evaluated: If some module imports the whole world, then we will have to deal with it.

Enforcement

In a first stage, we use code reviews to highlight discrepancies and preserve the module layout expressed above.

In a second stage, we enable golangci-lint's existing depguard linter for apis and runtime; pkg and e2e remain review-only. It defines strict rules selected by path like **/apis/**/*.go or **/runtime/**/*.go. Each rule allows $gostd, the module's own package prefix, and the package prefixes belonging to its allowed current direct dependencies.

Depguard analyzes import declarations rather than the module graph, so it checks only direct imports. The file globs include tests. An import such as an AWS or Oracle SDK from a runtime test therefore fails the existing make lint and make reviewable gates without constraining dependencies loaded transitively by an allowed package.

The existing go mod tidy and make check-diff flow remains responsible for removing stale go.mod requirements. No new command, dependency, or CI job is needed.