remove repetitive examples, add docs and good examples#100
Merged
Conversation
There was a problem hiding this comment.
Pull request overview
This PR streamlines the repository’s examples by removing many repetitive primitive-specific examples and replacing them with a smaller set of more opinionated, well-documented examples that demonstrate core framework patterns (mutation gating, extraction/guards, component prerequisites, unstructured resources, and grace inconsistency suppression). It also updates the example harness in the Makefile and extends the shared example CRD spec to support new scenarios.
Changes:
- Removed numerous legacy
*-primitiveexamples and updatedmake run-examplesto run the new curated example set. - Added new examples (
mutations-and-gating,extraction-and-guards,component-prerequisites,custom-resource,grace-inconsistency) with golden YAML fixtures and unit tests. - Enhanced shared example infrastructure (
EnableDebugLogginginExampleAppSpec, plus a shared fake client helper with RESTMapper setup).
Reviewed changes
Copilot reviewed 174 out of 179 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| Makefile | Update run-examples to run the new curated examples. |
| examples/shared/app/owner.go | Add EnableDebugLogging to the shared ExampleApp spec. |
| examples/shared/app/fakeclient.go | Add shared helper to build a fake client with RESTMapper entries. |
| examples/statefulset-primitive/resources/statefulset.go | Remove legacy statefulset primitive example resource factory. |
| examples/statefulset-primitive/README.md | Remove legacy statefulset example documentation. |
| examples/statefulset-primitive/features/mutations.go | Remove legacy statefulset example feature mutations. |
| examples/statefulset-primitive/features/handlers.go | Remove legacy statefulset example status/suspend handlers. |
| examples/statefulset-primitive/app/owner.go | Remove legacy statefulset example owner re-export. |
| examples/statefulset-primitive/app/controller.go | Remove legacy statefulset example controller. |
| examples/serviceaccount-primitive/resources/serviceaccount.go | Remove legacy serviceaccount primitive example resource factory. |
| examples/serviceaccount-primitive/README.md | Remove legacy serviceaccount example documentation. |
| examples/serviceaccount-primitive/features/mutations.go | Remove legacy serviceaccount example feature mutations. |
| examples/serviceaccount-primitive/app/controller.go | Remove legacy serviceaccount example controller. |
| examples/service-primitive/resources/service.go | Remove legacy service primitive example resource factory. |
| examples/service-primitive/README.md | Remove legacy service example documentation. |
| examples/service-primitive/features/mutations.go | Remove legacy service example feature mutations. |
| examples/service-primitive/app/controller.go | Remove legacy service example controller. |
| examples/secret-primitive/resources/secret.go | Remove legacy secret primitive example resource factory. |
| examples/secret-primitive/README.md | Remove legacy secret example documentation. |
| examples/secret-primitive/features/mutations.go | Remove legacy secret example feature mutations. |
| examples/secret-primitive/app/controller.go | Remove legacy secret example controller. |
| examples/rolebinding-primitive/resources/rolebinding.go | Remove legacy rolebinding primitive example resource factory. |
| examples/rolebinding-primitive/README.md | Remove legacy rolebinding example documentation. |
| examples/rolebinding-primitive/main.go | Remove legacy rolebinding example entrypoint. |
| examples/rolebinding-primitive/features/mutations.go | Remove legacy rolebinding example feature mutations. |
| examples/rolebinding-primitive/app/controller.go | Remove legacy rolebinding example controller. |
| examples/role-primitive/resources/role.go | Remove legacy role primitive example resource factory. |
| examples/role-primitive/README.md | Remove legacy role example documentation. |
| examples/role-primitive/features/mutations.go | Remove legacy role example feature mutations. |
| examples/role-primitive/app/controller.go | Remove legacy role example controller. |
| examples/replicaset-primitive/resources/replicaset.go | Remove legacy replicaset primitive example resource factory. |
| examples/replicaset-primitive/README.md | Remove legacy replicaset example documentation. |
| examples/replicaset-primitive/features/mutations.go | Remove legacy replicaset example feature mutations. |
| examples/replicaset-primitive/app/owner.go | Remove legacy replicaset example owner re-export. |
| examples/replicaset-primitive/app/controller.go | Remove legacy replicaset example controller. |
| examples/pvc-primitive/resources/pvc.go | Remove legacy pvc primitive example resource factory. |
| examples/pvc-primitive/README.md | Remove legacy pvc example documentation. |
| examples/pvc-primitive/features/mutations.go | Remove legacy pvc example feature mutations. |
| examples/pvc-primitive/app/owner.go | Remove legacy pvc example owner re-export. |
| examples/pvc-primitive/app/controller.go | Remove legacy pvc example controller. |
| examples/pv-primitive/resources/pv.go | Remove legacy pv primitive example resource factory. |
| examples/pv-primitive/README.md | Remove legacy pv example documentation. |
| examples/pv-primitive/features/mutations.go | Remove legacy pv example feature mutations. |
| examples/pv-primitive/app/controller.go | Remove legacy pv example package docs/controller placeholder. |
| examples/pod-primitive/resources/pod.go | Remove legacy pod primitive example resource factory. |
| examples/pod-primitive/README.md | Remove legacy pod example documentation. |
| examples/pod-primitive/features/mutations.go | Remove legacy pod example feature mutations. |
| examples/pod-primitive/app/owner.go | Remove legacy pod example owner re-export. |
| examples/pod-primitive/app/controller.go | Remove legacy pod example controller. |
| examples/pdb-primitive/resources/pdb.go | Remove legacy pdb primitive example resource factory. |
| examples/pdb-primitive/README.md | Remove legacy pdb example documentation. |
| examples/pdb-primitive/features/mutations.go | Remove legacy pdb example feature mutations. |
| examples/pdb-primitive/app/controller.go | Remove legacy pdb example controller. |
| examples/networkpolicy-primitive/resources/networkpolicy.go | Remove legacy networkpolicy primitive example resource factory. |
| examples/networkpolicy-primitive/README.md | Remove legacy networkpolicy example documentation. |
| examples/networkpolicy-primitive/main.go | Remove legacy networkpolicy example entrypoint. |
| examples/networkpolicy-primitive/features/mutations.go | Remove legacy networkpolicy example feature mutations. |
| examples/networkpolicy-primitive/app/controller.go | Remove legacy networkpolicy example controller. |
| examples/job-primitive/resources/job.go | Remove legacy job primitive example resource factory. |
| examples/job-primitive/README.md | Remove legacy job example documentation. |
| examples/job-primitive/features/status.go | Remove legacy job example custom converge status handler. |
| examples/job-primitive/features/mutations.go | Remove legacy job example feature mutations. |
| examples/job-primitive/app/controller.go | Remove legacy job example controller. |
| examples/ingress-primitive/resources/ingress.go | Remove legacy ingress primitive example resource factory. |
| examples/ingress-primitive/README.md | Remove legacy ingress example documentation. |
| examples/ingress-primitive/features/mutations.go | Remove legacy ingress example feature mutations. |
| examples/ingress-primitive/app/controller.go | Remove legacy ingress example controller. |
| examples/hpa-primitive/resources/hpa.go | Remove legacy hpa primitive example resource factory. |
| examples/hpa-primitive/README.md | Remove legacy hpa example documentation. |
| examples/hpa-primitive/features/mutations.go | Remove legacy hpa example feature mutations. |
| examples/hpa-primitive/app/controller.go | Remove legacy hpa example controller. |
| examples/deployment-primitive/resources/deployment.go | Remove legacy deployment primitive example resource factory. |
| examples/deployment-primitive/README.md | Remove legacy deployment example documentation. |
| examples/deployment-primitive/features/status.go | Remove legacy deployment example custom status/suspend handlers. |
| examples/deployment-primitive/features/mutations.go | Remove legacy deployment example feature mutations. |
| examples/deployment-primitive/app/controller.go | Remove legacy deployment example controller. |
| examples/daemonset-primitive/resources/daemonset.go | Remove legacy daemonset primitive example resource factory. |
| examples/daemonset-primitive/README.md | Remove legacy daemonset example documentation. |
| examples/daemonset-primitive/features/mutations.go | Remove legacy daemonset example feature mutations. |
| examples/daemonset-primitive/app/controller.go | Remove legacy daemonset example controller. |
| examples/configmap-primitive/resources/configmap.go | Remove legacy configmap primitive example resource factory. |
| examples/configmap-primitive/README.md | Remove legacy configmap example documentation. |
| examples/configmap-primitive/features/mutations.go | Remove legacy configmap example feature mutations. |
| examples/configmap-primitive/app/controller.go | Remove legacy configmap example controller. |
| examples/cronjob-primitive/resources/cronjob.go | Remove legacy cronjob primitive example resource factory. |
| examples/cronjob-primitive/README.md | Remove legacy cronjob example documentation. |
| examples/cronjob-primitive/features/mutations.go | Remove legacy cronjob example feature mutations. |
| examples/cronjob-primitive/app/controller.go | Remove legacy cronjob example controller/aliases. |
| examples/clusterrolebinding-primitive/resources/clusterrolebinding.go | Remove legacy clusterrolebinding primitive example resource factory. |
| examples/clusterrolebinding-primitive/README.md | Remove legacy clusterrolebinding example documentation. |
| examples/clusterrolebinding-primitive/main.go | Remove legacy clusterrolebinding example entrypoint. |
| examples/clusterrolebinding-primitive/features/mutations.go | Remove legacy clusterrolebinding example feature mutations. |
| examples/clusterrolebinding-primitive/app/controller.go | Remove legacy clusterrolebinding example controller. |
| examples/clusterrole-primitive/resources/clusterrole.go | Remove legacy clusterrole primitive example resource factory. |
| examples/clusterrole-primitive/README.md | Remove legacy clusterrole example documentation. |
| examples/clusterrole-primitive/features/mutations.go | Remove legacy clusterrole example feature mutations. |
| examples/clusterrole-primitive/app/controller.go | Remove legacy clusterrole example controller. |
| examples/mutations-and-gating/README.md | Add new example docs for version/boolean gating and ordering. |
| examples/mutations-and-gating/main.go | Add new example entrypoint. |
| examples/mutations-and-gating/app/owner.go | Add owner type re-export for the example. |
| examples/mutations-and-gating/app/controller.go | Add controller demonstrating resource-level gating + suspension. |
| examples/mutations-and-gating/resources/deployment.go | Add Deployment baseline + gated mutations composition. |
| examples/mutations-and-gating/resources/configmap.go | Add ConfigMap baseline + gated metrics config mutation. |
| examples/mutations-and-gating/resources/deployment_test.go | Add golden tests for Deployment combinations. |
| examples/mutations-and-gating/resources/configmap_test.go | Add golden tests for ConfigMap combinations. |
| examples/mutations-and-gating/resources/testdata/deployment-v1.yaml | Golden YAML for v1 baseline. |
| examples/mutations-and-gating/resources/testdata/deployment-v1-debug.yaml | Golden YAML for v1 + debug. |
| examples/mutations-and-gating/resources/testdata/deployment-v1-tracing.yaml | Golden YAML for v1 + tracing. |
| examples/mutations-and-gating/resources/testdata/deployment-v1-tracing-debug.yaml | Golden YAML for v1 + tracing + debug. |
| examples/mutations-and-gating/resources/testdata/deployment-v2.yaml | Golden YAML for v2 baseline. |
| examples/mutations-and-gating/resources/testdata/deployment-v2-debug.yaml | Golden YAML for v2 + debug. |
| examples/mutations-and-gating/resources/testdata/deployment-v2-tracing.yaml | Golden YAML for v2 + tracing. |
| examples/mutations-and-gating/resources/testdata/deployment-v2-tracing-debug.yaml | Golden YAML for v2 + tracing + debug. |
| examples/mutations-and-gating/resources/testdata/configmap-baseline.yaml | Golden YAML for ConfigMap baseline. |
| examples/mutations-and-gating/resources/testdata/configmap-metrics.yaml | Golden YAML for ConfigMap + metrics. |
| examples/mutations-and-gating/features/constraint.go | Add semver-based feature.VersionConstraint implementation. |
| examples/mutations-and-gating/features/debug_logging.go | Add boolean-gated debug logging mutation. |
| examples/mutations-and-gating/features/debug_logging_test.go | Add unit test for debug logging mutation. |
| examples/mutations-and-gating/features/legacy_container.go | Add backward-compat container rename/port mutation. |
| examples/mutations-and-gating/features/legacy_container_test.go | Add unit test for backward-compat mutation. |
| examples/mutations-and-gating/features/metrics_config.go | Add metrics ConfigMap YAML merge mutation. |
| examples/mutations-and-gating/features/metrics_config_test.go | Add unit test for metrics config mutation. |
| examples/mutations-and-gating/features/tracing_sidecar.go | Add tracing sidecar injection mutation. |
| examples/mutations-and-gating/features/tracing_sidecar_test.go | Add unit test for tracing sidecar mutation. |
| examples/extraction-and-guards/README.md | Add new example docs for extraction + guard ordering. |
| examples/extraction-and-guards/main.go | Add new example entrypoint. |
| examples/extraction-and-guards/app/owner.go | Add owner type re-export for the example. |
| examples/extraction-and-guards/app/controller.go | Add controller that wires extractor output into a downstream guard. |
| examples/extraction-and-guards/resources/configmap.go | Add ConfigMap baseline + data extractor capturing db-host. |
| examples/extraction-and-guards/resources/secret.go | Add Secret baseline + guard that blocks until extracted data exists. |
| examples/extraction-and-guards/resources/configmap_test.go | Add golden test for ConfigMap baseline. |
| examples/extraction-and-guards/resources/secret_test.go | Add golden test for Secret baseline. |
| examples/extraction-and-guards/resources/testdata/configmap.yaml | Golden YAML for db ConfigMap. |
| examples/extraction-and-guards/resources/testdata/secret.yaml | Golden YAML for credentials Secret. |
| examples/component-prerequisites/README.md | Add new example docs for component prerequisites (DependsOn). |
| examples/component-prerequisites/main.go | Add new example entrypoint. |
| examples/component-prerequisites/app/owner.go | Add owner type re-export for the example. |
| examples/component-prerequisites/app/controller.go | Add controller demonstrating two components + prerequisite ordering. |
| examples/component-prerequisites/resources/configmap.go | Add infra ConfigMap baseline resource. |
| examples/component-prerequisites/resources/deployment.go | Add app Deployment baseline + version mutation. |
| examples/component-prerequisites/resources/configmap_test.go | Add golden test for infra ConfigMap baseline. |
| examples/component-prerequisites/resources/deployment_test.go | Add golden tests for versioned Deployment shapes. |
| examples/component-prerequisites/resources/testdata/configmap.yaml | Golden YAML for infra ConfigMap. |
| examples/component-prerequisites/resources/testdata/deployment-v1.yaml | Golden YAML for app Deployment v1. |
| examples/component-prerequisites/resources/testdata/deployment-v2.yaml | Golden YAML for app Deployment v2. |
| examples/custom-resource/README.md | Add new example docs for unstructured/static custom resources. |
| examples/custom-resource/main.go | Add new example entrypoint. |
| examples/custom-resource/app/owner.go | Add owner type re-export for the example. |
| examples/custom-resource/app/controller.go | Add controller managing an unstructured CertificateRequest. |
| examples/custom-resource/resources/certificate.go | Add unstructured baseline + mutation/editing + extraction. |
| examples/custom-resource/resources/certificate_test.go | Add golden tests for base and mutated CertificateRequest. |
| examples/custom-resource/resources/testdata/certificate-base.yaml | Golden YAML for unstructured base object. |
| examples/custom-resource/resources/testdata/certificate.yaml | Golden YAML for mutated unstructured object. |
| examples/grace-inconsistency/README.md | Add new example docs for suppressing grace inconsistency warnings. |
| examples/grace-inconsistency/main.go | Add new example entrypoint. |
| examples/grace-inconsistency/app/owner.go | Add owner type re-export for the example. |
| examples/grace-inconsistency/app/controller.go | Add controller using grace period + suppression option. |
| examples/grace-inconsistency/resources/deployment.go | Add monitoring Deployment baseline + custom grace handler. |
| examples/grace-inconsistency/resources/deployment_test.go | Add golden test for monitoring Deployment baseline. |
| examples/grace-inconsistency/resources/testdata/deployment.yaml | Golden YAML for monitoring Deployment. |
Comment on lines
124
to
+130
| .PHONY: run-examples | ||
| run-examples: ## Run all examples to verify they execute without error. | ||
| go run ./examples/deployment-primitive/. | ||
| go run ./examples/configmap-primitive/. | ||
| go run ./examples/serviceaccount-primitive/. | ||
| go run ./examples/secret-primitive/. | ||
| go run ./examples/statefulset-primitive/. | ||
| go run ./examples/replicaset-primitive/. | ||
| go run ./examples/rolebinding-primitive/. | ||
| go run ./examples/custom-resource-implementation/. | ||
| go run ./examples/service-primitive/. | ||
| go run ./examples/role-primitive/. | ||
| go run ./examples/pdb-primitive/. | ||
| go run ./examples/daemonset-primitive/. | ||
| go run ./examples/hpa-primitive/. | ||
| go run ./examples/clusterrolebinding-primitive/. | ||
| go run ./examples/clusterrole-primitive/. | ||
| go run ./examples/cronjob-primitive/. | ||
| go run ./examples/ingress-primitive/. | ||
| go run ./examples/job-primitive/. | ||
| go run ./examples/networkpolicy-primitive/. | ||
| go run ./examples/pod-primitive/. | ||
| go run ./examples/pvc-primitive/. | ||
| go run ./examples/pv-primitive/. | ||
| go run ./examples/mutations-and-gating/. | ||
| go run ./examples/extraction-and-guards/. | ||
| go run ./examples/component-prerequisites/. | ||
| go run ./examples/custom-resource/. | ||
| go run ./examples/grace-inconsistency/. |
There was a problem hiding this comment.
make test (used by CI) excludes ./examples/..., but this PR adds multiple *_test.go golden tests under examples/. As-is, those tests won't run in CI and can silently drift. Consider adding a dedicated test-examples target (e.g., go test ./examples/...) and wiring it into all/CI, or at minimum run go test ./examples/... as part of run-examples so these golden tests execute regularly.
Comment on lines
+9
to
+15
| // TracingSidecarMutation injects a Jaeger sidecar and sets JAEGER_AGENT_HOST on | ||
| // the application container. It is boolean-gated on the enableTracing flag. | ||
| func TracingSidecarMutation(enabled bool) deployment.Mutation { | ||
| return deployment.Mutation{ | ||
| Name: "Tracing", | ||
| Feature: feature.NewVersionGate("any", nil).When(enabled), | ||
| Mutate: func(m *deployment.Mutator) error { |
There was a problem hiding this comment.
The comment says this mutation sets JAEGER_AGENT_HOST on the application container, but it calls m.EnsureContainerEnvVar(...) which (per the deployment mutator) applies to all containers, including the sidecar you just injected. Either update the comment to match the actual behavior, or change the implementation to target only the intended container via a selector.
Comment on lines
+35
to
+37
| builder.WithGuard(func(_ corev1.Secret) (concepts.GuardStatusWithReason, error) { | ||
| if *dbHost == "" { | ||
| fmt.Println(" Guard: blocked, waiting for db-host from ConfigMap") |
There was a problem hiding this comment.
This guard unconditionally dereferences dbHost (*dbHost) and will panic if the caller passes nil. Since NewSecretResource accepts a *string, add a nil check and treat nil as blocked (or return an error) to keep the example robust and avoid surprising panics.
Comment on lines
+36
to
+38
| builder.WithDataExtractor(func(cm corev1.ConfigMap) error { | ||
| *dbHost = cm.Data["db-host"] | ||
| fmt.Printf(" Extracted db-host: %q\n", *dbHost) |
There was a problem hiding this comment.
The data extractor writes to *dbHost without checking for nil. Since dbHost is passed in as a pointer, consider validating it (return an error if nil) before writing to avoid a potential panic if the helper is reused incorrectly.
Comment on lines
+64
to
+67
| builder.WithDataExtractor(func(obj uns.Unstructured) error { | ||
| dnsNames, _, _ := uns.NestedStringSlice(obj.Object, "spec", "dnsNames") | ||
| fmt.Printf(" Certificate DNS names: %v\n", dnsNames) | ||
| return nil |
There was a problem hiding this comment.
The data extractor ignores the error return from unstructured.NestedStringSlice (dnsNames, _, _ := ...). Since this example is intended as a “good example”, it would be better to handle and return that error so failed/unexpected object shapes don’t get silently masked.
Comment on lines
+10
to
+12
| - **Version-gated backward compat mutation**: `BackwardCompatV1Container` activates for versions `< 2.0.0` and rolls the | ||
| baseline back to the v1 layout (container named "server", HTTP port only). Uses a `semver.Constraint` as a | ||
| `feature.VersionConstraint`. The `BackwardCompat` prefix makes the pattern immediately recognizable. |
There was a problem hiding this comment.
The README claims the backward-compat mutation uses a semver.Constraint, but the implementation wraps *semver.Constraints returned by semver.NewConstraint. Please adjust the wording to refer to a semver constraint expression / *semver.Constraints to avoid misleading readers about the actual type involved.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.