-
Notifications
You must be signed in to change notification settings - Fork 73
Add docs for installing agent using Helm #1375
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
Merged
Merged
Changes from all commits
Commits
Show all changes
5 commits
Select commit
Hold shift + click to select a range
be78917
Add docs for installing agent using Helm
kilfoyle a55a70a
Fixup
kilfoyle 568bd95
Add link to examples; Note to use 8.16 branch
kilfoyle 3a66f62
Address Karen's feedback
kilfoyle c936e51
Add link to Helm install from 'Deployment models' page
kilfoyle 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
152 changes: 152 additions & 0 deletions
152
...t-management/elastic-agent/example-kubernetes-fleet-managed-agent-helm.asciidoc
This file contains hidden or 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,152 @@ | ||
[[example-kubernetes-fleet-managed-agent-helm]] | ||
= Example: Install {fleet}-managed {agent} on {k8s} using Helm | ||
|
||
preview::[] | ||
|
||
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}. | ||
|
||
For an overview of the {agent} Helm chart and its benefits, refer to <<install-on-kubernetes-using-helm>>. | ||
|
||
This guide takes you through these steps: | ||
|
||
* <<agent-fleet-managed-helm-example-install-agent>> | ||
* <<agent-fleet-managed-helm-example-install-integration>> | ||
* <<agent-fleet-managed-helm-example-tidy-up>> | ||
|
||
|
||
[discrete] | ||
[[agent-fleet-managed-helm-example-prereqs]] | ||
=== Prerequisites | ||
|
||
To get started, you need: | ||
|
||
* A local install of the link:https://helm.sh/[Helm] {k8s} package manager. | ||
* An link:{ess-trial}[{ecloud}] hosted {es} cluster on version 8.16 or higher. | ||
* An active {k8s} cluster. | ||
* 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. | ||
kilfoyle marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
[discrete] | ||
[[agent-fleet-managed-helm-example-install-agent]] | ||
=== Install {agent} | ||
|
||
. Open your {ecloud} deployment, and from the navigation menu select **Fleet**. | ||
. From the **Agents** tab, select **Add agent**. | ||
. In the **Add agent** UI, specify a policy name and select **Create policy**. Leave the **Collect system logs and metrics** option selected. | ||
. Scroll down in the **Add agent** flyout to the **Install Elastic Agent on your host** section. | ||
. 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. | ||
. Open a terminal shell and change into a directory in your local clone of the `elastic-agent` repo. | ||
. Copy this command. | ||
+ | ||
[source,sh] | ||
---- | ||
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 | ||
---- | ||
+ | ||
Note that the command has these properties: | ||
|
||
* `helm install` runs the Helm CLI install tool. | ||
* `demo` gives a name to the installed chart. You can choose any name. | ||
* `./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). | ||
* `--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. | ||
* `--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). | ||
* `--set agent.fleet.token=<Fleet-token>` sets the enrollment token that {agent} uses to authenticate with {fleet}. | ||
* `--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`). | ||
+ | ||
-- | ||
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]. | ||
-- | ||
. Update the command to replace: | ||
.. `<Fleet-URL>` with the URL that you copied earlier. | ||
.. `<Fleet-token>` with the enrollment token that you copied earlier. | ||
+ | ||
After your updates, the command should look something like this: | ||
+ | ||
[source,sh] | ||
---- | ||
helm install demo ./deploy/helm/elastic-agent \ | ||
--set agent.fleet.enabled=true \ | ||
--set agent.fleet.url=https://256575858845283fxxxxxxxd5265d2b4.fleet.us-central1.gcp.foundit.no:443 \ | ||
--set agent.fleet.token=eSVvFDUvSUNPFldFdhhZNFwvS5xxxxxxxxxxxxFEWB1eFF1YedUQ1NWFXwr== \ | ||
--set agent.fleet.preset=perNode | ||
---- | ||
|
||
. Run the command. | ||
+ | ||
The command output should confirm that {agent} has been installed: | ||
+ | ||
[source,sh] | ||
---- | ||
... | ||
Installed agent: | ||
- perNode [daemonset - managed mode] | ||
... | ||
---- | ||
|
||
. Run the `kubectl get pods -n default` command to confirm that the {agent} pod is running: | ||
+ | ||
[source,sh] | ||
---- | ||
NAME READY STATUS RESTARTS AGE | ||
agent-pernode-demo-86mst 1/1 Running 0 12s | ||
---- | ||
|
||
. In the **Add agent** flyout, wait a minute or so for confirmation that {agent} has successfully enrolled with {fleet} and that data is flowing: | ||
+ | ||
[role="screenshot"] | ||
image::images/helm-example-nodes-enrollment-confirmation.png[Screen capture of Add Agent UI showing that the agent has enrolled in Fleet] | ||
|
||
. In {fleet}, open the **Agents** tab and see that an **Agent-pernode-demo-#####** agent is running. | ||
|
||
. Select the agent to view its details. | ||
|
||
. 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. | ||
+ | ||
[role="screenshot"] | ||
image::images/helm-example-nodes-logs-and-metrics.png[Screen capture of the Logs and Metrics view on the Integrations pane] | ||
|
||
|
||
[discrete] | ||
[[agent-fleet-managed-helm-example-install-integration]] | ||
=== Install the Kubernetes integration | ||
|
||
Now that you've {agent} and data is flowing, you can set up the {k8s} integration. | ||
|
||
. In your {ecloud} deployment, from the {kib} menu open the **Integrations** page. | ||
. Run a search for `Kubernetes` and then select the {k8s} integration card. | ||
. On the {k8s} integration page, click **Add Kubernetes** to add the integration to your {agent} policy. | ||
. 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. | ||
+ | ||
You can leave all of the other integration settings at their default values. | ||
. Click **Save and continue**. When prompted, select to **Add Elastic Agent later** since you've already added it using Helm. | ||
. On the {k8s} integration page, open the **Assets** tab and select the **[Metrics Kubernetes] Pods** dashboard. | ||
+ | ||
On the dashboard, you can view the status of your {k8s} pods, including metrics on memory usage, CPU usage, and network throughput. | ||
+ | ||
[role="screenshot"] | ||
image::images/helm-example-fleet-metrics-dashboard.png[Screen capture of the Metrics Kubernetes pods dashboard] | ||
|
||
You've successfully installed {agent} using Helm, and your {k8s} metrics data is available for viewing in {kib}. | ||
|
||
[discrete] | ||
[[agent-fleet-managed-helm-example-tidy-up]] | ||
=== Tidy up | ||
|
||
After you've run through this example, run the `helm uninstall` command to uninstall {agent}. | ||
|
||
[source,sh] | ||
---- | ||
helm uninstall demo | ||
---- | ||
|
||
The uninstall should be confirmed as shown: | ||
|
||
[source,sh] | ||
---- | ||
release "demo" uninstalled | ||
---- | ||
|
||
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]. |
Oops, something went wrong.
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.
Uh oh!
There was an error while loading. Please reload this page.