diff --git a/readme.md b/readme.md index f6702f7..f6b9bdc 100644 --- a/readme.md +++ b/readme.md @@ -1,9 +1,9 @@ # Ingress NGINX Migration -The Ingress NGINX Migration is a tool that analyzes Kubernetes NGINX Ingress resources to help with migration planning to Traefik. - screenshot black +The Ingress NGINX Migration is a tool that analyzes Kubernetes NGINX Ingress resources to help with migration planning to Traefik. + ## Features The Ingress NGINX Migration tool creates and serves an interactive HTML report, @@ -19,7 +19,7 @@ and to do so it: - Unsupported annotations and their frequency - Provides flexible ingress filtering by controller class, ingress class name, and namespace -### Supported NGINX Annotations +## Supported NGINX Annotations The Ingress NGINX Migration checks for compatibility with common Ingress NGINX Controller annotations including: - Authentication (`auth-type`, `auth-secret`, `auth-realm`, etc.) @@ -29,44 +29,33 @@ The Ingress NGINX Migration checks for compatibility with common Ingress NGINX C - CORS (`enable-cors`, `cors-allow-*`) - And more... -## Send Report Feature +For a complete list of supported annotations and their Traefik equivalents, see the [Ingress NGINX Annotations table](https://doc.traefik.io/traefik/reference/routing-configuration/kubernetes/ingress-nginx/#annotations-support) in the Traefik documentation. -The Ingress NGINX Migration tool includes an optional feature to share anonymized usage statistics with Traefik Labs. -This helps the Traefik team understand real-world NGINX Ingress usage patterns and prioritize compatibility improvements for the migration process. -The data is transmitted securely over HTTPS to Traefik Labs. +## Installation -### Privacy and Data Protection +### Quick Install (Recommended) -**Important: No sensitive data is transmitted.** -The tool only sends aggregated statistics and counts - never actual ingress configurations, resource names, namespaces, or any other identifying information from your cluster. +Install the latest version using the install script: -### Data Transmitted +```bash +curl -sSL https://raw.githubusercontent.com/traefik/ingress-nginx-migration/main/scripts/install.sh | bash +``` -When you choose to share your report, only the following anonymized data is sent: +Install a specific version: -```json -{ - "generationDate": "2024-12-03T14:30:25.123Z", - "version": "v1.0.0", - "ingressCount": 42, - "compatibleIngressCount": 38, - "vanillaIngressCount": 15, - "supportedIngressCount": 23, - "unsupportedIngressCount": 4, - "unsupportedIngressAnnotations": { - "nginx.ingress.kubernetes.io/custom-annotation": 2, - "nginx.ingress.kubernetes.io/experimental-feature": 2 - } -} +```bash +curl -sSL https://raw.githubusercontent.com/traefik/ingress-nginx-migration/main/scripts/install.sh | TAG=v0.0.1 bash ``` -### How to Use +Install without sudo (installs to `~/bin`): -**Via Web Interface:** -1. Open the migration report in your browser -2. Click the "Share Report" button in the report interface -3. Optionally view the exact data to be sent before confirming +```bash +curl -sSL https://raw.githubusercontent.com/traefik/ingress-nginx-migration/main/scripts/install.sh | bash -s -- --no-sudo +``` +### Manual Download + +Download the appropriate binary for your platform from the [releases page](https://github.com/traefik/ingress-nginx-migration/releases). ## Usage @@ -92,6 +81,16 @@ GLOBAL OPTIONS: --help, -h Show help ``` +> [!TIP] +> **Quick Start:** Run the tool with your kubeconfig: +> ```bash +> ingress-nginx-migration --kubeconfig ~/.kube/config +> ``` +> Or using environment variables: +> ```bash +> KUBECONFIG=~/.kube/config ingress-nginx-migration +> ``` + ### Required Permissions The Ingress NGINX Migration requires specific read-only permissions to analyze your cluster's Ingress resources. @@ -105,10 +104,11 @@ Your kubeconfig user or service account must have the following permissions: | `networking.k8s.io/v1` | `ingressclasses` | `list`, `get`, `watch` | Cluster-wide | | `networking.k8s.io/v1` | `ingresses` | `list`, `get`, `watch` | Namespace-scoped* | -**Namespace Scope:** The tool supports the `--namespaces` flag. -If specific namespaces are provided, permissions are only required for those namespaces. -If no namespaces are specified, the tool will attempt to analyze all namespaces, -and requiring permission across all namespaces for Ingresses. +> [!NOTE] +> **Namespace Scope:** +> The tool supports the `--namespaces` flag. +> If specific namespaces are provided, permissions are only required for those namespaces. +> If no namespaces are specified, the tool will attempt to analyze all namespaces, and requiring permission across all namespaces for Ingresses. ### Why These Permissions? @@ -121,45 +121,43 @@ Informers require `list`, `get`, and `watch` permissions to: All operations are read-only - the tool never modifies any cluster resources. -## Installation - -### Quick Install (Recommended) - -Install the latest version using the install script: - -```bash -curl -sSL https://raw.githubusercontent.com/traefik/ingress-nginx-migration/main/scripts/install.sh | bash -``` - -Install a specific version: - -```bash -curl -sSL https://raw.githubusercontent.com/traefik/ingress-nginx-migration/main/scripts/install.sh | TAG=v0.0.1 bash -``` - -Install without sudo (installs to `~/bin`): +## Send Report Feature -```bash -curl -sSL https://raw.githubusercontent.com/traefik/ingress-nginx-migration/main/scripts/install.sh | bash -s -- --no-sudo -``` +The Ingress NGINX Migration tool includes an optional feature to share anonymized usage statistics with Traefik Labs. +This helps the Traefik team understand real-world NGINX Ingress usage patterns and prioritize compatibility improvements for the migration process. +The data is transmitted securely over HTTPS to Traefik Labs. -### Manual Download +### Privacy and Data Protection -Download the appropriate binary for your platform from the [releases page](https://github.com/traefik/ingress-nginx-migration/releases). +**Important: No sensitive data is transmitted.** +The tool only sends aggregated statistics and counts - never actual ingress configurations, resource names, namespaces, or any other identifying information from your cluster. -## Running +### Data Transmitted -Run: +When you choose to share your report, the following anonymized data is sent: -```bash -KUBECONFIG=~/.kube/config ingress-nginx-migration +```json +{ + "generationDate": "2024-12-03T14:30:25.123Z", + "version": "v1.0.0", + "ingressCount": 42, + "compatibleIngressCount": 38, + "vanillaIngressCount": 15, + "supportedIngressCount": 23, + "unsupportedIngressCount": 4, + "unsupportedIngressAnnotations": { + "nginx.ingress.kubernetes.io/custom-annotation": 2, + "nginx.ingress.kubernetes.io/experimental-feature": 2 + } +} ``` -Run with a kubeconfig file: +### How to Use -```bash -ingress-nginx-migration --kubeconfig ~/.kube/config -``` +**Via Web Interface:** +1. Open the migration report in your browser +2. Click the "Share Report" button in the report interface +3. Optionally view the exact data to be sent before confirming ## Utility endpoints exposed by the Ingress NGINX Migration tool