migrate_8_0.asciidoc

Breaking changes in 8.0

8.0

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

See also [whats-new] and [release-notes].

• Index pattern changes

• Settings changes

Index pattern changes

Removed support for time-based internal index patterns

Details: Time-based interval index patterns were deprecated in 5.x. In 6.x, you could no longer create time-based interval index patterns, but they continued to function as expected. Support for these index patterns has been removed in 8.0.

Impact: You must migrate your time_based index patterns to a wildcard pattern, for example, logstash-*.

Settings changes

Multitenancy by changing kibana.index is no longer supported

Details: kibana.index, xpack.reporting.index and xpack.task_manager.index can no longer be specified.

Impact: Users who relied on changing these settings to achieve multitenancy should use Spaces, cross-cluster replication, or cross-cluster search instead. To migrate to Spaces, users are encouraged to use saved object management to export their saved objects from a tenant into the default tenant in a space. Improvements are planned to improve on this workflow. See #82020 for more details.

Disabling most plugins with the {plugin_name}.enabled setting is no longer supported

Details: The ability for most plugins to be disabled using the {plugin_name}.enabled config option has been removed.

Impact: Some plugins, such as telemetry, newsfeed, reporting, and the various vis_type plugins will continue to support this setting, however the rest of the plugins that ship with Kibana will not. By default, any newly created plugins will not support this configuration unless it is explicitly added to the plugin’s configSchema.

If you are currently using one of these settings in your Kibana config, please remove it before upgrading to 8.0. If you were using these settings to control user access to certain Kibana applications, we recommend leveraging Feature Controls instead.

Legacy browsers are now rejected by default

Details: csp.strict is now enabled by default, so Kibana will fail to load for older, legacy browsers that do not enforce basic Content Security Policy protections - notably Internet Explorer 11.

Impact: To allow Kibana to function for these legacy browsers, set csp.strict: false. Since this is about enforcing a security protocol, we strongly discourage disabling csp.strict unless it is critical that you support Internet Explorer 11.

Configuring content security policy rules is no longer supported

Details: Configuring csp.rules is removed in favor of per-directive specific configuration. Configuring the default csp.script_src, csp.workers_src and csp.style_src values is not required.

Impact: Configure per-directive sources instead. See #102059 for more details.

Default logging timezone is now the system’s timezone

Details: In prior releases the timezone used in logs defaulted to UTC. We now use the host machine’s timezone by default.

Impact: To restore the previous behavior, in kibana.yml use the pattern layout, with a {kibana-ref}/logging-configuration.html#date-format[date modifier]:

logging:
  appenders:
    custom:
      type: console
      layout:
        type: pattern
        pattern: "%date{ISO8601_TZ}{UTC}"

See #90368 for more details.

Responses are never logged by default

Details: Previously responses would be logged if either logging.json was true, logging.dest was specified, or a TTY was detected. With the new logging configuration, these are provided by a dedicated logger.

Impact: To restore the previous behavior, in kibana.yml enable debug for the http.server.response logger:

logging:
  appenders:
    custom:
      type: console
      layout:
        type: pattern
  loggers:
    - name: http.server.response
      appenders: [custom]
      level: debug

See #87939 for more details.

Logging destination is specified by the appender

Details: Previously log destination would be stdout and could be changed to file using logging.dest. With the new logging configuration, you can specify the destination using {kibana-ref}/logging-configuration.html#logging-appenders[appenders].

Impact: To restore the previous behavior and log records to stdout, in kibana.yml use an appender with type: console.

logging:
  appenders:
    custom:
      type: console
      layout:
        type: pattern
  root:
    appenders: [default, custom]

To send logs to file with a given file path, you should define a custom appender with type:file:

logging:
  appenders:
    file:
      type: file
      fileName: /var/log/kibana.log
      layout:
        type: pattern
  root:
    appenders: [default, file]

Set log verbosity with root

Details: Previously logging output would be specified by logging.silent (none), logging.quiet (error messages only) and logging.verbose (all). With the new logging configuration, set the minimum required {kibana-ref}/logging-configuration.html#log-level[log level].

Impact: To restore the previous behavior, in kibana.yml specify logging.root.level:

# suppress all logs
logging:
  root:
    level: off

# only log error messages
logging:
  root:
    level: error

# log all events
logging:
  root:
    level: all

Declare log message format

Details: Previously all events would be logged in json format when logging.json was true. With the new logging configuration you can specify the output format with layouts. You can choose between json and pattern format depending on your needs.

Impact: To restore the previous behavior, in kibana.yml configure the logging format for each custom appender with the appender.layout property. There is no default for custom appenders and each one must be configured expilictly.

logging:
  appenders:
    custom_console:
      type: console
      layout:
        type: pattern
    custom_json:
      type: console
      layout:
        type: json
  loggers:
    - name: plugins.myPlugin
      appenders: [custom_console]
  root:
    appenders: [default, custom_json]
    level: warn

Configure log rotation with the rolling-file appender

Details: Previously log rotation would be enabled when logging.rotate.enabled was true.

Impact: To restore the previous behavior, in kibana.yml use the {kibana-ref}/logging-configuration.html#rolling-file-appender[rolling-file] appender.

logging:
  appenders:
    rolling-file:
      type: rolling-file
      fileName: /var/logs/kibana.log
      policy:
        type: size-limit
        size: 50mb
      strategy:
        type: numeric
        pattern: '-%i'
        max: 2
      layout:
        type: pattern
  loggers:
    - name: plugins.myPlugin
      appenders: [rolling-file]

xpack.security.authProviders is no longer valid

Details: The deprecated xpack.security.authProviders setting in the kibana.yml file has been removed.

Impact: Use xpack.security.authc.providers instead.

xpack.security.authc.providers has changed value format

Details: xpack.security.authc.providers setting in the kibana.yml has changed value format.

Impact: Array of provider types as a value is no longer supported, use extended object format instead.

xpack.security.authc.saml is no longer valid

Details: The deprecated xpack.security.authc.saml setting in the kibana.yml file has been removed.

Impact: Configure SAML authentication providers using xpack.security.authc.providers.saml.{provider unique name}.* settings instead.

xpack.security.authc.oidc is no longer valid

Details: The deprecated xpack.security.authc.oidc setting in the kibana.yml file has been removed.

Impact: Configure OpenID Connect authentication providers using xpack.security.authc.providers.oidc.{provider unique name}.* settings instead.

xpack.security.public is no longer valid

Details: Previously Kibana was choosing the appropriate Elasticsearch SAML realm automatically using the Assertion Consumer Service URL that it derived from the actual server address and xpack.security.public setting. Starting in 8.0.0, the deprecated xpack.security.public setting in the kibana.yml file has been removed and the Elasticsearch SAML realm name that Kibana will use should be specified explicitly.

Impact: Define xpack.security.authc.providers.saml.{provider unique name}.realm when using the SAML authentication providers instead.

/api/security/v1/saml endpoint is no longer supported

Details: The deprecated /api/security/v1/saml endpoint is no longer supported.

Impact: Rely on /api/security/saml/callback endpoint when using SAML instead. This change should be reflected in Elasticsearch and Identity Provider SAML settings.

/api/security/v1/oidc endpoint is no longer supported

Details: The deprecated /api/security/v1/oidc endpoint is no longer supported.

Impact: Rely on /api/security/oidc/callback endpoint when using OpenID Connect instead. This change should be reflected in Elasticsearch and OpenID Connect Provider settings.

/api/security/v1/oidc endpoint is no longer supported for Third Party initiated login

Details: The deprecated /api/security/v1/oidc endpoint is no longer supported for Third Party initiated login.

Impact: Rely on /api/security/oidc/initiate_login endpoint when using Third Party initiated OpenID Connect login instead. This change should be reflected in Elasticsearch and OpenID Connect Provider settings.

/api/security/v1/oidc/implicit endpoint is no longer supported

Details: The deprecated /api/security/v1/oidc/implicit endpoint is no longer supported.

Impact: Rely on /api/security/oidc/implicit endpoint when using OpenID Connect Implicit Flow instead. This change should be reflected in OpenID Connect Provider settings.

optimize directory is now in the data folder

Details: Generated bundles have moved to the configured path.data folder.

Impact: Any workflow that involved manually clearing generated bundles will have to be updated with the new path.

Legacy optimize.* settings are no longer supported

Details: The legacy optimizer has been removed and any optimize.* settings have been deprecated since 7.10. These settings have been removed as they are no longer in use.

Impact: Any of the legacy optimize.* settings will prevent Kibana from starting up. Going forward, to run the @kbn/optimizer separately in development, pass --no-optimizer to yarn start. See #73154 for more details.

kibana.keystore has moved from the data folder to the config folder

Details: By default, kibana.keystore has moved from the configured path.data folder to <root>/config for archive distributions and /etc/kibana for package distributions. If a pre-existing keystore exists in the data directory that path will continue to be used.

User role changes

kibana_user role has been removed and kibana_admin has been added.

Details: The kibana_user role has been removed and kibana_admin has been added to better reflect its intended use. This role continues to grant all access to every {kib} feature. If you wish to restrict access to specific features, create custom roles with {kibana-ref}/kibana-privileges.html[{kib} privileges].

Impact: Any users currently assigned the kibana_user role will need to instead be assigned the kibana_admin role to maintain their current access level.

kibana_dashboard_only_user role has been removed.

Details: The kibana_dashboard_only_user role has been removed. If you wish to restrict access to just the Dashboard feature, create custom roles with {kibana-ref}/kibana-privileges.html[{kib} privileges].

Impact: Any users currently assigned the kibana_dashboard_only_user role will need to be assigned a custom role which only grants access to the Dashboard feature.

Granting additional cluster or index privileges may enable certain Stack Monitoring features.

Reporting changes

Legacy job parameters are no longer supported

Details: POST URL snippets that were copied in Kibana 6.2 or earlier are no longer supported. These logs have been deprecated with warnings that have been logged throughout 7.x. Please use Kibana UI to re-generate the POST URL snippets if you depend on these for automated PDF reports.

Configurations starting with xpack.telemetry are no longer valid

Details: The xpack. prefix has been removed for all telemetry configurations.

Impact: For any configurations beginning with xpack.telemetry, remove the xpack prefix. Use {kibana-ref}/telemetry-settings-kbn.html#telemetry-general-settings[telemetry.enabled] instead.

SysV init support has been removed

Details: All supported operating systems support using systemd service files. Any system that doesn’t already have service aliased to use kibana.service should use systemctl start kibana.service instead of the service start kibana.

Impact: Any installations using .deb or .rpm packages using SysV will need to migrate to systemd.

TLS v1.0 and v1.1 are disabled by default

Details: Support can be re-enabled by setting --tls-min-1.0 in the node.options config file that can be found inside kibana/config folder or any other configured with the environment variable KBN_PATH_CONF (for example in Debian based system would be /etc/kibana).

Impact: Browser and proxy clients communicating over TLS v1.0 and v1.1.

Platform removed from root folder name for .tar.gz and .zip archives

Details: The output directory after extracting an archive no longer includes the target platform. For example, kibana-8.0.0-linux-aarch64.tar.gz will produce a folder named kibana-8.0.0.

Impact: Configuration management tools and automation will need to be updated to use the new directory.

elasticsearch.preserveHost is no longer valid

Details: The deprecated elasticsearch.preserveHost setting in the kibana.yml file has been removed.

Impact: Configure {kibana-ref}/settings.html#elasticsearch-requestHeadersWhitelist[elasticsearch.requestHeadersWhitelist] to whitelist client-side headers.

elasticsearch.startupTimeout is no longer valid

Details: The deprecated elasticsearch.startupTimeout setting in the kibana.yml file has been removed.

Impact: Kibana will keep on trying to connect to Elasticsearch until it manages to connect.

savedObjects.indexCheckTimeout is no longer valid

Details: The deprecated savedObjects.indexCheckTimeout setting in the kibana.yml file has been removed.

server.xsrf.token is no longer valid

Details: The deprecated server.xsrf.token setting in the kibana.yml file has been removed.

newsfeed.defaultLanguage is no longer valid

Details: Specifying a default language to retrieve newsfeed items is no longer supported.

Impact: Newsfeed items will be retrieved based on the browser locale and fallback to 'en' if an item does not have a translation for the locale. Configure {kibana-ref}/i18n-settings-kb.html#general-i18n-settings-kb[i18n.locale] to override the default behavior.

xpack.banners.placement has changed value

Details: xpack.banners.placement: 'header' setting in kibana.yml has changed value.

Impact: Use {kibana-ref}/banners-settings-kb.html#banners-settings-kb[xpack.banners.placement: 'top'] instead.

cpu.cgroup.path.override is no longer valid

Details: The deprecated cpu.cgroup.path.override setting is no longer supported.

Impact: Configure {kibana-ref}/settings.html#ops-cGroupOverrides-cpuPath[ops.cGroupOverrides.cpuPath] instead.

cpuacct.cgroup.path.override is no longer valid

Details: The deprecated cpuacct.cgroup.path.override setting is no longer supported.

Impact: Configure {kibana-ref}/settings.html#ops-cGroupOverrides-cpuAcctPath[ops.cGroupOverrides.cpuAcctPath] instead.

server.xsrf.whitelist is no longer valid

Details: The deprecated server.xsrf.whitelist setting is no longer supported.

Impact: Use {kibana-ref}/settings.html#settings-xsrf-allowlist[server.xsrf.allowlist] instead.