Skip to main content

Getting started with Okteto Divert

Divert allows you to create Development Environments that include only the services you are actively working on while leveraging a shared environment for all other microservices. This dramatically reduces infrastructure costs and setup time, especially in large microservice applications.

In this tutorial, you'll learn how to use Okteto Divert to set up a Development Environment that contains only the services you are actively working on, while all other services automatically fall back to a shared environment.

tip

Learn more about Divert's architecture and traffic routing in the Divert core concepts guide.

Prerequisites​

  • Access to an Okteto instance
  • Okteto CLI installed and configured
  • ModHeader browser extension (or similar header modification tool)

Sample Application​

We'll use the Movies with Divert sample application, which consists of five microservices:

ServiceTechnologyPurpose
FrontendReact/Node.jsUser interface
API GatewayGoPublic API routing
CatalogNode.js/ExpressMovie catalog management
RentJava/Spring BootRental logic
WorkerGoBackground job processing

The application also includes MongoDB, PostgreSQL, and Kafka for data storage and messaging.

┌─────────────────────────────────────────────────────────────────┐
│                         Frontend                                 │
│                           (React)                                │
└─────────────────────────────────────────────────────────────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        ▼                     ▼                     ▼
┌───────────────┐     ┌───────────────┐     ┌───────────────┐
│    Catalog    │     │  API Gateway  │     │     Rent      │
│   (Node.js)   │     │     (Go)      │     │    (Java)     │
└───────┬───────┘     └───────┬───────┘     └───────┬───────┘
        │                     │                     │
        ▼                     ▼                     ▼
┌───────────────┐     ┌───────────────┐     ┌───────────────┐
│    MongoDB    │     │  PostgreSQL   │     │    Kafka      │
└───────────────┘     └───────────────┘     └───────┬───────┘
                                                    │
                                                    ▼
                                            ┌───────────────┐
                                            │    Worker     │
                                            │     (Go)      │
                                            └───────────────┘

Step 1: Deploy the Shared Environment​

First, deploy the complete Movies application to serve as the shared environment.

Clone the Repository​

git clone https://github.com/okteto-community/movies-with-divert
cd movies-with-divert

Deploy to a Shared Namespace​

okteto preview deploy \
  --repository https://github.com/okteto-community/movies-with-divert \
  --label=okteto-shared \
  movies-shared

This command:

  1. Creates a namespace called movies-shared
  2. Deploys all five services plus their databases
  3. Labels it as a shared environment

Wait for all services to be ready, then visit the application at its endpoint (e.g., https://movies-movies-shared.okteto.example.com). Rent a few movies to populate the database with test data.

Step 2: Deploy Your Personal Development Environment​

Now let's deploy only the Catalog service for development, while using the shared environment for everything else.

Set the Shared Namespace​

export OKTETO_SHARED_NAMESPACE="movies-shared"

Deploy the Catalog Service​

okteto deploy -f okteto.catalog.yaml

Let's examine the okteto.catalog.yaml manifest:

build:
  catalog:
    context: catalog

deploy:
  commands:
    - helm upgrade --install catalog .hacks/catalog/chart --set image=${OKTETO_BUILD_CATALOG_IMAGE}
    - helm upgrade --install mongodb .hacks/mongodb/chart
  divert:
    driver: nginx
    namespace: ${OKTETO_SHARED_NAMESPACE:-staging}

dev:
  catalog:
    image: node:18
    command: bash
    sync:
      - catalog:/app
    forward:
      - 9229:9229

Key elements:

  • build: Builds only the catalog service image
  • deploy.commands: Deploys catalog and its MongoDB dependency
  • deploy.divert: Routes missing services to the shared namespace
  • dev: Configuration for live development with okteto up

Step 3: Test Your Diverted Environment​

Without the Baggage Header​

First, test the shared environment directly:

curl https://movies-movies-shared.okteto.example.com/api/catalog/healthz

Response:

{"status": "ok", "namespace": "movies-shared"}

With the Baggage Header​

Now test with the divert header pointing to your namespace:

curl -H "baggage: okteto-divert=cindy" \
  https://movies-movies-shared.okteto.example.com/api/catalog/healthz

Response:

{"status": "ok", "namespace": "cindy"}

The request was routed to your personal catalog service!

Using ModHeader in Your Browser​

  1. Install the ModHeader browser extension
  2. Add a request header:
    • Name: baggage
    • Value: okteto-divert=<your-namespace>
  3. Visit the shared environment URL

With the header enabled, requests will route to your diverted services while falling back to shared services for everything else.

Step 4: Start Developing​

Start a development session with hot-reload:

okteto up -f okteto.catalog.yaml

This:

  1. Swaps your deployed catalog with a development container
  2. Syncs your local catalog/ folder to the container
  3. Forwards port 9229 for debugging

Make changes to your local code and see them reflected immediately in your running environment.

Available Divert Configurations​

The repository includes several pre-configured manifests for different development scenarios:

Frontend Development (okteto.frontend.yaml)​

Use when: Working on React UI components

export OKTETO_SHARED_NAMESPACE="movies-shared"
okteto deploy -f okteto.frontend.yaml

Deploys: Frontend only Shares: All backend services and databases

Catalog Development (okteto.catalog.yaml)​

Use when: Working on movie catalog or MongoDB integration

export OKTETO_SHARED_NAMESPACE="movies-shared"
okteto deploy -f okteto.catalog.yaml

Deploys: Catalog service, MongoDB Shares: Frontend, API, Rent, Worker, other databases

API Gateway Development (okteto.api.yaml)​

Use when: Working on the public API

export OKTETO_SHARED_NAMESPACE="movies-shared"
okteto deploy -f okteto.api.yaml

Deploys: API Gateway only Shares: All other services and databases

Rentals Development (okteto.rentals.yaml)​

Use when: Working on rental logic or Kafka integration

export OKTETO_SHARED_NAMESPACE="movies-shared"
okteto deploy -f okteto.rentals.yaml

Deploys: Rent service, Worker, Kafka, PostgreSQL Shares: Frontend, Catalog, API, MongoDB

Understanding the Traffic Flow​

With Divert enabled, here's how traffic flows for a user working on the Catalog service:

User Request (with baggage: okteto-divert=cindy)
         │
         ▼
    ┌─────────┐
    │Frontend │ ← Shared (movies-shared namespace)
    └────┬────┘
         │ (header propagated)
         ▼
    ┌─────────┐
    │ Catalog │ ← Your version (cindy namespace)
    └────┬────┘
         │
         ▼
    ┌─────────┐
    │ MongoDB │ ← Your version (cindy namespace)
    └─────────┘

The key insight: only Catalog and MongoDB run in your namespace. Everything else comes from the shared environment, saving significant resources.

Cleanup​

When you're done developing, delete your personal namespace:

okteto namespace delete cindy

The shared environment remains available for other developers.

Alternative: Divert with Queues​

For applications using message queues, check out the TacoShop with Divert Queues example, which demonstrates:

  • SQS queue routing based on the baggage header
  • Message filtering by namespace
  • Producer/consumer patterns for diverted environments

Next Steps​

Congratulations! You've deployed your first diverted Development Environment 🚀