From a870267b874fc2414129541ec2c2740ab6342462 Mon Sep 17 00:00:00 2001 From: Rory Hunter Date: Tue, 16 Nov 2021 14:21:57 +0000 Subject: [PATCH 1/4] Document the declarative plugins configuration file Follow-up to #77544. --- docs/plugins/plugin-script.asciidoc | 56 ++++++++++++++++++++++++++++- 1 file changed, 55 insertions(+), 1 deletion(-) diff --git a/docs/plugins/plugin-script.asciidoc b/docs/plugins/plugin-script.asciidoc index a93102bf0406c..b74fa7943e292 100644 --- a/docs/plugins/plugin-script.asciidoc +++ b/docs/plugins/plugin-script.asciidoc @@ -1,7 +1,7 @@ [[plugin-management]] == Plugin Management -The `plugin` script is used to install, list, and remove plugins. It is +The `elasticsearch-plugin` tool is used to install, list, and remove plugins. It is located in the `$ES_HOME/bin` directory by default but it may be in a different location depending on which Elasticsearch package you installed: @@ -26,6 +26,11 @@ Otherwise run `bin/elasticsearch-plugin` as the user that owns all of the Elasti files. ===================== +==== Docker + +If you are running Elasticsearch using Docker, you can choose instead to +use manage plugins via a configuration file. + [[installation]] === Installing Plugins @@ -279,3 +284,52 @@ The default location of the `plugins` directory depends on which package you ins * {ref}/zip-windows.html#windows-layout[Directory layout of Windows `.zip` archives] * {ref}/deb.html#deb-layout[Directory layout of Debian package] * {ref}/rpm.html#rpm-layout[Directory layout of RPM] + + +[discrete] +=== Managing plugins using a configuration file + +[IMPORTANT] +. Docker only +===================== +At present, this feature is only available when running {es} using our +Docker images. Other distributions of {es} will not start if they find a +plugin configuration file. +===================== + +You can choose to manage plugins using a declarative configuration file. +When {es} starts up, it will compare the plugins in the file with those +that are currently installed, and add or remove plugins as required. {es} +will also upgrade plugins when you upgrade {es} itself. + +The file is called `elasticsearch-plugins.yml`, and must be placed in the +Elasticsearch configuration directory, alongside `elasticsearch.yml`. Here +is an example: + +[source,yaml] +----------------------------------- +plugins: + - id: analysis-icu + - id: repository-azure + - id: custom-mapper + location: https://example.com/archive/custom-mapper-1.0.0.zip +----------------------------------- + +This example installs the official plugins `analysis-icu` and +`repository-azure`, and one unofficial plugin. Every plugin must provide +an `id`, and unofficial plugins must also provide a `location`. This is +typically a URL, but Maven coordinates are also supported. The downloaded +plugin's name must match the ID in the configuration file. + +While {es} will respect the +https://docs.oracle.com/javase/8/docs/technotes/guides/net/proxies.html[standard +Java proxy system properties] when downloading plugins, you can also configure an +HTTP proxy to use explicitly in the configuration file. For example: + +[source,yaml] +----------------------------------- +plugins: + - id: custom-mapper + location: https://example.com/archive/custom-mapper-1.0.0.zip +proxy: proxy.example.com:8443 +----------------------------------- From aa8bb66989be16c9e8c298f04c4a2e41f615d42e Mon Sep 17 00:00:00 2001 From: Rory Hunter Date: Tue, 16 Nov 2021 14:34:16 +0000 Subject: [PATCH 2/4] Fix --- docs/plugins/plugin-script.asciidoc | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/plugins/plugin-script.asciidoc b/docs/plugins/plugin-script.asciidoc index b74fa7943e292..dc2b281ef065e 100644 --- a/docs/plugins/plugin-script.asciidoc +++ b/docs/plugins/plugin-script.asciidoc @@ -26,10 +26,11 @@ Otherwise run `bin/elasticsearch-plugin` as the user that owns all of the Elasti files. ===================== -==== Docker +=== Docker If you are running Elasticsearch using Docker, you can choose instead to -use manage plugins via a configuration file. +use manage plugins via a +<>. [[installation]] === Installing Plugins @@ -287,6 +288,7 @@ The default location of the `plugins` directory depends on which package you ins [discrete] +[[manage-plugins-using-configuration-file]] === Managing plugins using a configuration file [IMPORTANT] From 740bcb0a8dafcdf195fe39d09f46545c0ef05cba Mon Sep 17 00:00:00 2001 From: Rory Hunter Date: Wed, 17 Nov 2021 10:25:45 +0000 Subject: [PATCH 3/4] Clarify that only official plugins are upgraded --- docs/plugins/plugin-script.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/plugins/plugin-script.asciidoc b/docs/plugins/plugin-script.asciidoc index dc2b281ef065e..775ecdc9b8194 100644 --- a/docs/plugins/plugin-script.asciidoc +++ b/docs/plugins/plugin-script.asciidoc @@ -302,7 +302,7 @@ plugin configuration file. You can choose to manage plugins using a declarative configuration file. When {es} starts up, it will compare the plugins in the file with those that are currently installed, and add or remove plugins as required. {es} -will also upgrade plugins when you upgrade {es} itself. +will also upgrade offical plugins when you upgrade {es} itself. The file is called `elasticsearch-plugins.yml`, and must be placed in the Elasticsearch configuration directory, alongside `elasticsearch.yml`. Here From 65a1244a91bfbd012f5295c13c8ebe27561d7951 Mon Sep 17 00:00:00 2001 From: Rory Hunter Date: Wed, 17 Nov 2021 21:00:46 +0000 Subject: [PATCH 4/4] Apply suggestions from code review Co-authored-by: James Rodewig --- docs/plugins/plugin-script.asciidoc | 32 ++++++++++++++--------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/docs/plugins/plugin-script.asciidoc b/docs/plugins/plugin-script.asciidoc index 775ecdc9b8194..c0d1956a44678 100644 --- a/docs/plugins/plugin-script.asciidoc +++ b/docs/plugins/plugin-script.asciidoc @@ -1,7 +1,7 @@ [[plugin-management]] == Plugin Management -The `elasticsearch-plugin` tool is used to install, list, and remove plugins. It is +Use the `elasticsearch-plugin` command line tool to install, list, and remove plugins. It is located in the `$ES_HOME/bin` directory by default but it may be in a different location depending on which Elasticsearch package you installed: @@ -26,10 +26,11 @@ Otherwise run `bin/elasticsearch-plugin` as the user that owns all of the Elasti files. ===================== +[discrete] +[[plugin-management-docker]] === Docker -If you are running Elasticsearch using Docker, you can choose instead to -use manage plugins via a +If you run {es} using Docker, you can manage plugins using a <>. [[installation]] @@ -287,19 +288,18 @@ The default location of the `plugins` directory depends on which package you ins * {ref}/rpm.html#rpm-layout[Directory layout of RPM] -[discrete] [[manage-plugins-using-configuration-file]] -=== Managing plugins using a configuration file +=== Manage plugins using a configuration file [IMPORTANT] -. Docker only +.Docker only ===================== -At present, this feature is only available when running {es} using our -Docker images. Other distributions of {es} will not start if they find a +This feature is only available for https://www.docker.elastic.co/[official {es} +Docker images]. Other {es} distributions will not start with a plugin configuration file. ===================== -You can choose to manage plugins using a declarative configuration file. +If you run {es} using Docker, you can manage plugins using a declarative configuration file. When {es} starts up, it will compare the plugins in the file with those that are currently installed, and add or remove plugins as required. {es} will also upgrade offical plugins when you upgrade {es} itself. @@ -309,17 +309,17 @@ Elasticsearch configuration directory, alongside `elasticsearch.yml`. Here is an example: [source,yaml] ------------------------------------ +---- plugins: - id: analysis-icu - id: repository-azure - id: custom-mapper location: https://example.com/archive/custom-mapper-1.0.0.zip ------------------------------------ +---- -This example installs the official plugins `analysis-icu` and -`repository-azure`, and one unofficial plugin. Every plugin must provide -an `id`, and unofficial plugins must also provide a `location`. This is +This example installs the official `analysis-icu` and +`repository-azure` plugins, and one unofficial plugin. Every plugin must provide +an `id`. Unofficial plugins must also provide a `location`. This is typically a URL, but Maven coordinates are also supported. The downloaded plugin's name must match the ID in the configuration file. @@ -329,9 +329,9 @@ Java proxy system properties] when downloading plugins, you can also configure a HTTP proxy to use explicitly in the configuration file. For example: [source,yaml] ------------------------------------ +---- plugins: - id: custom-mapper location: https://example.com/archive/custom-mapper-1.0.0.zip proxy: proxy.example.com:8443 ------------------------------------ +----