This is an automated email from the ASF dual-hosted git repository.
traky pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix-ingress-controller.git
The following commit(s) were added to refs/heads/master by this push:
new 2b7b2478 docs: add `apisix.apache.org/parameters-namespace` to
annotation doc (#2702)
2b7b2478 is described below
commit 2b7b24780c51932e5fec4c630e9200b2a8cbf955
Author: Traky Deng <[email protected]>
AuthorDate: Fri Jan 16 15:31:42 2026 +0800
docs: add `apisix.apache.org/parameters-namespace` to annotation doc (#2702)
---
docs/en/latest/config.json | 2 +-
.../{ingress-annotation.md => annotations.md} | 40 +++++++++++++++++++---
2 files changed, 36 insertions(+), 6 deletions(-)
diff --git a/docs/en/latest/config.json b/docs/en/latest/config.json
index e469fdb7..520b5775 100644
--- a/docs/en/latest/config.json
+++ b/docs/en/latest/config.json
@@ -41,7 +41,7 @@
"reference/example",
"reference/troubleshoot",
"reference/configuration-file",
- "reference/ingress-annotation"
+ "reference/annotations"
]
},
{
diff --git a/docs/en/latest/reference/ingress-annotation.md
b/docs/en/latest/reference/annotations.md
similarity index 92%
rename from docs/en/latest/reference/ingress-annotation.md
rename to docs/en/latest/reference/annotations.md
index bb68422a..c1607e63 100644
--- a/docs/en/latest/reference/ingress-annotation.md
+++ b/docs/en/latest/reference/annotations.md
@@ -1,14 +1,14 @@
---
-title: Ingress Annotations
+title: Annotations
slug: /reference/apisix-ingress-controller/annotation
-description: Learn how annotations extend the functionality of Kubernetes
Ingress resource in APISIX Ingress Controller to configure routing, security,
and gateway behaviors.
+description: Learn how annotations extend the functionality of Kubernetes
Ingress and IngressClass resource in APISIX Ingress Controller to configure
routing, security, and gateway behaviors.
---
-Annotations are key-value pairs that allow controllers to configure
functionalities that are not available through standard Kubernetes resource
fields. In APISIX Ingress Controller, annotations are commonly used with
Ingress resources to configure gateway behaviors, routing rules, upstream
settings, plugins, and other features. Alternatively, you can use APISIX CRDs
to configure these features for a better experience.
+Annotations are key-value pairs that allow controllers to configure
functionalities that are not available through standard Kubernetes resource
fields. In APISIX Ingress Controller, annotations are commonly used to
configure gateway behaviors, routing rules, upstream settings, plugins, and
other features. Alternatively, you can use APISIX CRDs to configure these
features for a better experience.
This document describes all available annotations and their uses.
-## All Annotations
+## Ingress Annotations
| Annotation |
| ------------------------------------------------------ |
@@ -52,6 +52,12 @@ This document describes all available annotations and their
uses.
| `k8s.apisix.apache.org/auth-type` |
| `k8s.apisix.apache.org/svc-namespace` |
+## IngressClass Annotations
+
+| Annotation |
+| ------------------------------------------------------ |
+| `apisix.apache.org/parameters-namespace` |
+
## Annotation Details
Note that annotation keys and values can only be strings.
@@ -272,8 +278,9 @@ apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: cross-namespace-ingress
+ namespace: aic # Ingress is in aic namespace
annotations:
- k8s.apisix.apache.org/svc-namespace: "other-namespace"
+ k8s.apisix.apache.org/svc-namespace: "other-namespace" # Service is in
other-namespace
spec:
ingressClassName: apisix
rules:
@@ -610,3 +617,26 @@ spec:
port:
number: 80
```
+
+### GatewayProxy Namespace Specification
+
+The `apisix.apache.org/parameters-namespace` annotation enables the
specification of a custom namespace for GatewayProxy resources referenced by an
IngressClass. This is used when a GatewayProxy resource resides in a specific
namespace, as IngressClass is cluster-scoped and requires the namespace to
locate the resource.
+
+The annotation takes precedence over the `parameters.namespace` field in the
IngressClass spec. If neither is specified, it defaults to the `default`
namespace.
+
+For example:
+
+```yaml
+apiVersion: networking.k8s.io/v1
+kind: IngressClass
+metadata:
+ name: apisix
+ annotations:
+ apisix.apache.org/parameters-namespace: "apisix-system"
+spec:
+ controller: apisix.apache.org/ingress-controller
+ parameters:
+ apiGroup: apisix.apache.org
+ kind: GatewayProxy
+ name: apisix-config
+```
