mirror of
https://github.com/elastic/kibana.git
synced 2025-04-24 09:48:58 -04:00
01e51d3e6e
# Backport This will backport the following commits from `main` to `8.x`: - [[HTTP] Log deprecated api usages (#207904)](https://github.com/elastic/kibana/pull/207904) <!--- Backport version: 9.4.3 --> ### Questions ? Please refer to the [Backport tool documentation](https://github.com/sqren/backport) <!--BACKPORT [{"author":{"name":"Jesus Wahrman","email":"41008968+jesuswr@users.noreply.github.com"},"sourceCommit":{"committedDate":"2025-01-28T14:28:14Z","message":"[HTTP] Log deprecated api usages (#207904)\n\n## Summary\r\n\r\nResolves https://github.com/elastic/kibana/issues/199616\r\n\r\nAdded a debug logger when calling deprecated APIs. This logger is\r\ndisabled by default, to enable it you have to set\r\n`deprecation.enable_http_debug_logs: true`.\r\n\r\nTo test this you can play with the config value and do a request like\r\nthis to a deprecated endpoint:\r\n\r\n```shell\r\n#!/bin/bash\r\nAPI_KEY=\"\"\r\ncurl -X GET \"http://localhost:5601/api/cases/status\" -i \\\r\n-H \"Content-Type: application/json\" \\\r\n-H \"Authorization: ApiKey $API_KEY\"\r\n``` \r\n\r\n\r\n### Checklist\r\n\r\nCheck the PR satisfies following conditions. \r\n\r\nReviewers should verify this PR satisfies this list as well.\r\n\r\n- [x]\r\n[Documentation](https://www.elastic.co/guide/en/kibana/master/development-documentation.html)\r\nwas added for features that require explanation or tutorials\r\n- [x] [Unit or functional\r\ntests](https://www.elastic.co/guide/en/kibana/master/development-tests.html)\r\nwere updated or added to match the most common scenarios\r\n- [x] The PR description includes the appropriate Release Notes section,\r\nand the correct `release_note:*` label is applied per the\r\n[guidelines](https://www.elastic.co/guide/en/kibana/master/contributing.html#kibana-release-notes-process)\r\n\r\n### Identify risks\r\n\r\nDoes this PR introduce any risks? For example, consider risks like hard\r\nto test bugs, performance regression, potential of data loss.\r\n\r\nDescribe the risk, its severity, and mitigation for each identified\r\nrisk. Invite stakeholders and evaluate how to proceed before merging.\r\n\r\n---------\r\n\r\nCo-authored-by: Elastic Machine <elasticmachine@users.noreply.github.com>\r\nCo-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>\r\nCo-authored-by: florent-leborgne <florent.leborgne@elastic.co>\r\nCo-authored-by: Jean-Louis Leysens <jloleysens@gmail.com>","sha":"23b7f0fb33cecf080879f50a0b946d123f52f6ba","branchLabelMapping":{"^v9.0.0$":"main","^v8.18.0$":"8.x","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["release_note:enhancement","Feature:http","Team:Core","deprecation_warnings","v9.0.0","backport:version","v8.18.0"],"title":"[HTTP] Log deprecated api usages","number":207904,"url":"https://github.com/elastic/kibana/pull/207904","mergeCommit":{"message":"[HTTP] Log deprecated api usages (#207904)\n\n## Summary\r\n\r\nResolves https://github.com/elastic/kibana/issues/199616\r\n\r\nAdded a debug logger when calling deprecated APIs. This logger is\r\ndisabled by default, to enable it you have to set\r\n`deprecation.enable_http_debug_logs: true`.\r\n\r\nTo test this you can play with the config value and do a request like\r\nthis to a deprecated endpoint:\r\n\r\n```shell\r\n#!/bin/bash\r\nAPI_KEY=\"\"\r\ncurl -X GET \"http://localhost:5601/api/cases/status\" -i \\\r\n-H \"Content-Type: application/json\" \\\r\n-H \"Authorization: ApiKey $API_KEY\"\r\n``` \r\n\r\n\r\n### Checklist\r\n\r\nCheck the PR satisfies following conditions. \r\n\r\nReviewers should verify this PR satisfies this list as well.\r\n\r\n- [x]\r\n[Documentation](https://www.elastic.co/guide/en/kibana/master/development-documentation.html)\r\nwas added for features that require explanation or tutorials\r\n- [x] [Unit or functional\r\ntests](https://www.elastic.co/guide/en/kibana/master/development-tests.html)\r\nwere updated or added to match the most common scenarios\r\n- [x] The PR description includes the appropriate Release Notes section,\r\nand the correct `release_note:*` label is applied per the\r\n[guidelines](https://www.elastic.co/guide/en/kibana/master/contributing.html#kibana-release-notes-process)\r\n\r\n### Identify risks\r\n\r\nDoes this PR introduce any risks? For example, consider risks like hard\r\nto test bugs, performance regression, potential of data loss.\r\n\r\nDescribe the risk, its severity, and mitigation for each identified\r\nrisk. Invite stakeholders and evaluate how to proceed before merging.\r\n\r\n---------\r\n\r\nCo-authored-by: Elastic Machine <elasticmachine@users.noreply.github.com>\r\nCo-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>\r\nCo-authored-by: florent-leborgne <florent.leborgne@elastic.co>\r\nCo-authored-by: Jean-Louis Leysens <jloleysens@gmail.com>","sha":"23b7f0fb33cecf080879f50a0b946d123f52f6ba"}},"sourceBranch":"main","suggestedTargetBranches":["8.x"],"targetPullRequestStates":[{"branch":"main","label":"v9.0.0","branchLabelMappingKey":"^v9.0.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/207904","number":207904,"mergeCommit":{"message":"[HTTP] Log deprecated api usages (#207904)\n\n## Summary\r\n\r\nResolves https://github.com/elastic/kibana/issues/199616\r\n\r\nAdded a debug logger when calling deprecated APIs. This logger is\r\ndisabled by default, to enable it you have to set\r\n`deprecation.enable_http_debug_logs: true`.\r\n\r\nTo test this you can play with the config value and do a request like\r\nthis to a deprecated endpoint:\r\n\r\n```shell\r\n#!/bin/bash\r\nAPI_KEY=\"\"\r\ncurl -X GET \"http://localhost:5601/api/cases/status\" -i \\\r\n-H \"Content-Type: application/json\" \\\r\n-H \"Authorization: ApiKey $API_KEY\"\r\n``` \r\n\r\n\r\n### Checklist\r\n\r\nCheck the PR satisfies following conditions. \r\n\r\nReviewers should verify this PR satisfies this list as well.\r\n\r\n- [x]\r\n[Documentation](https://www.elastic.co/guide/en/kibana/master/development-documentation.html)\r\nwas added for features that require explanation or tutorials\r\n- [x] [Unit or functional\r\ntests](https://www.elastic.co/guide/en/kibana/master/development-tests.html)\r\nwere updated or added to match the most common scenarios\r\n- [x] The PR description includes the appropriate Release Notes section,\r\nand the correct `release_note:*` label is applied per the\r\n[guidelines](https://www.elastic.co/guide/en/kibana/master/contributing.html#kibana-release-notes-process)\r\n\r\n### Identify risks\r\n\r\nDoes this PR introduce any risks? For example, consider risks like hard\r\nto test bugs, performance regression, potential of data loss.\r\n\r\nDescribe the risk, its severity, and mitigation for each identified\r\nrisk. Invite stakeholders and evaluate how to proceed before merging.\r\n\r\n---------\r\n\r\nCo-authored-by: Elastic Machine <elasticmachine@users.noreply.github.com>\r\nCo-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>\r\nCo-authored-by: florent-leborgne <florent.leborgne@elastic.co>\r\nCo-authored-by: Jean-Louis Leysens <jloleysens@gmail.com>","sha":"23b7f0fb33cecf080879f50a0b946d123f52f6ba"}},{"branch":"8.x","label":"v8.18.0","branchLabelMappingKey":"^v8.18.0$","isSourceBranch":false,"state":"NOT_CREATED"}]}] BACKPORT--> Co-authored-by: Jesus Wahrman <41008968+jesuswr@users.noreply.github.com>
79 lines
No EOL
4 KiB
Text
79 lines
No EOL
4 KiB
Text
[[upgrade]]
|
|
== Upgrade {kib}
|
|
|
|
To upgrade from 7.16.0 or earlier to {version},
|
|
**you must first upgrade to {prev-major-last}**, which enables you to use the *Upgrade Assistant* to
|
|
{stack-ref}/upgrading-elastic-stack.html#prepare-to-upgrade[prepare for the upgrade].
|
|
Before you upgrade, you must resolve all critical issues identified by the *Upgrade Assistant*.
|
|
|
|
In addition, we recommend to carefully review the <<breaking-changes-summary,list of breaking changes and deprecations>> and to take any necessary actions to mitigate their impact on the upgrade.
|
|
You can enable the <<enable-http-debug-logs, deprecated APIs debug logs config>> to get information about calls to deprecated APIs.
|
|
|
|
Rolling upgrades are unsupported in {kib}. To upgrade,
|
|
you must shut down all {kib} instances, install the new software, and restart {kib}.
|
|
Upgrading while older {kib} instances are running can cause data loss or upgrade failures.
|
|
|
|
[WARNING]
|
|
====
|
|
When required, {kib} automatically migrates <<saved-object-migrations, saved objects>>.
|
|
In case of an upgrade failure, you can roll back to an
|
|
earlier version of {kib}. To roll back, you **must** have a
|
|
{ref}/snapshot-restore.html[backup snapshot] that includes the `kibana` feature
|
|
state. By default, snapshots include the `kibana` feature state.
|
|
====
|
|
|
|
For more information about upgrading,
|
|
refer to {stack-ref}/upgrading-elastic-stack.html[Upgrading to Elastic {version}.]
|
|
|
|
IMPORTANT: You can upgrade to pre-release versions for testing,
|
|
but upgrading from a pre-release to the General Available version is unsupported.
|
|
You should use pre-release versions only for testing in a temporary environment.
|
|
|
|
[float]
|
|
=== Upgrading multiple {kib} instances
|
|
When upgrading several {kib} instances connected to the same {es} cluster,
|
|
ensure that all outdated instances are shut down before starting the upgrade.
|
|
|
|
Rolling upgrades are unsupported in {kib}. However, when outdated instances are shut down, you can start all upgraded instances in parallel,
|
|
which allows all instances to participate in the upgrade migration in parallel.
|
|
|
|
For large deployments with more than 10 {kib} instances, and more than 10,000 saved objects,
|
|
you can reduce the upgrade downtime by bringing up a single {kib} instance and waiting for it to
|
|
complete the upgrade migration before bringing up the remaining instances.
|
|
|
|
[float]
|
|
[[preventing-migration-failures]]
|
|
=== Preparing for migration
|
|
|
|
Take these extra steps to ensure you are ready for migration.
|
|
|
|
[float]
|
|
==== Ensure your {es} cluster is healthy
|
|
Problems with your {es} cluster can prevent {kib} upgrades from succeeding.
|
|
|
|
During the upgrade process, {kib} creates new indices into which updated documents are written. If a cluster is approaching the low watermark, there's a high risk of {kib} not being able to create these. Reading, transforming and writing updated documents can be memory intensive, using more available heap than during routine operation. You must make sure that enough heap is available to prevent requests from timing out or throwing errors from circuit breaker exceptions. You should also ensure that all shards are replicated and assigned.
|
|
|
|
A healthy cluster has:
|
|
|
|
* Enough free disk space, at least twice the amount of storage taken up by the `.kibana` and `.kibana_task_manager` indices
|
|
* Sufficient heap size
|
|
* A "green" cluster status
|
|
|
|
[float]
|
|
==== Ensure that all {kib} instances are the same
|
|
When you perform an upgrade migration of different {kib} versions, the migration can fail.
|
|
Ensure that all {kib} instances are running the same version, configuration, and plugins.
|
|
|
|
[float]
|
|
==== Back up your data
|
|
Be sure to have a {ref}/snapshot-restore.html[snapshot] of all your data before attempting a migration.
|
|
If something goes wrong during migration, you can restore from the snapshot and try again.
|
|
|
|
Review the <<resolve-migrations-failures,common causes of {kib} upgrade failures>> and how to prevent them.
|
|
|
|
|
|
include::upgrade/saved-objects-migration.asciidoc[]
|
|
|
|
include::upgrade/resolving-migration-failures.asciidoc[]
|
|
|
|
include::upgrade/rollback-migration.asciidoc[] |