You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+94-63Lines changed: 94 additions & 63 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,6 +9,99 @@ This tool automates the migration of Kubernetes Ingress resources from **NGINX I
9
9
-**Full Coverage Testing**: Includes an End-to-End (E2E) test suite validating the migration against a live cluster.
10
10
-**Safe Defaults**: Generates standard configuration while warning about incompatible or manual-intervention items.
11
11
12
+
## UI Dashboard
13
+
14
+
The migration tool includes a web-based dashboard that connects to your cluster and lets you browse, analyse, and migrate Ingress resources interactively.
15
+
16
+
### Run locally with binary
17
+
18
+
Download the binary from [the releases page](https://github.com/Kong/nginx-kong-migrator/releases), then start the dashboard:
19
+
20
+
```bash
21
+
./migrator ui
22
+
```
23
+
24
+
Optional flags:
25
+
-`-port <int>` — port to listen on (default: `8080`)
26
+
-`-namespace <string>` — restrict to a single namespace (default: all namespaces)
27
+
-`-kubeconfig <string>` — path to kubeconfig (falls back to `$KUBECONFIG` or `~/.kube/config`)
28
+
29
+
Example:
30
+
```bash
31
+
./migrator ui -port 9090 -namespace kong
32
+
```
33
+
34
+
Open [http://localhost:8080](http://localhost:8080) in your browser. The dashboard reads Ingress resources from your currently active cluster context and colour-codes each one:
35
+
36
+
-**Green** — already migrated (non-NGINX ingress)
37
+
-**Yellow** — ready to migrate, may have followup notes
38
+
-**Red** — has unmigrated annotations that require manual intervention
39
+
40
+
From the dashboard you can:
41
+
-**Migrate Selected / Migrate Single** — applies the migration in-cluster: sets `ingressClassName: kong`, creates `KongPlugin` and `KongUpstreamPolicy` CRDs
42
+
-**Copy to Namespace** — copies one or more ingresses (with their Kong resources) to a target namespace
43
+
-**Download as Kong Ingress YAML / Gateway API YAML** — export the migrated manifests without applying them
44
+
-**Refresh** — reload the ingress list from the cluster
45
+
46
+
### Run locally with Docker (out-of-cluster)
47
+
48
+
You can run the dashboard as a Docker container outside the cluster by mounting your kubeconfig:
Then open [http://localhost:8080](http://localhost:8080). The container reads the mounted kubeconfig to connect to whichever cluster context is currently active.
59
+
60
+
To target a specific context, set it before running:
The `deploy/kubernetes.yaml` manifest creates a dedicated `kong-migrator` namespace and installs all required resources (ServiceAccount, ClusterRole, ClusterRoleBinding, Deployment, Service):
74
+
75
+
```bash
76
+
kubectl apply -f deploy/kubernetes.yaml
77
+
```
78
+
79
+
Wait for the pod to become ready:
80
+
81
+
```bash
82
+
kubectl -n kong-migrator rollout status deployment/kong-migrator
Then open [http://localhost:8080](http://localhost:8080) in your browser. The dashboard reads Ingress resources across all namespaces using the pod's service account — no kubeconfig or extra credentials required.
94
+
95
+
To restrict the dashboard to a single namespace, edit the Deployment and add `--namespace <your-namespace>` to the `args` list.
96
+
97
+
### Uninstall
98
+
99
+
```bash
100
+
kubectl delete -f deploy/kubernetes.yaml
101
+
```
102
+
103
+
This removes all resources created by the manifest, including the `kong-migrator` namespace.
104
+
12
105
## Supported Annotations
13
106
14
107
The tool supports **25+ NGINX Ingress annotations** across multiple categories:
@@ -86,7 +179,7 @@ The following annotations are detected but not automatically migrated:
86
179
-`configuration-snippet` (non-header) - Complex snippets not supported
The migration tool includes a web-based dashboard that connects to your cluster and lets you browse, analyse, and migrate Ingress resources interactively.
215
-
216
-
### Deploy to Kubernetes
217
-
218
-
The `deploy/kubernetes.yaml` manifest creates a dedicated `kong-migrator` namespace and installs all required resources (ServiceAccount, ClusterRole, ClusterRoleBinding, Deployment, Service):
219
-
220
-
```bash
221
-
kubectl apply -f deploy/kubernetes.yaml
222
-
```
223
-
224
-
Wait for the pod to become ready:
225
-
226
-
```bash
227
-
kubectl -n kong-migrator rollout status deployment/kong-migrator
Then open [http://localhost:8080](http://localhost:8080) in your browser. The dashboard reads Ingress resources across all namespaces using the pod's service account — no kubeconfig or extra credentials required.
239
-
240
-
To restrict the dashboard to a single namespace, edit the Deployment and add `--namespace <your-namespace>` to the `args` list.
241
-
242
-
### Run locally with Docker (out-of-cluster)
243
-
244
-
You can run the dashboard as a Docker container outside the cluster by mounting your kubeconfig:
Then open [http://localhost:8080](http://localhost:8080). The container reads the mounted kubeconfig to connect to whichever cluster context is currently active.
255
-
256
-
To target a specific context, set it before running:
0 commit comments