[[running-on-kubernetes]]
[role="xpack"]
=== Run {agent} on Kubernetes

You can use {agent} https://www.docker.elastic.co/r/beats/elastic-agent[Docker images] on Kubernetes to
retrieve cluster metrics.

ifeval::["{release-state}"=="unreleased"]

However, version {version} of {agent} has not yet been
released, so no Docker image is currently available for this version.

endif::[]


[float]
==== Kubernetes deploy manifests

You deploy {agent} in two different ways at the same time:

* As a https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/[DaemonSet]
to ensure that there's a running instance on each node of the cluster. These
instances are used to retrieve most metrics from the host, such as system
metrics, Docker stats, and metrics from all the services running on top of
Kubernetes.

* As a single {agent} instance created using a https://kubernetes.io/docs/concepts/workloads/controllers/Deployment/[Deployment].
This instance is used to retrieve metrics that are unique for the whole
cluster, such as Kubernetes events or
https://github.com/kubernetes/kube-state-metrics[kube-state-metrics].

Everything is deployed under the `kube-system` namespace by default. To change
the namespace, modify the manifest file.

To download the manifest file, run:

["source", "sh", subs="attributes"]
------------------------------------------------
curl -L -O https://raw.githubusercontent.com/elastic/beats/{branch}/deploy/kubernetes/elastic-agent-kubernetes.yaml
------------------------------------------------

[float]
==== Settings

By default, {agent} is enrolled to an existing Kibana deployment,
if present using the specified credentials. FLEET_ENROLLMENT_TOKEN parameter is used to connect Agent to the
corresponding {agent} policy. It is suggested to connect Daemonset Agents to a node scope configuration
and Deployment Agent to a cluster scope configuration. Then Kubernetes package will be deployed enabling cluster scope
datasets using cluster scope configuration while node scope datasets will be enabled under node scope configuration.

To specify different destination/credentials,
change the following parameters in the manifest file:

[source,yaml]
------------------------------------------------
- name: FLEET_ENROLLMENT_TOKEN
  value: "abcdf_token"
- name: KIBANA_HOST
  value: "http://kibana:5601"
- name: KIBANA_USERNAME
  value: "elastic"
- name: KIBANA_PASSWORD
  value: "changeme"
------------------------------------------------

[float]
===== Running {agent} on master nodes

Kubernetes master nodes can use https://kubernetes.io/docs/concepts/configuration/taint-and-toleration/[taints]
to limit the workloads that can run on them. To run {agent} on master nodes you may need to
update the Daemonset spec to include proper tolerations:

[source,yaml]
------------------------------------------------
spec:
 tolerations:
 - key: node-role.kubernetes.io/master
   effect: NoSchedule
------------------------------------------------


[float]
==== Deploy

If planing to deploy `state_*` datasets of Kubernetes package,
https://github.com/kubernetes/kube-state-metrics#usage[kube-state-metrics] is needed to be already deployed
in the cluster. If `kube-state-metrics` is not already running, deploy it now (see the
https://github.com/kubernetes/kube-state-metrics#kubernetes-deployment[Kubernetes
deployment] docs).

To deploy to Kubernetes, run:

["source", "sh", subs="attributes"]
------------------------------------------------
kubectl create -f elastic-agent-kubernetes.yaml
------------------------------------------------

To check the status, run:

["source", "sh", subs="attributes"]
------------------------------------------------
$ kubectl --namespace=kube-system get pods -l group=ingest-management

NAME                                                    READY   STATUS    RESTARTS   AGE
agent-ingest-management-clusterscope-574dbfc48f-sfrdt   1/1     Running     3        8d
agent-ingest-management-nodescope-jt9zj                 1/1     Running     3        8d
------------------------------------------------

Agents should be enrolled to Fleet and user should be able to deploy Kubernetes package accordingly.
