Skip to content

Commit be78917

Browse files
kilfoylekilfoyle
committed
Add docs for installing agent using Helm
1 parent 98d9db9 commit be78917

9 files changed

+441
-0
lines changed

‎docs/en/ingest-management/elastic-agent/example-kubernetes-fleet-managed-agent-helm.asciidoc‎

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
[[example-kubernetes-fleet-managed-agent-helm]]
2+
= Example: Install {fleet}-managed {agent} on Kubernetes using Helm
3+
4+
This example demonstrates how to install {fleet}-managed {agent} on a Kubernetes system using a Helm chart, in order to gather Kubernetes metrics and send them to an {es} cluster in an {ecloud} deployment.
5+
6+
* <<agent-fleet-managed-helm-example-install-agent>>
7+
* <<agent-fleet-managed-helm-example-install-integration>>
8+
* <<agent-fleet-managed-helm-example-tidy-up>>
9+
10+
11+
[discrete]
12+
[[agent-fleet-managed-helm-example-prereqs]]
13+
=== Prerequisites
14+
15+
To get started, you need:
16+
17+
* A local install of the link:https://helm.sh/[Helm] Kubernetes package manager.
18+
* An {ess} deployment on version 8.16 or higher.
19+
* An {es} API key. Refer to <<create-api-key-standalone-agent,Create API keys for standalone agents>> for the steps to create a new API key.
20+
* An active Kubernetes cluster. For this example we're using a local Kubernetes test environment using Kind.
21+
* A local clone of the link:https://github.com/elastic/elastic-agent[elastic/elastic-agent] GitHub repository.
22+
23+
[discrete]
24+
[[agent-fleet-managed-helm-example-install-agent]]
25+
=== Install {agent}
26+
27+
. Open your {ecloud} deployment, and from the navigation menu select **Fleet**.
28+
. From the **Agents** tab, select **Add agent**.
29+
. In the **Add agent** UI, specify a policy name and select **Create policy**. Leave the **Collect system logs and metrics** selected.
30+
. Scroll down in the **Add agent** flyout to the **Install Elastic Agent on your host** section.
31+
. Select the **Linux TAR** tab and copy the values for `url` and `enrollment-token`. You'll use these when you run the `helm install` command.
32+
. Open a terminal shell and change into a directory in your local clone of the `elastic-agent` repo.
33+
. Copy the command below. Before running it you'll need to make a couple of changes.
34+
+
35+
[source,sh]
36+
----
37+
helm install demo ./deploy/helm/elastic-agent --set agent.fleet.enabled=true --set agent.fleet.url=<Fleet-URL> --set agent.fleet.token=<Fleet-token> --set agent.fleet.preset=perNode
38+
----
39+
+
40+
The command has the following properties:
41+
42+
* `helm install` runs the Helm CLI install tool.
43+
* `demo` gives a name to the installed chart. You can choose any name.
44+
* `./deploy/helm/elastic-agent` is a local path to the Helm chart (once the Helm chart has been published, this path can be to a public URL).
45+
* `--set agent.fleet.enabled=true` enables {fleet}-managed {agent} by overriding the default setting `agent.fleet.enabled` in the {agent} link:https://github.com/elastic/elastic-agent/blob/main/deploy/helm/elastic-agent/values.yaml[values.yaml] file, changing it to `true`.
46+
* `--set agent.fleet.url=<Fleet-URL>` sets the address where {agent} will connect to {fleet} in your {ecloud} deployment over port 443 (again, overriding the setting as defined in the {agent} link:https://github.com/elastic/elastic-agent/blob/main/deploy/helm/elastic-agent/values.yaml[values.yaml] file).
47+
* `--set agent.fleet.token=<Fleet-token>` sets the enrollment token that {agent} uses to authenticate with {fleet}.
48+
* `--set agent.fleet.preset=perNode` enables Kubernetes metrics on `per node` basis. You can alternatively set cluster wide metrics (`clusterWide`) or kube-state-metrics (`ksmSharded`).
49+
+
50+
--
51+
TIP: For a full list of all available YAML settings and descriptions, refer to the link:https://github.com/elastic/elastic-agent/tree/main/deploy/helm/elastic-agent[{agent} Helm Chart Readme].
52+
--
53+
. Update the command to replace:
54+
.. `<Fleet-URL>` with the value for `url` that you copied earlier.
55+
.. `<Fleet-token>` with value for `enrollment-token` that you copied earlier.
56+
+
57+
After your updates, the command should look something like this:
58+
+
59+
[source,sh]
60+
----
61+
helm install demo ./deploy/helm/elastic-agent --set agent.fleet.enabled=true --set agent.fleet.url=https://256575858845283f9eea4b2d5265d2b4.fleet.us-central1.gcp.foundit.no:443 --set agent.fleet.token=eSVvFDUvSUNPFldFdhhZNFwvS5g6XHMxY3y0PFEWB1eFF1YedUQ1NWFXwr== --set agent.fleet.preset=perNode
62+
----
63+
64+
. Run the command.
65+
+
66+
The command output should confirm that three {agents} have been installed as well as the Kubernetes integration:
67+
+
68+
[source,sh]
69+
----
70+
...
71+
Installed agent:
72+
- perNode [daemonset - managed mode]
73+
...
74+
----
75+
76+
. Run the `kubectl get pods -n default` command to confirm that the {agent} pods are running:
77+
+
78+
[source,sh]
79+
----
80+
NAME READY STATUS RESTARTS AGE
81+
agent-pernode-demo-86mst 1/1 Running 0 12s
82+
----
83+
84+
. In the **Add agent** flyout, wait a check for confirmation that {agent} has successfully enrolled with {fleet} and that data is flowing (you may need to wait for a minute or so):
85+
+
86+
[role="screenshot"]
87+
image::images/helm-example-nodes-enrollment-confirmation.png[Screen capture of Add Agent UI showing that the agent has enrolled in Fleet]
88+
89+
. In {fleet}, open the **Agents** tab and see that an **Agent-pernode-demo-#####** agent is running.
90+
91+
. Select the agent to view its details.
92+
93+
. On the **Agent details** tab, on the **Integrations** pane, expand `system-1` to confirm that logs and metrics are incoming. You can click either the `Logs` or `Metrics` links to view details.
94+
+
95+
[role="screenshot"]
96+
image::images/helm-example-nodes-logs-and-metrics.png[Screen capture of the Logs and Metrics view on the Integrations pane]
97+
98+
99+
[discrete]
100+
[[agent-fleet-managed-helm-example-install-integration]]
101+
=== Install the Kubernetes integration
102+
103+
Now that you've {agent} and data is flowing, you can set up the Kubernetes integration.
104+
105+
. In your {ecloud} deployment, from the {kib} menu open the **Integrations** page.
106+
. Run a search for `Kubernetes` and then select the Kubernetes integration card.
107+
. On the Kubernetes integration page, click **Add Kubernetes** to add the integration to your {agent} policy.
108+
. Scroll to the bottom of **Add Kubernetes integration** page. Under **Where to add this integration?** select the **Existing hosts** tab. On the **Agent policies** menu, select the agent policy that you created previously in the <<agent-fleet-managed-helm-example-install-agent>> steps.
109+
. For this example, you can leave all of the other integration settings at their default values.
110+
. Click **Save and continue**. When prompted, select to **Add Elastic Agent later** since you've already added it using Helm.
111+
. On the Kubernetes integration page, open the **Assets** tab and select the **[Metrics Kubernetes] Pods** dashboard.
112+
+
113+
On the dashboard, you can view the status of your Kubernetes pods, including metrics on memory usage, CPU usage, and network throughput.
114+
+
115+
[role="screenshot"]
116+
image::images/helm-example-fleet-metrics-dashboard.png[Screen capture of the Metrics Kubernetes pods dashboard]
117+
118+
[discrete]
119+
[[agent-fleet-managed-helm-example-tidy-up]]
120+
=== Tidy up
121+
122+
After you've run through this example, to uninstall {agent} simply run the `helm uninstall` command.
123+
124+
[source,sh]
125+
----
126+
helm uninstall demo
127+
----
128+
129+
The uninstall should be confirmed as shown:
130+
131+
[source,sh]
132+
----
133+
release "demo" uninstalled
134+
----
135+
136+
As a reminder, for full details about using the {agent} Helm chart refer to the link:https://github.com/elastic/elastic-agent/tree/main/deploy/helm/elastic-agent[{agent} Helm Chart Readme].
137+
138+
139+
140+
141+
142+

0 commit comments

Comments
 (0)