mirror of
https://github.com/elastic/kibana.git
synced 2025-04-22 08:49:27 -04:00
fb9e3c9ec8
This adds steps to the [Install Kibana with Docker](https://www.elastic.co/guide/en/kibana/current/docker.html) page for verifying the downloaded Docker images. I split apart the original version which had all the commands in one block. Having them separate allows us to add in the optional "verify images" step with a link to the Elasticsearch docs for additional info. Rel: https://github.com/elastic/dev/issues/2002 **Preview** ---  ---  --------- Co-authored-by: Tiago Costa <tiago.costa@elastic.co>
284 lines
8.7 KiB
Text
284 lines
8.7 KiB
Text
[[docker]]
|
|
=== Install {kib} with Docker
|
|
++++
|
|
<titleabbrev>Install with Docker</titleabbrev>
|
|
++++
|
|
|
|
:docker-repo: docker.elastic.co/kibana/kibana
|
|
:docker-image: {docker-repo}:{version}
|
|
:es-docker-repo: docker.elastic.co/elasticsearch/elasticsearch
|
|
:es-docker-image: {es-docker-repo}:{version}
|
|
|
|
Docker images for {kib} are available from the Elastic Docker registry. The
|
|
base image is https://hub.docker.com/_/ubuntu[ubuntu:20.04].
|
|
|
|
A list of all published Docker images and tags is available at
|
|
https://www.docker.elastic.co[www.docker.elastic.co]. The source code is in
|
|
https://github.com/elastic/dockerfiles/tree/{branch}/kibana[GitHub].
|
|
|
|
These images contain both free and subscription features.
|
|
<<managing-licenses,Start a 30-day trial>> to try out all of the features.
|
|
|
|
[discrete]
|
|
[[run-kibana-on-docker-for-dev]]
|
|
=== Run {kib} on Docker for development
|
|
|
|
. Start an {es} container for development or testing:
|
|
+
|
|
--
|
|
ifeval::["{release-state}"=="unreleased"]
|
|
|
|
NOTE: No Docker images are currently available for {kib} {version}.
|
|
|
|
endif::[]
|
|
|
|
ifeval::["{release-state}"!="unreleased"]
|
|
|
|
.. Create a new Docker network for {es} and {kib}:
|
|
+
|
|
[source,sh,subs="attributes"]
|
|
----
|
|
docker network create elastic
|
|
----
|
|
|
|
.. Pull the {es} Docker image:
|
|
+
|
|
[source,sh,subs="attributes"]
|
|
----
|
|
docker pull {es-docker-image}
|
|
----
|
|
|
|
.. Optional: Verify the {es} Docker image signature::
|
|
+
|
|
[source,sh,subs="attributes"]
|
|
----
|
|
wget https://artifacts.elastic.co/cosign.pub
|
|
cosign verify --key cosign.pub {docker-repo}:{version}
|
|
----
|
|
+
|
|
For details about this step, refer to {ref}/docker.html#docker-verify-signature[Verify the {es} Docker image signature] in the {es} documentation.
|
|
|
|
.. Start {es} in Docker:
|
|
+
|
|
[source,sh,subs="attributes"]
|
|
----
|
|
docker run --name es-node01 --net elastic -p 9200:9200 -p 9300:9300 -t {es-docker-image}
|
|
----
|
|
|
|
|
|
|
|
endif::[]
|
|
|
|
--
|
|
+
|
|
When you start {es} for the first time, the following security configuration
|
|
occurs automatically:
|
|
+
|
|
* {ref}/configuring-stack-security.html#stack-security-certificates[Certificates and keys]
|
|
are generated for the transport and HTTP layers.
|
|
* The Transport Layer Security (TLS) configuration settings are written to
|
|
`elasticsearch.yml`.
|
|
* A password is generated for the `elastic` user.
|
|
* An enrollment token is generated for {kib}.
|
|
+
|
|
NOTE: You might need to scroll back a bit in the terminal to view the password
|
|
and enrollment token.
|
|
|
|
. Copy the generated password and enrollment token and save them in a secure
|
|
location. These values are shown only when you start {es} for the first time.
|
|
You'll use these to enroll {kib} with your {es} cluster and log in.
|
|
|
|
. In a new terminal session, start {kib} and connect it to your {es} container:
|
|
+
|
|
--
|
|
ifeval::["{release-state}"=="unreleased"]
|
|
|
|
NOTE: No Docker images are currently available for {kib} {version}.
|
|
|
|
endif::[]
|
|
|
|
ifeval::["{release-state}"!="unreleased"]
|
|
|
|
[source,sh,subs="attributes"]
|
|
----
|
|
docker pull {docker-image}
|
|
docker run --name kib-01 --net elastic -p 5601:5601 {docker-image}
|
|
----
|
|
|
|
.. Pull the {kib} Docker image:
|
|
+
|
|
[source,sh,subs="attributes"]
|
|
----
|
|
docker pull {docker-image}
|
|
----
|
|
|
|
.. Optional: Verify the {kib} Docker image signature::
|
|
+
|
|
[source,sh,subs="attributes"]
|
|
----
|
|
wget https://artifacts.elastic.co/cosign.pub
|
|
cosign verify --key cosign.pub {docker-repo}:{version}
|
|
----
|
|
+
|
|
For details about this step, refer to {ref}/docker.html#docker-verify-signature[Verify the {es} Docker image signature] in the {es} documentation.
|
|
|
|
.. Start {kib} in Docker:
|
|
+
|
|
[source,sh,subs="attributes"]
|
|
----
|
|
docker run --name kib-01 --net elastic -p 5601:5601 {docker-image}
|
|
----
|
|
|
|
|
|
|
|
|
|
|
|
endif::[]
|
|
--
|
|
+
|
|
When you start {kib}, a unique link is output to your terminal.
|
|
|
|
. To access {kib}, click the generated link in your terminal.
|
|
|
|
.. In your browser, paste the enrollment token that you copied when starting
|
|
{es} and click the button to connect your {kib} instance with {es}.
|
|
|
|
.. Log in to {kib} as the `elastic` user with the password that was generated
|
|
when you started {es}.
|
|
|
|
[[docker-generate]]
|
|
[discrete]
|
|
=== Generate passwords and enrollment tokens
|
|
If you need to reset the password for the `elastic` user or other
|
|
built-in users, run the {ref}/reset-password.html[`elasticsearch-reset-password`]
|
|
tool. This tool is available in the {es} `bin` directory of the Docker container.
|
|
|
|
For example, to reset the password for the `elastic` user:
|
|
|
|
[source,sh]
|
|
----
|
|
docker exec -it es-node01 /usr/share/elasticsearch/bin/elasticsearch-reset-password -u elastic
|
|
----
|
|
|
|
If you need to generate new enrollment tokens for {kib} or {es} nodes, run the
|
|
{ref}/create-enrollment-token.html[`elasticsearch-create-enrollment-token`] tool.
|
|
This tool is available in the {es} `bin` directory of the Docker container.
|
|
|
|
For example, to generate a new enrollment token for {kib}:
|
|
|
|
[source,sh]
|
|
----
|
|
docker exec -it es-node01 /usr/share/elasticsearch/bin/elasticsearch-create-enrollment-token -s kibana
|
|
----
|
|
|
|
[discrete]
|
|
=== Remove Docker containers
|
|
|
|
To remove the containers and their network, run:
|
|
|
|
[source,sh]
|
|
----
|
|
docker network rm elastic
|
|
docker rm es-node01
|
|
docker rm kib-01
|
|
----
|
|
|
|
[discrete]
|
|
[[configuring-kibana-docker]]
|
|
=== Configure {kib} on Docker
|
|
|
|
The Docker images provide several methods for configuring {kib}. The
|
|
conventional approach is to provide a `kibana.yml` file as described in
|
|
{kibana-ref}/settings.html[Configuring Kibana], but it's also possible to use
|
|
environment variables to define settings.
|
|
|
|
[discrete]
|
|
[[bind-mount-config]]
|
|
==== Bind-mounted configuration
|
|
|
|
One way to configure {kib} on Docker is to provide `kibana.yml` via bind-mounting.
|
|
With `docker-compose`, the bind-mount can be specified like this:
|
|
|
|
["source","yaml",subs="attributes"]
|
|
--------------------------------------------
|
|
version: '2'
|
|
services:
|
|
kibana:
|
|
image: {docker-image}
|
|
volumes:
|
|
- ./kibana.yml:/usr/share/kibana/config/kibana.yml
|
|
--------------------------------------------
|
|
|
|
==== Persist the {kib} keystore
|
|
|
|
By default, {kib} auto-generates a keystore file for secure settings at startup. To persist your {kibana-ref}/secure-settings.html[secure settings], use the `kibana-keystore` utility to bind-mount the parent directory of the keystore to the container. For example:
|
|
|
|
["source","sh",subs="attributes"]
|
|
----
|
|
docker run -it --rm -v full_path_to/config:/usr/share/kibana/config -v full_path_to/data:/usr/share/kibana/data {docker-image} bin/kibana-keystore create
|
|
docker run -it --rm -v full_path_to/config:/usr/share/kibana/config -v full_path_to/data:/usr/share/kibana/data {docker-image} bin/kibana-keystore add test_keystore_setting
|
|
----
|
|
|
|
[discrete]
|
|
[[environment-variable-config]]
|
|
==== Environment variable configuration
|
|
|
|
Under Docker, {kib} can be configured via environment variables. When
|
|
the container starts, a helper process checks the environment for variables that
|
|
can be mapped to Kibana command-line arguments.
|
|
|
|
For compatibility with container orchestration systems, these
|
|
environment variables are written in all capitals, with underscores as
|
|
word separators. The helper translates these names to valid
|
|
{kib} setting names.
|
|
|
|
WARNING: All information that you include in environment variables is visible through the `ps` command, including sensitive information.
|
|
|
|
Some example translations are shown here:
|
|
|
|
.Example Docker Environment Variables
|
|
[horizontal]
|
|
**Environment Variable**:: **Kibana Setting**
|
|
`SERVER_NAME`:: `server.name`
|
|
`SERVER_BASEPATH`:: `server.basePath`
|
|
`ELASTICSEARCH_HOSTS`:: `elasticsearch.hosts`
|
|
|
|
In general, any setting listed in <<settings>> can be configured with this technique.
|
|
|
|
Supplying array options can be tricky. The following example shows the syntax for providing an array to `ELASTICSEARCH_HOSTS`.
|
|
|
|
These variables can be set with +docker-compose+ like this:
|
|
|
|
["source","yaml",subs="attributes"]
|
|
----------------------------------------------------------
|
|
version: '2'
|
|
services:
|
|
kibana:
|
|
image: {docker-image}
|
|
environment:
|
|
SERVER_NAME: kibana.example.org
|
|
ELASTICSEARCH_HOSTS: '["http://es01:9200","http://es02:9200","http://es03:9200"]'
|
|
----------------------------------------------------------
|
|
|
|
Since environment variables are translated to CLI arguments, they take
|
|
precedence over settings configured in `kibana.yml`.
|
|
|
|
[discrete]
|
|
[[docker-defaults]]
|
|
==== Docker defaults
|
|
The following settings have different default values when using the Docker
|
|
images:
|
|
|
|
[horizontal]
|
|
`server.host`:: `"0.0.0.0"`
|
|
`server.shutdownTimeout`:: `"5s"`
|
|
`elasticsearch.hosts`:: `http://elasticsearch:9200`
|
|
`monitoring.ui.container.elasticsearch.enabled`:: `true`
|
|
|
|
These settings are defined in the default `kibana.yml`. They can be overridden
|
|
with a <<bind-mount-config,custom `kibana.yml`>> or via
|
|
<<environment-variable-config,environment variables>>.
|
|
|
|
IMPORTANT: If replacing `kibana.yml` with a custom version, be sure to copy the
|
|
defaults to the custom file if you want to retain them. If not, they will
|
|
be "masked" by the new file.
|