Skip to content

Commit 759d6ec

Browse files
vishaangelovarhr323
authored andcommitted
Update Kubernetes quickstart guide with instructions for v9.2 (elastic#3597)
This PR updates the [Quickstart: Monitor your Kubernetes cluster with Elastic Agent](https://www.elastic.co/docs/solutions/observability/get-started/quickstart-monitor-kubernetes-cluster-with-elastic-agent) doc to include tje changes in the flow for the 9.2 version (using a `helm` command instead of `kubectl` one) by adding a separate tab for this version. Disclaimer: we’re using simple tabs as applies switches do not support version ranges yet. Also reordered the tabs to start with the Serverless use case as we aim to promote Serverless first. Resolves elastic#2456
1 parent 7b08868 commit 759d6ec

File tree

1 file changed

+99
-23
lines changed

1 file changed

+99
-23
lines changed

solutions/observability/get-started/quickstart-monitor-kubernetes-cluster-with-elastic-agent.md

Lines changed: 99 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -15,13 +15,26 @@ products:
1515

1616
In this quickstart guide, you’ll learn how to create the Kubernetes resources required to monitor your cluster infrastructure by using a single command to download, install, and configure {{agent}} in your Kubernetes cluster.
1717

18+
:::{note}
19+
In {{stack}} versions 9.0 and 9.1, the quickstart uses [Kubectl](https://kubernetes.io/docs/reference/kubectl/) to install {{agent}} in a Kubernetes cluster. However, these versions also support using [Helm](https://helm.sh/docs/) charts, which is now the preferred method for installing {{agent}} on Kubernetes. If your cluster is on version 9.0 or 9.1, we recommend that you follow the [Install Elastic Agent on Kubernetes using Helm](/reference/fleet/install-on-kubernetes-using-helm.md) guide to deploy {{agent}}.
20+
:::
21+
1822
## Prerequisites [_prerequisites_2]
1923

2024
:::::{tab-set}
2125
:group: stack-serverless
2226

23-
::::{tab-item} {{stack}}
24-
:sync: stack
27+
::::{tab-item} {{serverless-short}}
28+
:sync: serverless
29+
30+
* An {{obs-serverless}} project. To learn more, refer to [Create an Observability project](/solutions/observability/get-started.md).
31+
* A user with the **Admin** role or higher (required to onboard system logs and metrics). To learn more, refer to [Assign user roles and privileges](/deploy-manage/users-roles/cloud-organization/user-roles.md#general-assign-user-roles).
32+
* A running Kubernetes cluster with internet access
33+
* [Helm](https://helm.sh/docs/)
34+
::::
35+
36+
::::{tab-item} {{stack}} 9.2 and later
37+
:sync: stack-9.2
2538

2639
* A running {{stack}} deployment, either self-managed or orchestrated by platforms like {{ech}}, {{ece}}, or {{eck}}, with internet access. To get started quickly, try out [{{ecloud}}](https://cloud.elastic.co/registration?page=docs&placement=docs-body).
2740
* A user with the `superuser` [built-in role](elasticsearch://reference/elasticsearch/roles.md) or the privileges required to onboard data.
@@ -33,16 +46,23 @@ In this quickstart guide, you’ll learn how to create the Kubernetes resources
3346
:::
3447

3548
* A running Kubernetes cluster with internet access
36-
* [Kubectl](https://kubernetes.io/docs/reference/kubectl/)
49+
* [Helm](https://helm.sh/docs/)
3750
::::
3851

39-
::::{tab-item} Serverless
40-
:sync: serverless
52+
::::{tab-item} {{stack}} 9.0-9.1
53+
:sync: stack-9.0-9.1
54+
55+
* A running {{stack}} deployment, either self-managed or orchestrated by platforms like {{ech}}, {{ece}}, or {{eck}}, with internet access. To get started quickly, try out [{{ecloud}}](https://cloud.elastic.co/registration?page=docs&placement=docs-body).
56+
* A user with the `superuser` [built-in role](elasticsearch://reference/elasticsearch/roles.md) or the privileges required to onboard data.
57+
58+
:::{dropdown} Expand to view required privileges
59+
* [**Cluster**](elasticsearch://reference/elasticsearch/security-privileges.md#privileges-list-cluster): `['monitor', 'manage_own_api_key']`
60+
* [**Index**](elasticsearch://reference/elasticsearch/security-privileges.md#privileges-list-indices): `{ names: ['logs-*-*', 'metrics-*-*'], privileges: ['auto_configure', 'create_doc'] }`
61+
* [**Kibana**](/deploy-manage/users-roles/cluster-or-deployment-auth/kibana-privileges.md): `{ spaces: ['*'], feature: { fleet: ['all'], fleetv2: ['all'] } }`
62+
:::
4163

42-
* An {{obs-serverless}} project. To learn more, refer to [Create an Observability project](/solutions/observability/get-started.md).
43-
* A user with the **Admin** role or higher (required to onboard system logs and metrics). To learn more, refer to [Assign user roles and privileges](/deploy-manage/users-roles/cloud-organization/user-roles.md#general-assign-user-roles).
4464
* A running Kubernetes cluster with internet access
45-
* [Helm](https://helm.sh/docs/)
65+
* [Kubectl](https://kubernetes.io/docs/reference/kubectl/)
4666
::::
4767

4868
:::::
@@ -61,15 +81,36 @@ The installation command provided by the UI during the quickstart cannot be used
6181
:::::{tab-set}
6282
:group: stack-serverless
6383

64-
::::{tab-item} Elastic Stack
65-
:sync: stack
84+
::::{tab-item} {{serverless-short}}
85+
:sync: serverless
6686

67-
1. In {{kib}}, go to the **Observability** UI and click **Add Data**.
87+
1. Go to your [{{obs-serverless}}](/solutions/observability/get-started.md) project, then go to **Add data**.
6888
2. In the **What do you want to monitor?** section, select **Kubernetes**, and then select **Elastic Agent: Logs & Metrics**.
69-
7089
3. To install {{agent}} on your host, copy and run the install command.
7190

72-
By running this command, you use `kubectl kustomize` to download a manifest file, inject deployment-specific data such as the API key generated by {{kib}} for the acting user, and create the Kubernetes resources for {{agent}}.
91+
By running this command, you use the Helm package manager to install and configure an instance of the {{agent}} Helm chart with additional deployment-specific data such as the API key generated by {{kib}} for the acting user.
92+
93+
The Helm chart also includes a default installation of [`kube-state-metrics` (KSM)](https://github.com/kubernetes/kube-state-metrics), which is required by the Kubernetes integration to collect cluster-level metrics.
94+
95+
If you encounter an error during the installation, refer to [Troubleshooting](#monitor-k8s-with-agent-troubleshooting).
96+
97+
:::{dropdown} Details about the install command
98+
The install command provided by the UI may be similar to:
99+
100+
```sh subs=true
101+
helm repo add elastic https://helm.elastic.co/ && helm install elastic-agent elastic/elastic-agent --version {{version.stack}} -n kube-system --set outputs.default.url=https:<elasticsearch-url>:443 --set kubernetes.onboardingID=<internal-id> --set kubernetes.enabled=true --set outputs.default.type=ESPlainAuthAPI --set outputs.default.api_key=$(echo "<api-key>" | base64 -d)
102+
```
103+
104+
Where:
105+
106+
- `elastic-agent` is the name of the specific installation of the Helm chart, known as **release name**.
107+
- `elastic/elastic-agent` defines the name of the chart to install, using the format `<repository>/<chart-name>`.
108+
- {{version.stack}} is the version of the {{agent}} Helm chart to be installed.
109+
- `kube-system` is the namespace where {{agent}} is to be installed.
110+
- `--set` parameters add configuration values specific to the serverless project, the acting user, and the deployment method of the Helm chart.
111+
112+
Refer to [Install standalone Elastic Agent on Kubernetes using Helm](/reference/fleet/example-kubernetes-standalone-agent-helm.md#agent-standalone-helm-example-install) for a more detailed explanation of the configuration options used.
113+
:::
73114

74115
4. Go back to the **Kubernetes: Logs & Metrics** page in {{kib}}.
75116

@@ -79,10 +120,10 @@ The installation command provided by the UI during the quickstart cannot be used
79120

80121
::::
81122

82-
::::{tab-item} Serverless
83-
:sync: serverless
123+
::::{tab-item} {{stack}} 9.2 and later
124+
:sync: stack-9.2
84125

85-
1. Go to your [{{obs-serverless}}](/solutions/observability/get-started.md) project, then go to **Add Data**.
126+
1. In {{kib}}, go to the **Observability** overview page, and click **Add Data**.
86127
2. In the **What do you want to monitor?** section, select **Kubernetes**, and then select **Elastic Agent: Logs & Metrics**.
87128
3. To install {{agent}} on your host, copy and run the install command.
88129

@@ -118,6 +159,24 @@ The installation command provided by the UI during the quickstart cannot be used
118159

119160
::::
120161

162+
::::{tab-item} {{stack}} 9.0-9.1
163+
:sync: stack-9.0-9.1
164+
165+
1. In {{kib}}, go to the **Observability** UI and click **Add Data**.
166+
2. In the **What do you want to monitor?** section, select **Kubernetes**, and then select **Elastic Agent: Logs & Metrics**.
167+
168+
3. To install {{agent}} on your host, copy and run the install command.
169+
170+
By running this command, you use `kubectl kustomize` to download a manifest file, inject deployment-specific data such as the API key generated by {{kib}} for the acting user, and create the Kubernetes resources for {{agent}}.
171+
172+
4. Go back to the **Kubernetes: Logs & Metrics** page in {{kib}}.
173+
174+
There might be a slight delay before data is ingested. When ready, you will see the message **We are monitoring your cluster**.
175+
176+
5. Click **Explore Kubernetes cluster** to navigate to dashboards and explore your data.
177+
178+
::::
179+
121180
:::::
122181

123182
## Visualize your data [_visualize_your_data_2]
@@ -138,17 +197,25 @@ Refer to [Observability overview](/solutions/observability/get-started/what-is-e
138197
::::{tab-set}
139198
:group: stack-serverless
140199

141-
:::{tab-item} Elastic Stack
142-
:sync: stack
200+
:::{tab-item} {{serverless-short}}
201+
:sync: serverless
143202

144-
To uninstall {{agent}} and the Kubernetes resources installed with `kubectl`:
203+
To uninstall {{agent}} and the Kubernetes resources installed with Helm, run:
145204

146-
1. Copy the `kubectl` quickstart command for installing {{agent}} described in the [Collect your data](#_collect_your_data_2) section.
147-
2. Replace `| kubectl apply -f-` with `| kubectl delete -f-`, then run the command.
205+
```sh
206+
helm uninstall <release-name> -n <namespace> <1>
207+
```
208+
1. Substitute `<release-name>` with the release name and `<namespace>` with the namespace used in the quickstart command described in the [Collect your data](#_collect_your_data_2) section.
209+
210+
If you used the default values from the quickstart, the command would be:
211+
212+
```sh
213+
helm uninstall elastic-agent -n kube-system
214+
```
148215
:::
149216

150-
:::{tab-item} Serverless
151-
:sync: serverless
217+
:::{tab-item} {{stack}} 9.2 and later
218+
:sync: stack-9.2
152219

153220
To uninstall {{agent}} and the Kubernetes resources installed with Helm, run:
154221

@@ -164,6 +231,15 @@ helm uninstall elastic-agent -n kube-system
164231
```
165232
:::
166233

234+
:::{tab-item} {{stack}} 9.0-9.1
235+
:sync: stack-9.0-9.1
236+
237+
To uninstall {{agent}} and the Kubernetes resources installed with `kubectl`:
238+
239+
1. Copy the `kubectl` quickstart command for installing {{agent}} described in the [Collect your data](#_collect_your_data_2) section.
240+
2. Replace `| kubectl apply -f-` with `| kubectl delete -f-`, then run the command.
241+
:::
242+
167243
::::
168244

169245
## Troubleshooting [monitor-k8s-with-agent-troubleshooting]

0 commit comments

Comments
 (0)