zuplo 6.67.32 → 6.68.0

package/docs/articles/migrate-from-azure-apim.md

@@ -0,0 +1,292 @@
+---
+title: Migrate from Azure API Management to Zuplo
+sidebar_label: Migrate from Azure APIM
+---
+
+This guide walks through migrating from Azure API Management (APIM) to Zuplo. It
+covers the key differences, concept mapping, policy translation, and a
+step-by-step migration process.
+
+## Why teams migrate from Azure APIM
+
+Azure API Management is a natural choice for organizations running on Microsoft
+Azure. However, teams frequently encounter friction points that prompt them to
+evaluate alternatives:
+
+- **Slow deployments** — Azure APIM deployments can take 15-45 minutes to
+  propagate, creating long feedback loops during development. Creating a new
+  APIM instance can take 30-60 minutes.
+- **Expensive per-environment pricing** — Each APIM instance (dev, staging,
+  production) is billed separately. The Developer tier starts at ~$50/month, but
+  the Standard tier needed for production starts at ~$700/month per instance.
+- **Poor GitOps support** — Azure APIM uses ARM templates, Bicep, or Terraform
+  for infrastructure-as-code, but the policy definitions are embedded XML that
+  does not merge well in version control.
+- **XML policy complexity** — Like Apigee, Azure APIM policies are written in
+  XML with C# expressions. The syntax is verbose and error-prone, especially for
+  complex transformations.
+- **Azure lock-in** — APIM is tightly integrated with the Azure ecosystem. Using
+  it with non-Azure backends or multi-cloud architectures adds friction.
+- **Limited developer portal customization** — The built-in developer portal has
+  improved over time but still requires significant effort to customize and
+  lacks features like self-serve API key management with built-in billing.
+
+:::tip
+
+[Imburse Payments](https://zuplo.com/blog/imburse-choose-zuplo-over-azure-api-management),
+a UK fintech, chose Zuplo over Azure API Management to optimize the API
+experience for their customers and improve their engineering team's workflow.
+
+:::
+
+## Concept mapping: Azure APIM to Zuplo
+
+| Azure APIM concept      | Zuplo equivalent                                                         |
+| ----------------------- | ------------------------------------------------------------------------ |
+| API                     | Routes in your [OpenAPI spec](./openapi.md)                              |
+| Operation               | Route (path + method) in OpenAPI spec                                    |
+| Backend                 | [URL Forward handler](../handlers/url-forward.md) target                 |
+| Inbound policy (XML)    | [Inbound policy](./policies.md) (TypeScript)                             |
+| Outbound policy (XML)   | [Outbound policy](./policies.md) (TypeScript)                            |
+| Named value             | [Environment variable](./environment-variables.md)                       |
+| Subscription key        | [API Key Authentication](../policies/api-key-inbound.md)                 |
+| Product                 | API key with [metadata](./api-key-management.md)                         |
+| Service (APIM instance) | [Environment](./environments.md)                                         |
+| Developer portal        | [Zuplo Developer Portal](../dev-portal/introduction.md)                  |
+| Application Insights    | [Logging integrations](./logging.md) (Datadog, Splunk, etc.)             |
+| API revision            | Git branch with [branch-based deployment](./branch-based-deployments.md) |
+| Gateway (self-hosted)   | [Self-hosted Zuplo](../self-hosted/overview.md)                          |
+
+## Step-by-step migration
+
+### Step 1: Export your API definition
+
+Azure APIM stores API definitions as OpenAPI specs. Export them:
+
+**Using the Azure Portal:**
+
+1. Navigate to your APIM instance.
+2. Select **APIs** from the sidebar.
+3. Select the API you want to export.
+4. Click the **...** menu and select **Export**.
+5. Choose **OpenAPI v3 (JSON)**.
+
+**Using the Azure CLI:**
+
+```bash
+az apim api export \
+  --resource-group myResourceGroup \
+  --service-name myApimService \
+  --api-id my-api \
+  --export-format openapi-link
+```
+
+### Step 2: Map Azure APIM policies to Zuplo policies
+
+The following table maps common Azure APIM policies to Zuplo equivalents:
+
+| Azure APIM policy                  | Zuplo policy                                                              |
+| ---------------------------------- | ------------------------------------------------------------------------- |
+| `check-header`                     | [Custom Code Policy](../policies/custom-code-inbound.md) checking headers |
+| `set-header`                       | [Set Headers](../policies/set-headers-inbound.md)                         |
+| `remove-header`                    | [Remove Headers](../policies/remove-headers-inbound.md)                   |
+| `set-body`                         | [Set Body](../policies/set-body-inbound.md)                               |
+| `set-query-parameter`              | [Set Query Params](../policies/set-query-params-inbound.md)               |
+| `rewrite-uri`                      | [URL Rewrite handler](../handlers/url-rewrite.md)                         |
+| `rate-limit` / `rate-limit-by-key` | [Rate Limiting](../policies/rate-limit-inbound.md)                        |
+| `quota` / `quota-by-key`           | [Quota](../policies/quota-inbound.md)                                     |
+| `validate-jwt`                     | [Open ID JWT Authentication](../policies/open-id-jwt-auth-inbound.md)     |
+| `authentication-basic`             | [Basic Authentication](../policies/basic-auth-inbound.md)                 |
+| `ip-filter`                        | [IP Restriction](../policies/ip-restriction-inbound.md)                   |
+| `cors`                             | Built-in [CORS configuration](../programmable-api/custom-cors-policy.md)  |
+| `json-to-xml` / `xml-to-json`      | [XML to JSON](../policies/xml-to-json-outbound.md) or custom code         |
+| `find-and-replace`                 | [Replace String](../policies/replace-string-outbound.md)                  |
+| `cache-lookup` / `cache-store`     | [Caching](../policies/caching-inbound.md)                                 |
+| `mock-response`                    | [Mock API](../policies/mock-api-inbound.md)                               |
+| Custom C# expression               | [Custom Code Policy](../policies/custom-code-inbound.md) (TypeScript)     |
+
+### Step 3: Translate policy configuration
+
+Here is an example of translating an Azure APIM rate limit policy to a Zuplo
+rate limit policy.
+
+**Azure APIM XML policy:**
+
+```xml
+<policies>
+  <inbound>
+    <rate-limit-by-key
+      calls="100"
+      renewal-period="60"
+      counter-key="@(context.Subscription.Id)" />
+    <set-header name="X-Request-Id" exists-action="skip">
+      <value>@(Guid.NewGuid().ToString())</value>
+    </set-header>
+  </inbound>
+</policies>
+```
+
+**Zuplo policy configuration:**
+
+```json
+{
+  "policies": {
+    "inbound": [
+      {
+        "name": "rate-limit-inbound",
+        "policyType": "rate-limit-inbound",
+        "handler": {
+          "export": "RateLimitInboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "rateLimitBy": "user",
+            "requestsAllowed": 100,
+            "timeWindowMinutes": 1
+          }
+        }
+      },
+      {
+        "name": "set-request-id",
+        "policyType": "set-headers-inbound",
+        "handler": {
+          "export": "SetHeadersInboundPolicy",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "headers": [
+              {
+                "name": "X-Request-Id",
+                "value": "$function(generateId)",
+                "overwrite": false
+              }
+            ]
+          }
+        }
+      }
+    ]
+  }
+}
+```
+
+### Step 4: Translate C# policy expressions to TypeScript
+
+Azure APIM allows inline C# expressions in XML policies. Translate these to
+TypeScript custom code policies.
+
+**Azure APIM C# expression:**
+
+```xml
+<policies>
+  <inbound>
+    <set-header name="X-Forwarded-For" exists-action="override">
+      <value>@(context.Request.IpAddress)</value>
+    </set-header>
+    <choose>
+      <when condition="@(context.Request.Headers
+        .GetValueOrDefault("Authorization","")
+        .Length == 0)">
+        <return-response>
+          <set-status code="401" reason="Unauthorized" />
+          <set-body>{"error": "Missing authorization"}</set-body>
+        </return-response>
+      </when>
+    </choose>
+  </inbound>
+</policies>
+```
+
+**Equivalent Zuplo TypeScript policy:**
+
+```typescript
+import { ZuploContext, ZuploRequest, HttpProblems } from "@zuplo/runtime";
+
+export default async function (
+  request: ZuploRequest,
+  context: ZuploContext,
+  options: never,
+  policyName: string,
+) {
+  const authHeader = request.headers.get("authorization");
+
+  if (!authHeader) {
+    return HttpProblems.unauthorized(request, context, {
+      detail: "Missing authorization",
+    });
+  }
+
+  // Forward the client IP
+  const headers = new Headers(request.headers);
+  headers.set("X-Forwarded-For", request.headers.get("x-real-ip") ?? "");
+
+  return new ZuploRequest(request, { headers });
+}
+```
+
+### Step 5: Migrate subscription keys to Zuplo API keys
+
+Azure APIM uses subscription keys tied to products. Migrate to Zuplo's API key
+system:
+
+| Azure APIM subscription feature | Zuplo equivalent                                            |
+| ------------------------------- | ----------------------------------------------------------- |
+| Subscription key                | [API key](./api-key-management.md)                          |
+| Product grouping                | API key metadata for access control                         |
+| Subscription approval           | API key creation via Portal or API                          |
+| Key regeneration                | Key rotation in the Zuplo Portal or Developer Portal        |
+| Usage reporting                 | Built-in analytics and [logging](./logging.md) integrations |
+
+### Step 6: Migrate named values to environment variables
+
+Azure APIM named values become Zuplo
+[environment variables](./environment-variables.md):
+
+| Azure APIM named value type | Zuplo equivalent            |
+| --------------------------- | --------------------------- |
+| Plain value                 | Environment variable        |
+| Secret value                | Secret environment variable |
+| Key Vault reference         | Secret environment variable |
+
+Access environment variables in route configuration using `$env(VARIABLE_NAME)`
+or in custom code using `context.env.VARIABLE_NAME`.
+
+### Step 7: Deploy and migrate traffic
+
+1. Deploy your Zuplo project by pushing to your connected Git repository.
+2. Set up a [custom domain](./custom-domains.md) for Zuplo.
+3. Route a subset of traffic to Zuplo using Azure Front Door, Traffic Manager,
+   or DNS-based routing.
+4. Validate behavior matches your Azure APIM configuration.
+5. Gradually shift all traffic to Zuplo.
+6. Decommission your Azure APIM instances.
+
+## Keeping Azure backends with Zuplo
+
+You do not need to migrate your backend infrastructure. Zuplo works with any
+HTTP backend, including:
+
+- Azure App Service
+- Azure Functions
+- Azure Kubernetes Service (AKS)
+- Azure Container Apps
+- Any Azure service with an HTTP endpoint
+
+Use [backend security](./securing-your-backend.md) options to secure the
+connection between Zuplo and your Azure backends.
+
+## Deployment model comparison
+
+| Feature               | Azure APIM                         | Zuplo                                        |
+| --------------------- | ---------------------------------- | -------------------------------------------- |
+| Deployment time       | 15-45 minutes                      | Under 20 seconds                             |
+| New instance creation | 30-60 minutes                      | Instant                                      |
+| Environment cost      | ~$700/month per Standard instance  | Free tier available; environments are free   |
+| Preview environments  | Manual setup required              | Automatic per Git branch                     |
+| Global distribution   | Premium tier + multi-region config | Built-in across 300+ edge locations          |
+| GitOps workflow       | ARM/Bicep + XML policies           | OpenAPI + TypeScript, native Git integration |
+
+## Next steps
+
+- [Set up your first Zuplo gateway](./step-1-setup-basic-gateway.md)
+- [Add rate limiting](./step-2-add-rate-limiting.md)
+- [Add API key authentication](./step-3-add-api-key-auth.md)
+- [Configure your developer portal](../dev-portal/introduction.md)
+- [Set up source control](./source-control.md)

package/docs/articles/migrate-from-kong.md

@@ -0,0 +1,300 @@
+---
+title: Migrate from Kong Gateway to Zuplo
+sidebar_label: Migrate from Kong
+---
+
+This guide walks through migrating from Kong Gateway (Community Edition or
+Enterprise) to Zuplo. Whether you're running Kong OSS on Kubernetes, Kong
+Konnect, or a self-hosted Kong cluster, this guide covers the key differences,
+concept mapping, and step-by-step migration process.
+
+## Why teams migrate from Kong
+
+Kong Gateway is a powerful, plugin-driven API gateway built on NGINX and Lua.
+However, teams frequently encounter challenges that drive them to seek
+alternatives:
+
+- **Community Edition stagnation** — Kong's open-source Community Edition
+  receives fewer updates and lacks critical features like the developer portal,
+  RBAC, and advanced rate limiting that are reserved for Enterprise tiers.
+- **Kubernetes complexity** — Running Kong in production requires managing
+  Postgres or Cassandra databases, configuring the Kong Ingress Controller, and
+  maintaining Kubernetes clusters across environments.
+- **Lua plugin development** — Kong's plugin architecture requires Lua, a niche
+  language that few developers know. This limits who on your team can extend the
+  gateway and makes AI-assisted code generation less effective.
+- **Cost escalation** — Kong Konnect pricing starts at ~$105/month per gateway
+  service plus ~$34/million API requests, with additional charges for analytics,
+  portals, and mesh management. Self-hosted Kong requires significant SRE
+  investment.
+- **Global scaling challenges** — Scaling Kong globally requires deploying and
+  synchronizing clusters across regions manually, each with its own database and
+  configuration state.
+
+:::tip
+
+[Copilot Travel](https://zuplo.com/customers/copilot-travel) switched from Kong
+to Zuplo after nine months, achieving over 50% faster API implementation and
+reducing development time from months to days. Their team eliminated the need
+for a dedicated DevOps engineer to maintain the API gateway.
+
+:::
+
+## Concept mapping: Kong to Zuplo
+
+| Kong concept               | Zuplo equivalent                                                        |
+| -------------------------- | ----------------------------------------------------------------------- |
+| Service                    | Backend URL configured in a [route handler](../handlers/url-forward.md) |
+| Route                      | Route in your [OpenAPI spec](./openapi.md)                              |
+| Plugin (Lua)               | [Policy](./policies.md) (TypeScript) or built-in policy                 |
+| Consumer                   | [API key consumer](./api-key-management.md)                             |
+| Consumer group             | API key metadata with custom rate limit logic                           |
+| Upstream                   | [URL forward handler](../handlers/url-forward.md) target                |
+| Workspace (Enterprise)     | [Environment](./environments.md)                                        |
+| Kong Manager / Konnect UI  | [Zuplo Portal](./development-options.md) or local development with Git  |
+| DB-less declarative config | [OpenAPI route config](./openapi.md) in Git                             |
+| Admin API                  | [Zuplo API](./accounts/zuplo-api-keys.md) or `git push`                 |
+| Kong Dev Portal            | [Zuplo Developer Portal](../dev-portal/introduction.md)                 |
+
+## Step-by-step migration
+
+### Step 1: Export your API definitions
+
+If you have OpenAPI specs for your APIs, export them from Kong. If you're using
+Kong's declarative configuration, convert your service and route definitions to
+an OpenAPI spec.
+
+**From Kong declarative config (deck):**
+
+```yaml
+# kong.yml - Your existing Kong config
+services:
+  - name: my-api
+    url: http://backend-service:8080
+    routes:
+      - name: get-users
+        paths:
+          - /users
+        methods:
+          - GET
+      - name: create-user
+        paths:
+          - /users
+        methods:
+          - POST
+```
+
+**Equivalent OpenAPI spec for Zuplo:**
+
+```json
+{
+  "openapi": "3.1.0",
+  "info": {
+    "title": "My API",
+    "version": "1.0.0"
+  },
+  "paths": {
+    "/users": {
+      "get": {
+        "operationId": "get-users",
+        "summary": "Get users",
+        "x-zuplo-route": {
+          "corsPolicy": "none",
+          "handler": {
+            "export": "urlForwardHandler",
+            "module": "$import(@zuplo/runtime)",
+            "options": {
+              "baseUrl": "http://backend-service:8080"
+            }
+          },
+          "policies": {
+            "inbound": []
+          }
+        }
+      },
+      "post": {
+        "operationId": "create-user",
+        "summary": "Create user",
+        "x-zuplo-route": {
+          "corsPolicy": "none",
+          "handler": {
+            "export": "urlForwardHandler",
+            "module": "$import(@zuplo/runtime)",
+            "options": {
+              "baseUrl": "http://backend-service:8080"
+            }
+          },
+          "policies": {
+            "inbound": []
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### Step 2: Map Kong plugins to Zuplo policies
+
+The following table maps common Kong plugins to their Zuplo policy equivalents:
+
+| Kong plugin              | Zuplo policy                                                             |
+| ------------------------ | ------------------------------------------------------------------------ |
+| `key-auth`               | [API Key Authentication](../policies/api-key-inbound.md)                 |
+| `jwt`                    | [Open ID JWT Authentication](../policies/open-id-jwt-auth-inbound.md)    |
+| `basic-auth`             | [Basic Authentication](../policies/basic-auth-inbound.md)                |
+| `rate-limiting`          | [Rate Limiting](../policies/rate-limit-inbound.md)                       |
+| `rate-limiting-advanced` | [Complex Rate Limiting](../policies/complex-rate-limit-inbound.md)       |
+| `request-transformer`    | [Transform Body](../policies/transform-body-inbound.md)                  |
+| `response-transformer`   | [Transform Body Outbound](../policies/transform-body-outbound.md)        |
+| `cors`                   | Built-in [CORS configuration](../programmable-api/custom-cors-policy.md) |
+| `ip-restriction`         | [IP Restriction](../policies/ip-restriction-inbound.md)                  |
+| `request-size-limiting`  | [Request Size Limit](../policies/request-size-limit-inbound.md)          |
+| `request-validation`     | [Request Validation](../policies/request-validation-inbound.md)          |
+| `acl`                    | [ACL Policy](../policies/acl-policy-inbound.md)                          |
+| Custom Lua plugin        | [Custom Code Policy](../policies/custom-code-inbound.md) (TypeScript)    |
+
+### Step 3: Translate plugin configuration
+
+Here is an example of translating a Kong rate limiting plugin to a Zuplo rate
+limit policy.
+
+**Kong plugin configuration:**
+
+```yaml
+plugins:
+  - name: rate-limiting
+    config:
+      minute: 100
+      policy: local
+      limit_by: consumer
+```
+
+**Zuplo policy configuration:**
+
+```json
+{
+  "name": "rate-limit-inbound",
+  "policyType": "rate-limit-inbound",
+  "handler": {
+    "export": "RateLimitInboundPolicy",
+    "module": "$import(@zuplo/runtime)",
+    "options": {
+      "rateLimitBy": "user",
+      "requestsAllowed": 100,
+      "timeWindowMinutes": 1
+    }
+  }
+}
+```
+
+:::note
+
+Zuplo's rate limiter is globally distributed across 300+ edge locations. Unlike
+Kong, which enforces rate limits per-node or per-cluster (requiring Redis
+synchronization), Zuplo enforces limits as a single global zone automatically.
+
+:::
+
+### Step 4: Migrate authentication
+
+**Kong `key-auth` to Zuplo API Key Authentication:**
+
+Kong uses consumers with key credentials stored in its database. In Zuplo, API
+keys are managed through the built-in
+[API key management system](./api-key-management.md), which includes a
+self-serve developer portal for key creation and rotation.
+
+1. Add the `api-key-inbound` policy to your routes.
+2. Create API key consumers through the Zuplo Portal or API.
+3. Optionally, enable the [Developer Portal](../dev-portal/introduction.md) for
+   self-serve key management.
+
+**Kong `jwt` to Zuplo JWT Authentication:**
+
+Replace Kong's JWT plugin with one of Zuplo's JWT authentication policies:
+
+- [Auth0 JWT](../policies/auth0-jwt-auth-inbound.md)
+- [AWS Cognito JWT](../policies/cognito-jwt-auth-inbound.md)
+- [Firebase JWT](../policies/firebase-jwt-inbound.md)
+- [Open ID JWT](../policies/open-id-jwt-auth-inbound.md) (generic OIDC)
+
+### Step 5: Set up your project and deploy
+
+1. Create a new project in the [Zuplo Portal](https://portal.zuplo.com/signup)
+   or using the [Zuplo CLI](../cli/overview.md).
+2. Import your OpenAPI spec as the route configuration file.
+3. Add policies to your routes.
+4. Connect your project to [source control](./source-control.md).
+5. Push to deploy — Zuplo deploys globally in under 20 seconds.
+
+### Step 6: Migrate traffic
+
+Run Zuplo alongside Kong during migration:
+
+1. Point a subset of traffic to Zuplo using DNS or a load balancer.
+2. Monitor both gateways for correctness and performance.
+3. Gradually shift more traffic to Zuplo.
+4. Decommission Kong once all traffic is migrated.
+
+## Custom Lua plugins to TypeScript
+
+If you have custom Kong plugins written in Lua, rewrite them as Zuplo
+[custom code policies](../policies/custom-code-inbound.md) in TypeScript.
+
+**Kong Lua plugin example:**
+
+```lua
+local MyPlugin = {}
+
+function MyPlugin:access(conf)
+  local header_value = kong.request.get_header("x-custom-header")
+  if not header_value then
+    return kong.response.exit(403, { message = "Missing required header" })
+  end
+end
+
+return MyPlugin
+```
+
+**Equivalent Zuplo TypeScript policy:**
+
+```typescript
+import { ZuploContext, ZuploRequest, HttpProblems } from "@zuplo/runtime";
+
+export default async function (
+  request: ZuploRequest,
+  context: ZuploContext,
+  options: never,
+  policyName: string,
+) {
+  const headerValue = request.headers.get("x-custom-header");
+  if (!headerValue) {
+    return HttpProblems.forbidden(request, context, {
+      detail: "Missing required header",
+    });
+  }
+  return request;
+}
+```
+
+## Kong DB-less mode to Zuplo GitOps
+
+If you use Kong's DB-less declarative mode, you're already familiar with
+configuration-as-code. Zuplo takes this further with native GitOps:
+
+| Kong DB-less                  | Zuplo GitOps                                                         |
+| ----------------------------- | -------------------------------------------------------------------- |
+| Single `kong.yml` file        | OpenAPI spec + policy configs in Git                                 |
+| `deck sync` to apply changes  | `git push` triggers automatic deployment                             |
+| Manual environment management | Automatic [branch-based environments](./branch-based-deployments.md) |
+| No PR-based review workflow   | PR reviews with preview environments                                 |
+| Manual rollback               | `git revert` and push                                                |
+
+## Next steps
+
+- [Set up your first Zuplo gateway](./step-1-setup-basic-gateway.md)
+- [Add rate limiting](./step-2-add-rate-limiting.md)
+- [Add API key authentication](./step-3-add-api-key-auth.md)
+- [Configure your developer portal](../dev-portal/introduction.md)
+- [Set up source control](./source-control.md)

package/docs/articles/migration-overview.md

@@ -0,0 +1,81 @@
+---
+title: Migrate to Zuplo from Other API Gateways
+sidebar_label: Migration Overview
+---
+
+Moving to Zuplo from another API gateway is straightforward. Zuplo is
+OpenAPI-native, so you can import your existing API definitions and start
+configuring policies in minutes. This section provides migration guides for the
+most common API gateways.
+
+## Why teams migrate to Zuplo
+
+Teams migrate to Zuplo from legacy API gateways for several common reasons:
+
+- **Reduce operational complexity** — Eliminate self-hosted infrastructure,
+  database management, and Kubernetes overhead with a fully managed platform.
+- **Lower total cost of ownership** — Replace expensive enterprise licensing and
+  hidden infrastructure costs with transparent, usage-based pricing.
+- **Accelerate development velocity** — Deploy globally in under 20 seconds with
+  GitOps workflows, TypeScript policies, and instant preview environments.
+- **Modernize the developer experience** — Replace XML configs, Lua plugins, or
+  CloudFormation templates with TypeScript and OpenAPI-native configuration.
+- **Go multi-cloud** — Deploy to 300+ edge locations worldwide without
+  single-cloud lock-in.
+
+## Migration guides by platform
+
+| Source platform                                      | Common migration triggers                                                   |
+| ---------------------------------------------------- | --------------------------------------------------------------------------- |
+| [Kong Gateway](./migrate-from-kong.md)               | Community Edition stagnation, Kubernetes complexity, Lua plugin limitations |
+| [Google Apigee](./migrate-from-apigee.md)            | Apigee Edge EOL, GCP lock-in, XML policy complexity, high costs             |
+| [AWS API Gateway](./migrate-from-aws-api-gateway.md) | AWS lock-in, limited customization, no built-in developer portal            |
+| [Azure API Management](./migrate-from-azure-apim.md) | Slow deployments, expensive per-environment pricing, poor GitOps support    |
+
+## General migration approach
+
+Regardless of your source platform, the migration process follows a similar
+pattern:
+
+1. **Export your API definitions** — Extract OpenAPI specs from your current
+   gateway. If you don't have OpenAPI specs, create them from your existing
+   route configuration.
+2. **Import into Zuplo** — Import your OpenAPI spec through the Zuplo Portal or
+   by adding the file to your project repository.
+3. **Map policies** — Translate your existing gateway policies (authentication,
+   rate limiting, transformation) to Zuplo's built-in
+   [policy library](./policies.md).
+4. **Configure backend connectivity** — Set up
+   [URL forwarding](../handlers/url-forward.md) or
+   [URL rewriting](../handlers/url-rewrite.md) to route traffic to your existing
+   backends.
+5. **Test in a preview environment** — Use Zuplo's
+   [branch-based deployments](./branch-based-deployments.md) to validate your
+   configuration before going live.
+6. **Migrate traffic incrementally** — Route a subset of traffic through Zuplo
+   first, then gradually shift all traffic once you've validated the
+   configuration.
+
+## Concept mapping
+
+The following table maps common API gateway concepts to their Zuplo equivalents:
+
+| Concept          | Kong                 | Apigee              | AWS API Gateway      | Azure APIM            | Zuplo                                                  |
+| ---------------- | -------------------- | ------------------- | -------------------- | --------------------- | ------------------------------------------------------ |
+| Route definition | Service + Route      | API Proxy           | Resource + Method    | API + Operation       | [OpenAPI route](./openapi.md)                          |
+| Request policy   | Plugin (Lua)         | Policy (XML)        | Lambda authorizer    | Policy (XML)          | [Inbound policy](./policies.md) (TypeScript)           |
+| Response policy  | Plugin (Lua)         | PostFlow (XML)      | Response mapping     | Outbound policy (XML) | [Outbound policy](./policies.md) (TypeScript)          |
+| Authentication   | Plugin               | VerifyAPIKey policy | API key / Authorizer | Subscription key      | [API key](./api-key-authentication.md) or JWT policy   |
+| Rate limiting    | Rate Limiting plugin | SpikeArrest / Quota | Usage plan           | rate-limit policy     | [Rate limit policy](../policies/rate-limit-inbound.md) |
+| Developer portal | Kong Dev Portal      | Drupal portal       | N/A (self-build)     | Built-in portal       | [Developer Portal](../dev-portal/introduction.md)      |
+| Environment      | Workspace            | Environment         | Stage                | Service               | [Environment](./environments.md)                       |
+| Deployment       | Deck / Admin API     | API deploy          | CloudFormation / SAM | ARM / Bicep           | `git push` with [GitOps](./source-control.md)          |
+
+## Get migration support
+
+Need help planning your migration? Zuplo's team can assist with migration
+planning, policy translation, and architecture review.
+
+- [Book a demo](https://zuplo.com/meeting)
+- [Contact support](https://zuplo.com/support)
+- [Join the Discord community](https://discord.gg/W4mQqNnfSq)