Feb 21, 2024: Announcing Linkerd 2.15 with support for VM workloads, native sidecars, and SPIFFE! Read more »


This is not the latest version of Linkerd!
This documentation is for an older version of Linkerd. You may want the Linkerd 2.15 (current) documentation instead.

viz

viz manages the linkerd-viz extension of Linkerd service mesh.

Flags

Flag Usage
--api-addr Override kubeconfig and communicate directly with the control plane at host:port (mostly for testing)
--as Username to impersonate for Kubernetes operations
--as-group Group to impersonate for Kubernetes operations
--context Name of the kubeconfig context to use
--kubeconfig Path to the kubeconfig file to use for CLI requests
--linkerd-namespace
-L
Namespace in which Linkerd is installed
--verbose Turn on debug logging
--viz-namespace Name of the linkerd-viz namespace. If not set, it’s automatically detected

Subcommands

allow-scrapes

Output Kubernetes resources to authorize Prometheus scrapes in a namespace or cluster with config.linkerd.io/default-inbound-policy: deny.

Examples

# Allow scrapes in the 'emojivoto' namespace
linkerd viz allow-scrapes --namespace emojivoto | kubectl apply -f -

Flags

Flag Usage
--namespace
-n
The namespace in which to authorize Prometheus scrapes.

authz

Display stats for authorizations for a resource.

Flags

Flag Usage
--namespace
-n
Namespace of the specified resource
--output
-o
Output format; one of: “table” or “json” or “wide”
--selector
-l
Selector (label query) to filter on, supports ‘=’, ‘==’, and ‘!=’
--time-window
-t
Stat window (for example: “15s”, “1m”, “10m”, “1h”). Needs to be at least 15s.

check

Check the Linkerd Viz extension for potential problems.

The check command will perform a series of checks to validate that the Linkerd Viz extension is configured correctly. If the command encounters a failure it will print additional information about the failure and exit with a non-zero exit code.

Examples

# Check that the viz extension is up and running
linkerd viz check

Flags

Flag Usage
--namespace
-n
Namespace to use for –proxy checks (default: all namespaces)
--output
-o
Output format. One of: basic, json
--proxy Also run data-plane checks, to determine if the data plane is healthy
--wait Maximum allowed time for all tests to pass

dashboard

Open the Linkerd dashboard in a web browser

Check out the architecture docs for a more thorough explanation of what this command does.

Flags

Flag Usage
--address The address at which to serve requests
--port
-p
The local port on which to serve requests (when set to 0, a random port will be used)
--show Open a dashboard in a browser or show URLs in the CLI (one of: linkerd, grafana, url)
--wait Wait for dashboard to become available if it’s not available when the command is run

(*) You’ll need to tweak the dashboard’s enforced-host parameter with this value, as explained in the DNS-rebinding protection docs

edges

Display connections between resources, and Linkerd proxy identities.

The RESOURCETYPE argument specifies the type of resource to display edges within.

Examples:

  • cronjob
  • deploy
  • ds
  • job
  • po
  • rc
  • rs
  • sts

Valid resource types include:

  • cronjobs
  • daemonsets
  • deployments
  • jobs
  • pods
  • replicasets
  • replicationcontrollers
  • statefulsets

Examples

# Get all edges between pods that either originate from or terminate in the test namespace.
linkerd viz edges po -n test

# Get all edges between pods that either originate from or terminate in the default namespace.
linkerd viz edges po

# Get all edges between pods in all namespaces.
linkerd viz edges po --all-namespaces

Flags

Flag Usage
--all-namespaces
-A
If present, returns edges across all namespaces, ignoring the “–namespace” flag
--namespace
-n
Namespace of the specified resource
--output
-o
Output format; one of: “table” or “json” or “wide”

install

Output Kubernetes resources to install linkerd-viz extension.

Examples

# Default install.
linkerd viz install | kubectl apply -f -

The installation can be configured by using the --set, --values, --set-string and --set-file flags.
A full list of configurable values can be found at https://www.github.com/linkerd/linkerd2/tree/main/viz/charts/linkerd-viz/README.md

Flags

Flag Usage
--ha Install Viz Extension in High Availability mode.
--ignore-cluster Ignore the current Kubernetes cluster when checking for existing cluster configuration (default false)
--set set values on the command line (can specify multiple or separate values with commas: key1=val1,key2=val2)
--set-file set values from respective files specified via the command line (can specify multiple or separate values with commas: key1=path1,key2=path2)
--set-string set STRING values on the command line (can specify multiple or separate values with commas: key1=val1,key2=val2)
--skip-checks Skip checks for linkerd core control-plane existence
--values
-f
specify values in a YAML file or a URL (can specify multiple)
--wait Wait for core control-plane components to be available

list

Lists which pods can be tapped

Flags

Flag Usage
--all-namespaces
-A
If present, list pods across all namespaces
--namespace
-n
The namespace to list pods in

profile

Output service profile config for Kubernetes based off tap data.

Examples

# Generate a profile by watching live traffic.
linkerd viz profile -n emojivoto web-svc --tap deploy/web --tap-duration 10s --tap-route-limit 5

Flags

Flag Usage
--namespace
-n
Namespace of the service
--tap Output a service profile based on tap data for the given target resource
--tap-duration Duration over which tap data is collected (for example: “10s”, “1m”, “10m”)
--tap-route-limit Max number of routes to add to the profile

routes

The routes command displays per-route service metrics. In order for this information to be available, a service profile must be defined for the service that is receiving the requests. For more information about how to create a service profile, see service profiles. and the profile command reference.

Inbound Metrics

By default, routes displays inbound metrics for a target. In other words, it shows information about requests which are sent to the target and responses which are returned by the target. For example, the command:

linkerd viz routes deploy/webapp

Displays the request volume, success rate, and latency of requests to the webapp deployment. These metrics are from the webapp deployment’s perspective, which means that, for example, these latencies do not include the network latency between a client and the webapp deployment.

Outbound Metrics

If you specify the --to flag then linkerd viz routes displays outbound metrics from the target resource to the resource in the --to flag. In contrast to the inbound metrics, these metrics are from the perspective of the sender. This means that these latencies do include the network latency between the client and the server. For example, the command:

linkerd viz routes deploy/traffic --to deploy/webapp

Displays the request volume, success rate, and latency of requests from traffic to webapp from the perspective of the traffic deployment.

Effective and Actual Metrics

If you are looking at outbound metrics (by specifying the --to flag) you can also supply the -o wide flag to differentiate between effective and actual metrics.

Effective requests are requests which are sent by some client to the Linkerd proxy. Actual requests are requests which the Linkerd proxy sends to some server. If the Linkerd proxy is performing retries, one effective request can translate into more than one actual request. If the Linkerd proxy is not performing retries, effective requests and actual requests will always be equal. When enabling retries, you should expect to see the actual request rate increase and the effective success rate increase. See the retries and timeouts section for more information.

Because retries are only performed on the outbound (client) side, the -o wide flag can only be used when the --to flag is specified.

Examples

# Routes for the webapp service in the test namespace.
linkerd viz routes service/webapp -n test

# Routes for calls from the traffic deployment to the webapp service in the test namespace.
linkerd viz routes deploy/traffic -n test --to svc/webapp

Flags

Flag Usage
--namespace
-n
Namespace of the specified resource
--output
-o
Output format; one of: “table”, “wide”, or “json”
--selector
-l
Selector (label query) to filter on, supports ‘=’, ‘==’, and ‘!=’
--time-window
-t
Stat window (for example: “10s”, “1m”, “10m”, “1h”)
--to If present, shows outbound stats to the specified resource
--to-namespace Sets the namespace used to lookup the “–to” resource; by default the current “–namespace” is used

stat

Display traffic stats about one or many resources.

The RESOURCES argument specifies the target resource(s) to aggregate stats over: (TYPE [NAME] | TYPE/NAME) or (TYPE [NAME1] [NAME2]…) or (TYPE1/NAME1 TYPE2/NAME2…)

Examples:

  • cronjob/my-cronjob
  • deploy
  • deploy/my-deploy
  • deploy/ po/
  • ds/my-daemonset
  • job/my-job
  • ns/my-ns
  • po/mypod1 rc/my-replication-controller
  • po mypod1 mypod2
  • rc/my-replication-controller
  • rs
  • rs/my-replicaset
  • sts/my-statefulset
  • ts/my-split
  • authority
  • au/my-authority
  • httproute/my-route
  • route/my-route
  • all

Valid resource types include:

  • cronjobs
  • daemonsets
  • deployments
  • namespaces
  • jobs
  • pods
  • replicasets
  • replicationcontrollers
  • statefulsets
  • authorities (not supported in –from)
  • authorizationpolicies (not supported in –from)
  • httproutes (not supported in –from)
  • services (not supported in –from)
  • servers (not supported in –from)
  • serverauthorizations (not supported in –from)
  • all (all resource types, not supported in –from or –to)

This command will hide resources that have completed, such as pods that are in the Succeeded or Failed phases. If no resource name is specified, displays stats about all resources of the specified RESOURCETYPE

Examples

# Get all deployments in the test namespace.
linkerd viz stat deployments -n test

# Get the hello1 replication controller in the test namespace.
linkerd viz stat replicationcontrollers hello1 -n test

# Get all namespaces.
linkerd viz stat namespaces

# Get all inbound stats to the web deployment.
linkerd viz stat deploy/web

# Get all inbound stats to the pod1 and pod2 pods
linkerd viz stat po pod1 pod2

# Get all inbound stats to the pod1 pod and the web deployment
linkerd viz stat po/pod1 deploy/web

# Get all pods in all namespaces that call the hello1 deployment in the test namespace.
linkerd viz stat pods --to deploy/hello1 --to-namespace test --all-namespaces

# Get all pods in all namespaces that call the hello1 service in the test namespace.
linkerd viz stat pods --to svc/hello1 --to-namespace test --all-namespaces

# Get the web service. With Services, metrics are generated from the outbound metrics
# of clients, and thus will not include unmeshed client request metrics.
linkerd viz stat svc/web

# Get the web services and metrics for any traffic coming to the service from the hello1 deployment
# in the test namespace.
linkerd viz stat svc/web --from deploy/hello1 --from-namespace test

# Get the web services and metrics for all the traffic that reaches the web-pod1 pod
# in the test namespace exclusively.
linkerd viz stat svc/web --to pod/web-pod1 --to-namespace test

# Get all services in all namespaces that receive calls from hello1 deployment in the test namespace.
linkerd viz stat services --from deploy/hello1 --from-namespace test --all-namespaces

# Get all namespaces that receive traffic from the default namespace.
linkerd viz stat namespaces --from ns/default

# Get all inbound stats to the test namespace.
linkerd viz stat ns/test

# Get all inbound stats to the emoji-grpc server
linkerd viz stat server/emoji-grpc

# Get all inbound stats to the web-public server authorization resource
linkerd viz stat serverauthorization/web-public

# Get all inbound stats to the web-get and web-delete HTTP route resources
linkerd viz stat route/web-get route/web-delete

# Get all inbound stats to the web-authz authorization policy resource
linkerd viz stat authorizationpolicy/web-authz

Flags

Flag Usage
--all-namespaces
-A
If present, returns stats across all namespaces, ignoring the “–namespace” flag
--from If present, restricts outbound stats from the specified resource name
--from-namespace Sets the namespace used from lookup the “–from” resource; by default the current “–namespace” is used
--namespace
-n
Namespace of the specified resource
--output
-o
Output format; one of: “table” or “json” or “wide”
--selector
-l
Selector (label query) to filter on, supports ‘=’, ‘==’, and ‘!=’
--time-window
-t
Stat window (for example: “15s”, “1m”, “10m”, “1h”). Needs to be at least 15s.
--to If present, restricts outbound stats to the specified resource name
--to-namespace Sets the namespace used to lookup the “–to” resource; by default the current “–namespace” is used
--unmeshed If present, include unmeshed resources in the output

tap

Listen to a traffic stream.

The RESOURCE argument specifies the target resource(s) to tap: (TYPE [NAME] | TYPE/NAME)

Examples:

  • cronjob/my-cronjob
  • deploy
  • deploy/my-deploy
  • deploy my-deploy
  • ds/my-daemonset
  • job/my-job
  • ns/my-ns
  • rs
  • rs/my-replicaset
  • sts
  • sts/my-statefulset

Valid resource types include:

  • cronjobs
  • daemonsets
  • deployments
  • jobs
  • namespaces
  • pods
  • replicasets
  • replicationcontrollers
  • statefulsets
  • services (only supported as a –to resource)

Examples

# tap the web deployment in the default namespace
linkerd viz tap deploy/web

# tap the web-dlbvj pod in the default namespace
linkerd viz tap pod/web-dlbvj

# tap the test namespace, filter by request to prod namespace
linkerd viz tap ns/test --to ns/prod

Flags

Flag Usage
--authority Display requests with this :authority
--max-rps Maximum requests per second to tap.
--method Display requests with this HTTP method
--namespace
-n
Namespace of the specified resource
--output
-o
Output format. One of: “wide”, “json”
--path Display requests with paths that start with this prefix
--scheme Display requests with this scheme
--selector
-l
Selector (label query) to filter on, supports ‘=’, ‘==’, and ‘!=’
--to Display requests to this resource
--to-namespace Sets the namespace used to lookup the “–to” resource; by default the current “–namespace” is used

top

Display sorted information about live traffic.

The RESOURCE argument specifies the target resource(s) to view traffic for: (TYPE [NAME] | TYPE/NAME)

Examples:

  • cronjob/my-cronjob
  • deploy
  • deploy/my-deploy
  • deploy my-deploy
  • ds/my-daemonset
  • job/my-job
  • ns/my-ns
  • rs
  • rs/my-replicaset
  • sts
  • sts/my-statefulset

Valid resource types include:

  • cronjobs
  • daemonsets
  • deployments
  • jobs
  • namespaces
  • pods
  • replicasets
  • replicationcontrollers
  • statefulsets
  • services (only supported as a –to resource)

Examples

# display traffic for the web deployment in the default namespace
linkerd viz top deploy/web

# display traffic for the web-dlbvj pod in the default namespace
linkerd viz top pod/web-dlbvj

Flags

Flag Usage
--authority Display requests with this :authority
--hide-sources Hide the source column
--max-rps Maximum requests per second to tap.
--method Display requests with this HTTP method
--namespace
-n
Namespace of the specified resource
--path Display requests with paths that start with this prefix
--routes Display data per route instead of per path
--scheme Display requests with this scheme
--selector
-l
Selector (label query) to filter on, supports ‘=’, ‘==’, and ‘!=’
--to Display requests to this resource
--to-namespace Sets the namespace used to lookup the “–to” resource; by default the current “–namespace” is used

uninstall

Output Kubernetes resources to uninstall the linkerd-viz extension.

This command provides all Kubernetes namespace-scoped and cluster-scoped resources (e.g services, deployments, RBACs, etc.) necessary to uninstall the Linkerd-viz extension.

Examples

linkerd viz uninstall | kubectl delete -f -