-
Notifications
You must be signed in to change notification settings - Fork 161
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
Add EKS documentation #2360
Merged
tetianakravchenko
merged 6 commits into
elastic:main
from
tetianakravchenko:elastic-agent-on-eks
Nov 15, 2022
Merged
Add EKS documentation #2360
Changes from all commits
Commits
Show all changes
6 commits
Select commit
Hold shift + click to select a range
cabd50b
add eks documentation
tetianakravchenko a27a978
fix processor example
tetianakravchenko 8373a54
fix indentation for add_fields processor; add info about orchestrator…
tetianakravchenko 7f4c965
fix install elastic-agent list
tetianakravchenko aec0a40
remove empty line
tetianakravchenko 438b2ee
Update docs/en/ingest-management/elastic-agent/running-on-eks-managed…
tetianakravchenko File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
176 changes: 176 additions & 0 deletions
176
docs/en/ingest-management/elastic-agent/running-on-eks-managed-by-fleet.asciidoc
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,176 @@ | ||
[[running-on-eks-managed-by-fleet]] | ||
= Run {agent} on Amazon EKS managed by {fleet} | ||
|
||
Use {agent} https://www.docker.elastic.co/r/beats/elastic-agent[Docker images] on Kubernetes to | ||
retrieve cluster metrics. | ||
|
||
TIP: Running {ecloud} on Kubernetes? Refer to {eck-ref}/k8s-elastic-agent-fleet.html[Run {elastic-agent} on ECK]. | ||
|
||
ifeval::["{release-state}"=="unreleased"] | ||
|
||
However, version {version} of {agent} has not yet been | ||
released, so no Docker image is currently available for this version. | ||
|
||
endif::[] | ||
|
||
[discrete] | ||
== Important Notes: | ||
|
||
On managed Kubernetes solutions like EKS, {agent} has no access to several data sources. Find below the list of the non available data: | ||
|
||
1. Metrics from https://kubernetes.io/docs/concepts/overview/components/#control-plane-components[Kubernetes control plane] | ||
components are not available. Consequently metrics are not available for `kube-scheduler` and `kube-controller-manager` components. | ||
In this regard, the respective **dashboards** will not be populated with data. | ||
2. **Audit logs** are available only on Kubernetes master nodes as well, hence cannot be collected by {agent}. | ||
3. Fields `orchestrator.cluster.name` and `orchestrator.cluster.url` are not populated. `orchestrator.cluster.name` field is used as a cluster selector for default Kubernetes dashboards, shipped with https://docs.elastic.co/en/integrations/kubernetes[Kubernetes integration]. | ||
+ | ||
In this regard, you can use https://www.elastic.co/guide/en/beats/filebeat/current/add-fields.html[`add_fields` processor] to add `orchestrator.cluster.name` and `orchestrator.cluster.url` fields for each https://docs.elastic.co/en/integrations/kubernetes[Kubernetes integration]'s component: | ||
+ | ||
[source,yaml] | ||
.Processors configuration | ||
------------------------------------------------ | ||
- add_fields: | ||
target: orchestrator.cluster | ||
fields: | ||
name: clusterName | ||
url: clusterURL | ||
------------------------------------------------ | ||
|
||
[discrete] | ||
== Prerequisites | ||
|
||
`kube-state-metrics` is not deployed by default in Amazon EKS! | ||
|
||
Data_streams with the `state_` prefix require `kube-state-metrics` to be present. | ||
|
||
In order to install `kube-state-metrics` follow the instructions for its deployment, that are available | ||
https://github.com/kubernetes/kube-state-metrics#kubernetes-deployment[here]. | ||
Generally `kube-state-metrics` runs a `Deployment` and is accessible via a service called `kube-state-metrics` on | ||
`kube-system` namespace, which will be the service to use in agent configuration. | ||
|
||
[discrete] | ||
== 1. Configure a Fleet policy | ||
|
||
In order for the Agents to enable the proper inputs, they need to be enrolled to the proper policy. | ||
For achieving Kubernetes observability, one need to create a policy and enable the Kubernetes integration. | ||
|
||
Refer to <<create-a-policy>> to learn how to enable | ||
the https://docs.elastic.co/en/integrations/kubernetes[Kubernetes integration]. | ||
|
||
[discrete] | ||
== 2. Enroll Elastic Agent to Fleet | ||
|
||
With {fleet}, each agent enrolls in a policy defined in {kib} and stored in | ||
{es}. The policy specifies how to collect observability data from the services | ||
to be monitored. The {agent} connects to a trusted {fleet-server} instance | ||
to retrieve the policy and report agent events. | ||
|
||
We recommend using {fleet} management because it makes the management and | ||
upgrade of agents' integrations considerably easier. | ||
|
||
{agent} is enrolled to a running {fleet-server} using `FLEET_URL` parameter. | ||
The `FLEET_ENROLLMENT_TOKEN` parameter is used to connect {agent} to a | ||
specific {agent} policy. | ||
To learn how to get an enrollment token from {fleet}, see <<fleet-enrollment-tokens>>. | ||
|
||
// forces a unique ID so that settings can be included multiple times on the same page | ||
:type: k8s-eks | ||
|
||
To specify different destination/credentials, | ||
change the following parameters in the manifest file: | ||
|
||
[source,yaml] | ||
------------------------------------------------ | ||
- name: FLEET_URL | ||
value: "https://fleet-server_url:port" | ||
- name: FLEET_ENROLLMENT_TOKEN | ||
value: "token" | ||
------------------------------------------------ | ||
|
||
// Begin collapsed section | ||
[%collapsible] | ||
.Configuration details | ||
==== | ||
**** | ||
|
||
[cols="2*<a"] | ||
|=== | ||
| Settings | Description | ||
|
||
include::configuration/env/shared-env.asciidoc[tag=fleet-url] | ||
|
||
include::configuration/env/shared-env.asciidoc[tag=fleet-enrollment-token] | ||
|
||
|=== | ||
|
||
Refer to <<agent-environment-variables>> for all available options. | ||
|
||
**** | ||
==== | ||
|
||
[discrete] | ||
== 3. Deploy kubernetes manifests | ||
|
||
On Kubernetes, we suggest deploying {agent} as a https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/[DaemonSet] | ||
to ensure that there is a running instance on each node of the cluster. | ||
These instances are used to retrieve metrics from the host, such as system metrics, container stats, | ||
and metrics from all the services running on top of Kubernetes. | ||
|
||
In addition, one of the Pods in the DaemonSet will constantly hold a _leader lock_ which makes it responsible for | ||
handling cluster-wide monitoring. | ||
Find more information about leader election configuration options at <<kubernetes_leaderelection-provider, leader election provider>>. | ||
This instance is used to retrieve metrics that are unique for the whole | ||
cluster, such as Kubernetes events or | ||
https://github.com/kubernetes/kube-state-metrics[kube-state-metrics]. | ||
|
||
|
||
Default namespace of deployment is `kube-system` . To change | ||
the namespace, modify the manifest file. | ||
|
||
To download the manifest file, run: | ||
|
||
["source", "sh", subs="attributes"] | ||
------------------------------------------------ | ||
curl -L -O https://raw.githubusercontent.com/elastic/elastic-agent/{branch}/deploy/kubernetes/elastic-agent-managed-kubernetes.yaml | ||
------------------------------------------------ | ||
|
||
To deploy {agent} on Kubernetes, run: | ||
|
||
["source", "sh", subs="attributes"] | ||
------------------------------------------------ | ||
kubectl create -f elastic-agent-managed-kubernetes.yaml | ||
------------------------------------------------ | ||
|
||
To check the status, run: | ||
|
||
["source", "sh", subs="attributes"] | ||
------------------------------------------------ | ||
$ kubectl get pod -n kube-system -l app=elastic-agent | ||
|
||
NAME READY STATUS RESTARTS AGE | ||
elastic-agent-hrjbg 1/1 Running 0 12m | ||
elastic-agent-olpsd 1/1 Running 0 12m | ||
------------------------------------------------ | ||
|
||
NOTE: You might need to adjust https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/[resource limits] of the elastic-agent container | ||
in the `elastic-agent-managed-kubernetes.yaml` manifest. Container resource usage depends on the number of data streams | ||
and the environment size. | ||
|
||
{agent}s should be enrolled to {fleet} and users should be able to see Kubernetes data flowing to Elastic accordingly. | ||
This can be confirmed in {kib} under {fleet} / Agents section. | ||
|
||
|
||
[discrete] | ||
== Deploying {agent} to collect cluster-level metrics in large clusters | ||
|
||
The size and the number of nodes in a Kubernetes cluster can be fairly large at times, | ||
and in such cases the Pod that will be collecting cluster level metrics might face performance | ||
issues due to resources limitations. In this case users might consider to avoid using the | ||
leader election strategy and instead run a dedicated, standalone {agent} instance using | ||
a Deployment in addition to the DaemonSet. | ||
|
||
[discrete] | ||
== Verify installation | ||
|
||
After Agents are successfully enrolled one can navigate to Kibana under **Analytics** > **Dashboards** > `[Metrics Kubernetes] Cluster Overview` | ||
dashboard and start exploring the incoming data as well build their own visualisations and dashboards. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
link to the view: https://observability-docs_2360.docs-preview.app.elstc.co/guide/en/fleet/master/install-elastic-agents-in-containers.html