Skip to content

Commit 2ab612b

Browse files
kayx23kayx23
committed
update reference exmaple docs
1 parent 6b98bdb commit 2ab612b

File tree

1 file changed

+234
-13
lines changed

1 file changed

+234
-13
lines changed

‎docs/en/latest/reference/example.md‎

Lines changed: 234 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,14 @@ spec:
5252
value: replace-with-your-admin-key
5353
```
5454
55+
:::important
56+
57+
All resources within the same gateway group must use the same IngressClass (for Ingress / APISIX CRDs) or Gateway (for Gateway API), each of which points to a single GatewayProxy.
58+
59+
Using multiple GatewayProxy, IngressClass, or Gateway resources for a single gateway group can lead to conflicts and unintended resource overwrites.
60+
61+
:::
62+
5563
## Define Controller and Gateway
5664
5765
To specify the controller responsible for handling resources before applying further configurations:
@@ -94,7 +102,7 @@ spec:
94102
name: apisix-config # 5
95103
```
96104
97-
❶ The controllerName field in GatewayClass needs to be customized if you are running multiple distinct instances of the APISIX Ingress Controller in the same cluster (not a single instance with multiple replicas). Each ingress controller instance must use a unique controllerName in its [configuration file](configuration-file.md), and the corresponding GatewayClass should reference that value.
105+
❶ The controller name should be customized if you are running multiple distinct instances of the APISIX Ingress Controller in the same cluster (not a single instance with multiple replicas). Each ingress controller instance must use a unique controllerName in its [configuration file](configuration-file.md), and the corresponding GatewayClass should reference that value.
98106
99107
❷ The `port` in the Gateway listener is required but ignored. This is due to limitations in the data plane: it cannot dynamically open new ports. Since the Ingress Controller does not manage the data plane deployment, it cannot automatically update the configuration or restart the data plane to apply port changes.
100108

@@ -115,15 +123,25 @@ metadata:
115123
namespace: ingress-apisix
116124
name: apisix
117125
spec:
118-
controller: apisix.apache.org/apisix-ingress-controller
126+
controller: apisix.apache.org/apisix-ingress-controller # 1
119127
parameters:
120-
apiGroup: apisix.apache.org
121-
kind: GatewayProxy
122-
name: apisix-config
123-
namespace: ingress-apisix
124-
scope: Namespace
128+
apiGroup: apisix.apache.org # 2
129+
kind: GatewayProxy # 3
130+
name: apisix-config # 4
131+
namespace: ingress-apisix # 5
132+
scope: Namespace # 6
125133
```
126134

135+
❷ API group of the referenced resource.
136+
137+
❸ Kind of the referenced resource.
138+
139+
❹ Name of the referenced resource. Should match the `metadata.name` of the GatewayProxy resource.
140+
141+
❺ Namespace where the referenced resource is defined.
142+
143+
❻ Scope of the referenced resource.
144+
127145
</TabItem>
128146

129147
<TabItem value="apisix-crd">
@@ -135,15 +153,25 @@ metadata:
135153
namespace: ingress-apisix
136154
name: apisix
137155
spec:
138-
controller: apisix.apache.org/apisix-ingress-controller
156+
controller: apisix.apache.org/apisix-ingress-controller # 1
139157
parameters:
140-
apiGroup: apisix.apache.org
141-
kind: GatewayProxy
142-
name: apisix-config
143-
namespace: ingress-apisix
144-
scope: Namespace
158+
apiGroup: apisix.apache.org # 2
159+
kind: GatewayProxy # 3
160+
name: apisix-config # 4
161+
namespace: ingress-apisix # 5
162+
scope: Namespace # 6
145163
```
146164

165+
❷ API group of the referenced resource.
166+
167+
❸ Kind of the referenced resource.
168+
169+
❹ Name of the referenced resource. Should match the `metadata.name` of the GatewayProxy resource.
170+
171+
❺ Namespace where the referenced resource is defined.
172+
173+
❻ Scope of the referenced resource.
174+
147175
</TabItem>
148176

149177
</Tabs>
@@ -836,6 +864,15 @@ metadata:
836864
namespace: ingress-apisix
837865
name: apisix-config
838866
spec:
867+
provider:
868+
type: ControlPlane
869+
controlPlane:
870+
endpoints:
871+
- https://xxx.xxx.xxx.xxx:7443 # update with your CP endpoint
872+
auth:
873+
type: AdminKey
874+
adminKey:
875+
value: xxxxxxxxxxx # update with your admin key
839876
plugins:
840877
- name: clickhouse-logger
841878
config:
@@ -894,6 +931,15 @@ metadata:
894931
namespace: ingress-apisix
895932
name: apisix-config
896933
spec:
934+
provider:
935+
type: ControlPlane
936+
controlPlane:
937+
endpoints:
938+
- https://xxx.xxx.xxx.xxx:7443 # update with your CP endpoint
939+
auth:
940+
type: AdminKey
941+
adminKey:
942+
value: xxxxxxxxxxx # update with your admin key
897943
pluginMetadata:
898944
opentelemetry: {
899945
"trace_id_source": "x-request-id",
@@ -1023,6 +1069,154 @@ spec:
10231069

10241070
</Tabs>
10251071

1072+
## Configure Downstream (m)TLS
1073+
1074+
To configure downstream TLS:
1075+
1076+
<Tabs
1077+
groupId="k8s-api"
1078+
defaultValue="gateway"
1079+
values={[
1080+
{label: 'Gateway API', value: 'gateway'},
1081+
{label: 'APISIX CRD', value: 'apisix-crd'},
1082+
]}>
1083+
1084+
<TabItem value="gateway">
1085+
1086+
```yaml
1087+
apiVersion: v1
1088+
kind: Secret
1089+
metadata:
1090+
namespace: api7
1091+
name: test-tls-secret
1092+
type: kubernetes.io/tls
1093+
data:
1094+
tls.crt: <base64-encoded cert>
1095+
tls.key: <base64-encoded key>
1096+
---
1097+
apiVersion: gateway.networking.k8s.io/v1
1098+
kind: Gateway
1099+
metadata:
1100+
namespace: api7
1101+
name: apisix
1102+
spec:
1103+
gatewayClassName: apisix
1104+
listeners:
1105+
- name: https
1106+
protocol: HTTPS
1107+
port: 443
1108+
hostname: apisix.test
1109+
tls:
1110+
certificateRefs:
1111+
- kind: Secret
1112+
group: ""
1113+
name: test-tls-secret
1114+
infrastructure:
1115+
parametersRef:
1116+
group: apisix.apache.org
1117+
kind: GatewayProxy
1118+
name: apisix-proxy-config
1119+
```
1120+
1121+
:::note
1122+
1123+
The `port` in the Gateway listener is required but ignored. This is due to limitations in the data plane: it cannot dynamically open new ports. Since the Ingress Controller does not manage the data plane deployment, it cannot automatically update the configuration or restart the data plane to apply port changes.
1124+
1125+
:::
1126+
1127+
</TabItem>
1128+
1129+
<TabItem value="apisix-crd">
1130+
1131+
```yaml
1132+
apiVersion: v1
1133+
kind: Secret
1134+
metadata:
1135+
namespace: api7
1136+
name: test-tls-secret
1137+
type: kubernetes.io/tls
1138+
data:
1139+
tls.crt: <base64-encoded cert>
1140+
tls.key: <base64-encoded key>
1141+
---
1142+
apiVersion: apisix.apache.org/v2
1143+
kind: ApisixTls
1144+
metadata:
1145+
namespace: api7
1146+
name: test-tls
1147+
spec:
1148+
ingressClassName: apisix-tls
1149+
hosts:
1150+
- apisix.test
1151+
secret:
1152+
name: test-tls-secret
1153+
namespace: api7
1154+
```
1155+
1156+
</TabItem>
1157+
1158+
</Tabs>
1159+
1160+
To configure downstream mTLS:
1161+
1162+
<Tabs
1163+
groupId="k8s-api"
1164+
defaultValue="gateway"
1165+
values={[
1166+
{label: 'Gateway API', value: 'gateway'},
1167+
{label: 'APISIX CRD', value: 'apisix-crd'},
1168+
]}>
1169+
1170+
<TabItem value="gateway">
1171+
1172+
Not supported.
1173+
1174+
</TabItem>
1175+
1176+
<TabItem value="apisix-crd">
1177+
1178+
```yaml
1179+
apiVersion: v1
1180+
kind: Secret
1181+
metadata:
1182+
namespace: api7
1183+
name: test-mtls-secret
1184+
type: kubernetes.io/tls
1185+
data:
1186+
tls.crt: <base64-encoded cert>
1187+
tls.key: <base64-encoded key>
1188+
---
1189+
apiVersion: v1
1190+
kind: Secret
1191+
metadata:
1192+
namespace: api7
1193+
name: test-ca-secret
1194+
data:
1195+
cert: <base64-encoded caCert>
1196+
---
1197+
apiVersion: apisix.apache.org/v2
1198+
kind: ApisixTls
1199+
metadata:
1200+
namespace: api7
1201+
name: test-mtls
1202+
spec:
1203+
ingressClassName: apisix-tls
1204+
hosts:
1205+
- apisix.test
1206+
secret:
1207+
name: test-mtls-secret
1208+
namespace: api7
1209+
client:
1210+
caSecret:
1211+
name: test-ca-secret
1212+
namespace: api7
1213+
depth: 1
1214+
```
1215+
1216+
</TabItem>
1217+
1218+
</Tabs>
1219+
10261220
## Configure Gateway Access Information
10271221

10281222
These configurations allow Ingress Controller users to access the gateway.
@@ -1047,6 +1241,15 @@ metadata:
10471241
namespace: ingress-apisix
10481242
name: apisix-config
10491243
spec:
1244+
provider:
1245+
type: ControlPlane
1246+
controlPlane:
1247+
endpoints:
1248+
- https://xxx.xxx.xxx.xxx:7443 # update with your CP endpoint
1249+
auth:
1250+
type: AdminKey
1251+
adminKey:
1252+
value: xxxxxxxxxxx # update with your admin key
10501253
statusAddress:
10511254
- 10.24.87.13
10521255
```
@@ -1066,6 +1269,15 @@ metadata:
10661269
namespace: ingress-apisix
10671270
name: apisix-config
10681271
spec:
1272+
provider:
1273+
type: ControlPlane
1274+
controlPlane:
1275+
endpoints:
1276+
- https://xxx.xxx.xxx.xxx:7443 # update with your CP endpoint
1277+
auth:
1278+
type: AdminKey
1279+
adminKey:
1280+
value: xxxxxxxxxxx # update with your admin key
10691281
statusAddress:
10701282
- 10.24.87.13
10711283
```
@@ -1079,6 +1291,15 @@ metadata:
10791291
namespace: ingress-apisix
10801292
name: apisix-config
10811293
spec:
1294+
provider:
1295+
type: ControlPlane
1296+
controlPlane:
1297+
endpoints:
1298+
- https://xxx.xxx.xxx.xxx:7443 # update with your CP endpoint
1299+
auth:
1300+
type: AdminKey
1301+
adminKey:
1302+
value: xxxxxxxxxxx # update with your admin key
10821303
publishService: apisix-ee-3-gateway-gateway
10831304
```
10841305

0 commit comments

Comments
 (0)