[[breaking-changes-7.0]]
== Breaking changes in 7.0
++++
<titleabbrev>7.0</titleabbrev>
++++

This section discusses the changes that you need to be aware of when migrating
your application to Kibana 7.0.

See also <<whats-new>> and <<release-notes>>.

* <<breaking_70_api_changes>>
* <<breaking_70_browser_support_changes>>
* <<breaking_70_ems_changes>>
* <<breaking_70_packaging_changes>>
* <<breaking_70_plugin_changes>>
* <<breaking_70_security_changes>>
* <<breaking_70_setting_changes>>
* <<breaking_70_advanced_settings_changes>>
* <<breaking_70_UI_changes>>

////
The following section is re-used in the Installation and Upgrade Guide
[[breaking_70_notable]]
=== Notable breaking changes
////
// tag::notable-breaking-changes[]

// end::notable-breaking-changes[]

[float]
[[breaking_70_api_changes]]
=== API changes

[float]
==== Deprecated API `/shorten` has been removed
*Details:* The `/shorten` API has been deprecated since 6.5, when it was replaced by the `/api/shorten_url` API.

*Impact:* The '/shorten' API has been removed. Use the '/api/shorten_url' API instead.

[float]
[[breaking-changes-7.0-saved-objects]]
==== Saved object structure change
*Details:* Saved objects no longer contain ids of other saved objects under `attributes`. They have been moved under `references` with a named reference in `attributes`.

Example structure before:
[source,js]
--------------------------------------------------
{
  ...
  "attributes": {
    ...
    "panelsJSON": [{
      ...
      "type": "visualization",
      "id": "dbf71bb0-ffad-11e8-acfd-d359b3d9069"
    }]
  }
}
--------------------------------------------------


Example structure after:
[source,js]
--------------------------------------------------
{
  ...
  "attributes": {
    ...
    "panelsJSON": [{
      ...
      "panelRefName": "panel_0"
    }]
  },
  "references": [{
    "name": "panel_0",
    "type": "visualization",
    "id": "dbf71bb0-ffad-11e8-acfd-d359b3d9069"
  }]
}
--------------------------------------------------


*Impact:* Users who query directly for ids will have to use the new `hasReference` in the find API. Users who save ids within attributes will have to move them into the `references` attribute and have a named reference to it.

[float]
[[breaking_70_browser_support_changes]]
=== Browser support changes

[float]
==== Removed support for using PhantomJS browser for screenshots in Reporting
*Details:* Since the first release of Kibana Reporting, PhantomJS was used as
the headless browser to capture screenshots of Kibana dashboards and
visualizations. In that short time, Chromium has started offering a new
headless browser library and the PhantomJS maintainers abandoned their project.
We started planning for a transition in 6.5.0, when we made Chromium the
default option, but allowed users to continue using Phantom with the
`xpack.reporting.capture.browser.type: phantom` setting. In 7.0, that setting
will still exist for compatibility, but the only valid option will be
`chromium`.

*Impact:* Before upgrading to 7.0, if you have `xpack.reporting.capture.browser.type`
set in kibana.yml, make sure it is set to `chromium`.

[NOTE]
============
Reporting 7.0 uses a version of the Chromium headless browser that RHEL 6,
CentOS 6.x, and other old versions of Linux derived from RHEL 6. This change
effectively removes RHEL 6 OS server support from Kibana Reporting. Users with
RHEL 6 must upgrade to RHEL 7 to use Kibana Reporting starting with version
7.0.0 of the Elastic stack.
============


[float]
==== Legacy browsers (namely IE11) will see a security warning message whenever they load Kibana
*Details:* Kibana now has a Content Security Policy, but it's only effective if browsers enforce it, and since older
browsers like Internet Explorer 11 do not support CSP, we show them a warning message whenever they load Kibana.

*Impact:* Nothing needs to be done necessarily, but if you don't need to support legacy browsers like IE11, we recommend
that you set `csp.strict: true` in your kibana.yml to block access to those browsers entirely. If your organization requires
users to use IE11, you might like to disable the warning entirely with `csp.warnLegacyBrowsers: false` in your kibana.yml.


[float]
[[breaking_70_ems_changes]]
=== Elastic Maps Service changes

[float]
==== Removed overseas territories from France Departments vector layer

*Details:* Overseas territories in the France Departments vector layer have 
been removed. These territories have no ISO 3166-2 or INSEE codes to join to 
{es} data.

*Impact:* Region Map, Vega, and Maps plugin visualizations using the France 
Departments layer will not show overseas territories. 

[float]
==== USA Zip Codes vector layer updated with latest US Census data

*Details:* The USA Zip Codes layer has been updated based on the 
https://www.census.gov/geo/reference/zctas.html[2018 Zip Code Tabulation 
Areas (ZCTAs)] distributed by the US Census Bureau. ZCTA boundaries have been 
generalized from the source data for visualization and locations are approximate.

*Impact:* Region Map, Vega, and Maps plugin visualizations using the USA Zip 
Codes layer will appear differently. ZCTA boundaries have changed dramatically 
in some areas. Also, some zip codes have been deprecated and new ones have been added.

[float]
[[breaking_70_packaging_changes]]
=== Packaging changes

[float]
==== Removed support for running Kibana with a global Node.js installation
*Details:* Previous versions of Kibana would fallback to using a global installation of Node.js if the distribution included with Kibana was not found.
Kibana 7.0 will only use the Node.js distribution included in the package.

*Impact:* There is no expected impact unless Kibana is installed in a non-standard way.

[float]
[[breaking_70_plugin_changes]]
=== Plugin changes

[float]
==== Optimization step deferred until server start
*Details:* Prior versions of Kibana would run the optimization step after each plugin installation.  This is now run on server start when necessary.

*Impact:* Users can trigger a standalone optimization after all plugins have been installed with `bin/kibana --optimize` or let the server manage it on startup.

[float]
[[breaking_70_security_changes]]
=== Security changes

[float]
==== Removed support for users relying on direct index privileges to the Kibana index in Elasticsearch
*Details:* With the introduction of Kibana RBAC in 6.4, users no longer require privileges to the Kibana index in Elasticsearch. Instead, users
should be granted <<kibana-privileges>>. Prior to 7.0, when a user who relies upon direct index privileges logged into Kibana, a deprecation warning was logged. 

*Impact:* You must change any roles that grant access to Kibana using index privileges to use <<kibana-privileges>> instead. 
Watcher jobs using the Reporting attachment type must also be updated.

If you use a custom `kibana.index` for multitenancy, you can 
no longer use `kibana_user` or `kibana_dashboard_only_user` to provide access, 
and will have to start using {kib} privileges.

In addition, roles cannot be shared across Kibana tenants when granting access to Kibana privileges.
For example, a tenant using `kibana.index: .kibana` will have its own set 
of roles created to grant access to Kibana. If you create another tenant 
at `kibana.index: .some-other-index`, it will need its own set of roles 
to grant access to that tenant.

[float]
[[breaking_70_setting_changes]]
=== Settings changes

[float]
==== Removed support for tribe nodes
*Details:* Elasticsearch 7.0 removes the tribe node feature, so Kibana removes it as well.

*Impact:* You must remove any tribe node configurations in Kibana. Consider using <<management-cross-cluster-search>> instead, which does not require kibana.yml configurations in Kibana.


[float]
==== `elasticsearch.ssl.ca` is no longer valid

*Details:* The deprecated `elasticsearch.ssl.ca` setting in the `kibana.yml` 
file has been removed.

*Impact:* Use `elasticsearch.ssl.certificateAuthorities` instead.

[float]
==== `elasticsearch.ssl.cert` is no longer valid

*Details:* The deprecated `elasticsearch.ssl.cert` setting in the `kibana.yml`
file has been removed.

*Impact:* Use `elasticsearch.ssl.certificate` instead.

[float]
==== `elasticsearch.ssl.verify` is no longer valid

*Details:* The deprecated `elasticsearch.ssl.verify` setting in the `kibana.yml`
file has been removed.

*Impact:* Use `elasticsearch.ssl.verificationMode` instead. If you set
`elasticsearch.ssl.verify` to `true`, that is equal to setting 
`elasticsearch.ssl.verificationMode` to `full`.

[float]
==== `elasticsearch.url` is no longer valid

*Details:* The deprecated `elasticsearch.url` setting in the `kibana.yml` file
has been removed. 

*Impact:* Use `elasticsearch.hosts` instead. In prior versions of Kibana, if no
port was specified in `elasticsearch.url`, a default of 9200 was chosen. The
port in `elasticsearch.hosts` is protocol dependent: https ports will use 443,
and http ports will use 80. If your `elasticsearch.url` setting was dependent on
an unspecified port set to 9200, append `:9200` to the url in the
`elasticsearch.hosts` setting.

[float]
==== `i18n.defaultLocale` is no longer valid

*Details:* The deprecated `i18n.defaultLocale` setting in the `kibana.yml` file
has been removed.

*Impact:* Use `i18n.locale` instead.

[float]
==== `index_management.<any setting>` is no longer valid

*Details:* The deprecated `index_management.*` settings in the `kibana.yml`
file have been removed.

*Impact:* Use `xpack.index_management.<any setting>` instead.

[float]
==== `license_management.<any setting>` is no longer valid

*Details:* The deprecated `license_management.*` settings in the `kibana.yml`
file have been removed.

*Impact:* Use `xpack.license_management.<any setting>` instead.

[float]
==== `logging.useUTC` is no longer valid

*Details:* The deprecated `logging.useUTC` setting in the `kibana.yml` file has
been removed. 

*Impact:* If `logging.useUTC` was set to `true` (its default value), the
timezone id was `UTC`. Use `logging.timezone` instead. Any timezone can now be
specified by canonical id. 

[float]
==== `regionmap` is no longer valid

*Details:* The deprecated `regionmap` setting in the `kibana.yml` file has been
removed.

*Impact:* Use `map.regionmap` instead.

[float]
==== `rollup.<any setting>` is no longer valid

*Details:* The deprecated `rollup.*` settings in the `kibana.yml` file have been
removed.

*Impact:* Use `xpack.rollup.<any setting>` instead.

[float]
==== `server.ssl.cert` is no longer valid

*Details:* The deprecated `server.ssl.cert` setting in the `kibana.yml` file has
been removed.

*Impact:* Use `server.ssl.certificate` instead

[float]
==== `server.ssl.enabled` must be set to `true` to enable SSL

*Details:* Previously, if the `server.ssl.certificate` and `server.ssl.key`
settins were specified in the `kibana.yml` file, SSL would be automatically
enabled. It's now required that you set `server.ssl.enabled` to `true` for this
to occur.

*Impact:* Users with both `server.ssl.certificate` and `server.ssl.key` set must
now also set `server.ssl.enabled` to enable SSL.

[float]
==== `server.ssl.supportedProtocols` excludes TLSv1 by default

*Details:* By default, TLSv1 support has been removed. It's still possible to
opt-in to TLSv1 support by explicitly setting `server.ssl.supportedProtocols` in
the `kibana.yml` file.

*Impact:* Users relying on TLSv1 will be unable to use Kibana unless
`server.ssl.supportedProtocols` is explicitly set.

[float]
==== `tilemap` is no longer valid

*Details:* The deprecated `tilemap` setting in the `kibana.yml` file has been
removed.

*Impact:* Use `map.tilemap` instead.

[float]
==== `upgrade_assistant.<any setting>` is no longer valid

*Details:* The deprecated `upgrade_assistant.*` settings in the `kibana.yml`
file have been removed.

*Impact:* Use `xpack.upgrade_assistant.<any setting>` instead.

[float]
==== `xpack.monitoring.beats.index_pattern` is no longer valid

*Details:* The unsupported `xpack.monitoring.beats.index_pattern` setting in the
`kibana.yml` file has been officially removed.

*Impact:* The ability to customize this pattern is no longer supported.

[float]
==== `xpack.monitoring.cluster_alerts.index` is no longer valid

*Details:* The unsupported `xpack.monitoring.cluster_alerts.index` setting in
the `kibana.yml` file has been officially removed. 

*Impact:* The ability to customize this index is no longer supported.

[float]
==== `xpack.monitoring.elasticsearch.index_pattern` is no longer valid

*Details:* The unsupported `xpack.monitoring.elasticsearch.index_pattern`
setting in the `kibana.yml` file has been officially removed.

*Impact:* The ability to customize this pattern is no longer supported.

[float]
==== `xpack.monitoring.elasticsearch.ssl.ca` is no longer valid

*Details:* The deprecated `xpack.monitoring.elasticsearch.ssl.ca` setting in the
`kibana.yml` file has been removed. 

*Impact:* Use `xpack.monitoring.elasticsearch.ssl.certificateAuthorities` instead.

[float]
==== `xpack.monitoring.elasticsearch.ssl.cert` is no longer valid

*Details:* The deprecated `xpack.monitoring.elasticsearch.ssl.cert` setting in
the `kibana.yml` file has been removed. 

*Impact:* Use `xpack.monitoring.elasticsearch.ssl.certificate` instead.

[float]
==== `xpack.monitoring.elasticsearch.ssl.verify` is no longer valid

*Details:* The deprecated `xpack.monitoring.elasticsearch.ssl.verify` setting in
the `kibana.yml` file has been removed. 

*Impact:* Use `xpack.monitoring.elasticsearch.ssl.verificationMode` instead. If
you previously set `xpack.monitoring.elasticsearch.ssl.verify` to `true`, it is
equal to setting `xpack.monitoring.elasticsearch.ssl.verificationMode` to `full`.

[float]
==== `xpack.monitoring.elasticsearch.url` is no longer valid

*Details:* The deprecated `xpack.monitoring.elasticsearch.url` setting in the
`kibana.yml` file has been removed. 

*Impact:* Use `xpack.monitoring.elasticsearch.hosts` instead. In prior versions
of Kibana, if no port was specified in `xpack.monitoring.elasticsearch.url` a
default of 9200 was chosen. The port in `xpack.monitoring.elasticsearch.hosts`
is protocol dependent: https ports will use 443, and http ports will use 80. If
`xpack.monitoring.elasticsearch.url` was dependent on an unspecified port set to
9200, append `:9200` to the url in `xpack.monitoring.elasticsearch.hosts`.

[float]
==== `xpack.monitoring.index_pattern` is no longer valid

*Details:* The unsupported `xpack.monitoring.index_pattern` setting in the
`kibana.yml` file has been officially removed.

*Impact:* The ability to customize this pattern is no longer supported.

[float]
==== `xpack.monitoring.kibana.index_pattern` is no longer valid

*Details:* The unsupported `xpack.monitoring.kibana.index_pattern` setting in
the `kibana.yml` file has been officially removed.

*Impact:* The ability to customize this pattern is no longer supported.

[float]
==== `xpack.monitoring.logstash.index_pattern` is no longer valid

*Details:* The unsupported `xpack.monitoring.logstash.index_pattern` setting in
the `kibana.yml` file has been officially removed.

*Impact:* The ability to customize this pattern is no longer supported.

[float]
==== `xpack.monitoring.node_resolver` is no longer valid

*Details:* The deprecated `xpack.monitoring.node_resolver` setting in the
`kibana.yml` file has been removed. This setting has been deprecated since 5.6,
when it was explicitly recommended to use `uuid` as its value.

*Impact:* This setting is no longer necessary. If you enable the {stack}
{monitor-features}, a monitoring agent runs on each Elasticsearch node, Logstash
node, Kibana instance, and Beat to collect and index metrics. Each node and
instance is considered unique based on its persistent UUID, which is written to
the `path.data` directory when the node or instance starts.

[float]
==== `xpack.monitoring.report_stats` is no longer valid

*Details:* The deprecated `xpack.monitoring.report_stats` setting in the
`kibana.yml` file has been removed. 

*Impact:* Use `xpack.xpack_main.telemetry.enabled` instead.

[float]
==== `management/kibana/(index|indices)` => `management/kibana/index_pattern(?s)`

*Details:* Kibana management URLs pertaining to index patterns have been changed
to accurately reflect their content, from `management/kibana/index` or
`management/kibana/indices` to `managemen/kibana/index_pattern` or
`management/kibana/index_patterns`. 

*Impact:* References to these URLs will need to be updated.

[float]
[[breaking_70_advanced_settings_changes]]
=== Advanced settings changes


[float]
==== Advanced setting query:queryString:options no longer applies to filters
*Details:* In previous versions of Kibana the Advanced Setting `query:queryString:options` was applied to both queries
and custom filters using the `query_string` query. This could cause errors if a custom filter used options that
conflicted with the Advanced Setting. In 7.0 `query:queryString:options` will no longer be applied to filters so that
users can have full control over their custom filters.

*Impact:* You must ensure that any saved searches with a `query_string` filter aren't relying implicitly on
`query:queryString:options`.

[float]
==== Advanced setting query:queryString:options no longer applies `default_field: *` by default.
*Details:* Elasticsearch removed the ability to create indices with an _all field in 6.0. As a result, a user could end
up with a mix of indices with and without _all fields if they upgraded from an older version of ES. This could lead to
inconsistent highlighting in Discover. To work around this issue we added `default_field: *` to query:queryString:options
to force consistent querying across indices with and without _all. In 7.0 the _all field will be gone from all indices
so we no longer need this workaround.

*Impact:* Since we'll no longer send the `default_field` parameter in Kibana's query_string query, Elasticsearch
will use the index setting instead. The default for the index setting is also `*`, so most users should not be impacted.
If some of your indices have a non-default `default_field` setting, you may want to update it or re-add the parameter
to Kibana's advanced setting.

[float]
[[breaking_70_UI_changes]]
=== UI changes

[float]
==== Dark mode is now global
*Details:* Both the Dashboard and Maps applications offer "Dark Mode" options which have been removed in favor of a global dark mode advanced setting. This means that instead of having to turn on dark mode in many places, users can choose to turn on the `theme:darkMode` advanced setting and it will apply to all applications.

*Impact:* The dark mode setting for Dashboards and Maps will be ignored and the global setting will be used instead.


[float]
==== KQL is now the default query language in the global search bar
*Details:* Language enhancements that were introduced in 6.3 on an opt-in basis are now turned on by default. This
is considered a breaking change because the enhancements include a simplifed syntax that has some small incompatibilities
with the old Lucene syntax. 

*Impact:* Users simply need to familiarize themselves with the new syntax. Existing saved searches, visualizations, and dashboards
that use the old Lucene syntax will continue to work, but users should consider migrating them to KQL to enjoy the other benefits
that come along with it. For the time being, individual users can still opt-out of KQL under the options menu in the query bar
and admins can still change the global default using the `search:queryLanguage` advanced setting.




[float]
==== Removed support for deeply nested table splits in data table visualizations
*Details:* Previously a user was able to create multiple "split table" aggregations in one table on arbitrary levels.
The potential for deeply nested tables posed maintenance and accessibility challenges, and was inconsistent with other
visualizations that only allow one table split. This change does not limit the number of split rows a user can put into
a table; it only restricts the number of split tables to one.

*Impact:* To prevent breaking existing visualizations, saved objects containing nested table splits will be automatically
migrated to contain only one split table, converting any existing split tables beyond the first to split rows. No action
should be required as a result of this change, but be aware that users with saved data table visualizations that contain
multiple split tables will now see those tables rendered differently.

[float]
==== Imported Kibana dashboards might require small grid layout adjustments due to design changes
*Details:* Kibana 7.0 introduces a new default font for the application and also comes with several design changes in dashboards that slightly change padding and margin for dashboard panels. You may find you need to adjust grid layouts to compensate.

*Impact:* Minimal. In most cases, the dashboards should render as they did previously. In some cases, panels might overflow and require scroll bars where they did not previously. Simply adjust the panel sizes and edit your dashboard layouts if these bother you.

[float]
==== Timelion no longer appears in the side navigation
*Details:* Timelion sheets will continue to work in *Visualize*, but the 
Timelion application no longer appears by default in the {kib} side navigation. 

*Impact:* To create a Timelion visualization, go to *Visualize* and select 
*Timelion* from the visualization types. If you have a lot of existing Timelion 
visualizations and want to add Timelion back in the side
navigation, set `timelion.ui.enabled` to `true` in `kibana.yml`.



