Skip to content

Latest commit

 

History

History
284 lines (218 loc) · 8.68 KB

docker.asciidoc

File metadata and controls

284 lines (218 loc) · 8.68 KB

Install {kib} with Docker

Install with Docker

Docker images for {kib} are available from the Elastic Docker registry. The base image is ubuntu:20.04.

A list of all published Docker images and tags is available at www.docker.elastic.co. The source code is in GitHub.

These images contain both free and subscription features. Start a 30-day trial to try out all of the features.

Run {kib} on Docker for development

  1. Start an {es} container for development or testing:

    1. Create a new Docker network for {es} and {kib}:

      docker network create elastic

    2. Pull the {es} Docker image:

      docker pull docker.elastic.co/elasticsearch/elasticsearch:{version}

    3. Optional: Verify the {es} Docker image signature::

      wget https://artifacts.elastic.co/cosign.pub
cosign verify --key cosign.pub docker.elastic.co/kibana/kibana:{version}

      For details about this step, refer to {ref}/docker.html#docker-verify-signature[Verify the {es} Docker image signature] in the {es} documentation.

    4. Start {es} in Docker:

      docker run --name es-node01 --net elastic -p 9200:9200 -p 9300:9300 -t docker.elastic.co/elasticsearch/elasticsearch:{version}

    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.

  2. 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.

  3. In a new terminal session, start {kib} and connect it to your {es} container:

    docker pull docker.elastic.co/kibana/kibana:{version}
docker run --name kib-01 --net elastic -p 5601:5601 docker.elastic.co/kibana/kibana:{version}

    1. Pull the {kib} Docker image:

      docker pull docker.elastic.co/kibana/kibana:{version}

    2. Optional: Verify the {kib} Docker image signature::

      wget https://artifacts.elastic.co/cosign.pub
cosign verify --key cosign.pub docker.elastic.co/kibana/kibana:{version}

      For details about this step, refer to {ref}/docker.html#docker-verify-signature[Verify the {es} Docker image signature] in the {es} documentation.

    3. Start {kib} in Docker:

      docker run --name kib-01 --net elastic -p 5601:5601 docker.elastic.co/kibana/kibana:{version}

    When you start {kib}, a unique link is output to your terminal.

  4. To access {kib}, click the generated link in your terminal.

    1. In your browser, paste the enrollment token that you copied when starting {es} and click the button to connect your {kib} instance with {es}.

    2. Log in to {kib} as the elastic user with the password that was generated when you started {es}.

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:

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}:

docker exec -it es-node01 /usr/share/elasticsearch/bin/elasticsearch-create-enrollment-token -s kibana

Remove Docker containers

To remove the containers and their network, run:

docker network rm elastic
docker rm es-node01
docker rm kib-01

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.

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:

version: '2'
services:
  kibana:
    image: docker.elastic.co/kibana/kibana:{version}
    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:

docker run -it --rm -v full_path_to/config:/usr/share/kibana/config -v full_path_to/data:/usr/share/kibana/data docker.elastic.co/kibana/kibana:{version} 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.elastic.co/kibana/kibana:{version} bin/kibana-keystore add test_keystore_setting

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
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:

version: '2'
services:
  kibana:
    image: docker.elastic.co/kibana/kibana:{version}
    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.

Docker defaults

The following settings have different default values when using the Docker images:

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 custom kibana.yml or via 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.