Merge pull request #2602 from pareenaverma/content_review

Flink LP tech review

Author: pareenaverma

content/learning-paths/servers-and-cloud-computing/flink-on-gcp/background.md

@@ -16,10 +16,10 @@ To learn more about Google Axion, refer to the [Introducing Google Axion Process
 
 ## Apache Flink
 
-[Apache Flink](https://flink.apache.org/) is an open-source, distributed **stream and batch data processing framework** developed under the [Apache Software Foundation](https://www.apache.org/).
+[Apache Flink](https://flink.apache.org/) is an open-source, distributed stream and batch data processing framework** developed under the [Apache Software Foundation](https://www.apache.org/).
 
-Flink is designed for **high-performance, low-latency, and stateful computations** on both unbounded (streaming) and bounded (batch) data. It provides a robust runtime and APIs in **Java**, **Scala**, and **Python** for building scalable, fault-tolerant data processing pipelines.
+Flink is designed for high-performance, low-latency, and stateful computations on both unbounded (streaming) and bounded (batch) data. It provides a robust runtime and APIs in Java, Scala, and Python for building scalable, fault-tolerant data processing pipelines.
 
-Flink is widely used for **real-time analytics**, **event-driven applications**, **data pipelines**, and **machine learning workloads**. It integrates seamlessly with popular systems such as **Apache Kafka**, **Hadoop**, and various **cloud storage services**.
+Flink is widely used for real-time analytics, event-driven applications, data pipelines, and machine learning workloads. It integrates seamlessly with popular systems such as Apache Kafka, Hadoop, and various cloud storage services.
 
 To learn more, visit the [Apache Flink official website](https://flink.apache.org/) and explore the [documentation](https://nightlies.apache.org/flink/flink-docs-release-2.1/).

content/learning-paths/servers-and-cloud-computing/flink-on-gcp/baseline.md

@@ -7,10 +7,11 @@ layout: learningpathall
 ---
 
 ## Apache Flink Baseline Testing on GCP SUSE VM
-This guide explains how to perform **baseline testing** for Apache Flink after installation on a **GCP SUSE VM**. Baseline testing ensures that the Flink cluster is operational, the environment is correctly configured, and basic jobs run successfully.
+In this section you will perform baseline testing for Apache Flink after installation on a GCP SUSE VM. Baseline testing validates that your installation is correct, the JVM is functioning properly, and Flink’s JobManager/TaskManager can execute jobs successfully.
+
+### Install Maven (Required to Build and Run Flink Jobs)
+Before running Flink jobs, ensure that Maven is installed on your VM. Many Flink examples and real-world jobs require Apache Maven to compile Java applications.
 
-### Download and Extract Maven
-Before running Flink jobs, ensure that **Java** and **Maven** are installed on your VM.  
 Download Maven and extract it:
 
 ```console
@@ -20,8 +21,8 @@ sudo tar -xvzf apache-maven-3.8.6-bin.tar.gz
 sudo mv apache-maven-3.8.6 /opt/maven
 ```
 
-### Set Environment Variables
-Configure the environment so Maven commands are recognized system-wide:
+### Configure Environment Variables
+Configure the environment so Maven commands can be run system-wide:
 
 ```console
 echo "export M2_HOME=/opt/maven" >> ~/.bashrc
@@ -47,9 +48,9 @@ OS name: "linux", version: "5.14.21-150500.55.124-default", arch: "aarch64", fam
 At this point, both Java and Maven are installed and ready to use.
 
 ### Start the Flink Cluster
-Before proceeding to start the Flink cluster, you need to allow port 8081 from your GCP console.
+Before launching Flink, open port 8081 in the Google Cloud Firewall Rules so that the Web UI is reachable externally.
 
-Start the Flink cluster using the provided startup script:
+Start the standalone Flink cluster using the provided startup script:
 
 ```console
 cd $FLINK_HOME
@@ -64,7 +65,7 @@ Starting standalonesession daemon on host lpprojectsusearm64.
 Starting taskexecutor daemon on host lpprojectsusearm64.
 ```
 
-Verify that the JobManager and TaskManager processes are running:
+Verify that the Flink Processes (JobManager and TaskManager) are running:
 
 ```console
 jps
@@ -76,30 +77,29 @@ You should see output similar to:
 2621 Jps
 2559 TaskManagerRunner
 ```
+StandaloneSessionClusterEntrypoint is the JobManager process
+TaskManagerRunner is the worker responsible for executing tasks and maintaining state.
 
 ### Access the Flink Web UI
 
-Open the Flink Web UI in a browser:
+In a browser, navigate to:
 
 ```console
 http://<VM_IP>:8081
 ```
-
-- A successfully loaded dashboard confirms the cluster network and UI functionality.
--This serves as the baseline for network and UI validation.
-
+You should see the Flink Dashboard:
 ![Flink Dashboard alt-text#center](images/flink-dashboard.png "Figure 1: Flink Dashboard")
 
+A successfully loaded dashboard confirms the cluster network and UI functionality. This serves as the baseline for network and UI validation.
+
 ### Run a Simple Example Job
-Execute a sample streaming job to verify that Flink can run tasks correctly:
+A basic sanity test is to run the built-in WordCount example:
 
 ```console
 cd $FLINK_HOME
 ./bin/flink run examples/streaming/WordCount.jar
 ```
-
-- Monitor the job in the Web UI or check console logs.
-- Confirm that the job completes successfully.
+You can monitor the job in the Web UI or check console logs. A successful WordCount run confirms that your Flink cluster lifecycle works end-to-end.
 
 ![Flink Dashboard alt-text#center](images/wordcount.png "Figure 2: Word Count Job")
 

content/learning-paths/servers-and-cloud-computing/flink-on-gcp/benchmarking.md

@@ -8,44 +8,52 @@ layout: learningpathall
 
 
 ## Apache Flink Benchmarking
-This guide provides step-by-step instructions to set up and run **Apache Flink Benchmarks** on a **GCP SUSE VMs**. It covers cloning the repository, building the benchmarks, exploring the JAR, and listing available benchmarks.
+This section walks you through running Apache Flink microbenchmarks on a Google Cloud Axion C4A (Arm64) SUSE VM. You will clone the official Flink-benchmarks repository, build the benchmark suite, explore available tests, and run the Remote Channel Throughput Benchmark, one of the key indicators of Flink’s communication and data-transfer performance.
 
 ### Clone the Repository
-Start by cloning the official Flink benchmarks repository. This repository contains all the benchmark definitions and example jobs.
+Clone the official Flink microbenchmarks repository:
 
 ```console
 cd ~
 git clone https://github.com/apache/flink-benchmarks.git
 cd flink-benchmarks
 ```
+This repository contains microbenchmarks built using JMH (Java Microbenchmark Harness), widely used for JVM-level performance testing.
 
 ### Build the Benchmarks with Maven
-Use Maven to compile the benchmarks and generate the benchmark JAR. Skip tests to save time.
+Compile the benchmarks and create the executable JAR:
 
 ```console
 mvn clean package -DskipTests
 ```
-- **mvn clean package** → Cleans previous builds and packages the project.
+What this does:
+  * clean removes previous build artifacts
+  * package compiles the code and produces benchmark JARs
+  * -DskipTests speeds up the build since unit tests aren’t needed for benchmarking
+    
+After building, the compiled **benchmarks.jar** files appear under:
 
-After this step, the target directory will contain the compiled **benchmarks.jar**.
+```output
+flink-benchmarks/target/
+```
 
 ### Explore the JAR Contents
-Verify the generated files inside the `target` directory:
+Verify that benchmarks.jar was generated:
 
 ```console
 cd target
 ls
 ```
-You should see an output similar to:
+You should see:
 
 ```output
 benchmark-0.1.jar  classes            generated-test-sources  maven-status         protoc-plugins
 benchmarks.jar     generated-sources  maven-archiver          protoc-dependencies  test-classes
 ```
-- **benchmarks.jar**→ The main benchmark JAR file used to run Flink benchmarks.
+benchmarks.jar — Contains all Flink microbenchmarks packaged with JMH.
 
 ### List Available Benchmarks
-To view all the benchmarks included in the JAR:
+View all benchmarks included in the JAR:
 
 ```console
 java -jar benchmarks.jar -l
@@ -54,13 +62,15 @@ java -jar benchmarks.jar -l
 - This helps you identify which benchmarks you want to execute on your VM.
 
 ### Run Selected Benchmarks
-While the Flink benchmarking project includes multiple suites for state backends, windowing, checkpointing, and scheduler performance, this Learning path focuses on the Remote Channel Throughput benchmark to evaluate network and I/O performance.
+While the Flink benchmarking project includes multiple suites for state backends, windowing, checkpointing, and scheduler performance, in this Learning path you will run the Remote Channel Throughput benchmark to evaluate network and I/O performance.
+
+**Remote Channel Throughput**: This benchmark measures the data transfer rate between remote channels in Flink, helping to evaluate network and I/O performance.
 
-**Remote Channel Throughput**: Measures the data transfer rate between remote channels in Flink, helping to evaluate network and I/O performance.
+Run the benchmark:
 ```console
 java -jar benchmarks.jar org.apache.flink.benchmark.RemoteChannelThroughputBenchmark.remoteRebalance
 ```
-You should see an output similar to:
+You should see output similar to:
 ```output
 
 Result "org.apache.flink.benchmark.RemoteChannelThroughputBenchmark.remoteRebalance":
@@ -83,25 +93,17 @@ RemoteChannelThroughputBenchmark.remoteRebalance  DEBLOAT  thrpt   30  10536.511
 - **Min Throughput**: The lowest throughput was observed, and it shows worst-case performance.  
 - **Max Throughput**: Highest throughput observed, shows best-case performance.
 
-### Benchmark summary on x86_64
-To compare the benchmark results, the following results were collected by running the same benchmark on a `x86 - c4-standard-4` (4 vCPUs, 15 GB Memory) x86_64 VM in GCP, running SUSE:
-
-| Benchmark                                          | Mode     | Count | Score (ops/ms) | Error (±) | Min        | Max        | Stdev    | CI (99.9%)             | Units  |
-|---------------------------------------------------|---------|-------|----------------|-----------|------------|------------|---------|------------------------|--------|
-| RemoteChannelThroughputBenchmark.remoteRebalance | ALIGNED | 30    | 24873.046      | 892.673   | 11195.028  | 12425.761  | 421.057 | [11448.649, 12011.275] | ops/ms |
-| RemoteChannelThroughputBenchmark.remoteRebalance | DEBLOAT | 30    | 11729.962      | 281.313   | 11195.028  | 12425.761  | 421.057 | [11448.649, 12011.275] | ops/ms |
-
 ### Benchmark summary on Arm64
-Results from the earlier run on the `c4a-standard-4` (4 vCPU, 16 GB memory) Arm64 VM in GCP (SUSE):
+Results from the run on the `c4a-standard-4` (4 vCPU, 16 GB memory) Arm64 VM in GCP (SUSE) are summarized below:
 
 | Benchmark                                          | Mode     | Count | Score (ops/ms) | Error (±) | Min       | Max       | Stdev   | CI (99.9%)             | Units  |
 |---------------------------------------------------|---------|-------|----------------|-----------|-----------|-----------|---------|------------------------|--------|
 | RemoteChannelThroughputBenchmark.remoteRebalance | ALIGNED | 30    | 17445.341      | 153.256   | 10289.593 | 10687.736 | 89.987  | [10476.390, 10596.633] | ops/ms |
 | RemoteChannelThroughputBenchmark.remoteRebalance | DEBLOAT | 30    | 10536.511      | 60.121    | 10289.593 | 10687.736 | 89.987  | [10476.390, 10596.633] | ops/ms |
 
-### Apache Flink performance benchmarking comparison on Arm64 and x86_64
+### Apache Flink performance benchmarking observations on Arm64
+
+- Both the ALIGNED mode and DEBLOAT modes demonstrate a strong throughput on the Arm64 VM.  
+- The benchmark confirms that the Arm64 architecture efficiently handles Flink's remote channel throughput workloads.  
 
-- The **ALIGNED mode** achieved an average throughput of **17,445 ops/ms**, demonstrating higher performance on the Arm64 VM.  
-- The **DEBLOAT mode** achieved an average throughput of **10,537 ops/ms**, slightly lower due to optimization differences.  
-- The benchmark confirms that the **Arm64 architecture** efficiently handles Flink's remote channel throughput workloads.  
-- Overall, the average throughput across both modes is approximately **14,854 ops/ms**, indicating strong baseline performance for Arm64 deployments.
+Overall, Arm64 VMs have shown that they are highly suitable for real-time Flink workloads, especially streaming analytics, ETL pipelines, and JVM-based microbenchmarks.

content/learning-paths/servers-and-cloud-computing/flink-on-gcp/installation.md

@@ -7,11 +7,11 @@ layout: learningpathall
 ---
 
 ## Install Apache Flink on GCP VM
-This guide walks you through installing **Apache Flink** and its required dependencies on a **Google Cloud Platform (GCP) SUSE Arm64 Virtual Machine (VM)**. By the end of this section, you will have a fully configured Flink environment ready for job execution and benchmarking.
+In this section you will install Apache Flink and its required dependencies on a Google Cloud Platform (GCP) SUSE Arm64 Virtual Machine (VM). By the end, you will have a fully configured Flink environment ready for local execution, standalone clusters, or benchmarking Flink workloads on Arm.
 
 ###  Update the System and Install Java
-Before installing Flink, ensure your system packages are up to date and Java is installed.
-
+Apache Flink requires a Java runtime (JRE) and development kit (JDK).
+Update the system and install Java:
 ```console
 sudo zypper refresh
 sudo zypper update -y
@@ -20,7 +20,7 @@ sudo zypper install -y java-17-openjdk java-17-openjdk-devel
 This step ensures you have the latest system updates and the Java runtime needed to execute Flink applications.
 
 ### Download Apache Flink Binary
-Next, download the pre-built binary package for **Apache Flink** from the official Apache mirror.
+Navigate to /opt (a standard location for system-wide tools) and download the official Flink distribution:
 
 ```console
 cd /opt
@@ -32,45 +32,42 @@ This command retrieves the official Flink binary distribution for installation o
 Flink 2.0.0 introduced Disaggregated State Management architecture, which enables more efficient resource utilization in cloud-native environments, ensuring high-performance real-time processing while minimizing resource overhead.
 You can view [this release note](https://flink.apache.org/2025/03/24/apache-flink-2.0.0-a-new-era-of-real-time-data-processing/)
 
-The [Arm Ecosystem Dashboard](https://developer.arm.com/ecosystem-dashboard/) recommends Flink version 2.0.0, the minimum recommended on the Arm platforms.
+For best performance on Arm, the [Arm Ecosystem Dashboard](https://developer.arm.com/ecosystem-dashboard/) recommends using Flink ≥ 2.0.0.
 {{% /notice %}}
 
 ### Extract the Downloaded Archive
-Extract the downloaded `.tgz` archive to make the Flink files accessible for configuration.
+Untar the archive:
 
 ```console
 sudo tar -xvzf flink-2.1.1-bin-scala_2.12.tgz
 ```
 After extraction, you will have a directory named `flink-2.1.1` under `/opt`.
 
-**Rename the extracted directory for convenience:**
-For easier access and management, rename the extracted Flink directory to a simple name like `/opt/flink`.
-
+Rename it for convenience:
 ```console
 sudo mv flink-2.1.1 /opt/flink
 ```
-This makes future references to your Flink installation path simpler and more consistent.
+This makes configuration, upgrades, and scripting easier for your Flink installation.
 
 ### Configure Environment Variables
-Set the environment variables so the Flink commands are recognized system-wide. This ensures you can run `flink` from any terminal session.
+Add Flink to your shell environment:
 
 ```console
 echo "export FLINK_HOME=/opt/flink" >> ~/.bashrc
 echo "export PATH=\$FLINK_HOME/bin:\$PATH" >> ~/.bashrc
 ```
-
-Additionally, create a dedicated log directory for Flink and assign proper permissions:
+Create a logging directory and assign proper permissions:
 ```console
 sudo mkdir -p /opt/flink/log
 sudo chown -R $(whoami):$(id -gn) /opt/flink/log
 sudo chmod -R 755 /opt/flink/log
 ```
-
-**Apply the changes:**
+Apply the changes:
 
 ```console
 source ~/.bashrc
 ```
+Adding Flink to the global PATH lets you use commands like `flink`, `start-cluster.sh`, and `taskmanager.sh` from any terminal.
 
 ### Verify the Installation
 To confirm that Flink has been installed correctly, check its version:

content/learning-paths/servers-and-cloud-computing/flink-on-gcp/instance.md

@@ -8,7 +8,7 @@ layout: learningpathall
 
 ## Overview
 
-In this section, you will learn how to provision a Google Axion C4A Arm virtual machine on Google Cloud Platform (GCP) using the `c4a-standard-4` (4 vCPUs, 16 GB memory) machine type in the Google Cloud Console.  
+In this section, you will create a Google Axion C4A Arm virtual machine on Google Cloud Platform (GCP) using the `c4a-standard-4` (4 vCPUs, 16 GB memory) machine type in the Google Cloud Console.  
 
 {{% notice Note %}}
 For support on GCP setup, see the Learning Path [Getting started with Google Cloud Platform](https://learn.arm.com/learning-paths/servers-and-cloud-computing/csp/google/).