Add documentation and tests for dollar sign escaping in config

apollo-router/src/configuration/expansion.rs

@@ -536,4 +536,30 @@ mod test {
             assert_yaml_snapshot!(value);
         })
     }
+
+    #[test]
+    fn test_dollar_escape() {
+        // Test that $$ is escaped to a literal $ by shellexpand
+        let expansion = Expansion::builder()
+            .mocked_env_var("API_HOST", "api.example.com")
+            .supported_mode("env")
+            .build();
+
+        let value = json!({
+            // $$ should become a single $
+            "literal_dollar": "some$$api$$key",
+            // $$ alongside ${env.VAR} expansion
+            "mixed": "https://${env.API_HOST}/path?price=$$100",
+            // Multiple $$ in a row
+            "multiple_escapes": "$$first $$second $$third",
+            // $$ at start and end
+            "edges": "$$start and end$$",
+            // No expansion needed (plain string)
+            "plain": "no dollars here"
+        });
+        let result = expansion.expand(&value).expect("expansion must succeed");
+        insta::with_settings!({sort_maps => true}, {
+            assert_yaml_snapshot!(result);
+        })
+    }
 }

apollo-router/src/configuration/snapshots/apollo_router__configuration__expansion__test__dollar_escape.snap

@@ -0,0 +1,9 @@
+---
+source: apollo-router/src/configuration/expansion.rs
+expression: result
+---
+edges: $start and end$
+literal_dollar: some$api$key
+mixed: "https://api.example.com/path?price=$100"
+multiple_escapes: $first $second $third
+plain: no dollars here

docs/source/routing/configuration/yaml.mdx

@@ -841,6 +841,13 @@ headers:
 
 Here, the `name` and `value` entries under `&insert_custom_header` are reused under `*insert_custom_header`.
 
+### Escaping special characters
+
+To include a literal `$` character, double it as `$$`. The router converts each `$$` to a single `$`:
+
+- Config value: `prefix$$suffix`
+- Result: `prefix$suffix`
+
 ## Related topics
 
 - [Checklist for configuring the router for production](/technotes/TN0008-production-readiness-checklist/#apollo-router)