Install Scalyr Agent (Kubernetes)

These instructions are for installing the Scalyr Agent as a DaemonSet on your Kubernetes cluster. If you plan to run the Agent directly on Linux, see the Linux installation page. For Windows, see the Windows installation page, and for running the Agent separately in a Docker container, see the Docker installation page.

We're assuming you have a conceptual understanding of Kubernetes such as DaemonSets, Pods, Nodes, Config Maps etc.

The Scalyr Agent is a daemon that uploads logs and container metrics from a Kubernetes cluster to Scalyr servers. This is achieved with the Kubernetes monitor plugin. This page has streamlined instructions to get you up and running quickly in a Kubernetes environment.

We implement the Kubernetes-recommended node-level logging architecture, running the Scalyr Agent as a DaemonSet in your cluster. The DaemonSet runs a Scalyr Agent pod on each node. Each Agent pod collects logs from all other pods running on the same node. By default, the Scalyr Agent will collect pod logs, container metrics, and Kubernetes Events for all nodes.

  • Logs: Log collection is supported regardless of underlying runtime (Docker Engine, Containerd, CRI-O etc). As long as the container logs are accessible to the Scalyr Agent pod, the Agent can monitor and upload them.
  • Metrics: Metrics are currently only supported for the Docker Engine runtime.
  • Kubernetes Events: Kubernetes Events represent state changes, errors or other Kubernetes system messages. The Scalyr Agent can monitor Kubernetes Events regardless of underlying runtime. For more details on Kubernetes Events, including how to disable event collection, see the Kubernetes Events monitor plugin.


Listed below are instructions for installing Scalyr Kubernetes Agent for the first time. These instructions are the recommended approach for Agent release 2.1.1 and above. Instructions for versions prior to 2.0.47 can be viewed here.

1. Create the `scalyr` namespace.

kubectl create namespace scalyr

2. Create a Secret that contains your Write Logs API key. You can find your API key here under "Logs Access Keys". Make sure the key has "write" access.

kubectl create secret generic scalyr-api-key --namespace=scalyr --from-literal=scalyr-api-key="(log in to view API tokens)"

3. Create a ConfigMap that defines your cluster name (and any other environment-aware variables you may need). We recommend doing this in a YAML file but you can also create it from literals.

> curl -O
> cat scalyr-agent-2-configmap.yaml
apiVersion: v1
kind: ConfigMap
  SCALYR_K8S_CLUSTER_NAME: <your_cluster_name>
  # EU customers must uncomment this next line:
  # Define any other environment variables for config variables that are "environment aware".
  # Most environment variables start with "SCALYR_"
  # See for more details.
  # Example:
  name: scalyr-config
  namespace: scalyr

> (Edit and save scalyr-agent-2-configmap.yaml)

> kubectl create -f scalyr-agent-2-configmap.yaml

4. Create the DaemonSet object that runs the Scalyr Agent in your cluster, as well as other objects it requires such as the service account granting the Scalyr Agent access to the Kubernetes API.

kubectl apply -f
kubectl apply -f

Note: If running on Google Kubernetes Engine v1.11.x and older, you must also execute the following command to circumvent a known permissions issue:

kubectl create clusterrolebinding cluster-admin-binding --namespace=scalyr --clusterrole cluster-admin --user <google_cloud_account>


Your cluster logs should be searchable in Scalyr within seconds. For further configuration refinements, please see Configuring Scalyr Agent (Kubernetes).


To upgrade the Scalyr Kubernetes Agent from version 2.1.1 or newer run:

kubectl apply -f
kubectl apply -f

This will perform a rolling upgrade of all Agent pods.

If you see errors containing `namespaces "scalyr" not found` when you upgrade, it is likely that you installed the Scalyr Agent using the instructions before the 2.1.1 Scalyr Agent release. See below for how to resolve this.

upgrade-pre-2.1.1 <Upgrading Scalyr Agents running in default namespace (pre-2.1.1)>

Upgrading Scalyr Agents running in default namespace (pre-2.1.1)

If you are upgrading from an earlier version it is probably installed in the default namespace, if you wish to switch to the `scalyr` namespace first move your existing secret and configmap to the new namespace.

kubectl get secret scalyr-api-key --namespace=default --export -o yaml | kubectl apply -f - --namespace=scalyr

kubectl get configmap scalyr-config --namespace=default --export -o yaml | kubectl apply -f - --namespace=scalyr

Then delete your old deployment to avoid running two Agents at once.

kubectl delete -f

Then create the new DaemonSet in the new namespace.

kubectl apply -f
kubectl apply -f

Staying in the default namespace

If you want to keep your installation in the default namespace you can upgrade your agent by running the following:

kubectl apply -f
kubectl apply -f

Useful tips

Checking the status of a Scalyr Agent container

To check the status of a currently running Scalyr Agent container, first use kubectl to find the name of the pod in which you are interested.

kubectl get pods --namespace=scalyr

Once you have the name of the pod running the Scalyr Agent, use the following command:

kubectl exec <pod_name> -- scalyr-agent-2 status

For more verbose output, run:

kubectl exec <pod_name> -- scalyr-agent-2 status -v

Stopping the Scalyr Agent DaemonSet

If you wish to stop running the Scalyr Agent DaemonSet entirely, then assuming you are using the default configuration and your DaemonSet's name is 'scalyr-agent-2' run:

kubectl delete daemonset scalyr-agent-2 --namespace=scalyr

There is currently no convenient way to stop the Scalyr Agent already running on a specific node. But you can prevent the agent from starting up on specific nodes by following the instructions in the next section:

Disabling the agent on the Master Node

The Scalyr Agent DaemonSet runs an Agent pod on each node. This also runs the Agent on the master node. To disable the Agent on the master node, comment the following in the DaemonSet scalyr-agent-2.yaml file:

  - key: ""
    operator: "Exists"
    effect: "NoSchedule"

Running the DaemonSet on select nodes

To run the Scalyr Agent on specific nodes of your cluster, add a nodeSelector or nodeAffinity section to your pod config file. For example, if your desired nodes are labeled logging=scalyr then adding the following nodeSelector will restrict Scalyr Agent pods to Nodes that have a logging=scalyr label:

    logging: scalyr

or if you wanted to use nodeAffinity:

        - matchExpressions:
          - key: logging
            operator: In
            values: ["scalyr"]

Read more about specifying node selectors and affinity.

Conclusion and Next Steps

We hope that was easy. If you've had any trouble, please let us know. Otherwise, if this is your first time using Scalyr, this would be an excellent time read the Getting Started guide.

Now that you have the Scalyr Kubernetes Agent up and running, please see Configuring Scalyr Agent (Kubernetes) for details on configuring the agent and logging of pod logs.