Skip to content

Commit 07908b7

Browse files
leecalcoteleecalcote
authored
Merge pull request #887 from layer5io/leecalcote/docs/kanvas/operator
Operator: Live-tail log stream rewrite
2 parents 9e5e3e3 + 60ffaed commit 07908b7

File tree

4 files changed

+154
-19
lines changed

4 files changed

+154
-19
lines changed

‎.github/agents/documentation.agent.md‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,6 @@
11
---
22
name: "Diátaxis Documentation Expert"
3-
agent: 'agent'
4-
tools: ['edit/editFiles', 'search', 'fetch']
3+
tools: ['search/changes', 'search/codebase', 'edit/editFiles', 'vscode/extensions', 'web/fetch', 'web/githubRepo', 'vscode/getProjectSetupInfo', 'vscode/installExtension', 'vscode/newWorkspace', 'vscode/runCommand', 'vscode/openSimpleBrowser', 'read/problems', 'execute/getTerminalOutput', 'execute/runInTerminal', 'read/terminalLastCommand', 'read/terminalSelection', 'execute/createAndRunTask', 'execute', 'execute/runTask', 'execute/runTests', 'search', 'search/searchResults', 'read/terminalLastCommand', 'read/terminalSelection', 'execute/testFailure', 'search/usages', 'vscode/vscodeAPI', 'github/*']
54
description: 'Diátaxis Documentation Expert. An expert technical writer specializing in creating high-quality software documentation, guided by the principles and structure of the Diátaxis technical documentation authoring framework.'
65
---
76

‎content/en/kanvas/operator/_index.md‎

Lines changed: 2 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -24,20 +24,5 @@ Using the search bar, you can search for specific resources and select them. The
2424

2525
Operator supports connecting to Kubernetes pods via the following methods.
2626

27-
### Understanding Log Streamer
28-
29-
<!-- {{< figure src="images/log-stream-sequence-diagram.svg" link="images/log-stream-sequence-diagram.svg" width="100%" alt="log-stream-sequence-diagram" >}} -->
30-
31-
![log-stream-sequence-diagram](images/log-stream-sequence-diagram.svg)
32-
33-
### Understanding Interactive Terminal
34-
35-
The interactive terminal behaves in a fashion similar to similar to the behavior of the `kubectl exec` command, but web-based.
36-
37-
{{< alert type="note" title="Distinct Capabilities" >}} Note that each component offers its own capabilities, and that these capabilities differ between Designer mode and Operator mode. For example, in operator mode, if you right-click (and hold) on a Kubernetes pod, you will see actions unique to the Pod component, which are to open either an interactive terminal to one or all of the containers in the pod or to start streaming logs from any/all of the containers in the pod. {{< /alert >}}
38-
39-
While using using the interactive terminal, understand that you can only open one session per container. Each session's data is streamed via Meshery Broker (NATS) from MeshSync to Meshery Server / Kanvas. The GraphQL subscription between your web browser running Kanvas and Meshery Server provides isolation between other users who might be concurrently sharing an interactive terminal. Each connection established a unique session ID.
40-
41-
<!-- {{< figure src="images/interactive-terminal-sequence-diagram.svg" link="images/interactive-terminal-sequence-diagram.svg" width="100%" alt="interactive-terminal-sequence-diagram" >}} -->
42-
43-
![interactive-terminal-sequence-diagram](images/interactive-terminal-sequence-diagram.svg)
27+
- [Log Streaming](/kanvas/operator/log-streaming): Learn how to live-tail logs from your Kubernetes pods and containers directly within the visual topology.
28+
- [Interactive Terminal](/kanvas/operator/interactive-terminal): Learn how to establish an interactive shell session with your containers.

‎content/en/kanvas/operator/interactive-terminal.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
---
2+
title: Interactive Terminal
3+
description: >
4+
Learn about Interactive Terminal in Operator mode
5+
categories: [Operator]
6+
---
7+
8+
When operating cloud native infrastructure, deep diagnostics often require direct access to the container shell. The **Interactive Terminal** in Kanvas enables you to execute commands and inspect the filesystem of your running containers directly from the visual topology. By integrating terminal sessions into the Kanvas interface, you can troubleshoot issues, verify configurations, and test network connectivity without switching context to external CLI tools like `kubectl`.
9+
10+
## Overview
11+
12+
The Kanvas Interactive Terminal allows operators to establish a secure, low-latency shell session with one or more pods simultaneously. This feature is essential for "last mile" debugging where metrics and logs alone are insufficient. The interactive terminal behaves in a fashion similar to the behavior of the `kubectl exec` command, but web-based.
13+
14+
### Key Features
15+
16+
* **Direct Shell Access:** Instantly `exec` into any running container within your Kubernetes cluster to run standard shell commands (e.g., `ls`, `curl`, `top`).
17+
* **Multi-Session Support:** Open concurrent terminal sessions for different pods to compare environments or run simultaneous tests.
18+
* **Integrated Workflow:** Debug specific nodes while maintaining visibility of the surrounding infrastructure topology.
19+
* **Session Management:** Configure preferences such as "Auto-close Terminal Sessions" to manage resources efficiently.
20+
21+
## How to Access the Terminal
22+
23+
To use the Interactive Terminal, ensure you are in **Operator Mode** and have a connected Kubernetes cluster.
24+
25+
1. **Navigate to Visualizer:** Open Kanvas and switch to **Operator** mode to view your active cluster resources.
26+
2. **Select a Workload:** Click on a **Pod** or **Deployment** node within your design.
27+
3. **Launch the Session:**
28+
* Expand the **Details** panel (bottom drawer).
29+
* Select the **Terminal** tab (located alongside *Performance* and *Log Stream*).
30+
* If the pod contains multiple containers, select the specific container you wish to access.
31+
* Click **Connect** to initialize the session.
32+
33+
## Use Cases and Examples
34+
35+
### 1. Verifying Network Connectivity
36+
37+
**Scenario:** A backend service is failing to connect to a database, but the service status appears green.
38+
**Action:** Open a terminal in the backend pod and use `curl` or `nc` (netcat) to attempt a connection to the database endpoint.
39+
**Benefit:** Confirms whether the issue is a network policy blocking traffic, a DNS resolution failure, or an application-layer configuration error, all while visualizing the connection in Kanvas.
40+
41+
### 2. Inspecting Configuration Files
42+
43+
**Scenario:** An application is behaving unexpectedly, and you suspect the mounted ConfigMap data is incorrect.
44+
**Action:** Use the terminal to `cat` the configuration files located in the file system (e.g., `/etc/config/app.conf`).
45+
**Benefit:** Verifies exactly what the application sees at runtime, ensuring that the latest ConfigMap updates have actually propagated to the pod.
46+
47+
### 3. Real-Time Resource Monitoring
48+
49+
**Scenario:** A specific pod is triggering high-memory alerts, but you need to know which process is the culprit.
50+
**Action:** Exec into the container and run `top` or `ps aux`.
51+
**Benefit:** Provides granular visibility into process-level resource consumption that aggregate metrics might miss.
52+
53+
### 4. Environment Variable Validation
54+
55+
**Scenario:** A deployment fails to authenticate with an external API.
56+
**Action:** Run the `env` command within the container's terminal.
57+
**Benefit:** Allows you to instantly verify if secret keys and API endpoints were injected correctly as environment variables during startup.
58+
59+
## Technical Architecture
60+
61+
The Interactive Terminal is built on an event-driven architecture designed for security and responsiveness:
62+
63+
1. **Session Initiation:** When a user initiates a session, the Meshery Server receives the request via the GraphQL API.
64+
2. **Orchestration:** The request is brokered to the **Meshery Operator**, which signals the **MeshSync** controller running inside the cluster to start the interactive session.
65+
3. **Data Transport:** Input and output data are streamed via **NATS** through the Meshery Broker. Shell output is preprocessed and transcribed before being delivered to the UI.
66+
4. **Session Isolation:** Each terminal session is mapped to a unique topic ID within the subscription, ensuring that data streams for multiple open terminals do not overlap.
67+
68+
{{< alert type="note" title="Distinct Capabilities" >}} Note that each component offers its own capabilities, and that these capabilities differ between Designer mode and Operator mode. For example, in operator mode, if you right-click (and hold) on a Kubernetes pod, you will see actions unique to the Pod component, which are to open either an interactive terminal to one or all of the containers in the pod or to start streaming logs from any/all of the containers in the pod. {{< /alert >}}
69+
70+
While using the interactive terminal, understand that you can only open one session per container. Each session's data is streamed via Meshery Broker (NATS) from MeshSync to Meshery Server / Kanvas. The GraphQL subscription between your web browser running Kanvas and Meshery Server provides isolation between other users who might be concurrently sharing an interactive terminal. Each connection establishes a unique session ID.
71+
72+
<!-- {{< figure src="images/interactive-terminal-sequence-diagram.svg" link="images/interactive-terminal-sequence-diagram.svg" width="100%" alt="interactive-terminal-sequence-diagram" >}} -->
73+
74+
![interactive-terminal-sequence-diagram](images/interactive-terminal-sequence-diagram.svg)
75+
76+
***
77+
78+
### See Also
79+
80+
* **[Log Streaming](/kanvas/operator/log-streaming):** Learn how to live-tail logs for real-time application monitoring.
81+
<!-- * **[Performance Management](/kanvas/performance):** Run load tests and analyze performance profiles. -->

‎content/en/kanvas/operator/log-streaming.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
---
2+
title: Log Streaming
3+
description: >
4+
Learn about Log Streaming in Operator mode
5+
categories: [Operator]
6+
---
7+
8+
Efficient troubleshooting requires immediate visibility into your application's behavior. The **Log Streamer** in Kanvas allows you to live-tail logs from your Kubernetes pods and containers directly within the visual topology. Unlike static log files, this feature provides a real-time, multiplexed view of your infrastructure's activities, enabling you to debug interactions between services without leaving the Kanvas interface.
9+
10+
## Overview
11+
12+
Kanvas Log Streaming is part of the **Operator** mode (Visualizer). It establishes a persistent, low-latency connection to your cluster resources, allowing you to stream `stdout` and `stderr` logs from one or multiple pods simultaneously.
13+
14+
### Key Features
15+
16+
* **Real-time Tailing:** Watch log generation instantly as events occur in your cluster.
17+
* **Multi-Pod Streaming:** Stream logs from a single specific pod or multiplex logs from several pods at once to correlate events across different services.
18+
* **Keyword Filtering:** Apply search filters to the log stream to isolate specific error codes, transaction IDs, or warning messages.
19+
* **Playback Controls:** Interactive controls to **Play**, **Pause**, **Stop**, and **Clear** the stream, giving you control over the flow of information during high-volume events.
20+
21+
## How to Access Log Streaming
22+
23+
To utilize the Log Streamer, ensure you are in **Operator Mode** and have a connected Kubernetes cluster with MeshSync active.
24+
25+
1. **Navigate to Visualizer:** Open Kanvas and toggle to **Operator** mode (Visualizer) to view your running cluster topology.
26+
2. **Select a Resource:** Click on a **Pod** or **Deployment** node within your design.
27+
3. **Open the Log Stream:**
28+
* **Via Context Menu:** Right-click the node and select **Stream Logs** from the context menu.
29+
* **Via Details Panel:** With the node selected, expand the bottom panel or the **Details** drawer. Locate the **Log Stream** tab next to the Terminal and Performance tabs.
30+
31+
## Using the Interface
32+
33+
Once the stream is active, the Log Streamer panel will display the output.
34+
35+
* **Search/Filter:** Use the search bar within the panel to highlight or filter lines containing specific strings (e.g., `Error`, `Exception`, or specific request IDs).
36+
* **Pause/Resume:** Use the playback toggle to pause the live feed to inspect a specific log line without losing your place, then resume to catch up with the live tail.
37+
* **Copy Logs:** Use the copy function to capture the current log buffer to your clipboard for external analysis or ticket submission.
38+
39+
## Use Cases and Examples
40+
41+
### 1. Troubleshooting CrashLoopBackOff
42+
43+
**Scenario:** A newly deployed pod is failing to start, entering a `CrashLoopBackOff` state.
44+
**Action:** Select the failing pod in Kanvas. The Log Streamer immediately captures the container's startup output.
45+
**Benefit:** You can instantly see the specific runtime error or missing environment variable causing the crash without manually running `kubectl logs -f` commands in a separate terminal window.
46+
47+
### 2. Correlating Microservice Interactions
48+
49+
**Scenario:** A frontend service is returning a 500 error, but the issue likely originates in a backend dependency.
50+
**Action:** Multi-select both the Frontend Pod and the Backend Pod in the visualizer and activate log streaming.
51+
**Benefit:** Kanvas multiplexes the streams. You can watch the request leave the frontend and fail at the backend in a single view, allowing you to pinpoint exactly where the transaction breaks.
52+
53+
### 3. Monitoring Real-time Traffic Patterns
54+
55+
**Scenario:** You have applied a new canary rollout pattern and want to verify traffic distribution.
56+
**Action:** Stream logs from the new version of your deployment while filtering for specific traffic headers or successful HTTP 200 codes.
57+
**Benefit:** Visually verify that the application logic is processing requests as expected during the deployment window.
58+
59+
## Technical Note
60+
61+
The Log Streamer utilizes a robust architecture where the **Meshery Operator** signals the **MeshSync** controller to start the log flow. Data is streamed using **NATS** to the Meshery Broker, preprocessed, and then delivered to your browser via a **WebSocket** connection using GraphQL subscriptions. This ensures minimal latency and high performance, even when streaming data from multiple active containers.
62+
63+
![log-stream-sequence-diagram](images/log-stream-sequence-diagram.svg)
64+
65+
***
66+
67+
### See Also
68+
69+
* **[Interactive Terminal](/kanvas/terminal):** Learn how to establish an interactive shell session with your containers.
70+
* **[Performance Management](/kanvas/performance):** Run ad-hoc performance tests alongside your log monitoring.

0 commit comments

Comments
 (0)