Skip to content

Commit fa8dc0f

Browse files
mergify[bot]kilfoyle
mergify[bot]
and
kilfoyle
authored
Add docs for installing agent using Helm (elastic#1375) (elastic#1443)
* Add docs for installing agent using Helm * Fixup * Add link to examples; Note to use 8.16 branch * Address Karen's feedback * Add link to Helm install from 'Deployment models' page (cherry picked from commit 160c9fd) Co-authored-by: David Kilfoyle <41695641+kilfoyle@users.noreply.github.com>
1 parent 659d1a2 commit fa8dc0f

10 files changed

+473
-1
lines changed

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

+152
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
[[example-kubernetes-fleet-managed-agent-helm]]
2+
= Example: Install {fleet}-managed {agent} on {k8s} using Helm
3+
4+
preview::[]
5+
6+
This example demonstrates how to install {fleet}-managed {agent} on a {k8s} system using a Helm chart, gather {k8s} metrics and send them to an {es} cluster in {ecloud}, and then view visualizations of those metrics in {kib}.
7+
8+
For an overview of the {agent} Helm chart and its benefits, refer to <<install-on-kubernetes-using-helm>>.
9+
10+
This guide takes you through these steps:
11+
12+
* <<agent-fleet-managed-helm-example-install-agent>>
13+
* <<agent-fleet-managed-helm-example-install-integration>>
14+
* <<agent-fleet-managed-helm-example-tidy-up>>
15+
16+
17+
[discrete]
18+
[[agent-fleet-managed-helm-example-prereqs]]
19+
=== Prerequisites
20+
21+
To get started, you need:
22+
23+
* A local install of the link:https://helm.sh/[Helm] {k8s} package manager.
24+
* An link:{ess-trial}[{ecloud}] hosted {es} cluster on version 8.16 or higher.
25+
* An active {k8s} cluster.
26+
* A local clone of the link:https://github.com/elastic/elastic-agent/tree/8.16[elastic/elastic-agent] GitHub repository. Make sure to use the `8.16` branch to ensure that {agent} has full compatibility with the Helm chart.
27+
28+
[discrete]
29+
[[agent-fleet-managed-helm-example-install-agent]]
30+
=== Install {agent}
31+
32+
. Open your {ecloud} deployment, and from the navigation menu select **Fleet**.
33+
. From the **Agents** tab, select **Add agent**.
34+
. In the **Add agent** UI, specify a policy name and select **Create policy**. Leave the **Collect system logs and metrics** option selected.
35+
. Scroll down in the **Add agent** flyout to the **Install Elastic Agent on your host** section.
36+
. 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.
37+
. Open a terminal shell and change into a directory in your local clone of the `elastic-agent` repo.
38+
. Copy this command.
39+
+
40+
[source,sh]
41+
----
42+
helm install demo ./deploy/helm/elastic-agent \
43+
--set agent.fleet.enabled=true \
44+
--set agent.fleet.url=<Fleet-URL> \
45+
--set agent.fleet.token=<Fleet-token> \
46+
--set agent.fleet.preset=perNode
47+
----
48+
+
49+
Note that the command has these properties:
50+
51+
* `helm install` runs the Helm CLI install tool.
52+
* `demo` gives a name to the installed chart. You can choose any name.
53+
* `./deploy/helm/elastic-agent` is a local path to the Helm chart to install (in time it's planned to have a public URL for the chart).
54+
* `--set agent.fleet.enabled=true` enables {fleet}-managed {agent}. The CLI parameter overrides the default `false` value for `agent.fleet.enabled` in the {agent} link:https://github.com/elastic/elastic-agent/blob/main/deploy/helm/elastic-agent/values.yaml[values.yaml] file.
55+
* `--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 value set by default in the {agent} link:https://github.com/elastic/elastic-agent/blob/main/deploy/helm/elastic-agent/values.yaml[values.yaml] file).
56+
* `--set agent.fleet.token=<Fleet-token>` sets the enrollment token that {agent} uses to authenticate with {fleet}.
57+
* `--set agent.fleet.preset=perNode` enables {k8s} metrics on `per node` basis. You can alternatively set cluster wide metrics (`clusterWide`) or kube-state-metrics (`ksmSharded`).
58+
+
59+
--
60+
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].
61+
--
62+
. Update the command to replace:
63+
.. `<Fleet-URL>` with the URL that you copied earlier.
64+
.. `<Fleet-token>` with the enrollment token that you copied earlier.
65+
+
66+
After your updates, the command should look something like this:
67+
+
68+
[source,sh]
69+
----
70+
helm install demo ./deploy/helm/elastic-agent \
71+
--set agent.fleet.enabled=true \
72+
--set agent.fleet.url=https://256575858845283fxxxxxxxd5265d2b4.fleet.us-central1.gcp.foundit.no:443 \
73+
--set agent.fleet.token=eSVvFDUvSUNPFldFdhhZNFwvS5xxxxxxxxxxxxFEWB1eFF1YedUQ1NWFXwr== \
74+
--set agent.fleet.preset=perNode
75+
----
76+
77+
. Run the command.
78+
+
79+
The command output should confirm that {agent} has been installed:
80+
+
81+
[source,sh]
82+
----
83+
...
84+
Installed agent:
85+
- perNode [daemonset - managed mode]
86+
...
87+
----
88+
89+
. Run the `kubectl get pods -n default` command to confirm that the {agent} pod is running:
90+
+
91+
[source,sh]
92+
----
93+
NAME READY STATUS RESTARTS AGE
94+
agent-pernode-demo-86mst 1/1 Running 0 12s
95+
----
96+
97+
. In the **Add agent** flyout, wait a minute or so for confirmation that {agent} has successfully enrolled with {fleet} and that data is flowing:
98+
+
99+
[role="screenshot"]
100+
image::images/helm-example-nodes-enrollment-confirmation.png[Screen capture of Add Agent UI showing that the agent has enrolled in Fleet]
101+
102+
. In {fleet}, open the **Agents** tab and see that an **Agent-pernode-demo-#####** agent is running.
103+
104+
. Select the agent to view its details.
105+
106+
. 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` link to view details.
107+
+
108+
[role="screenshot"]
109+
image::images/helm-example-nodes-logs-and-metrics.png[Screen capture of the Logs and Metrics view on the Integrations pane]
110+
111+
112+
[discrete]
113+
[[agent-fleet-managed-helm-example-install-integration]]
114+
=== Install the Kubernetes integration
115+
116+
Now that you've {agent} and data is flowing, you can set up the {k8s} integration.
117+
118+
. In your {ecloud} deployment, from the {kib} menu open the **Integrations** page.
119+
. Run a search for `Kubernetes` and then select the {k8s} integration card.
120+
. On the {k8s} integration page, click **Add Kubernetes** to add the integration to your {agent} policy.
121+
. 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.
122+
+
123+
You can leave all of the other integration settings at their default values.
124+
. Click **Save and continue**. When prompted, select to **Add Elastic Agent later** since you've already added it using Helm.
125+
. On the {k8s} integration page, open the **Assets** tab and select the **[Metrics Kubernetes] Pods** dashboard.
126+
+
127+
On the dashboard, you can view the status of your {k8s} pods, including metrics on memory usage, CPU usage, and network throughput.
128+
+
129+
[role="screenshot"]
130+
image::images/helm-example-fleet-metrics-dashboard.png[Screen capture of the Metrics Kubernetes pods dashboard]
131+
132+
You've successfully installed {agent} using Helm, and your {k8s} metrics data is available for viewing in {kib}.
133+
134+
[discrete]
135+
[[agent-fleet-managed-helm-example-tidy-up]]
136+
=== Tidy up
137+
138+
After you've run through this example, run the `helm uninstall` command to uninstall {agent}.
139+
140+
[source,sh]
141+
----
142+
helm uninstall demo
143+
----
144+
145+
The uninstall should be confirmed as shown:
146+
147+
[source,sh]
148+
----
149+
release "demo" uninstalled
150+
----
151+
152+
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].

0 commit comments

Comments
 (0)