Implement and review Kibana feature privilege deprecations. Use when deprecating features, renaming features, splitting features, consolidating features, moving privilege capabilities, reviewing deprecation PRs, or working with the replacedBy mapping system.
Implement and review Kibana feature privilege deprecations. Use when deprecating features, renaming features, splitting features, consolidating features, moving privilege capabilities, reviewing deprecation PRs, or working with the replacedBy mapping system.
Kibana Privilege Deprecation
Guides implementing and reviewing backward-compatible Kibana feature privilege deprecations using the deprecated privilege mapping framework.
When to Use
Renaming a feature (e.g. alpha -> beta)
Splitting a feature into multiple features
Consolidating multiple features into one
Moving capabilities between feature/sub-feature privileges
Reviewing PRs that deprecate features or change privilege mappings
Key Concepts
Deprecated feature: A feature marked with deprecated property that is frozen for backward compatibility. Not shown in role management UI; privileges still registered in Elasticsearch.
replacedBy mapping: Links each deprecated privilege to equivalent non-deprecated privilege(s). Required on every privilege of a deprecated feature.
Lazy migration: Roles are not auto-migrated. Deprecated privileges are replaced with current ones when an admin saves via UI.
kibana_system cannot alter roles - this is a security constraint driving the entire design.
Implementation Steps
Step 1: Create new replacement feature(s)
Register new feature(s) with desired privileges using deps.features.registerKibanaFeature().
Step 2: Mark existing feature as deprecated
Add deprecated property with a user-facing notice string. Feature ID must stay unchanged.
deps.features.registerKibanaFeature({
deprecated: {
notice: i18n.translate('xpack.yourPlugin.featureDeprecationNotice', {
defaultMessage: 'Feature X is deprecated. Use Feature Y instead. See {link}.',
values: { link: 'https://...' },
}),
// Optional: override which features conceptually replace this one (for Spaces UI).// By default derived from privilege-level replacedBy. Only needed when replacedBy// references multiple features but you want the Spaces UI to show a subset.replacedBy: ['feature_y'],
},
id: 'feature_x', // Must stay the samename: 'Feature X (DEPRECATED)',
privileges: { /* keep original privileges unchanged, add replacedBy */ },
});
Step 3: Define replacedBy on every privilege
Every all, read, and sub-feature privilege must have replacedBy.
Simple form -- use when the deprecated feature has NO sub-features:
Extended { default, minimal } form -- use when the deprecated feature HAS sub-features:
When a deprecated feature has sub-features, the top-level all privilege implicitly includes all sub-feature privileges granted via includeIn: 'all', while minimal_all does not. These two paths must map differently to preserve the distinction. The same applies to read / minimal_read.
Rule of thumb: If the deprecated feature defines subFeatures, always use the { default, minimal } form on its top-level privileges. The simple array form is only correct when there are no sub-features (it applies the same mapping to both default and minimal).
Step 4: Update code to use new features
API privileges: Replacement privileges must provide all API privileges from deprecated privileges. Routes use security.authz.requiredPrivileges for authorization. Ensure deprecated feature's api array is updated so that both deprecated and replacement privilege holders can access the same endpoints.
UI capabilities: Update client code to check capabilities.new_feature.capability instead of capabilities.old_feature.capability. The framework auto-maps deprecated capabilities to replacement ones.
Alerting consumers: New features must register deprecated feature ID as additional consumer so rules created under old feature remain accessible.
Cases owners: Follow same pattern as alerting for case ownership continuity.
Validation Rules (Enforced at Startup)
Kibana will refuse to start if any of these are violated:
Deprecated features must define replacedBy on every privilege
Non-deprecated features must not define replacedBy
Referenced replacement features must exist and not be deprecated
Referenced replacement privileges must exist
Enabled privileges cannot be replaced with disabled ones
feature.deprecated.replacedBy feature IDs (if set) must be a subset of features used in privilege-level replacedBy
PR Review Checklist
When reviewing deprecation PRs, focus on what startup validation does NOT catch:
Deprecated feature ID is unchanged from original
deprecated.notice is localized (i18n.translate) with a link to docs or PR
If deprecated feature has sub-features: top-level replacedBy uses { default, minimal } form, not simple array
Replacement privileges cover all SO types, api entries, ui capabilities, app, catalogue, and management from the deprecated ones
If replacement grants MORE access than deprecated, it is intentional and justified
New features register deprecated feature ID as additional alerting consumer and cases owner
Routes use security.authz.requiredPrivileges; deprecated feature's api array matches replacement's
Client code uses new feature ID for capability checks (e.g. capabilities.new_feature.ui_all)
