{"record":{"id":"6d13df6a9e0d94f8","repo":"cilium/cilium","slug":"endpoint-may-not-be-associated-reserved-labels","errorCode":null,"errorMessage":"endpoint may not be associated reserved labels","messagePattern":"endpoint may not be associated reserved labels","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"pkg/endpoint/endpoint.go","lineNumber":1750,"sourceCode":"\t\tstats.Forwarded++\n\t\tmetrics.ProxyPolicyL7Total.WithLabelValues(\"forwarded\", proxyType).Inc()\n\tcase accesslog.VerdictDenied:\n\t\tstats.Denied++\n\t\tmetrics.ProxyPolicyL7Total.WithLabelValues(\"denied\", proxyType).Inc()\n\tcase accesslog.VerdictError:\n\t\tstats.Error++\n\t\tmetrics.ProxyPolicyL7Total.WithLabelValues(\"parse_errors\", proxyType).Inc()\n\t}\n}\n\n// APICanModify determines whether API requests from a user are allowed to\n// modify this endpoint.\nfunc APICanModify(e *Endpoint) error {\n\tif e.IsInit() {\n\t\treturn nil\n\t}\n\tif e.labels.OrchestrationIdentity.IsReserved() {\n\t\treturn fmt.Errorf(\"endpoint may not be associated reserved labels\")\n\t}\n\treturn nil\n}\n\n// APICanModifyConfig determines whether API requests from users are allowed to\n// modify the configuration of the endpoint.\nfunc (e *Endpoint) APICanModifyConfig(n models.ConfigurationMap) error {\n\tif !e.labels.OrchestrationIdentity.IsReserved() {\n\t\treturn nil\n\t}\n\tfor config, val := range n {\n\t\tif optionSetting, err := option.NormalizeBool(val); err == nil {\n\t\t\tif e.Options.GetValue(config) == optionSetting {\n\t\t\t\t// The option won't be changed.\n\t\t\t\tcontinue\n\t\t\t}\n\t\t\tif config != option.Debug && config != option.DebugLB &&\n\t\t\t\tconfig != option.TraceNotify && config != option.PolicyVerdictNotify &&","sourceCodeStart":1732,"sourceCodeEnd":1768,"githubUrl":"https://github.com/cilium/cilium/blob/ac7b90affa4baf0642e6685319d56907b3a73a6d/pkg/endpoint/endpoint.go#L1732-L1768","documentation":"APICanModify enforces that API requests from users cannot modify endpoints carrying reserved orchestration-identity labels (e.g. reserved:host, reserved:init, reserved:health). If the endpoint's labels are reserved and it is not in init state, modification is rejected. Reserved endpoints are managed by Cilium itself.","triggerScenarios":"A user API call (PUT/PATCH via the Cilium API or cilium CLI, e.g. cilium endpoint config/labels <id>) targets an endpoint whose labels.OrchestrationIdentity contains reserved labels, and the endpoint is not in 'init' state.","commonSituations":"Trying to change configuration or labels of the host endpoint (reserved:host), health endpoints (reserved:health), or ingress/init endpoints via the API; automation scripts iterating all endpoints and attempting to modify reserved ones.","solutions":["Stop trying to modify reserved endpoints via the API — manage them through Cilium itself (they are auto-managed).","Filter out endpoints with reserved labels in automation: skip endpoints whose labels include reserved:* entries.","If you need to affect host networking behavior, use the appropriate host firewall/host policy settings instead of endpoint modification.","Use cilium endpoint list to check which endpoints are reserved before issuing modification requests."],"exampleFix":null,"handlingStrategy":"type-guard","validationCode":"if e.labels.OrchestrationIdentity.IsReserved() && !e.IsInit() {\n    // skip: reserved endpoints (reserved:host, reserved:health, ...) are agent-managed\n    return nil\n}\n// safe to issue API modification","typeGuard":"func apiCanModify(e *endpoint) bool { return e.IsInit() || !e.labels.OrchestrationIdentity.IsReserved() }","tryCatchPattern":"if err := APICanModify(e); err != nil {\n    if strings.Contains(err.Error(), \"reserved labels\") {\n        log.Printf(\"endpoint %s is reserved (host/init/health); manage via Cilium itself, skipping\", e.ID)\n        return nil\n    }\n    return err\n}","preventionTips":["Exclude endpoints with reserved:* labels from automation that modifies endpoints via the Cilium API.","Check `cilium endpoint list` for reserved endpoints before issuing modify calls.","Configure host networking behavior via host firewall/policy settings rather than endpoint APIs.","Treat this error as a guardrail: reserved endpoints are intentionally agent-managed."],"tags":["api","policy","reserved-labels","cilium"],"backgroundTag":"reserved-endpoint-modification-denied","analyzedSha":"ac7b90affa4baf0642e6685319d56907b3a73a6d","analyzedAt":"2026-08-31T18:27:15.868Z","schemaVersion":2},"datasetVersion":"2026-08-31T19:17:28.585Z"}