{"record":{"id":"724d0ec8da9fcbe0","repo":"kubernetes/kops","slug":"error-creating-kopsconfig-controller-w","errorCode":null,"errorMessage":"error creating KopsConfig controller: %w","messagePattern":"error creating KopsConfig controller: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"pkg/controllers/clusterapi/register.go","lineNumber":28,"sourceCode":"Unless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n*/\n\npackage clusterapi\n\nimport (\n\t\"fmt\"\n\n\t\"k8s.io/kops/pkg/client/simple\"\n\t\"sigs.k8s.io/controller-runtime/pkg/manager\"\n)\n\nfunc RegisterControllers(mgr manager.Manager, clientset simple.Clientset) error {\n\tif err := NewKopsConfigReconciler(mgr, clientset); err != nil {\n\t\treturn fmt.Errorf(\"error creating KopsConfig controller: %w\", err)\n\t}\n\n\tif err := NewClusterReconciler(mgr); err != nil {\n\t\treturn fmt.Errorf(\"error creating Cluster controller: %w\", err)\n\t}\n\n\treturn nil\n}\n","sourceCodeStart":10,"sourceCodeEnd":37,"githubUrl":"https://github.com/kubernetes/kops/blob/4c8573c808a73d578c5eadc86d410646ea0b0d73/pkg/controllers/clusterapi/register.go#L10-L37","documentation":"This error wraps failures from NewKopsConfigReconciler during RegisterControllers (pkg/controllers/clusterapi/register.go:27-29). The reconciler constructor calls ctrl.NewControllerManagedBy(mgr).For(&api.KopsConfig{}).Complete(r), so the error surfaces if the controller-runtime builder cannot set up watches for KopsConfig — most commonly because the KopsConfig CRD is not registered in the manager's scheme or the CRD is not installed in the cluster.","triggerScenarios":"The kops v1beta1 API types are not added to the manager's scheme so Complete fails to build the controller for the unknown type; the KopsConfig CRD (bootstrap.kops.k8s.io) is not installed in the management cluster; the manager has not started / scheme is misconfigured in main.","commonSituations":"Deploying the kops cluster-api controller against a management cluster where the kops bootstrap provider CRDs were never applied (make release / helm chart skipped); a version mismatch where the controller binary expects CRDs (v1beta1) that the installed chart provides at a different version; running the controller binary outside the intended main entrypoint with a scheme lacking kops types.","solutions":["Check the wrapped error: if it mentions 'no kind is registered' / 'no matches', the scheme lacks the KopsConfig type — ensure main registers kops v1beta1 bootstrap/controlplane types via AddToScheme before RegisterControllers.","Install the kops cluster-api CRDs in the management cluster (apply the CRDs from the kops release / helm chart matching the controller version).","Verify the controller image and CRD manifests are the same version — mismatched chart and binary cause scheme/CRD drift.","Restart the controller after installing the CRDs; the manager performs a fresh discovery at startup.","Confirm the manager is built with the correct scheme in main (scheme literal / clientgoscheme + kops AddToScheme calls)."],"exampleFix":"// before: scheme missing kops types in main\nmgr, err := ctrl.NewManager(cfg, ctrl.Options{Scheme: scheme}) // scheme lacks kops bootstrap types\n// after\nif err := bootstrapv1.AddToScheme(scheme); err != nil { // api/v1beta1 (bootstrap.kops.k8s.io)\n\treturn err\n}\nmgr, err := ctrl.NewManager(cfg, ctrl.Options{Scheme: scheme})","handlingStrategy":"validation","validationCode":"// Startup validation before RegisterControllers in main\nscheme := runtime.NewScheme()\nif err := clientgoscheme.AddToScheme(scheme); err != nil {\n\treturn err\n}\nif err := bootstrapkopsapi.AddToScheme(scheme); err != nil { // KopsConfig kind\n\treturn fmt.Errorf(\"kops bootstrap scheme not registered: %w\", err)\n}\n// Verify CRDs exist in the cluster:\n_, err := discoveryClient.ServerResourcesForGroupVersion(\"bootstrap.kops.k8s.io/v1beta1\")\nif err != nil {\n\treturn fmt.Errorf(\"KopsConfig CRD not installed in management cluster: %w\", err)\n}","typeGuard":null,"tryCatchPattern":"if err := RegisterControllers(mgr, clientset); err != nil {\n\tsetupLog.Error(err, \"cannot register controllers — check scheme registration and installed CRDs\")\n\tos.Exit(1) // fail fast; do not run a manager with missing controllers\n}","preventionTips":["Apply the kops cluster-api CRDs from the same release as the controller binary before deploying it.","Register all kops v1beta1 AddToScheme calls in main's scheme literal setup and cover them with a smoke test.","Keep controller image and CRD manifests versioned together (single helm chart / release artifact).","Fail fast at startup (os.Exit on RegisterControllers error) so missing CRDs are caught immediately in CI/deploy pipelines.","Add a readiness check asserting the controller's watches are established after manager start."],"tags":["kubernetes","controller-runtime","crd","scheme","startup"],"backgroundTag":"crd-not-registered","analyzedSha":"4c8573c808a73d578c5eadc86d410646ea0b0d73","analyzedAt":"2026-09-05T04:13:19.212Z","contentChangedAt":"2026-09-05T04:13:19.212Z","schemaVersion":2},"datasetVersion":"2026-09-12T07:17:12.445Z"}