kubectl-logs

Show logs for a single-container pod

$ kubectl logs [pod_name]

$ kubectl logs [[-c|--container]] [container_name] [pod_name]

$ kubectl logs --all-containers=[true] [pod_name]

$ kubectl logs [[-f|--follow]] [pod_name]

$ kubectl logs --since=[relative_time] [pod_name]

$ kubectl logs --tail=[10] [pod_name]

$ kubectl logs deployment/[deployment_name]

kubectl logs (POD | TYPE/NAME) [-c CONTAINER] [-f] [--follow] [--since DURATION] [--tail LINES] [--timestamps] [--all-containers] [-n NAMESPACE] [--selector SELECTOR]

POD
    The name of the pod from which to retrieve logs. This is typically the most common way to specify the target.

TYPE/NAME
    Alternatively, specify a resource type and name (e.g., 'deployment/my-app') to retrieve logs for pods managed by that resource.

-c, --container NAME
    Specify the name of the container within the pod from which to retrieve logs. Required if the pod has multiple containers and --all-containers is not used.

-f, --follow
    Stream the logs as they are written, similar to the behavior of tail -f. The command will continue to output new log lines until interrupted.

--since DURATION
    Only return logs newer than a relative duration, e.g., '5s' (5 seconds), '2m' (2 minutes), or '3h' (3 hours). Logs older than this duration will be excluded.

--since-time TIMESTAMP
    Only return logs after a specific date and time, specified in RFC3339 format, e.g., '2023-01-01T10:00:00Z'.

--tail LINES
    Output only the specified number of most recent log lines from the end of the logs. Useful for quickly seeing the latest activity.

--timestamps
    Include RFC3339 timestamps on each line of the log output, providing precise timing information.

--all-containers
    Display logs from all containers within the specified pod. Each log line will be prefixed with the container name to identify its source.

--previous
    Print the logs for the previous instance of the container in a pod, useful if a container has crashed and restarted.

-n, --namespace NAMESPACE
    If present, specifies the namespace scope for the CLI request. Defaults to the current context's namespace.

-l, --selector SELECTOR
    A label query to filter on when using TYPE/NAME. Supports '=', '==', and '!=' operators to select pods based on labels.

--ignore-errors
    When watching or following pod logs, this flag allows any errors that occur during log retrieval to be ignored, and the command will continue trying to fetch logs.

--limit-bytes BYTES
    Maximum bytes of logs to return. This is useful for large log files to limit the size of the output.

The kubectl logs command is a fundamental and essential tool for debugging and monitoring applications running within Kubernetes. It allows users to fetch and display logs generated by containers inside a specific pod. This command connects directly to the kubelet agent on the node where the pod is running to retrieve the log output, providing real-time insights into application behavior, errors, and status messages. It supports various modes, including streaming logs (similar to tail -f), fetching historical logs, and filtering output based on time duration or number of lines. Indispensable for troubleshooting and understanding containerized workloads, kubectl logs helps developers and operators diagnose issues and observe application flow without needing direct access to the underlying cluster nodes.

Logs retrieved by kubectl logs are ephemeral and are typically stored on the node where the pod runs. They might be subject to:
Rotation policies: Container runtimes often rotate log files, meaning older logs might be truncated or deleted automatically.
Pod lifecycle: If a pod is deleted, its logs are generally lost from the node unless an external logging solution is in place.
Resource limitations: Very large log files or extremely high log volume might affect performance or storage on the node.
Permissions: Users must have appropriate Kubernetes RBAC permissions ('get' and 'watch' on pods and their logs) to retrieve logs successfully.

Container logs are primarily captured from the container's stdout (standard output) and stderr (standard error) streams. The container runtime (e.g., Containerd, Docker) on the Kubernetes node captures these streams and usually writes them to log files on the node's filesystem. The kubelet agent on the node then provides an API endpoint for kubectl logs to retrieve these stored logs.

For robust and persistent log management, especially in production environments, it is highly recommended to implement an external logging solution (e.g., Fluentd, Filebeat, Logstash, Loki, Splunk, ELK Stack). These solutions collect, aggregate, and centralize logs from all pods across the cluster, providing persistent storage, advanced querying capabilities, alerting, and dashboards, moving beyond the ephemeral nature of kubectl logs on individual nodes.

The kubectl logs command has been a core and indispensable part of the kubectl CLI from the early days of Kubernetes, which was open-sourced by Google in 2014. Its functionality has remained largely consistent due to its fundamental role in debugging and monitoring containerized applications. Over time, new options like --all-containers, --previous, and enhanced time-based filtering were added to address the evolving needs of complex Kubernetes deployments and multi-container patterns, making it even more versatile.

kubectl describe pod(1), kubectl exec(1), docker logs(1), journalctl(1), tail(1)