agicmigration

Application Gateway for Containers Migration Utility

A CLI utility for migrating Kubernetes Ingress resources from Application Gateway Ingress Controller (AGIC) or NGINX Ingress Controller to Azure Application Gateway for Containers using Gateway API.

Overview

The Application Gateway for Containers Migration Utility automates the translation of ingress annotations and routing rules into Gateway API resources compatible with Azure Application Gateway for Containers. It supports:

• AGIC (Application Gateway Ingress Controller) annotations
• NGINX Ingress Controller annotations
• Detailed migration reports with actionable recommendations
• Individual or consolidated Gateway API translation ready for deployment

Prerequisites

• Go 1.25 or later
• Access to a Kubernetes cluster (for cluster mode) or YAML manifests (for files mode)

Deployment Modes

Application Gateway for Containers supports two deployment strategies:

Bring Your Own (BYO) Deployment

In BYO mode, you create the AGC resources in Azure first (via Portal, CLI, Terraform, etc.), then reference the resource ID when running the migration utility. Use --byo-resource-id to specify the existing AGC resource.

./agc-migration files --byo-resource-id "/subscriptions/.../applicationGateways/my-agc" ./manifests/*.yaml

See Create Application Gateway for Containers - bring your own deployment for setup instructions.

Managed by ALB Controller

In managed mode, the migration utility generates an ApplicationLoadBalancer custom resource that the ALB Controller uses to automatically create and manage the AGC resources in Azure. Use --managed-subnet-id to specify the delegated subnet.

./agc-migration cluster --managed-subnet-id "/subscriptions/.../subnets/agc-subnet"

See Create Application Gateway for Containers managed by ALB Controller for setup instructions.

Building the Utility

Build for all platforms

./build.sh

This creates binaries in the bin/ directory for:

• Linux (amd64, arm64)
• macOS (amd64, arm64)
• Windows (amd64, arm64)

Running the Utility

The migration utility reads ingress resources and generates Gateway API YAML configurations that you can review and apply when ready.

Note: This utility does not modify any existing resources on a live cluster.

Migrate from YAML Files

Converts ingress YAML files into Gateway API resources:

# AGIC ingresses (default provider)
./agc-migration files --byo-resource-id "$AGC_ID" ./manifests/*.yaml

# NGINX ingresses
./agc-migration files --provider nginx --ingress-class nginx --managed-subnet-id "$SUBNET_ID" ./manifests/*.yaml

# Output to a file instead of stdout
./agc-migration files --byo-resource-id "$AGC_ID" --output-file converted.yaml ./manifests/*.yaml

# Output to a directory (one file per resource)
./agc-migration files --byo-resource-id "$AGC_ID" --output-dir ./output ./manifests/*.yaml

If you have Go installed you can run it directly without building first:

# AGIC ingresses (default provider)
go run ./cmd agc-migration files --byo-resource-id "$AGC_ID" ./manifests/*.yaml

Migrate from a Live Cluster

Reads ingresses from your cluster and generates Gateway API resources. This is a read-only operation and does not modify or delete any existing ingresses or affect your production workloads.

# AGIC ingresses (default)
./agc-migration cluster --byo-resource-id "$AGC_ID"

# NGINX ingresses
./agc-migration cluster --provider nginx --ingress-class nginx --managed-subnet-id "$SUBNET_ID"

# Specify a kubeconfig context
./agc-migration cluster --context my-cluster --byo-resource-id "$AGC_ID"

CLI Options

Running Tests

Run all tests

go test ./... -v

Run provider unit tests only

# AGIC provider tests
go test ./conversion/providers/agic/... -v

# NGINX provider tests
go test ./conversion/providers/nginx/... -v

Run E2E tests

go test ./e2e/... -v

Run tests with coverage

./coverage.sh

Supported Annotations

AGIC Annotations

The following Application Gateway Ingress Controller annotations are supported for migration:

NGINX Annotations

The following NGINX Ingress Controller annotations are supported for migration:

Migration Report

The utility generates a detailed migration report that includes:

• Input Resources: List of ingresses processed
• Migrated Resources: Gateway API resources created
• Annotation Status: Per-annotation migration status
  • completed: Successfully migrated
  • warning: Migrated with notes
  • not-supported: No AGC equivalent
  • error: Migration failed
• Issues and Recommendations: Actionable guidance for manual steps

Project Structure

agicmigration/
├── aggregation/       # Resource collection from cluster/files
├── cmd/               # CLI entry point
├── conversion/        # Core conversion logic
│   └── providers/     # Provider implementations
│       ├── agic/      # AGIC annotation handlers
│       └── nginx/     # NGINX annotation handlers
├── crds/              # Custom Resource Definitions (Gateway API ALB extensions)
├── e2e/               # End-to-end tests
├── logging/           # Logging utilities
├── migration/         # High-level migration orchestration
├── output/            # Output formatting and writing
├── reporting/         # Migration report generation
├── resources/         # Resource types, annotations, and issue codes
└── testutil/          # Test utilities

Adding a New Provider

To add support for a new ingress controller:

1. Create a new package under conversion/providers/<name>/
2. Implement the Provider interface with GetAnnotationHandlers()
3. Register the provider in migration/migration.go
4. Add issue codes to resources/<name>_issues.go

See conversion/provider.go for details.

Note: you may also need to make changes to aggregation/ and migration/ until the provider interface is expanded to include these aspects.