Upgrade notes
editUpgrade notes
editBefore you upgrade, review the breaking changes and deprecations introduced since the version you are migrating from, then mitigate the impact.
If you are migrating from a version prior to version 9.0, you must first upgrade to the last 8.x version available.
For Elastic Security solution release information, refer to Elastic Security Solution Release Notes.
Breaking changes
editRemoved legacy security rules bulk endpoints (9.0.0)
Details
-
POST /api/detection_engine/rules/_bulk_create
has been replaced byPOST /api/detection_engine/rules/_import
-
PUT /api/detection_engine/rules/_bulk_update
has been replaced byPOST /api/detection_engine/rules/_bulk_action
-
PATCH /api/detection_engine/rules/_bulk_update has been replaced by `POST /api/detection_engine/rules/_bulk_action
-
DELETE /api/detection_engine/rules/_bulk_delete
has been replaced byPOST /api/detection_engine/rules/_bulk_action
-
POST api/detection_engine/rules/_bulk_delete
has been replaced byPOST /api/detection_engine/rules/_bulk_action
These changes were introduced in #197422.
Impact
Deprecated endpoints will fail with a 404 status code starting from version 9.0.0
Action
Update your implementations to use the new endpoints:
-
For bulk creation of rules:
-
Use
POST /api/detection_engine/rules/_import
(API documentation) to create multiple rules along with their associated entities (for example, exceptions and action connectors). -
Alternatively, create rules individually using
POST /api/detection_engine/rules
(API documentation).
-
Use
-
For bulk updates of rules:
-
Use
POST /api/detection_engine/rules/_bulk_action
(API documentation) to update fields in multiple rules simultaneously. -
Alternatively, update rules individually using
PUT /api/detection_engine/rules
(API documentation).
-
Use
-
For bulk deletion of rules:
-
Use
POST /api/detection_engine/rules/_bulk_action
(API documentation) to delete multiple rules by IDs or query. -
Alternatively, delete rules individually using
DELETE /api/detection_engine/rules
(API documentation).
-
Use
Remove deprecated endpoint management endpoints (9.0.0)
Details
-
POST /api/endpoint/isolate
has been replaced byPOST /api/endpoint/action/isolate
-
POST /api/endpoint/unisolate
has been replaced byPOST /api/endpoint/action/unisolate
-
GET /api/endpoint/policy/summaries
has been deprecated without replacement. Will be removed in v9.0.0 -
POST /api/endpoint/suggestions/{suggestion_type}
has been deprecated without replacement. Will be removed in v9.0.0 -
GET /api/endpoint/action_log/{agent_id}
has been deprecated without replacement. Will be removed in v9.0.0 -
GET /api/endpoint/metadata/transforms
has been deprecated without replacement. Will be removed in v9.0.0
Impact
Deprecated endpoints will fail with a 404 status code starting from version 9.0.0
Action
-
Remove references to
GET /api/endpoint/policy/summaries
endpoint. -
Remove references to
POST /api/endpoint/suggestions/{suggestion_type}
endpoint. -
Remove references to
GET /api/endpoint/action_log/{agent_id}
endpoint. -
Remove references to
GET /api/endpoint/metadata/transforms
endpoint. - Replace references to deprecated endpoints with the replacements listed in the breaking change details.
Removed legacy alerting endpoints (9.0.0)
Details
-
POST /api/alerts/alert/{id?}
has been replaced byPOST /api/alerting/rule/{id?}
-
GET /api/alerts/alert/{id}
has been replaced byGET /api/alerting/rule/{id}
-
PUT /api/alerts/alert/{id}
has been replaced byPUT /api/alerting/rule/rule/{id}
-
DELETE: /api/alerts/alert/{id}
has been replaced byDELETE /api/alerting/rule/{id}
-
POST /api/alerts/alert/{id}/_disable
has been replaced byPOST /api/alerting/rule/{id}/_disable
-
POST /api/alerts/alert/{id}/_enable
has been replaced byPOST /api/alerting/rule/{id}/_enable
-
GET /api/alerts/_find
has been replaced byGET /api/alerting/rules/_find
-
GET /api/alerts/_health
has been replaced byGET /api/alerting/rule/_health
-
GET /api/alerts/list_alert_types
has been replaced byGET /api/alerting/rule_types
-
POST /api/alerts/alert/{alert_id}/alert_instance/{alert_instance_id}/_mute
has been replaced byPOST /api/alerting/rule/{rule_id}/alert/{alert_id}/_mute
-
POST /api/alerts/alert/{alert_id}/alert_instance/{alert_instance_id}/_unmute
has been replaced byPOST /api/alerting/rule/{rule_id}/alert/{alert_id}/_unmute
-
POST /api/alerts/alert/{id}/_mute_all
has been replaced byPOST /api/alerting/rule/{id}/_mute_all
-
POST /api/alerts/alert/{id}/_unmute_all
has been replaced byPOST /api/alerting/rule/{id}/_unmute_all
-
POST /api/alerts/alert/{id}/_update_api_key
has been replaced byPOST /api/alerting/rule/{id}/_update_api_key
-
GET /api/alerts/{id}/_instance_summary
has been deprecated without replacement. Will be removed in v9.0.0 -
GET /api/alerts/{id}/state
has been deprecated without replacement. Will be removed in v9.0.0
Impact
Deprecated endpoints will fail with a 404 status code starting from version 9.0.0
Action
Remove references to GET /api/alerts/{id}/_instance_summary
endpoint.
Remove references to GET /api/alerts/{id}/state
endpoint.
Replace references to endpoints listed as deprecated by it’s replacement. See Details
section.
The updated APIs can be found here https://www.elastic.co/docs/api/doc/kibana/v8/group/endpoint-alerting
Removed legacy cases endpoints (9.0.0)
Details
-
GET /api/cases/status
has been deprecated with no replacement. Deleted in v9.0.0 -
GET /api/cases/{case_id}/comments
has been replaced byGET /api/cases/{case_id}/comments/_find
released in v7.13 -
GET /api/cases/<case_id>/user_actions
has been replaced byGET /api/cases/<case_id>/user_actions/_find
released in v8.7 -
includeComments
parameter inGET /api/cases/{case_id}
has been deprecated. UseGET /api/cases/{case_id}/comments/_find
instead, released in v7.13
Impact
Deprecated endpoints will fail with a 404 status code starting from version 9.0.0
Action
Remove references to GET /api/cases/status
endpoint.
Replace references to deprecated endpoints with the replacements listed in the breaking change details.
Removed all security v1 endpoints (9.0.0)
Details
All v1
Kibana security HTTP endpoints have been removed.
GET /api/security/v1/logout
has been replaced by GET /api/security/logout
GET /api/security/v1/oidc/implicit
has been replaced by GET /api/security/oidc/implicit
GET /api/security/v1/oidc
has been replaced by GET /api/security/oidc/callback
POST /api/security/v1/oidc
has been replaced by POST /api/security/oidc/initiate_login
POST /api/security/v1/saml
has been replaced by POST /api/security/saml/callback
GET /api/security/v1/me
has been removed with no replacement.
For more information, refer to #199656.
Impact
Any HTTP API calls to the v1
Kibana security endpoints will fail with a 404 status code starting from version 9.0.0.
Third party OIDC and SAML identity providers configured with v1
endpoints will no longer work.
Action
Update any OIDC and SAML identity providers to reference the corresponding replacement endpoint listed above.
Remove references to the /api/security/v1/me
endpoint from any automations, applications, tooling, and scripts.
Access to all internal APIs is blocked (9.0.0)
Details
Access to internal Kibana HTTP APIs is restricted from version 9.0.0. This is to ensure
that HTTP API integrations with Kibana avoid unexpected breaking changes.
Refer to #193792.
Impact
Any HTTP API calls to internal Kibana endpoints will fail with a 400 status code starting
from version 9.0.0.
Action
Do not integrate with internal HTTP APIs. They may change or be removed without notice,
and lead to unexpected behaviors. If you would like some capability to be exposed over an
HTTP API, create an issue.
We would love to discuss your use case.
Remove original user and host risk scoring and all associated UIs (9.0.0)
Details
The original host and risk score modules have been superseded since v8.10.0 by the Risk Engine.
In 9.0.0 these modules are no longer supported, the scores no longer display in the UI and all UI controls associated with managing or upgrading the legacy modules have been removed.
Impact
As well as the legacy risk scores not being shown in the UI, alerts no longer have the legacy risk score added to them in the <host|user>.risk.calculated_level
and <host|user>.risk.calculated_score_norm
fields.
The legacy risk scores are stored in the ml_host_risk_score_<space_id>
and ml_user_risk_score_<space_id>
indices, these indices will not be deleted if the user chooses not to upgrade.
Legacy risk scores are generated by the following transforms:
-
ml_hostriskscore_pivot_transform_<space_id>
-
ml_hostriskscore_latest_transform_<space_id>
-
ml_userriskscore_pivot_transform_<space_id>
-
ml_userriskscore_latest_transform_<space_id>
If a user does not upgrade to use the Risk Engine, these transforms will continue to run in 9.0.0, but it will be up to the user to manage them.
Action
Upgrade to use the Risk Engine in all spaces which use the legacy risk scoring modules:
- In the main menu, go to Security > Manage > Entity Risk Score.
- If the original user and host risk score modules are enabled, you’ll see a button to "Start update". Click the button, and follow the instructions.
Reporting uses Kibana feature privileges only to control access to reporting features
Details
In 8.x, the default access control model was based on a built-in role called reporting_user
, which granted access to reporting features. Since 7.13, the preferred model for controlling access to reporting features has been Kibana feature privileges, enabled by setting xpack.reporting.roles.enabled: false
in kibana.yml
.
In 9.0.0, the xpack.reporting.roles.*
settings will be ignored.
Impact
The built-in reporting_user
role is no longer deprecated and provides access to reporting features using Kibana feature privileges. This means that users that do not have privileges to use reporting will not see reporting features in the Kibana UI.
Action
Use Kibana feature privileges to control access to reporting features. For more information, see #200834.
-
The
reporting_user
role is still supported, but gives full access to all reporting features. We recommend creating custom roles with minimal privileges in Stack Management > Roles. -
The
xpack.reporting.roles.allow
setting is no longer supported. If you have axpack.reporting.roles.allow
value in yourkibana.yml
, you should remove this setting and assign privileges to reporting features using Kibana feature privileges.
Saved query privileges have been reworked (9.0.0)
Details
Saved query privileges have been reworked to rely solely on a single global savedQueryManagement
privilege, and eliminate app-specific overrides (e.g. implicit access with all
privilege for Discover, Dashboard, Maps, and Visualize apps). This change simplifies the security model and ensures consistency in the saved query management UI across Kibana, but results in different handling of saved query privileges for new user roles, and minor breaking changes to the existing management UX.
For more information, refer to #202863.
Impact
The savedQueryManagement
feature privilege now globally controls access to saved query management for all new user roles. Regardless of privileges for Discover, Dashboard, Maps, or Visualize, new user roles follow this behaviour:
. If savedQueryManagement
is none
, the user cannot see or access the saved query management UI or APIs.
. If savedQueryManagement
is read
, the user can load queries from the UI and access read APIs, but cannot save queries from the UI or make changes to queries through APIs.
. If savedQueryManagement
is all
, the user can both load and save queries from the UI and through APIs.
Action
Existing user roles that were previously implicitly granted access to saved queries through the dashboard, discover, visualize, or maps feature privileges will retain that access to prevent breaking changes. While no action is required for existing roles, it’s still advisable to audit relevant roles and re-save them to migrate to the latest privileges model. For new roles, ensure that the savedQueryManagement privilege is set as needed.
Deprecation notices
editThe following functionality is deprecated and will be removed at a future date. Deprecated functionality does not have an immediate impact on your application, but we strongly recommend you make the necessary updates to avoid use of deprecated features.
Use the Kibana Upgrade Assistant to prepare for your upgrade to the next version of the Elastic Stack. The assistant identifies deprecated settings in your configuration and guides you through the process of resolving issues if any deprecated features are enabled. To access the assistant, go to Stack Management > Upgrade Assistant.
Scripted field creation has been disabled in the Data Views management page (9.0.0)
Details
The ability to create new scripted fields has been removed from the Data Views management page in 9.0. Existing scripted fields can still be edited or deleted, and the creation UI can be accessed by navigating directly to /app/management/kibana/dataViews/dataView/{dataViewId}/create-field
, but we recommend migrating to runtime fields or ES|QL queries instead to prepare for removal.
For more information, refer to #202250.
Impact
It will no longer be possible to create new scripted fields directly from the Data Views management page.
Action
Migrate to runtime fields or ES|QL instead of creating new scripted fields. Existing scripted fields can still be edited or deleted.
Now HTTP/2 is the default protocol when TLS is enabled and a deprecation warning appears if HTTP/2 is not enabled or TLS is not configured (9.0.0)
Details
Starting from version 9.0.0, HTTP/2 is the default protocol when TLS is enabled. This ensures improved performance and security. However, if HTTP/2 is not enabled or TLS is not configured, a deprecation warning will be added.
For more information, refer to #204384.
Impact
Systems that have TLS enabled but don’t specify a protocol will start using HTTP/2 in 9.0.0.
Systems that use HTTP/1 or don’t have TLS configured will get a deprecation warning.
Action
Verify that TLS is properly configured by enabling it and providing valid certificates in the settings. Test your system to ensure that connections are established securely over HTTP/2.
If your Kibana server is hosted behind a load balancer or reverse proxy we recommend testing your deployment configuration before upgrading to 9.0.
Search sessions disabled by default (9.0.0)
Details
Starting from version 9.0.0, search sessions are disabled by default. To view, manage, and restore search sessions, the feature needs to be explicitly re-enabled.
Impact
Search sessions will be disabled unless they are explicitly enabled in config.yml.
Action
If you would like to continue using, managing, and restoring search sessions in 9.0, you’ll need to re-enable the feature in your kibana.yml configuration file. If not, no action is necessary.
To re-enable search sessions, add the following in your config.yml:
data.search.sessions.enabled: true