Document the declarative plugins configuration file

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
+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,6 +26,13 @@ Otherwise run `bin/elasticsearch-plugin` as the user that owns all of the Elasti
 files.
 =====================
 
+[discrete]
+[[plugin-management-docker]]
+=== Docker
+
+If you run {es} using Docker, you can manage plugins using a
+<<manage-plugins-using-configuration-file,configuration file>>.
+
 [[installation]]
 === Installing Plugins
 
@@ -279,3 +286,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]
+
+
+[[manage-plugins-using-configuration-file]]
+=== Manage plugins using a configuration file
+
+[IMPORTANT]
+.Docker only
+=====================
+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.
+=====================
+
+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.
+
+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 `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.
+
+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
+----