Skip to content

Commit 4066eca

Browse files
AlinsRanAlinsRan
committed
docs: add upgrade-guide doc
1 parent 4ee2596 commit 4066eca

File tree

2 files changed

+171
-0
lines changed

2 files changed

+171
-0
lines changed

‎docs/assets/images/upgrade-to-architecture.png‎

277 KB
Loading

‎docs/upgrade-guide.md‎

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
# APISIX Ingress Controller Upgrade Guide
2+
3+
## Upgrading from 1.x.x to 2.0.0: Key Changes and Considerations
4+
5+
This document outlines the major updates, configuration compatibility changes, API behavior differences, and critical considerations when upgrading the APISIX Ingress Controller from version 1.x.x to 2.0.0. Please read carefully and assess the impact on your existing system before proceeding with the upgrade.
6+
7+
### APISIX Version Dependency (Data Plane)
8+
9+
The `apisix-standalone` mode is supported only with **APISIX 3.13.0**. When using this mode, it is mandatory to upgrade the data plane APISIX instance along with the Ingress Controller.
10+
11+
### Architecture Changes
12+
13+
#### Architecture in 1.x.x
14+
15+
There were two main deployment architectures in 1.x.x:
16+
17+
| Mode | Description | Issue |
18+
| -------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
19+
| Admin API Mode | Runs a separate etcd instance, with APISIX Admin API managing data plane configuration | Complex to deploy; high maintenance overhead for etcd |
20+
| Mock-ETCD Mode | APISIX and the Ingress Controller are deployed in the same Pod, mocking etcd endpoints | Stateless Ingress cannot persist revision info; may lead to data inconsistency |
21+
22+
#### Architecture in 2.0.0
23+
24+
![upgrade to 2.0.0 architecture](./assets/images/upgrade-to-architecture.png)
25+
26+
##### Mock-ETCD Mode Deprecated
27+
28+
The mock-etcd architecture is no longer supported. This mode introduced significant reliability issues: stateless ingress controllers could not persist revision metadata, leading to memory pollution in the data plane and data inconsistencies.
29+
30+
The following configuration block has been removed:
31+
32+
```yaml
33+
etcdserver:
34+
enabled: false
35+
listen_address: ":12379"
36+
prefix: /apisix
37+
ssl_key_encrypt_salt: edd1c9f0985e76a2
38+
```
39+
40+
##### Controller-Only Configuration Source
41+
42+
In 2.0.0, all data plane configurations must originate from the Ingress Controller. Configurations via Admin API or any external methods are no longer supported and will be ignored or may cause errors.
43+
44+
### Ingress Configuration Changes
45+
46+
#### Configuration Path Changes
47+
48+
| Old Path | New Path |
49+
| ------------------------ | -------------------- |
50+
| `kubernetes.election_id` | `leader_election_id` |
51+
52+
#### Removed Configuration Fields
53+
54+
| Configuration Path | Description |
55+
| -------------------- | ---------------------------------------- |
56+
| `kubernetes.*` | Multi-namespace control / sync interval |
57+
| `plugin_metadata_cm` | Plugin metadata ConfigMap |
58+
| `log_rotation_*` | Log rotation settings |
59+
| `apisix.*` | Static Admin API configuration |
60+
| `etcdserver.*` | Configuration for mock-etcd (deprecated) |
61+
62+
#### Example: Legacy Configuration Removed in 2.0.0
63+
64+
```yaml
65+
apisix:
66+
admin_api_version: v3
67+
default_cluster_base_url: "http://127.0.0.1:9180/apisix/admin"
68+
default_cluster_admin_key: ""
69+
default_cluster_name: "default"
70+
```
71+
72+
#### New Configuration via `GatewayProxy` CRD
73+
74+
From version 2.0.0, the data plane must be connected via the `GatewayProxy` CRD:
75+
76+
```yaml
77+
apiVersion: networking.k8s.io/v1
78+
kind: IngressClass
79+
metadata:
80+
name: apisix
81+
spec:
82+
controller: "apisix.apache.org/apisix-ingress-controller"
83+
parameters:
84+
apiGroup: "apisix.apache.org"
85+
kind: "GatewayProxy"
86+
name: "apisix-proxy-config"
87+
namespace: "default"
88+
scope: "Namespace"
89+
---
90+
apiVersion: apisix.apache.org/v1alpha1
91+
kind: GatewayProxy
92+
metadata:
93+
name: apisix-proxy-config
94+
namespace: default
95+
spec:
96+
provider:
97+
type: ControlPlane
98+
controlPlane:
99+
endpoints:
100+
- https://127.0.0.1:9180
101+
auth:
102+
type: AdminKey
103+
adminKey:
104+
value: ""
105+
```
106+
107+
### API Changes
108+
109+
#### `ApisixUpstream`
110+
111+
Due to current limitations in the ADC (API Definition Controller) component, the following fields are not yet supported:
112+
113+
* `spec.discovery`: Service Discovery
114+
* `spec.healthCheck`: Health Checking
115+
116+
More details: [ADC Backend Differences](https://github.com/api7/adc/blob/2449ca81e3c61169f8c1e59efb4c1173a766bce2/libs/backend-apisix-standalone/README.md#differences-in-upstream)
117+
118+
#### Limited Support for Ingress Annotations
119+
120+
Ingress annotations used in version 1.x.x are not fully supported in 2.0.0. If your existing setup relies on any of the following annotations, validate compatibility or consider delaying the upgrade.
121+
122+
| Ingress Annotations |
123+
| ------------------------------------------------------ |
124+
| `k8s.apisix.apache.org/use-regex` |
125+
| `k8s.apisix.apache.org/enable-websocket` |
126+
| `k8s.apisix.apache.org/plugin-config-name` |
127+
| `k8s.apisix.apache.org/upstream-scheme` |
128+
| `k8s.apisix.apache.org/upstream-retries` |
129+
| `k8s.apisix.apache.org/upstream-connect-timeout` |
130+
| `k8s.apisix.apache.org/upstream-read-timeout` |
131+
| `k8s.apisix.apache.org/upstream-send-timeout` |
132+
| `k8s.apisix.apache.org/enable-cors` |
133+
| `k8s.apisix.apache.org/cors-allow-origin` |
134+
| `k8s.apisix.apache.org/cors-allow-headers` |
135+
| `k8s.apisix.apache.org/cors-allow-methods` |
136+
| `k8s.apisix.apache.org/enable-csrf` |
137+
| `k8s.apisix.apache.org/csrf-key` |
138+
| `k8s.apisix.apache.org/http-to-https` |
139+
| `k8s.apisix.apache.org/http-redirect` |
140+
| `k8s.apisix.apache.org/http-redirect-code` |
141+
| `k8s.apisix.apache.org/rewrite-target` |
142+
| `k8s.apisix.apache.org/rewrite-target-regex` |
143+
| `k8s.apisix.apache.org/rewrite-target-regex-template` |
144+
| `k8s.apisix.apache.org/enable-response-rewrite` |
145+
| `k8s.apisix.apache.org/response-rewrite-status-code` |
146+
| `k8s.apisix.apache.org/response-rewrite-body` |
147+
| `k8s.apisix.apache.org/response-rewrite-body-base64` |
148+
| `k8s.apisix.apache.org/response-rewrite-add-header` |
149+
| `k8s.apisix.apache.org/response-rewrite-set-header` |
150+
| `k8s.apisix.apache.org/response-rewrite-remove-header` |
151+
| `k8s.apisix.apache.org/auth-uri` |
152+
| `k8s.apisix.apache.org/auth-ssl-verify` |
153+
| `k8s.apisix.apache.org/auth-request-headers` |
154+
| `k8s.apisix.apache.org/auth-upstream-headers` |
155+
| `k8s.apisix.apache.org/auth-client-headers` |
156+
| `k8s.apisix.apache.org/allowlist-source-range` |
157+
| `k8s.apisix.apache.org/blocklist-source-range` |
158+
| `k8s.apisix.apache.org/http-allow-methods` |
159+
| `k8s.apisix.apache.org/http-block-methods` |
160+
| `k8s.apisix.apache.org/auth-type` |
161+
| `k8s.apisix.apache.org/svc-namespace` |
162+
163+
### Summary
164+
165+
| Category | Description |
166+
| ---------------- | ---------------------------------------------------------------------------------------------------- |
167+
| Architecture | The `mock-etcd` component has been removed. Configuration is now centralized through the Controller. |
168+
| Configuration | Static configuration fields have been removed. Use `GatewayProxy` CRD to configure the data plane. |
169+
| Data Plane | Requires APISIX version 3.13.0 running in `standalone` mode. |
170+
| API | Some fields in `Ingress Annotations` and `ApisixUpstream` are not yet supported. |
171+
| Upgrade Strategy | Blue-green deployment or canary release is recommended before full switchover. |

0 commit comments

Comments
 (0)