Add documentation to provide notice about deprecation of security tools in the next major release

[cwillum]

Description

The audit_config_migrater, hash, and securityadmin security tools will be deprecated in the next major release. This documentation alerts users to their imminent replacement.

Issues Resolved

Added an important banner note including the news of this deprecation in relevant places in documentation.

Fixes #503

Checklist

• By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license and subject to the Developers Certificate of Origin.
  For more information on following Developer Certificate of Origin and signing off your commits, please check here.

[cwillum]

@peternied I searched through the documentation website for instances where any of the four tools appear: install_demo_configuration, audit_config_migrater, hash, and securityadmin. Most surprising of all was not finding any mention of install_demo_configuration. Is this possibly an oversight in documentation?
In any case, I've added deprecation banner notes for hash and securityadmin wherever they appear as a first instance in relevant documentation. We can change or add to the wording. Could you have a look at the statements as they are currently? Thanks.

[cwillum]

@opensearch-project/security Hi team, when you have a chance, could someone look at these deprecation flags I've added to documentation to alert users that securityadmin and hash tools will be replaced in the next major version. Related to issue #1756. Thanks.

[cwillum]

@peternied @RyanL1997 Thanks for the reviews. Will move this along. One thing I forgot to ask about. I believe we'll want to backport this flag/alert through all minor versions of 2.x documentation and include 1.3. Can you confirm whether this is correct?

[peternied]

we'll want to backport this flag/alert through all minor versions of 2.x documentation and include 1.3.

Good idea @cwillum yes we should backport these documentation to all versions

[cwperks]

@cwillum @peternied Judging by the number of reactions on this comment: opensearch-project/security#1755 (comment) - the deprecation is definitely a controversial matter for these tools. Absent of a clear replacement in the next major version, I am at the moment more in favor of removing the deprecation notices on the tools. Long-term the OpenSearch project would like Security to move into the core of OpenSearch, but its not clear if that would be delivered by 3.0.0 or a future major version.

[cwillum]

@peternied @cwperks @RyanL1997 Thanks for the responses here. I'm going to put this on simmer for the moment. If over the next week some message more appropriate comes to mind, I could change the language and put this back in progress. Otherwise, I could close this one and leave the idea alone for the time being. If an alternative to these tools has a chance of appearing in 3.x with a full deprecation by version 4, it might be more appropriate to add the alert after version 3 releases. I'll stay in contact on the issue.

[davidlago]

I second @cwperks's comment... I think in hindsight we jumped on the deprecation bandwagon too quickly, or at least at the time it seemed like a replacement would definitely be in place by 3.0. I don't think we are investing in that replacement at this time, and with the potential of an external factor forcing our hand (for example, a Lucene version bump), I think it is more likely than not that this is a 4.0 thing rather than 3.0.

I don't think there is anything wrong with deprecation notices lasting more than just one major version bump, but we should perhaps hold off on giving this even more visibility until we have a more clear picture of what a replacement looks like and some sort of timeline.

[cwillum]

@davidlago This makes sense. I'm closing this PR. We can open a new one when the circumstances are right and we have a better picture of a replacement.