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: table, json, short |
--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”, “jsonpath” |
--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 -