[8.16] Add docs for installing agent using Helm (backport #1375)

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

@@ -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.
+
+[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].