Customize IP-based Rate Limiting for CCM's Internal WCM Access Route

This guide provides end-users with the understanding and step-by-step procedure to customize the IP-based rate limiting settings for the Customer Channel Manager's (CCM) internal-wcm-access route using APISIX plugin configurations in your Helm values.yaml file.

Introduction to IP Rate Limiting on CCM's `internal-wcm-access` Route

A. Purpose of Rate Limiting

The internal-wcm-access route for the CCM component (typically handling traffic from the Web Channel Manager via paths like /internal-wcm-to-ccm/*) has IP-based rate limiting configured. The primary purposes are to:

Protect the CCM service: Prevents the service from being overwhelmed by an excessive number of requests originating from a single IP address (likely the Web Channel Manager instances or internal systems).
Prevent Abuse & Ensure Fair Usage: Deters potential misuse or runaway processes from degrading service performance.
Enhance Service Stability & Availability: Contributes to the overall reliability of the CCM service by mitigating certain types of denial-of-service or high-load scenarios from specific sources.

B. How it's Implemented

This rate limiting is achieved using the limit-count plugin within APISIX. Key aspects of its implementation on this route include:

It's defined within the customPlugins list for the internal-wcm-access route specific to the ccm component in your Helm values.yaml (typically found in your "Core" chart or equivalent).
It works in conjunction with the real-ip plugin, which is configured to run before limit-count. The real-ip plugin ensures that APISIX uses the actual client IP address (e.g., from the X-Forwarded-For header) for rate limiting, rather than the IP of an intermediate proxy.

C. Example Current Configuration

Based on a typical configuration from your "Core" chart, the limit-count plugin for this route might be set to something like:

Limit: 10 requests
Time Window: 1 second
Per: Client IP Address
Rejection Code: 429 (Too Many Requests)

Always refer to your actual deployed values.yaml for the precise current settings.

Understanding Key `limit-count` Plugin Parameters

When customizing, you'll primarily interact with the following parameters within the config block of the limit-count plugin definition:

Parameter	Description	Impact of Customization
`count`	The maximum number of requests allowed from a single key (in this case, an IP address) within the defined `time_window`.	Increasing allows more requests (less restrictive); decreasing allows fewer (more restrictive).
`time_window`	The duration in seconds for which the `count` is enforced. After this window, the count for the key resets.	A shorter window resets limits more frequently. Balance this with `count` (e.g., 10 reqs/1 sec is different from 600 reqs/60 secs).
`key_type`	The type of key to be used for rate limiting. For IP-based limiting, this is typically `"var"`.	Usually kept as `"var"` for IP-based limiting when used with `key: "remote_addr"`.
`key`	The specific variable or identifier used for rate limiting. For IP-based, this is `"remote_addr"`, which refers to the client's IP address (resolved by the `real-ip` plugin).	Changing this would alter the basis of rate limiting (e.g., to a specific header or argument, which is a more advanced scenario not covered here). For IP limiting, keep as `"remote_addr"`.
`rejected_code`	The HTTP status code returned to the client when the rate limit is exceeded.	Typically `429` (Too Many Requests). Can be changed if a different error code is desired for specific client handling.
`rejected_msg`	The JSON message body returned when the rate limit is exceeded.	Can be customized to provide a more specific or user-friendly error message (ensure valid JSON format).
`show_limit_quota_header`	If set to `true`, APISIX adds response headers like `X-RateLimit-Limit` (total allowed), `X-RateLimit-Remaining` (remaining in window), and `X-RateLimit-Reset` (seconds until reset).	Setting to `true` is recommended as it helps clients understand their current limit status and adjust behavior programmatically.
`enable` (within this plugin's entry)	A boolean (`true` or `false`) that activates or deactivates this specific `limit-count` plugin instance.	Set to `false` to temporarily disable IP rate limiting on this route without removing the configuration.

Procedure for Customizing the IP Rate Limit

A. Prerequisites

Administrative or appropriate write access to the Helm values.yaml file for the "Core" chart (or the chart containing the ccm component definition).
A basic understanding of YAML syntax.
Access to tools or processes for deploying Helm chart changes (e.g., helm CLI, GitOps pipeline).

B. Locate the Configuration

Open your primary Helm values.yaml file (e.g., the "Core" chart's values).
Navigate to the ccm: component section.
Inside ccm:, find the apisixRoutes: list.
Identify the specific route definition that has nameSuffix: "internal-wcm-access". This route typically handles paths like /internal-wcm-to-ccm/*.
Within this route's definition, find the plugins: block, and then the customPlugins: list.
Locate the item (dictionary) in the customPlugins list where name: "limit-count".

C. Modify Parameters

You will edit the config: block for the limit-count plugin.

Example YAML snippet to modify (from ccm.apisixRoutes for internal-wcm-access):

CODE


# ... (other parts of the route definition) ...
customPlugins:
  - name: "real-ip"
    enable: true
    config:
      source: "X-Forwarded-For"
      trusted_addresses: ["10.42.0.0/16"] # Example: Ensure this matches your K8s Pod CIDR or trusted proxy ranges
  - name: "limit-count"
    enable: true  # Ensure this is true to keep rate limiting active
    config:
      count: 10                             # <-- To change max requests, modify this (e.g., to 50)
      time_window: 1                        # <-- To change time window, modify this (e.g., to 60 for 1 minute)
      key_type: "var"
      key: "remote_addr"                    # Identifies users by IP
      rejected_code: 429                    # HTTP code for rejected requests
      rejected_msg: "{\"error\":\"Internal rate limit exceeded .\"}" # <-- Customize this JSON message if needed
      show_limit_quota_header: true         # Set to true/false to control informative headers
# ... (other custom plugins or end of list) ...

To change the **maximum allowed requests** within the time window, modify the count: value.
To change the **duration of the time window**, modify the time_window: value (specified in seconds).
To change the **error message** for rejected requests, modify the rejected_msg: value. Ensure it remains valid JSON.
To **disable rate limiting temporarily** for this route, you can set enable: false for the limit-count plugin entry. Remember to set it back to true to re-enable.

D. Important Note on the `real-ip` Plugin

The limit-count plugin on this route relies on the real-ip plugin being configured correctly and enabled before it in the customPlugins list. The real-ip plugin (usually configured with source: "X-Forwarded-For" and appropriate trusted_addresses) ensures that the remote_addr variable used by limit-count contains the actual originating client IP address, not the IP of an internal Kubernetes proxy or load balancer.
Generally, you should not need to modify the real-ip plugin's settings unless your cluster's network ingress topology changes significantly or if you notice IPs from your internal proxy ranges being rate-limited.

E. Apply and Verify Changes

Save your modified values.yaml file.
Deploy the changes using your standard Helm chart deployment process (e.g., helm upgrade <release-name> <chart-path> -f values.yaml or via your GitOps pipeline).
Verify Thoroughly:
- Send a number of requests below the new count limit (from a single test IP) within the time_window to the /internal-wcm-to-ccm/* path. Confirm these requests are successful (e.g., HTTP 200).
- Send a number of requests exceeding the new count limit (from the same IP) within the time_window. Confirm these excess requests are rejected with the configured rejected_code (e.g., 429) and rejected_msg.
- If show_limit_quota_header: true, inspect the response headers of successful requests to see X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset.
- Monitor APISIX logs (if accessible) for entries related to rate limiting actions.
- Monitor the ccm service logs to ensure it's behaving as expected and not showing an unusual number of errors that might indicate overly restrictive limits affecting legitimate traffic.

Considerations & Best Practices for Customization

A. Determining Appropriate Limits

Analyze Traffic Patterns: Before changing limits, try to understand the typical and peak request rates for the /internal-wcm-to-ccm/* endpoint from its legitimate source (usually the Web Channel Manager). If you have metrics or logs, review them.
Service Capacity: Consider the capacity of the CCM service itself. The rate limit should help protect it, not be the bottleneck if the service can handle more.
Start Conservatively or Incrementally: If significantly changing limits, it's often safer to make incremental adjustments and monitor the impact rather than making very large changes at once.
Business Needs: Balance the need for protection against the risk of impacting legitimate service operations.

B. Impact of Changes

Too Restrictive Limits: May block legitimate traffic from the Web Channel Manager (or other internal systems using this route), leading to functional issues in the customer interaction flow. Symptoms might include failed operations in the Web Channel Manager or errors reported by it.
Too Permissive Limits: May not offer adequate protection against accidental high load (e.g., a misbehaving script in WCM) or potential abuse if the endpoint were ever indirectly exposed.

C. Communication

If other teams or systems rely on or manage the Web Channel Manager (the typical client for this internal route), inform them of any planned changes to the rate limits, as it might affect their troubleshooting or understanding of system behavior.

D. Monitoring

After applying changes, closely monitor:
- APISIX metrics or logs for the occurrence of 429 responses on this route. A sudden spike might indicate limits are too tight.
- The performance, error rates, and logs of the ccm service and the Web Channel Manager.

What the End-User Should Expect

A. Before Modification

The CCM component's /internal-wcm-to-ccm/* path is protected by its existing IP-based rate limit (e.g., the example of 10 requests/1 second per IP).
IP addresses (typically the Web Channel Manager instances) exceeding this limit will receive an HTTP 429 error with the configured JSON message.

B. During Modification (Deployment)

The Helm deployment process (helm upgrade or GitOps sync) will update the APISIX configuration.
APISIX typically reloads its configuration gracefully without dropping active connections. New requests will start adhering to the new rate limit rules very quickly after the update is effective in APISIX.

C. After Modification

The /internal-wcm-to-ccm/* path will enforce the newly configured rate limits (new count, time_window, etc.).
If the rejected_code or rejected_msg was changed, clients exceeding the limit will receive this new response.
The system (CCM and its interaction with Web Channel Manager) should operate normally under the new limits.
Crucially, verify that the change has achieved the desired outcome (e.g., reduced unnecessary 429s if limits were too low, or maintained protection if limits were adjusted for other reasons) without negatively impacting legitimate service functionality.

Introduction to IP Rate Limiting on CCM's internal-wcm-access Route