From 4fc44cfffacc0813b4b8fb9729c00baf1bdcb1b5 Mon Sep 17 00:00:00 2001 From: Geaus <14088898+geaus@user.noreply.gitee.com> Date: Thu, 25 Sep 2025 16:55:24 +0800 Subject: [PATCH 1/4] init doc Signed-off-by: Geaus <14088898+geaus@user.noreply.gitee.com> --- docs/developer-guide/Tests/e2e-quickstart.md | 0 docs/developer-guide/Tests/ipsec-auth-e2e-test.md | 0 2 files changed, 0 insertions(+), 0 deletions(-) create mode 100644 docs/developer-guide/Tests/e2e-quickstart.md create mode 100644 docs/developer-guide/Tests/ipsec-auth-e2e-test.md diff --git a/docs/developer-guide/Tests/e2e-quickstart.md b/docs/developer-guide/Tests/e2e-quickstart.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/developer-guide/Tests/ipsec-auth-e2e-test.md b/docs/developer-guide/Tests/ipsec-auth-e2e-test.md new file mode 100644 index 00000000..e69de29b From 97421de69401dcfab188246ef215ace6210c84ba Mon Sep 17 00:00:00 2001 From: xiaojiangao123 <2061389208@qq.com> Date: Mon, 20 Oct 2025 23:29:29 +0800 Subject: [PATCH 2/4] update quick start md Signed-off-by: xiaojiangao123 <2061389208@qq.com> --- docs/developer-guide/Tests/e2e-quickstart.md | 138 +++++++++++++++++++ 1 file changed, 138 insertions(+) diff --git a/docs/developer-guide/Tests/e2e-quickstart.md b/docs/developer-guide/Tests/e2e-quickstart.md index e69de29b..db1e5431 100644 --- a/docs/developer-guide/Tests/e2e-quickstart.md +++ b/docs/developer-guide/Tests/e2e-quickstart.md @@ -0,0 +1,138 @@ +# Quickstart for Kmesh E2E Testing + +This document is designed to help developers quickly get started with writing and running end-to-end (E2E) tests for the Kmesh project. It covers the prerequisites, the test environment setup, a simple test function template, and instructions for running tests. By following this guide, you will be able to write and execute E2E tests efficiently, ensuring the stability and correctness of Kmesh features. + +## Prerequisites + +Before getting started, ensure the following tools are installed in your environment: + +- **Go**: For running the test framework. +- **Docker**: For containerizing applications. +- **kubectl**: For managing Kubernetes clusters. + +## E2E Test Environment + +Kmesh E2E testing requires a two-node KinD cluster: + +- **Control Node**: Manages the cluster. +- **Worker Node**: Runs the test services. + +At the start of the test, two services will be deployed: + +1. **service-with-waypoint-at-service-granularity**: A service with a Waypoint. +2. **enrolled-to-kmesh**: A service without a Waypoint. + +Both services use Echo Pods, which are used to test different scenarios. + +## Writing E2E Tests + +Here is a simple E2E test function template: + +```go +func TestEchoCall(t *testing.T) { + framework.NewTest(t).Run(func(t framework.TestContext) { + t.NewSubTest("Echo Call Test").Run(func(t framework.TestContext) { + // Retrieve test services + src := apps.ServiceWithWaypointAtServiceGranularity[0] + dst := apps.EnrolledToKmesh + + // Define test cases + cases := []struct { + name string + checker echo.Checker + }{ + { + name: "basic call", + checker: echo.And(echo.ExpectOK(), echo.ExpectBodyContains("Hello")), + }, + } + + // Execute test cases + for _, c := range cases { + t.NewSubTest(c.name).Run(func(t framework.TestContext) { + src.CallOrFail(t, echo.CallOptions{ + Target: dst[0], + PortName: "http", + Checker: c.checker, + }) + }) + } + }) + }) +} +``` + +### Resource Cleanup + +Use the `t.Cleanup` method to ensure test resources are cleaned up after the test completes. For example: + +```go +t.Cleanup(func() { + // Clean up resources +}) +``` + +### Deploying Policies + +Use the `t.ConfigIstio` method to deploy policies required for the test. For example: + +```go +t.ConfigIstio().YAML("test-namespace", ` +apiVersion: security.istio.io/v1beta1 +kind: AuthorizationPolicy +metadata: + name: allow-all +spec: + rules: + - {} +`).ApplyOrFail(t) +``` + +### Using echo.Checker + +`echo.Checker` is used to verify whether a test case passes. For example: + +```go +// Example: Using echo.Checker to validate HTTP response +src.CallOrFail(t, echo.CallOptions{ + Target: dst[0], + PortName: "http", + Checker: echo.And( + echo.ExpectOK(), // Expect the HTTP call to succeed + echo.ExpectBodyContains("Hello"), // Expect the response body to contain "Hello" + echo.ExpectHeaders(map[string]string{ + "Content-Type": "text/plain", // Expect the Content-Type header to be "text/plain" + }), + ), +}) +``` + +## Running Tests + +### Run All Test Cases + +To run all test cases, use the following command: + +```bash +./test/e2e/run_test.sh +``` + +### Run a Single Test Case + +To run a single test case, use the following command: + +```bash +./test/e2e/run_test.sh --only-run-tests -run "TestEchoCall" +``` + +### Control Test Output Verbosity + +```bash +./test/e2e/run_test.sh -v +``` + +### Repeat Test Cases + +```bash +./test/e2e/run_test.sh -count=3 +``` From 5c3258c5a905fbe9b82f5d7203e2468cbe92626d Mon Sep 17 00:00:00 2001 From: xiaojiangao123 <2061389208@qq.com> Date: Mon, 20 Oct 2025 23:47:16 +0800 Subject: [PATCH 3/4] update e2e test doc Signed-off-by: xiaojiangao123 <2061389208@qq.com> --- .../Tests/ipsec-auth-e2e-test.md | 261 ++++++++++++++++++ 1 file changed, 261 insertions(+) diff --git a/docs/developer-guide/Tests/ipsec-auth-e2e-test.md b/docs/developer-guide/Tests/ipsec-auth-e2e-test.md index e69de29b..7e7f9d62 100644 --- a/docs/developer-guide/Tests/ipsec-auth-e2e-test.md +++ b/docs/developer-guide/Tests/ipsec-auth-e2e-test.md @@ -0,0 +1,261 @@ +# IPSec & Offload Authorization E2E Test Guide + +This document provides a step-by-step guide for executing the IPSec and Offload Authorization E2E tests for Kmesh. These tests ensure the reliability, security, and functionality of the IPSec feature and the Offload Authorization mechanisms. + +## Prerequisites + +Before running the tests, ensure the following: + +- **Kubernetes Cluster**: A two-node Kubernetes cluster with Kmesh installed. +- **Tools**: `kubectl`, `tcpdump`, and `kmeshctl`. +- **Applications**: `httpbin` and `sleep` applications deployed in the cluster. + +## IPSec E2E Tests + +### 1. Basic Connectivity Test + +This test verifies the establishment of IPSec tunnels and the correctness of encrypted communication. + +#### Steps + +1. Deploy the `httpbin` and `sleep` applications on different nodes: + + ```bash + kubectl apply -f httpbin.yaml + kubectl apply -f sleep.yaml + ``` + +2. Verify connectivity between the applications: + + ```bash + kubectl exec -- curl http:// + ``` + +3. Check IPSec state and policy rules: + + ```bash + ip xfrm state show + ip xfrm policy show + ``` + +4. Verify encryption using `tcpdump`: + + ```bash + tcpdump -i any esp + ``` + +### 2. Key Rotation Test + +This test ensures the reliability of the PSK update mechanism and validates service continuity during key changes. + +#### Steps + +1. Record the initial SPI and pre-shared key: + + ```bash + ip xfrm state show + kubectl get secret + ``` + +2. Send continuous traffic between the applications: + + ```bash + kubectl exec -- curl http:// -s -o /dev/null -w "%{http_code}\n" + ``` + +3. Update the pre-shared key: + + ```bash + kmeshctl secret create --key= + ``` + +4. Verify that the SPI and key are updated in the xfrm rules: + + ```bash + ip xfrm state show + ``` + +5. Ensure communication continuity and encryption status. + +## Offload Authorization E2E Tests + +### 1. IP Authorization Test + +This test verifies that traffic is allowed or denied based on source IP. + +#### Example Policy + +```yaml +apiVersion: security.istio.io/v1beta1 +kind: AuthorizationPolicy +metadata: + name: ip-allow-policy + namespace: test-ns1 +spec: + action: ALLOW + rules: + - from: + - source: + ipBlocks: + - "192.168.1.1" +``` + +#### Steps + +1. Apply the policy: + + ```bash + kubectl apply -f ip-allow-policy.yaml + ``` + +2. Test connectivity: + + ```bash + kubectl exec -- curl http:// + ``` + +### 2. Port Authorization Test + +This test verifies that traffic is allowed or denied based on destination ports. + +#### Example Policy + +```yaml +apiVersion: security.istio.io/v1beta1 +kind: AuthorizationPolicy +metadata: + name: port-allow-policy + namespace: test-ns1 +spec: + action: ALLOW + rules: + - to: + - operation: + ports: ["80"] +``` + +#### Steps + +1. Apply the policy: + + ```bash + kubectl apply -f port-allow-policy.yaml + ``` + +2. Test connectivity: + + ```bash + kubectl exec -- curl http:// + ``` + +### 3. Header Authorization Test + +This test verifies that traffic is allowed or denied based on HTTP headers. + +#### Example Policy + +```yaml +apiVersion: security.istio.io/v1beta1 +kind: AuthorizationPolicy +metadata: + name: header-allow-policy + namespace: test-ns1 +spec: + action: ALLOW + rules: + - when: + - key: request.headers["x-api-key"] + values: ["secret-token"] +``` + +#### Steps + +1. Apply the policy: + + ```bash + kubectl apply -f header-allow-policy.yaml + ``` + +2. Test connectivity: + + ```bash + kubectl exec -- curl -H "x-api-key: secret-token" http:// + ``` + +### 4. Namespace Authorization Test + +This test verifies that traffic is allowed or denied based on the source namespace. + +#### Example Policy + +```yaml +apiVersion: security.istio.io/v1beta1 +kind: AuthorizationPolicy +metadata: + name: namespace-allow-policy + namespace: test-ns1 +spec: + action: ALLOW + rules: + - from: + - source: + namespaces: ["test-ns2"] +``` + +#### Steps + +1. Apply the policy: + + ```bash + kubectl apply -f namespace-allow-policy.yaml + ``` + +2. Test connectivity: + + ```bash + kubectl exec -- curl http:// + ``` + +### 5. Host Authorization Test + +This test verifies that traffic is allowed or denied based on the destination host. + +#### Example Policy + +```yaml +apiVersion: security.istio.io/v1beta1 +kind: AuthorizationPolicy +metadata: + name: host-allow-policy + namespace: test-ns1 +spec: + action: ALLOW + rules: + - to: + - operation: + hosts: ["example.com"] +``` + +#### Steps + +1. Apply the policy: + + ```bash + kubectl apply -f host-allow-policy.yaml + ``` + +2. Test connectivity: + + ```bash + kubectl exec -- curl http://example.com + ``` + +## Cleanup + +After completing the tests, clean up the resources: + +```bash +kubectl delete -f httpbin.yaml +kubectl delete -f sleep.yaml +kubectl delete authorizationpolicy --all -n test-ns1 +``` From b1b7dccb9e0cb32887602139135f2affce9cba9d Mon Sep 17 00:00:00 2001 From: xiaojiangao123 <2061389208@qq.com> Date: Mon, 27 Oct 2025 17:12:55 +0800 Subject: [PATCH 4/4] fix doc Signed-off-by: xiaojiangao123 <2061389208@qq.com> --- docs/developer-guide/Tests/e2e-quickstart.md | 63 ++-- .../Tests/ipsec-auth-e2e-test.md | 276 +++++++++++------- 2 files changed, 194 insertions(+), 145 deletions(-) diff --git a/docs/developer-guide/Tests/e2e-quickstart.md b/docs/developer-guide/Tests/e2e-quickstart.md index db1e5431..ac0fe896 100644 --- a/docs/developer-guide/Tests/e2e-quickstart.md +++ b/docs/developer-guide/Tests/e2e-quickstart.md @@ -9,6 +9,8 @@ Before getting started, ensure the following tools are installed in your environ - **Go**: For running the test framework. - **Docker**: For containerizing applications. - **kubectl**: For managing Kubernetes clusters. +- **Kind**: For creating Kubernetes clusters locally. +- **Helm**: For managing Kubernetes applications. ## E2E Test Environment @@ -26,34 +28,40 @@ Both services use Echo Pods, which are used to test different scenarios. ## Writing E2E Tests -Here is a simple E2E test function template: +Here is a simple E2E test function template with step-by-step explanations: ```go func TestEchoCall(t *testing.T) { + // Create a new test suite for the current test framework.NewTest(t).Run(func(t framework.TestContext) { + // Define a subtest for the Echo Call functionality t.NewSubTest("Echo Call Test").Run(func(t framework.TestContext) { - // Retrieve test services + // Retrieve the source service (with Waypoint) and destination service (without Waypoint) src := apps.ServiceWithWaypointAtServiceGranularity[0] dst := apps.EnrolledToKmesh - // Define test cases + // Define test cases with a name and a checker to validate the response cases := []struct { name string checker echo.Checker }{ { - name: "basic call", - checker: echo.And(echo.ExpectOK(), echo.ExpectBodyContains("Hello")), + name: "basic call", // Name of the test case + checker: echo.And( + echo.ExpectOK(), // Expect the HTTP call to succeed + echo.ExpectBodyContains("Hello"), // Expect the response body to contain "Hello" + ), }, } - // Execute test cases + // Iterate over each test case and execute it for _, c := range cases { t.NewSubTest(c.name).Run(func(t framework.TestContext) { + // Perform the HTTP call from the source to the destination src.CallOrFail(t, echo.CallOptions{ - Target: dst[0], - PortName: "http", - Checker: c.checker, + Target: dst[0], // Target service + PortName: "http", // Port name to use for the call + Checker: c.checker, // Checker to validate the response }) }) } @@ -62,6 +70,15 @@ func TestEchoCall(t *testing.T) { } ``` +### Explanation of Steps + +1. **`framework.NewTest(t).Run`**: Initializes a new test suite for the current test. +2. **`t.NewSubTest("Echo Call Test").Run`**: Creates a subtest for the Echo Call functionality. +3. **Retrieve Services**: The `src` variable represents the source service (with Waypoint), and the `dst` variable represents the destination service (without Waypoint). +4. **Define Test Cases**: Each test case includes a name and a `checker` to validate the HTTP response. For example, `echo.ExpectOK()` ensures the HTTP call succeeds, and `echo.ExpectBodyContains("Hello")` checks the response body. +5. **Iterate and Execute**: For each test case, the `src.CallOrFail` method performs the HTTP call from the source to the destination and validates the response using the specified `checker`. +6. **`echo.CallOptions`**: Specifies the target service, port name, and checker for the HTTP call. + ### Resource Cleanup Use the `t.Cleanup` method to ensure test resources are cleaned up after the test completes. For example: @@ -109,30 +126,4 @@ src.CallOrFail(t, echo.CallOptions{ ## Running Tests -### Run All Test Cases - -To run all test cases, use the following command: - -```bash -./test/e2e/run_test.sh -``` - -### Run a Single Test Case - -To run a single test case, use the following command: - -```bash -./test/e2e/run_test.sh --only-run-tests -run "TestEchoCall" -``` - -### Control Test Output Verbosity - -```bash -./test/e2e/run_test.sh -v -``` - -### Repeat Test Cases - -```bash -./test/e2e/run_test.sh -count=3 -``` +For detailed instructions on running tests, refer to the [E2E Test Guide](https://kmesh.net/docs/developer-guide/Tests/e2e-test). diff --git a/docs/developer-guide/Tests/ipsec-auth-e2e-test.md b/docs/developer-guide/Tests/ipsec-auth-e2e-test.md index 7e7f9d62..b67c156f 100644 --- a/docs/developer-guide/Tests/ipsec-auth-e2e-test.md +++ b/docs/developer-guide/Tests/ipsec-auth-e2e-test.md @@ -8,7 +8,84 @@ Before running the tests, ensure the following: - **Kubernetes Cluster**: A two-node Kubernetes cluster with Kmesh installed. - **Tools**: `kubectl`, `tcpdump`, and `kmeshctl`. -- **Applications**: `httpbin` and `sleep` applications deployed in the cluster. +- **Applications**: `echo` and `sleep` applications deployed in the cluster. + +## Example YAML for Deployment + +**Sleep Application (save as `sleep.yaml`):** + +```yaml +apiVersion: v1 +kind: Service +metadata: + name: sleep + labels: + app: sleep +spec: + ports: + - port: 80 + name: http + selector: + app: sleep +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: sleep +spec: + replicas: 1 + selector: + matchLabels: + app: sleep + template: + metadata: + labels: + app: sleep + spec: + nodeName: kmesh-testing-control-plane + containers: + - name: sleep + image: curlimages/curl + command: ["/bin/sleep", "infinity"] +``` + +**Echo Application (save as `echo.yaml`):** + +```yaml +apiVersion: v1 +kind: Service +metadata: + name: echo +spec: + ports: + - name: http + port: 80 + targetPort: 8080 + selector: + app: echo +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: echo +spec: + replicas: 1 + selector: + matchLabels: + app: echo + template: + metadata: + labels: + app: echo + spec: + containers: + - name: echo + image: gcr.io/istio-testing/app:latest + args: + - --port=8080 + ports: + - containerPort: 8080 +``` ## IPSec E2E Tests @@ -18,49 +95,91 @@ This test verifies the establishment of IPSec tunnels and the correctness of enc #### Steps -1. Deploy the `httpbin` and `sleep` applications on different nodes: +1. Deploy the `sleep` and `echo` applications: ```bash - kubectl apply -f httpbin.yaml kubectl apply -f sleep.yaml + kubectl apply -f echo.yaml ``` 2. Verify connectivity between the applications: ```bash - kubectl exec -- curl http:// + kubectl exec -- curl http:// + ``` + + **Expected Output:** + + ```plaintext + Hello version: v1, instance: echo- ``` -3. Check IPSec state and policy rules: +3. Check IPSec state: ```bash ip xfrm state show + ``` + + **Expected Output:** + + ```plaintext + src {{SRC_IP}} dst {{DST_IP}} + proto esp spi 0x{{SPI}} reqid 1 mode tunnel + replay-window 0 + output-mark 0xd0/0xffffffff + aead rfc4106(gcm(aes)) {{KEY}} 128 + anti-replay context: seq 0x0, oseq 0x0, bitmap 0x00000000 + sel src ::/0 dst ::/0 + ``` + +4. Check IPSec policy: + + ```bash ip xfrm policy show ``` -4. Verify encryption using `tcpdump`: + **Expected Output:** + + ```plaintext + src ::/0 dst {{DST_SUBNET}} + dir out priority 0 + mark 0xe0/0xffffffff + tmpl src {{SRC_IP}} dst {{DST_IP}} + proto esp spi 0x{{SPI}} reqid 1 mode tunnel + ``` + +5. Verify encryption using `tcpdump`: ```bash tcpdump -i any esp ``` + **Expected Output:** ESP packets should be visible during communication. + ### 2. Key Rotation Test This test ensures the reliability of the PSK update mechanism and validates service continuity during key changes. #### Steps -1. Record the initial SPI and pre-shared key: +1. Record the initial SPI: ```bash ip xfrm state show - kubectl get secret + ``` + + **Expected Output:** + + ```plaintext + src {{SRC_IP}} dst {{DST_IP}} + proto esp spi 0x{{INITIAL_SPI}} reqid 1 mode tunnel + aead rfc4106(gcm(aes)) {{INITIAL_KEY}} 128 ``` 2. Send continuous traffic between the applications: ```bash - kubectl exec -- curl http:// -s -o /dev/null -w "%{http_code}\n" + kubectl exec -- curl http:// ``` 3. Update the pre-shared key: @@ -75,15 +194,40 @@ This test ensures the reliability of the PSK update mechanism and validates serv ip xfrm state show ``` + **Expected Output:** + + ```plaintext + src {{SRC_IP}} dst {{DST_IP}} + proto esp spi 0x{{INITIAL_SPI + 1}} reqid 1 mode tunnel + aead rfc4106(gcm(aes)) {{NEW_KEY}} 128 + ``` + 5. Ensure communication continuity and encryption status. ## Offload Authorization E2E Tests -### 1. IP Authorization Test +### Unified Steps for Authorization Tests -This test verifies that traffic is allowed or denied based on source IP. +1. Apply the policy: -#### Example Policy + ```bash + kubectl apply -f .yaml + ``` + +2. Test connectivity: + + ```bash + kubectl exec -- curl http:// + ``` + + **Expected Output:** + + - **ALLOW Policy:** The curl command should succeed, and the HTTP response code should be `200`. + - **DENY Policy:** The curl command should fail, and no response should be received. + +### Example Policies + +#### IP Authorization Policy ```yaml apiVersion: security.istio.io/v1beta1 @@ -97,28 +241,10 @@ spec: - from: - source: ipBlocks: - - "192.168.1.1" + - "{{ALLOWED_IP}}" ``` -#### Steps - -1. Apply the policy: - - ```bash - kubectl apply -f ip-allow-policy.yaml - ``` - -2. Test connectivity: - - ```bash - kubectl exec -- curl http:// - ``` - -### 2. Port Authorization Test - -This test verifies that traffic is allowed or denied based on destination ports. - -#### Example Policy +#### Port Authorization Policy ```yaml apiVersion: security.istio.io/v1beta1 @@ -131,28 +257,10 @@ spec: rules: - to: - operation: - ports: ["80"] + ports: ["{{ALLOWED_PORT}}"] ``` -#### Steps - -1. Apply the policy: - - ```bash - kubectl apply -f port-allow-policy.yaml - ``` - -2. Test connectivity: - - ```bash - kubectl exec -- curl http:// - ``` - -### 3. Header Authorization Test - -This test verifies that traffic is allowed or denied based on HTTP headers. - -#### Example Policy +#### Header Authorization Policy ```yaml apiVersion: security.istio.io/v1beta1 @@ -164,29 +272,11 @@ spec: action: ALLOW rules: - when: - - key: request.headers["x-api-key"] - values: ["secret-token"] + - key: request.headers["{{HEADER_NAME}}"] + values: ["{{HEADER_VALUE}}"] ``` -#### Steps - -1. Apply the policy: - - ```bash - kubectl apply -f header-allow-policy.yaml - ``` - -2. Test connectivity: - - ```bash - kubectl exec -- curl -H "x-api-key: secret-token" http:// - ``` - -### 4. Namespace Authorization Test - -This test verifies that traffic is allowed or denied based on the source namespace. - -#### Example Policy +#### Namespace Authorization Policy ```yaml apiVersion: security.istio.io/v1beta1 @@ -199,28 +289,10 @@ spec: rules: - from: - source: - namespaces: ["test-ns2"] + namespaces: ["{{SOURCE_NAMESPACE}}"] ``` -#### Steps - -1. Apply the policy: - - ```bash - kubectl apply -f namespace-allow-policy.yaml - ``` - -2. Test connectivity: - - ```bash - kubectl exec -- curl http:// - ``` - -### 5. Host Authorization Test - -This test verifies that traffic is allowed or denied based on the destination host. - -#### Example Policy +#### Host Authorization Policy ```yaml apiVersion: security.istio.io/v1beta1 @@ -233,29 +305,15 @@ spec: rules: - to: - operation: - hosts: ["example.com"] + hosts: ["{{TARGET_HOST}}"] ``` -#### Steps - -1. Apply the policy: - - ```bash - kubectl apply -f host-allow-policy.yaml - ``` - -2. Test connectivity: - - ```bash - kubectl exec -- curl http://example.com - ``` - ## Cleanup After completing the tests, clean up the resources: ```bash -kubectl delete -f httpbin.yaml kubectl delete -f sleep.yaml +kubectl delete -f echo.yaml kubectl delete authorizationpolicy --all -n test-ns1 ```