zuplo 6.67.32 → 6.68.0

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

@@ -0,0 +1,408 @@
+---
+title: Migrate from Google Apigee to Zuplo
+sidebar_label: Migrate from Apigee
+---
+
+This guide walks through migrating from Google Apigee (including Apigee X,
+Apigee hybrid, and legacy Apigee Edge) to Zuplo. It covers the key differences,
+concept mapping, policy translation, and a step-by-step migration process.
+
+:::caution{title="Apigee Edge End of Life"}
+
+Apigee Edge for Private Cloud v4.53 reached end of life on April 11, 2026. The
+final version (v4.53.01) reaches end of life on **February 26, 2027**. After
+these dates, Google provides no security patches, bug fixes, or support. If you
+are still running Apigee Edge, now is the time to migrate.
+
+:::
+
+## Pre-migration checklist
+
+Before starting your migration, gather the following from your Apigee
+environment:
+
+- [ ] **API proxy inventory** — List all active API proxies, their base paths,
+      and target endpoints
+- [ ] **OpenAPI specs** — Export specs for each proxy (or document endpoints if
+      specs don't exist)
+- [ ] **Policy audit** — List every policy attached to each proxy
+      (authentication, rate limiting, transformation, etc.)
+- [ ] **Environment configuration** — Document KVM entries, target servers,
+      keystores, and virtual host settings
+- [ ] **Developer portal content** — Export API documentation, custom pages, and
+      developer account data
+- [ ] **CI/CD pipeline configuration** — Document your current deployment
+      process and any automation scripts
+- [ ] **Traffic patterns** — Understand request volumes, peak usage times, and
+      geographic distribution of API consumers
+- [ ] **Custom Java callouts** — Identify any Java callouts that will need
+      translation to TypeScript
+
+## Why teams migrate from Apigee
+
+Apigee is one of the oldest API management platforms, acquired by Google
+in 2016. While it offers deep enterprise analytics and compliance features,
+teams increasingly find the platform difficult to justify:
+
+- **Apigee Edge end-of-life** — Google has been sunsetting legacy Apigee Edge
+  (on-premises and private cloud) versions, pushing customers to migrate to
+  Apigee X on Google Cloud. This forced migration is an opportunity to evaluate
+  modern alternatives.
+- **Google Cloud lock-in** — Apigee X is tightly coupled to Google Cloud
+  Platform. While Apigee hybrid exists, it adds operational complexity. Teams
+  running multi-cloud or non-GCP backends face unnecessary friction.
+- **High cost** — Apigee pricing starts at approximately $1,500/month for just
+  100K requests, with separate charges for environments, analytics, and
+  developer portals. Enterprise contracts often require five-figure monthly
+  commitments.
+- **XML-based policy configuration** — Apigee policies are configured in verbose
+  XML files that are difficult to read, maintain, and version control. Custom
+  logic uses a limited JavaScript engine.
+- **Slow deployment cycles** — Apigee deployments can take several minutes to
+  propagate, slowing down the development iteration loop.
+- **Drupal-based developer portal** — Apigee's developer portal is built on
+  Drupal, requiring significant setup, customization, and ongoing maintenance.
+
+:::tip
+
+Zuplo has a video walkthrough of the Apigee to Zuplo migration process:
+[Migrating from Apigee API Management Made Easy](https://zuplo.com/videos/migrating-from-apigee-api-management-made-easy).
+
+:::
+
+## Concept mapping: Apigee to Zuplo
+
+| Apigee concept          | Zuplo equivalent                                                       |
+| ----------------------- | ---------------------------------------------------------------------- |
+| API Proxy               | Routes in your [OpenAPI spec](./openapi.md)                            |
+| ProxyEndpoint           | Route path + [handler](../handlers/url-forward.md)                     |
+| TargetEndpoint          | [URL forward handler](../handlers/url-forward.md) base URL             |
+| Policy (XML)            | [Policy](./policies.md) (TypeScript) or built-in policy                |
+| PreFlow / PostFlow      | Inbound / outbound [policies](./policies.md)                           |
+| Conditional flow        | Custom code in a [custom policy](../policies/custom-code-inbound.md)   |
+| SharedFlow              | Reusable [custom code module](../programmable-api/reusing-code.md)     |
+| Environment             | [Environment](./environments.md)                                       |
+| API Product             | API key with [metadata](./api-key-management.md)                       |
+| Developer App           | [API key consumer](./api-key-management.md)                            |
+| Apigee Developer Portal | [Zuplo Developer Portal](../dev-portal/introduction.md)                |
+| VerifyAPIKey policy     | [API Key Authentication](../policies/api-key-inbound.md)               |
+| OAuthV2 policy          | [JWT authentication policies](../policies/open-id-jwt-auth-inbound.md) |
+| SpikeArrest             | [Rate Limiting](../policies/rate-limit-inbound.md)                     |
+| Quota                   | [Quota policy](../policies/quota-inbound.md)                           |
+| KVM (Key Value Map)     | [Environment variables](./environment-variables.md)                    |
+| Management API          | [Zuplo API](./accounts/zuplo-api-keys.md)                              |
+
+## Step-by-step migration
+
+### Step 1: Export your API definitions
+
+Apigee API proxies contain OpenAPI specs or can generate them. Export your API
+definitions:
+
+1. In the Apigee console, navigate to your API proxy.
+2. Download the OpenAPI spec from the **Develop** tab, or export the proxy
+   bundle as a ZIP file and extract the spec.
+3. If no spec exists, create one from your proxy's endpoint and resource
+   definitions.
+
+### Step 2: Map Apigee policies to Zuplo policies
+
+The following table maps common Apigee policies to Zuplo equivalents:
+
+| Apigee policy             | Zuplo policy                                                                                     |
+| ------------------------- | ------------------------------------------------------------------------------------------------ |
+| `VerifyAPIKey`            | [API Key Authentication](../policies/api-key-inbound.md)                                         |
+| `OAuthV2`                 | [Open ID JWT Authentication](../policies/open-id-jwt-auth-inbound.md)                            |
+| `BasicAuthentication`     | [Basic Authentication](../policies/basic-auth-inbound.md)                                        |
+| `SpikeArrest`             | [Rate Limiting](../policies/rate-limit-inbound.md)                                               |
+| `Quota`                   | [Quota](../policies/quota-inbound.md)                                                            |
+| `AssignMessage`           | [Set Headers](../policies/set-headers-inbound.md) or [Set Body](../policies/set-body-inbound.md) |
+| `ExtractVariables`        | [Custom Code Policy](../policies/custom-code-inbound.md)                                         |
+| `XMLToJSON` / `JSONToXML` | [XML to JSON](../policies/xml-to-json-outbound.md) or custom code                                |
+| `RaiseFault`              | Custom code returning an error [Response](../programmable-api/http-problems.md)                  |
+| `AccessControl`           | [IP Restriction](../policies/ip-restriction-inbound.md)                                          |
+| `CORS`                    | Built-in [CORS configuration](../programmable-api/custom-cors-policy.md)                         |
+| `JavaScript` callout      | [Custom Code Policy](../policies/custom-code-inbound.md) (TypeScript)                            |
+| `ServiceCallout`          | [Custom Code Policy](../policies/custom-code-inbound.md) using `fetch()`                         |
+
+### Step 3: Translate policy configuration
+
+Here is an example of translating an Apigee SpikeArrest policy to a Zuplo rate
+limit policy.
+
+**Apigee XML policy:**
+
+```xml
+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<SpikeArrest name="SA-RateLimit">
+  <Rate>100pm</Rate>
+  <Identifier ref="request.header.x-api-key"/>
+  <UseEffectiveCount>true</UseEffectiveCount>
+</SpikeArrest>
+```
+
+**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
+
+Apigee's SpikeArrest uses a smoothing algorithm that spreads allowed requests
+evenly across the time window. Zuplo's rate limiter uses a sliding window
+algorithm and is globally distributed — limits are enforced across all 300+ edge
+locations as a single zone, unlike Apigee which synchronizes within a region but
+not across regions by default.
+
+:::
+
+Here is an example of translating an Apigee OAuthV2 verification policy to a
+Zuplo JWT authentication policy.
+
+**Apigee OAuthV2 policy:**
+
+```xml
+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<OAuthV2 name="VerifyAccessToken">
+  <Operation>VerifyAccessToken</Operation>
+  <ExternalAuthorization>false</ExternalAuthorization>
+  <SupportedGrantTypes>
+    <GrantType>client_credentials</GrantType>
+  </SupportedGrantTypes>
+</OAuthV2>
+```
+
+**Zuplo JWT authentication policy configuration:**
+
+```json
+{
+  "name": "jwt-auth-inbound",
+  "policyType": "open-id-jwt-auth-inbound",
+  "handler": {
+    "export": "OpenIdJwtInboundPolicy",
+    "module": "$import(@zuplo/runtime)",
+    "options": {
+      "issuer": "$env(AUTH_ISSUER)",
+      "audience": "$env(AUTH_AUDIENCE)",
+      "jwkUrl": "$env(AUTH_JWK_URL)",
+      "allowUnauthenticatedRequests": false
+    }
+  }
+}
+```
+
+:::note
+
+Apigee can act as a full OAuth 2.0 server (issuing and managing tokens). Zuplo
+validates tokens issued by external identity providers (Auth0, Cognito, Clerk,
+Firebase, Supabase, or any OIDC-compliant provider). If you are using Apigee as
+your OAuth server, you will need to move token issuance to a dedicated identity
+provider during migration.
+
+:::
+
+Here is an example of translating an Apigee ResponseCache to a Zuplo caching
+policy.
+
+**Apigee ResponseCache policy:**
+
+```xml
+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<ResponseCache name="Cache-Response">
+  <CacheKey>
+    <KeyFragment ref="request.uri"/>
+  </CacheKey>
+  <ExpirySettings>
+    <TimeoutInSec>300</TimeoutInSec>
+  </ExpirySettings>
+</ResponseCache>
+```
+
+**Zuplo caching policy configuration:**
+
+```json
+{
+  "name": "caching-inbound",
+  "policyType": "caching-inbound",
+  "handler": {
+    "export": "CachingInboundPolicy",
+    "module": "$import(@zuplo/runtime)",
+    "options": {
+      "expirationSecondsTtl": 300
+    }
+  }
+}
+```
+
+### Step 4: Translate JavaScript callouts to TypeScript
+
+If you use Apigee JavaScript callouts, rewrite them as Zuplo custom code
+policies in TypeScript.
+
+**Apigee JavaScript callout:**
+
+```javascript
+var apiKey = context.getVariable("request.header.x-api-key");
+var clientId = context.getVariable("request.header.x-client-id");
+
+if (!apiKey || !clientId) {
+  context.setVariable("isError", true);
+  context.setVariable("errorMessage", "Missing required headers");
+}
+
+var payload = JSON.parse(context.getVariable("request.content"));
+payload.enriched = true;
+payload.timestamp = new Date().toISOString();
+context.setVariable("request.content", JSON.stringify(payload));
+```
+
+**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 apiKey = request.headers.get("x-api-key");
+  const clientId = request.headers.get("x-client-id");
+
+  if (!apiKey || !clientId) {
+    return HttpProblems.badRequest(request, context, {
+      detail: "Missing required headers",
+    });
+  }
+
+  const payload = await request.json();
+  payload.enriched = true;
+  payload.timestamp = new Date().toISOString();
+
+  return new ZuploRequest(request, {
+    body: JSON.stringify(payload),
+    headers: {
+      ...Object.fromEntries(request.headers.entries()),
+      "content-type": "application/json",
+    },
+  });
+}
+```
+
+### Step 5: Migrate your developer portal
+
+Apigee's Drupal-based developer portal requires significant setup and
+maintenance. Zuplo's [Developer Portal](../dev-portal/introduction.md) is
+automatically generated from your OpenAPI spec and includes:
+
+- Interactive API reference documentation
+- Self-serve API key management
+- Built-in authentication
+- Customizable theming
+- Zero maintenance — it updates automatically when your API changes
+
+### Step 6: Migrate environment configuration
+
+**Apigee KVMs to Zuplo environment variables:**
+
+Apigee uses Key Value Maps (KVMs) for environment-specific configuration. In
+Zuplo, use [environment variables](./environment-variables.md):
+
+| Apigee KVM                          | Zuplo environment variable          |
+| ----------------------------------- | ----------------------------------- |
+| `kvm.get("backend-url")`            | `$env(BACKEND_URL)` in route config |
+| `context.getVariable("my-kvm.key")` | `context.env.MY_KEY` in custom code |
+| Encrypted KVM entries               | Secret environment variables        |
+
+### 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 your Zuplo gateway.
+3. Route a subset of traffic to Zuplo using DNS-based traffic splitting.
+4. Monitor both gateways and compare behavior.
+5. Gradually shift all traffic to Zuplo.
+6. Decommission your Apigee environment.
+
+## Apigee Edge to Zuplo: a special case
+
+If you are migrating from legacy Apigee Edge (on-premises or private cloud)
+rather than Apigee X, the migration to Zuplo is an opportunity to modernize
+without the complexity of moving to Apigee X:
+
+- **Skip the Apigee X migration** — Instead of migrating from Edge to X (which
+  Google recommends but requires significant effort), migrate directly to Zuplo.
+- **Eliminate infrastructure** — Apigee Edge requires managing on-premises
+  infrastructure (Cassandra, ZooKeeper, Qpid clusters). Zuplo is fully managed.
+- **Reduce costs** — Apigee X pricing is often higher than Edge licensing. Zuplo
+  offers transparent, usage-based pricing starting with a free tier.
+- **No GCP dependency** — Apigee X requires Google Cloud Platform. Apigee hybrid
+  still requires GCP for its control plane. Zuplo is cloud-agnostic and can
+  front backends on any cloud provider.
+
+### Apigee Edge end-of-life timeline
+
+| Version | End-of-life date      | Status        |
+| ------- | --------------------- | ------------- |
+| 4.52.00 | August 31, 2024       | EOL reached   |
+| 4.52.01 | September 30, 2025    | EOL reached   |
+| 4.52.02 | December 31, 2025     | EOL reached   |
+| 4.53.00 | April 11, 2026        | EOL reached   |
+| 4.53.01 | **February 26, 2027** | Final version |
+
+After end of life, Google provides no security patches, bug fixes, hot fixes, or
+technical support for that version.
+
+## Common migration gotchas
+
+**Encrypted KVM entries cannot be exported.** Apigee's management API does not
+return values for encrypted Key Value Map entries. You will need to manually
+re-enter these values as Zuplo secret environment variables.
+
+**Apigee's OAuth server has no direct equivalent.** If you use Apigee to issue
+and manage OAuth tokens (not just validate them), you will need to move token
+issuance to a dedicated identity provider such as Auth0, Cognito, or Clerk.
+Zuplo validates tokens from external providers but does not act as an OAuth
+server.
+
+**Shared flows become reusable modules.** Apigee shared flows that are
+referenced across multiple proxies should be refactored into reusable TypeScript
+modules. See [Reusing Code](../programmable-api/reusing-code.md).
+
+**Java callouts require rewriting.** Apigee Java callouts have no direct
+TypeScript equivalent. Evaluate each callout and rewrite the logic as a
+[custom code policy](../policies/custom-code-inbound.md). In most cases, the
+TypeScript version will be simpler because you have access to the full npm
+ecosystem and standard web APIs.
+
+**Apigee analytics must be replaced.** Apigee's built-in analytics dashboards
+and custom reports do not migrate. Zuplo provides built-in analytics and
+integrates with observability platforms like [Datadog](./log-plugin-datadog.mdx)
+and [Google Cloud Logging](./log-plugin-gcp.mdx) for advanced reporting.
+
+**Test with representative traffic before cutover.** Use Zuplo's
+[branch-based deployments](./branch-based-deployments.md) to create a preview
+environment and route a subset of traffic through Zuplo before migrating
+production traffic. Compare response codes, latencies, and payload correctness
+between both gateways.
+
+## 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-aws-api-gateway.md

@@ -0,0 +1,248 @@
+---
+title: Migrate from AWS API Gateway to Zuplo
+sidebar_label: Migrate from AWS API Gateway
+---
+
+This guide walks through migrating from AWS API Gateway (REST API, HTTP API, or
+WebSocket API) to Zuplo. It covers the key differences, concept mapping, and a
+step-by-step migration process.
+
+## Why teams migrate from AWS API Gateway
+
+AWS API Gateway is a natural choice for teams already building on AWS. However,
+as API programs grow, teams encounter several limitations:
+
+- **AWS lock-in** — AWS API Gateway only works within the AWS ecosystem. If your
+  backends span multiple cloud providers or you want to avoid single-vendor
+  dependency, you need a multi-cloud solution.
+- **No built-in developer portal** — AWS API Gateway does not include a
+  developer-facing portal. The "Serverless Developer Portal" is a reference
+  implementation that requires self-hosting and maintenance.
+- **Complex customization** — Custom request/response transformations use
+  Velocity Template Language (VTL) for REST APIs, a templating language that is
+  difficult to write, debug, and maintain. More complex logic requires separate
+  Lambda functions.
+- **Region-bound traffic** — AWS API Gateway routes traffic through specific AWS
+  regions, not a global edge network. Users far from your selected region
+  experience higher latency.
+- **CloudFormation complexity** — Managing API Gateway configuration through
+  CloudFormation, SAM, or CDK templates adds significant complexity and slow
+  deployment cycles.
+- **Limited rate limiting** — Throttling is global or stage-based with limited
+  per-user or per-key customization. There is no built-in sliding window rate
+  limiter.
+
+## Concept mapping: AWS API Gateway to Zuplo
+
+| AWS API Gateway concept        | Zuplo equivalent                                                                                              |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------------- |
+| REST API / HTTP API            | [OpenAPI route configuration](./openapi.md)                                                                   |
+| Resource                       | Route path in OpenAPI spec                                                                                    |
+| Method                         | HTTP method on a route                                                                                        |
+| Integration (Lambda, HTTP)     | [Handler](../handlers/url-forward.md) (URL Forward, URL Rewrite, Custom)                                      |
+| Lambda Authorizer              | [Authentication policy](../policies/api-key-inbound.md) or [custom code](../policies/custom-code-inbound.md)  |
+| API Key + Usage Plan           | [API Key Authentication](../policies/api-key-inbound.md) + [Rate Limiting](../policies/rate-limit-inbound.md) |
+| Stage                          | [Environment](./environments.md)                                                                              |
+| Stage variables                | [Environment variables](./environment-variables.md)                                                           |
+| Request/Response mapping (VTL) | [Custom code policy](../policies/custom-code-inbound.md) (TypeScript)                                         |
+| CloudFormation / SAM / CDK     | [GitOps deployment](./source-control.md) via `git push`                                                       |
+| CloudWatch Logs                | [Logging integrations](./logging.md) (Datadog, Splunk, etc.)                                                  |
+| WAF integration                | [WAF & DDoS protection](./waf-ddos.md)                                                                        |
+| Custom domain                  | [Custom domains](./custom-domains.md)                                                                         |
+
+## Step-by-step migration
+
+### Step 1: Export your API definition
+
+AWS API Gateway supports exporting your API as an OpenAPI spec:
+
+**Using the AWS Console:**
+
+1. Navigate to your API in the API Gateway console.
+2. Select **Stages** and choose the stage to export.
+3. Go to the **Export** tab.
+4. Select **OpenAPI 3** and **JSON** format.
+5. Choose **Export as OpenAPI 3 + API Gateway Extensions** to include
+   integration details.
+
+**Using the AWS CLI:**
+
+```bash
+aws apigateway get-export \
+  --rest-api-id YOUR_API_ID \
+  --stage-name prod \
+  --export-type oas30 \
+  --accepts application/json \
+  output.json
+```
+
+### Step 2: Clean up and import your OpenAPI spec
+
+The exported spec includes AWS-specific extensions (`x-amazon-apigateway-*`)
+that you need to replace with Zuplo configuration.
+
+For each path and method, replace the `x-amazon-apigateway-integration` with
+Zuplo's `x-zuplo-route` extension:
+
+**AWS API Gateway export:**
+
+```json
+{
+  "/users": {
+    "get": {
+      "x-amazon-apigateway-integration": {
+        "type": "HTTP_PROXY",
+        "httpMethod": "GET",
+        "uri": "https://api.backend.example.com/users"
+      }
+    }
+  }
+}
+```
+
+**Zuplo route configuration:**
+
+```json
+{
+  "/users": {
+    "get": {
+      "operationId": "get-users",
+      "summary": "List users",
+      "x-zuplo-route": {
+        "corsPolicy": "none",
+        "handler": {
+          "export": "urlForwardHandler",
+          "module": "$import(@zuplo/runtime)",
+          "options": {
+            "baseUrl": "https://api.backend.example.com"
+          }
+        },
+        "policies": {
+          "inbound": []
+        }
+      }
+    }
+  }
+}
+```
+
+### Step 3: Map AWS integrations to Zuplo handlers
+
+| AWS integration type | Zuplo handler                                                                                                        |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| HTTP / HTTP_PROXY    | [URL Forward](../handlers/url-forward.md) or [URL Rewrite](../handlers/url-rewrite.md)                               |
+| Lambda               | [URL Forward](../handlers/url-forward.md) to Lambda function URL, or [AWS Lambda handler](../handlers/aws-lambda.md) |
+| Mock                 | [Mock API policy](../policies/mock-api-inbound.md)                                                                   |
+
+### Step 4: Replace VTL mappings with TypeScript
+
+If you use Velocity Template Language (VTL) for request/response
+transformations, replace them with TypeScript custom code policies.
+
+**AWS VTL mapping template:**
+
+```velocity
+#set($inputRoot = $input.path('$'))
+{
+  "userId": "$inputRoot.id",
+  "fullName": "$inputRoot.first_name $inputRoot.last_name",
+  "email": "$inputRoot.email"
+}
+```
+
+**Zuplo outbound custom code policy:**
+
+```typescript
+import { ZuploContext, ZuploRequest } from "@zuplo/runtime";
+
+export default async function (
+  response: Response,
+  request: ZuploRequest,
+  context: ZuploContext,
+  options: never,
+  policyName: string,
+) {
+  const data = await response.json();
+
+  const transformed = {
+    userId: data.id,
+    fullName: `${data.first_name} ${data.last_name}`,
+    email: data.email,
+  };
+
+  return new Response(JSON.stringify(transformed), {
+    status: response.status,
+    headers: response.headers,
+  });
+}
+```
+
+### Step 5: Migrate Lambda authorizers
+
+If you use Lambda authorizers for authentication, replace them with Zuplo's
+built-in authentication policies or custom code policies.
+
+**For API key authentication:**
+
+Replace the Lambda authorizer + usage plan pattern with Zuplo's
+[API Key Authentication](../policies/api-key-inbound.md) policy, which includes
+built-in key management, a developer portal, and per-key rate limiting.
+
+**For JWT / OAuth authentication:**
+
+Replace the Lambda authorizer with one of Zuplo's JWT 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)
+
+:::note
+
+You can continue using AWS Cognito as your identity provider. Use Zuplo's
+[Cognito JWT Authentication](../policies/cognito-jwt-auth-inbound.md) policy to
+validate Cognito tokens at the gateway.
+
+:::
+
+### Step 6: Replace usage plans with Zuplo rate limiting
+
+AWS API Gateway's usage plans provide basic throttling and quota management.
+Zuplo's rate limiting is more flexible:
+
+| AWS usage plan feature       | Zuplo equivalent                                                            |
+| ---------------------------- | --------------------------------------------------------------------------- |
+| Throttle rate (requests/sec) | [Rate Limiting](../policies/rate-limit-inbound.md) with `timeWindowMinutes` |
+| Quota (requests/period)      | [Quota policy](../policies/quota-inbound.md)                                |
+| Per-key throttling           | `rateLimitBy: "user"` on the rate limit policy                              |
+| Burst limit                  | Built-in — Zuplo's sliding window handles bursts naturally                  |
+
+### 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. Update your DNS to route traffic through Zuplo.
+4. Zuplo can forward requests to your existing AWS backends (Lambda, ALB, ECS)
+   without changes.
+5. Monitor traffic and gradually decommission your AWS API Gateway stages.
+
+## Keeping AWS backends with Zuplo
+
+You do not need to migrate your backend infrastructure. Zuplo works with any
+HTTP backend, including:
+
+- AWS Lambda (via function URLs or API Gateway pass-through)
+- Application Load Balancers (ALB)
+- Amazon ECS / EKS services
+- Any AWS service with an HTTP endpoint
+
+Use [backend security](./securing-your-backend.md) options like mTLS or shared
+secrets to secure the connection between Zuplo and your AWS backends.
+
+## 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)