Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: link to new APM book #1850

Merged
merged 5 commits into from
Oct 29, 2021
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
75 changes: 34 additions & 41 deletions docs/en/getting-started/get-started-docker.asciidoc
Original file line number Diff line number Diff line change
@@ -1,23 +1,23 @@
[[get-started-docker]]
== Running the {stack} on Docker

The Elastic Docker registry contains Docker images for all the products in
The Elastic Docker registry contains Docker images for all the products in
the {stack}: https://www.docker.elastic.co/.

[float]
[[run-stack-docker]]
=== Run with Docker Compose

To get the default distributions of {es} and {kib} up and running in Docker,
To get the default distributions of {es} and {kib} up and running in Docker,
you can use Docker Compose.

. Create a `docker-compose.yml` file for the Elastic Stack.
. Create a `docker-compose.yml` file for the Elastic Stack.
The following example brings up a three node cluster and Kibana so you can see how things work.
This all-in-one configuration is a handy way to bring up your first dev cluster before
you build a distributed deployment with multiple hosts.
+
ifeval::["{release-state}"=="unreleased"]
NOTE: Version {version} of {es} has not been released,
NOTE: Version {version} of {es} has not been released,
so the sample compose file is not yet available for this version.
See the {stack-gs-current}/get-started-docker.html[current version] for the latest sample files.
endif::[]
Expand All @@ -28,7 +28,7 @@ include::docker/docker-compose.yml[]
--------------------------------------------
endif::[]
// tag::docker-memory[]
. Make sure Docker Engine is allotted at least 4GiB of memory.
. Make sure Docker Engine is allotted at least 4GiB of memory.
In Docker Desktop, you configure resource usage on the Advanced tab in Preference (macOS)
or Settings (Windows).
// end::docker-memory[]
Expand All @@ -47,39 +47,39 @@ docker-compose up
curl -X GET "localhost:9200/_cat/nodes?v&pretty"
--------------------------------------------------

. Open {kib} to load sample data and interact with the cluster:
http://localhost:5601.
. Open {kib} to load sample data and interact with the cluster:
http://localhost:5601.

When you're done experimenting, you can tear down the containers and
When you're done experimenting, you can tear down the containers and
volumes by running `docker-compose down -v`.

[float]
[[get-started-docker-tls]]
=== Run in Docker with TLS enabled
=== Run in Docker with TLS enabled

If {security-features} are enabled, you must configure Transport Layer Security
(TLS) encryption for the {es} transport layer. While it is possible to use a
trial license without setting up TLS, we advise securing your stack from the
start.

To get an {es} cluster and {kib} up and running in Docker with security enabled,
To get an {es} cluster and {kib} up and running in Docker with security enabled,
you can use Docker Compose:

. Create the following compose and configuration files.
These files are also available from the
https://github.com/elastic/stack-docs/blob/master/docs/en/getting-started/docker/[elastic/stack-docs]
. Create the following compose and configuration files.
These files are also available from the
https://github.com/elastic/stack-docs/blob/master/docs/en/getting-started/docker/[elastic/stack-docs]
repository on GitHub.
+
--
ifeval::["{release-state}"=="unreleased"]
NOTE: Version {version} of {es} has not been released,
NOTE: Version {version} of {es} has not been released,
so the sample compose and configuration files are not yet available for this version.
See the {stack-gs-current}/get-started-docker.html[current version] for the latest sample files.
endif::[]

* `instances.yml` identifies the instances you need to create certificates for.
* `.env` sets environment variables to specify the {es} version and
the location where the {es} certificates will be created.
the location where the {es} certificates will be created.
* `create-certs.yml` is a Docker Compose file that launches a container to generate the certificates
for {es} and {kib}.
* `elastic-docker-tls.yml` is a Docker Compose file that brings up a three-node {es} cluster
Expand All @@ -91,7 +91,7 @@ ifeval::["{release-state}"!="unreleased"]
.`instances.yml`:
["source","yaml"]
----
include::docker/instances.yml[]
include::docker/instances.yml[]
----

.`.env`:
Expand All @@ -115,7 +115,7 @@ include::docker/elastic-docker-tls.yml[]
<1> Generate and apply a trial license that supports Transport Layer Security.
<2> Enable Transport Layer Security to encrypt client communications.
<3> Enable Transport Layer Security to encrypt internode communications.
<4> Allow the use of self-signed certificates by not requiring hostname verification.
<4> Allow the use of self-signed certificates by not requiring hostname verification.
endif::[]
--

Expand All @@ -141,12 +141,12 @@ docker-compose -f elastic-docker-tls.yml up -d
----

IMPORTANT: At this point, {kib} cannot connect to the {es} cluster.
You must generate a password for the built-in `kibana_system` user, update the `ELASTICSEARCH_PASSWORD`
in the compose file, and restart to enable {kib} to communicate with the secured cluster.
You must generate a password for the built-in `kibana_system` user, update the `ELASTICSEARCH_PASSWORD`
in the compose file, and restart to enable {kib} to communicate with the secured cluster.

--

. Run the `elasticsearch-setup-passwords` tool to generate passwords for all built-in users,
. Run the `elasticsearch-setup-passwords` tool to generate passwords for all built-in users,
including the `kibana_system` user. If you don't use PowerShell on Windows, remove the trailing `\`characters
and join the lines before running this command.
+
Expand All @@ -157,18 +157,18 @@ docker exec es01 /bin/bash -c "bin/elasticsearch-setup-passwords \
auto --batch --url https://es01:9200"
----

IMPORTANT: Make a note of the generated passwords.
You must configure the `kibana_system` user password in the compose file to enable {kib} to connect to {es},
and you'll need the password for the `elastic` superuser to
IMPORTANT: Make a note of the generated passwords.
You must configure the `kibana_system` user password in the compose file to enable {kib} to connect to {es},
and you'll need the password for the `elastic` superuser to
log in to {kib} and submit requests to {es}.
--

. Set `ELASTICSEARCH_PASSWORD` in the `elastic-docker-tls.yml` compose file to the password
. Set `ELASTICSEARCH_PASSWORD` in the `elastic-docker-tls.yml` compose file to the password
generated for the `kibana_system` user.
+
--
ifeval::["{release-state}"=="unreleased"]
NOTE: Version {version} of {es} has not been released,
NOTE: Version {version} of {es} has not been released,
so the sample compose file is not yet available for this version.
See the {stack-gs-current}/get-started-docker.html[current version] for the latest sample files.
endif::[]
Expand Down Expand Up @@ -210,23 +210,23 @@ docker-compose -f elastic-docker-tls.yml up -d
----
--

. Open {kib} to load sample data and interact with the cluster:
https://localhost:5601.
. Open {kib} to load sample data and interact with the cluster:
https://localhost:5601.
+
NOTE: Because SSL is also enabled for communications between {kib} and client browsers,
you must access {kib} via the HTTPS protocol.
NOTE: Because SSL is also enabled for communications between {kib} and client browsers,
you must access {kib} via the HTTPS protocol.

When you're done experimenting, you can tear down the containers, network, and
When you're done experimenting, you can tear down the containers, network, and
volumes by running `docker-compose -f elastic-docker-tls.yml down -v`.

[float]
[[load-settings-file]]
==== Loading settings from a file

Specifying settings for {es} and {{kib}} directly in the compose file is a convenient way to get started,
Specifying settings for {es} and {{kib}} directly in the compose file is a convenient way to get started,
but loading settings from a file is preferable once you get past the experimental stage.

For example, to use `es01.yml` as the configuration file for the `es01` {es} node,
For example, to use `es01.yml` as the configuration file for the `es01` {es} node,
you can create a bind mount in the volumes section.

["source","yaml"]
Expand All @@ -235,7 +235,7 @@ you can create a bind mount in the volumes section.
- data01:/usr/share/elasticsearch/data
- certs:$CERTS_DIR
- ./es01.yml:/usr/share/elasticsearch/config/elasticsearch.yml
----
----

Similarly, to load {kib} settings from a file, you overwrite `/usr/share/kibana/config/kibana.yml`:

Expand All @@ -252,11 +252,4 @@ Similarly, to load {kib} settings from a file, you overwrite `/usr/share/kibana/
See the product-specific documentation for information about running a specific Elastic product in Docker:

* {ref}/docker.html[Install {es} with Docker]
* {apm-server-ref}/running-on-docker.html[Running APM Server on Docker]
* {auditbeat-ref}/running-on-docker.html[Running {auditbeat} on Docker]
* {filebeat-ref}/running-on-docker.html[Running {filebeat} on Docker]
* {heartbeat-ref}/running-on-docker.html[Running {heartbeat} on Docker]
* {kibana-ref}/docker.html[Running {kib} on Docker]
* {logstash-ref}/docker.html[Running {ls} on Docker]
* {metricbeat-ref}/running-on-docker.html[Running {metricbeat} on Docker]
* {packetbeat-ref}/running-on-docker.html[Running {packetbeat} on Docker]
Comment on lines 254 to -262
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Getting started topic seems to focus on Elasticsearch, Kibana, and Beats. So maybe we just list the links for Elasticsearch, Kibana, and the Elastic Agent? It looks like the elastic-agent-container.html file hasn't been moved yet to the Observability guide.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It looks like the elastic-agent-container.html file hasn't been moved yet to the Observability guide.

I'm not planning to move to elastic-agent-container.html to the obs guide because the docs are needed for other use cases (not just observability).

I'm on the fence about removing these links because I think it's still hard for users to find all the content they need about running on containers (though I agree that Beats aren't really for "getting started"). We could group them under a section called "Legacy shippers"?

I'd be curious to hear what @lcawl thinks about the related links.

* {fleet-guide}/elastic-agent-container.html[Run Elastic Agent in a container]
8 changes: 4 additions & 4 deletions docs/en/glossary/glossary.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -429,9 +429,9 @@ point contribute to its outlier behavior. See

[[glossary-feature-importance]] feature importance::
In supervised {ml} methods such as {regression} and {classification}, feature
importance indicates the degree to which a specific feature affects a
importance indicates the degree to which a specific feature affects a
prediction.
See
See
{ml-docs}/ml-dfa-regression.html#dfa-regression-feature-importance[{regression-cap} feature importance]
and
{ml-docs}/ml-dfa-classification.html#dfa-classification-feature-importance[{classification-cap} feature importance].
Expand Down Expand Up @@ -1140,7 +1140,7 @@ different spaces for each team, use case, or individual. See

[[glossary-span]] span::
Information about the execution of a specific code path.
{apm-overview-ref-v}/transaction-spans.html[Spans] measure from the start to the end of an activity
{apm-guide-ref}/data-model-spans.html[Spans] measure from the start to the end of an activity
and can have a parent/child relationship with other spans.
//Source: Observability

Expand Down Expand Up @@ -1243,7 +1243,7 @@ referenced in an ingest pipeline or in a pipeline aggregation to perform

[[glossary-transaction]] transaction::
A special kind of <<glossary-span,span>> that has additional attributes associated with it.
{apm-overview-ref-v}/transactions.html[Transactions] describe an event captured by an
{apm-guide-ref}/data-model-transactions.html[Transactions] describe an event captured by an
Elastic <<glossary-apm-agent,APM agent>> instrumenting a service.
//Source: Observability

Expand Down
11 changes: 5 additions & 6 deletions docs/en/install-upgrade/breaking.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
== Breaking changes

Before you upgrade, you must review the breaking changes for each product you
use and make the necessary changes so your code is compatible with {version}.
use and make the necessary changes so your code is compatible with {version}.

** <<apm-breaking-changes,APM {version} breaking changes>>
** <<beats-breaking-changes,Beats {version} breaking changes>>
Expand All @@ -26,18 +26,18 @@ Upgrade Assistant provides information about which {dfeeds} need to be updated.
<titleabbrev>APM</titleabbrev>
++++

This list summarizes the most important breaking changes in APM.
For the complete list, go to {apm-get-started-ref}/apm-breaking-changes.html[APM breaking changes].
This list summarizes the most important breaking changes in APM.
For the complete list, go to {apm-guide-ref}/apm-breaking.html[APM breaking changes].

include::{apm-repo-dir}/apm-breaking-changes.asciidoc[tag=notable-v8-breaking-changes]
include::{apm-repo-dir}/apm-breaking.asciidoc[tag=notable-v8-breaking-changes]

[[beats-breaking-changes]]
=== Beats breaking changes
++++
<titleabbrev>Beats</titleabbrev>
++++

This list summarizes the most important breaking changes in Beats.
This list summarizes the most important breaking changes in Beats.
For the complete list, go to {beats-ref}/breaking-changes.html[Beats breaking changes].

include::{beats-repo-dir}/release-notes/breaking/breaking-8.0.asciidoc[tag=notable-breaking-changes]
Expand Down Expand Up @@ -176,4 +176,3 @@ the complete list, go to
{logstash-ref}/breaking-changes.html[Logstash breaking changes].

include::{ls-repo-dir}/static/breaking-changes.asciidoc[tag=notable-breaking-changes]

2 changes: 1 addition & 1 deletion docs/en/install-upgrade/index.asciidoc
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
[[elastic-stack]]
= Installation and Upgrade Guide

:apm-repo-dir: {apm-server-root}/docs/guide
:apm-repo-dir: {apm-server-root}/docs
:beats-repo-dir: {beats-root}/libbeat/docs
:es-repo-dir: {elasticsearch-root}/docs/reference
:hadoop-repo-dir: {elasticsearch-hadoop-root}/docs/src/reference/asciidoc
Expand Down
5 changes: 2 additions & 3 deletions docs/en/install-upgrade/installing-stack.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ Install the Elastic Stack products you want to use in the following order:
. Kibana ({kibana-ref}/install.html[install])
. Logstash ({logstash-ref}/installing-logstash.html[install])
. Beats ({beats-ref}/getting-started.html[install instructions])
. APM Server ({apm-server-ref}/installing.html[install instructions])
. APM ({apm-guide-ref}/apm-quick-start.html[install instructions])
. Elasticsearch Hadoop ({hadoop-ref}/install.html[install instructions])

Installing in this order ensures that the components each product depends
Expand All @@ -33,7 +33,7 @@ official hosted {es} and {kib} offering from Elastic. The {ess} is available on
both AWS and GCP.

Installing on {ecloud} is easy: a single click creates an {es} cluster
configured to the size you want, with or without high availability. The
configured to the size you want, with or without high availability. The
subscription features are always installed, so you automatically have the
ability to secure and monitor your cluster. {kib} can be enabled on a cluster
with a click, and a number of popular plugins are readily available.
Expand All @@ -43,4 +43,3 @@ information, see https://www.elastic.co/pricing/.

You can {ess-trial}[try out the {ess} for free]. For more information, see
{cloud}/ec-getting-started.html[Getting Started with {ecloud}].

2 changes: 1 addition & 1 deletion docs/en/install-upgrade/overview.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ to simplify the installation and upgrade process. The full stack
consists of:

* {beats-ref}/index.html[Beats {branch}]
* {apm-server-ref}/index.html[APM Server {branch}]
* {apm-guide-ref}/index.html[APM {branch}]
* {ref}/index.html[Elasticsearch {branch}]
* {hadoop-ref}/index.html[Elasticsearch Hadoop {branch}]
* {kibana-ref}/index.html[Kibana {branch}]
Expand Down
3 changes: 2 additions & 1 deletion docs/en/install-upgrade/upgrading-stack.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -61,9 +61,10 @@ on the cluster during the upgrade process. For more information, see
.. Java API Client: {java-api-client}/installation.html#maven[dependency configuration]
.. Logstash: {logstash-ref}/upgrading-logstash.html[upgrade instructions]
.. Beats: {beats-ref}/upgrading.html[upgrade instructions]
.. APM Server: {apm-server-ref}/upgrading.html[upgrade instructions]
.. APM: {apm-guide-ref}/upgrade.html[upgrade instructions]
.. {agent}: {fleet-guide}/upgrade-elastic-agent.html[upgrade instructions]


[WARNING]
====
If using {agent} in 7.12 or lower, your {agent}s will automatically be unenrolled
Expand Down