DEV Community: DevStories

OpenTelemetry for Beginners: Logs, Metrics and Traces in One Setup

DevStories — Tue, 27 Oct 2026 16:51:05 +0000

Picture this. A customer says checkout feels slow. You open the logs and find thousands of lines.

Which request was theirs? Which step was slow? Was it just them, or everyone?

Logs alone can't answer all of that. You need three kinds of data about the same request, and a way to connect them.

That's what OpenTelemetry gives you. It has a reputation for being complicated, but the core idea is small.

In this post you'll send traces, metrics and logs from a small FastAPI app into Grafana. The backend is one Docker command. The boilerplate is handled by zero-code instrumentation. You write a few lines yourself for the interesting parts.

Heads up on Python logs: In OpenTelemetry Python, traces and metrics are marked Stable, but logs are still marked Development. Logging works fine for this walkthrough. Just expect the logs side to change more than the other two.

What OpenTelemetry is (and what it isn't)

OpenTelemetry, or OTel for short, is an open standard and a set of tools for producing telemetry. That's the traces, metrics and logs your software emits about itself.

It's a Cloud Native Computing Foundation project, and it grew out of two older projects, OpenTracing and OpenCensus.

The key word is producing. OpenTelemetry doesn't store or display anything. You still need a backend for that.

The win is that you instrument once, and your code doesn't care which backend receives the data.

Here are the pieces you'll meet:

Piece	What it does	In this post
API and SDK	The code you call, and the engine behind it that batches and exports data	Installed with opentelemetry-distro
Instrumentation	Libraries that create telemetry for you (web frameworks, HTTP clients, databases)	FastAPI and logging
OTLP	The format and protocol the data travels in	gRPC on port 4317
Collector	A service that receives, processes and forwards telemetry	Built into the Grafana image
Backend	Where the data is stored and viewed	Tempo, Prometheus, Loki and Grafana

The three signals in plain words

Signal	Plain-English meaning	Question it answers	Example
Traces	The story of one request as it moves through your code	Where did this request spend its time?	POST /orders took 380 ms, and 340 of that was charge_card
Metrics	Numbers measured over time	How often? How slow? Is it getting worse?	Declined orders per minute
Logs	Timestamped messages, in words	What exactly happened?	Payment declined: keyboard

Two terms you'll see everywhere. A span is one step inside a trace, like "charge the card". A trace is a tree of spans.

Spans carry attributes, which are key-value details such as order.item = keyboard.

Which signal do you reach for first? It depends on the question:

The real power is in the links. A metric spike leads you to a trace. A span leads you to the logs written during it.

That last jump works because each log record carries the trace ID and span ID of the request that wrote it. OpenTelemetry adds them for you.

What we'll build

A tiny orders API with one endpoint, POST /orders. It "charges a card", which is just a short sleep with a 25% chance of being declined.

That gives you slow requests and failures to look at. Here's how the data flows:

Each request will produce a trace shaped like this:

The official docs make a useful point here. Automatic instrumentation captures what happens at the edges of your system, like inbound and outbound HTTP requests. It can't see what's going on inside your own code.

So the top span is free. The two inner spans, the counter and the histogram are yours.

You'll need Python 3.10 or newer (that's what OpenTelemetry Python supports), Docker, and a terminal.

Step 1: Start the backend

docker run -p 3000:3000 -p 4317:4317 -p 4318:4318 --rm -ti grafana/otel-lgtm

This is Grafana's otel-lgtm image. It bundles an OpenTelemetry Collector, Prometheus for metrics, Tempo for traces, Loki for logs and Grafana to look at all three.

The ports:

3000 is the Grafana UI
4317 is where OTLP over gRPC arrives
4318 is where OTLP over HTTP arrives

Open http://localhost:3000 and log in with user admin and password admin.

Development only: Grafana says this image is intended for development, demo and testing. The data lives inside the container, so it's gone when the container is. Don't use it as your production backend.

Step 2: Set up the project

mkdir orders-api && cd orders-api
python3 -m venv venv
source venv/bin/activate
pip install fastapi "uvicorn[standard]" opentelemetry-distro opentelemetry-exporter-otlp opentelemetry-instrumentation-logging
opentelemetry-bootstrap -a install

On Windows PowerShell, activate with .\venv\Scripts\Activate.ps1 and use python instead of python3.

What each piece does:

opentelemetry-distro brings the API and SDK, plus two commands: opentelemetry-bootstrap and opentelemetry-instrument.
opentelemetry-exporter-otlp lets the app send data over OTLP.
opentelemetry-instrumentation-logging connects Python's logging module to OpenTelemetry.
opentelemetry-bootstrap -a install looks at what's installed and adds the matching instrumentation. Here, that means FastAPI.

Run bootstrap after you install FastAPI, because it decides based on what it finds.

Step 3: Write the app

Create main.py:

import asyncio
import logging
import random
import time

from fastapi import FastAPI, HTTPException
from opentelemetry import metrics, trace
from pydantic import BaseModel, Field

app = FastAPI(title="orders-api")

# Let INFO records through.
logger = logging.getLogger("orders")
logger.setLevel(logging.INFO)

tracer = trace.get_tracer("orders.tracer")
meter = metrics.get_meter("orders.meter")

orders_processed = meter.create_counter(
    "orders.processed",
    description="Orders processed, by outcome",
)
payment_duration = meter.create_histogram(
    "payment.duration",
    unit="ms",
    description="Time spent charging the card",
)

class Order(BaseModel):
    item: str
    quantity: int = Field(ge=1, le=10)

class PaymentDeclined(Exception):
    """Raised when the pretend payment provider says no."""

async def charge_card(amount: float) -> None:
    started = time.perf_counter()
    with tracer.start_as_current_span("charge_card") as span:
        span.set_attribute("payment.amount", amount)
        try:
            await asyncio.sleep(random.uniform(0.05, 0.4))  # pretend to call a payment API
            if random.random() < 0.25:
                raise PaymentDeclined("card declined")
        finally:
            payment_duration.record((time.perf_counter() - started) * 1000)

@app.post("/orders")
async def create_order(order: Order):
    with tracer.start_as_current_span("process_order") as span:
        span.set_attribute("order.item", order.item)
        span.set_attribute("order.quantity", order.quantity)
        logger.info("Processing order: %s x%d", order.item, order.quantity)

        try:
            await charge_card(round(order.quantity * 9.99, 2))
            outcome = "paid"
            logger.info("Order paid: %s", order.item)
        except PaymentDeclined:
            outcome = "declined"
            logger.warning("Payment declined: %s", order.item)

        span.set_attribute("order.outcome", outcome)
        orders_processed.add(1, {"outcome": outcome})

    if outcome == "declined":
        raise HTTPException(status_code=402, detail="Payment declined")
    return {"status": "paid", "item": order.item}

You don't need to memorise any of it. These are the parts worth understanding.

Spans

tracer.start_as_current_span(...) opens a span for the length of the with block. A span opened inside another one becomes its child. That's how charge_card ends up under process_order.

set_attribute attaches details. Put anything here that will help you debug later, like the item or the amount.

There's a nice default too. If an exception escapes a with span block, the SDK records it on the span and marks the span as an error.

That's why a declined payment will show up as a red charge_card span, with no extra code from you.

Metrics

Two instruments, two jobs:

Counter: counts things, and only goes up. We add 1 for every order, labelled with its outcome.
Histogram: records measurements like durations. It lets you ask for percentiles later, such as "how slow are the slowest 5%?"

I record the duration in milliseconds on purpose. The default histogram buckets are tuned for millisecond-sized values: 5, 10, 25, 50 and so on up to 10,000.

Record seconds instead and almost everything lands in the first bucket, so your percentiles turn to mush.

Careful with metric attributes: Every unique combination of attribute values creates a new time series. outcome has two values, which is fine. A user ID or order ID would create millions. Keep high-detail values like order.item on spans, where they're cheap.

Logs

There's no special OpenTelemetry logging call here. You keep using Python's logging, and OpenTelemetry attaches a handler that ships the records.

One gotcha: Python only lets WARNING and above through by default. So we set our logger to INFO, or the "Processing order" lines would silently vanish.

Following an older tutorial? Before OpenTelemetry Python 1.40.0 you had to set OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true to turn on log instrumentation. In current versions you don't, as long as opentelemetry-instrumentation-logging is installed.

Step 4: Run it with auto-instrumentation

Set a few environment variables, then start the app through opentelemetry-instrument.

macOS and Linux:

export OTEL_SERVICE_NAME=orders-api
export OTEL_TRACES_EXPORTER=otlp
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
export OTEL_METRIC_EXPORT_INTERVAL=5000

opentelemetry-instrument uvicorn main:app --port 8000

Windows (PowerShell):

$env:OTEL_SERVICE_NAME = "orders-api"
$env:OTEL_TRACES_EXPORTER = "otlp"
$env:OTEL_METRICS_EXPORTER = "otlp"
$env:OTEL_LOGS_EXPORTER = "otlp"
$env:OTEL_EXPORTER_OTLP_ENDPOINT = "http://localhost:4317"
$env:OTEL_METRIC_EXPORT_INTERVAL = "5000"

opentelemetry-instrument uvicorn main:app --port 8000

What the variables do:

Variable	What it does
OTEL_SERVICE_NAME	The name shown in Grafana. Skip it and your data shows up as unknown_service.
OTEL_TRACES_EXPORTER, OTEL_METRICS_EXPORTER, OTEL_LOGS_EXPORTER	Where each signal goes. otlp means send it over OTLP.
OTEL_EXPORTER_OTLP_ENDPOINT	Where the backend listens. This is the gRPC default, shown so you know where to change it.
OTEL_METRIC_EXPORT_INTERVAL	Milliseconds between metric exports. Set low here so metrics show up quickly (more on that below).

Your code contains no SDK setup, no exporter wiring, no FastAPI hooks and no log handler.

opentelemetry-instrument did all of that before your app started. It also creates the POST /orders span and some HTTP metrics for every request.

Skip --reload and --workers for now. The auto-reloader spawns child processes and can break instrumentation. And with uvicorn --workers, the official troubleshooting guide says you get traces and metrics but no logs. For several workers, it recommends Gunicorn with Uvicorn workers, which exports all three.

Step 5: Send some traffic

In a second terminal, create load.py:

import json
import random
import urllib.error
import urllib.request

URL = "http://localhost:8000/orders"

for _ in range(40):
    body = json.dumps({
        "item": random.choice(["keyboard", "mouse", "monitor"]),
        "quantity": random.randint(1, 3),
    }).encode()
    request = urllib.request.Request(URL, data=body, headers={"Content-Type": "application/json"})
    try:
        urllib.request.urlopen(request)
        print("paid")
    except urllib.error.HTTPError as error:
        print("declined" if error.code == 402 else f"error {error.code}")

Run it a couple of times:

python load.py

A stream of paid and declined scrolls past. Roughly one in four orders is declined.

Step 6: Explore it in Grafana

Open Grafana and use Explore from the left menu. Pick a data source at the top, one signal at a time. Menu names move around between Grafana versions, so don't worry if yours looks slightly different.

Traces (Tempo)

Choose the Tempo data source and search for service orders-api. Open any trace.

A waterfall appears: POST /orders at the top, process_order under it, charge_card under that. Each bar's length is how long that step took.

Now find a declined one. Its charge_card span is marked as an error, with the exception attached.

Metrics (Prometheus)

Choose Prometheus and try these queries:

sum by (outcome) (rate(orders_processed_total[1m]))

histogram_quantile(0.95, sum by (le) (rate(payment_duration_milliseconds_bucket[1m])))

The first shows paid versus declined orders per second. The second shows the 95th percentile payment time.

Prometheus's default OTLP translation adjusts metric names: dots become underscores, counters gain _total, and the unit becomes a suffix (ms turns into milliseconds). If autocomplete shows a slightly different name, your setup uses another translation setting, so use what it shows.

Logs (Loki)

Choose Loki and run:

{service_name="orders-api"}

Your "Processing order" and "Payment declined" lines show up. Click one to expand it, and look for its trace ID.

Follow one failure across all three

This is the payoff. Try it:

In Prometheus, spot the declined rate.
In Tempo, open a trace with a red charge_card span.
Jump from that span to its logs, and read exactly what happened.

The image's Grafana comes pre-wired so you can click from a trace to its logs, and from a log line back to its trace.

If a link is missing in your version, query Loki directly. With Loki's native OTLP ingestion, the service name is an index label and the trace ID is structured metadata. So you can filter on the ID you copied from Tempo:

{service_name="orders-api"} | trace_id="PASTE_THE_TRACE_ID_HERE"

That's one request, seen through all three signals.

Why your metrics showed up later than your traces

Each signal is batched and sent on its own timer:

Signal	Default delay between exports	Variable
Logs	1 second	OTEL_BLRP_SCHEDULE_DELAY
Traces	5 seconds	OTEL_BSP_SCHEDULE_DELAY
Metrics	60 seconds	OTEL_METRIC_EXPORT_INTERVAL

Without the 5-second setting we used, you'd wait up to a minute to see your first metric. It's a classic first-day surprise.

Do you need your own Collector?

In this setup, the Collector inside the Grafana image does the job. You'll want your own as you grow.

The OpenTelemetry docs give a few reasons. It gives many services one shared place to send data. It can gather traces across services running on different hosts. And it's a central spot to process data before it reaches a backend.

It also keeps backend details out of your apps, so you can switch backends without touching your code.

Their advice is that unless you have a single service or you're just experimenting, you'll want a Collector in production.

A handy debugging trick

When data isn't arriving, run a bare Collector that just prints what it receives. Save this as otel-collector-config.yaml:

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318
exporters:
  debug:
    verbosity: detailed
service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [debug]
    metrics:
      receivers: [otlp]
      exporters: [debug]
    logs:
      receivers: [otlp]
      exporters: [debug]

Stop the Grafana container first, since both want the same ports. Then run:

docker run -p 4317:4317 -p 4318:4318 \
  -v $(pwd)/otel-collector-config.yaml:/etc/otel-collector-config.yaml \
  otel/opentelemetry-collector:latest \
  --config=/etc/otel-collector-config.yaml

On Windows, use the full path to the file instead of $(pwd).

Restart your app and send traffic. Every span, metric and log shows up in the Collector's output. If you see them there, your app is fine and the problem is further downstream.

Common first-day problems

Most of these are explained above, so this is just an index:

Symptom	Where to look
No data anywhere, and no errors	The app wasn't started through opentelemetry-instrument, or the endpoint is wrong. Run the debug Collector above to check.
Metrics are missing at first	The export delay table above
INFO logs are missing	The logging gotcha in Step 3
Logs vanish with --workers, or everything vanishes with --reload	The callout in Step 4
Everything disappeared	The note in Step 1 about where the image keeps its data

From demo to production

The demo is deliberately simple. A real setup adds a few things:

A real backend. Pick a managed service or a properly run self-hosted stack in place of the demo image.
Sampling. You usually don't keep every trace. Setting OTEL_TRACES_SAMPLER=parentbased_traceidratio and OTEL_TRACES_SAMPLER_ARG=0.1 keeps about 10%.
Care with sensitive data. Don't put passwords, tokens or personal data into attributes or log messages. The OpenTelemetry docs have a page on handling sensitive data.
Consistent names. OpenTelemetry has semantic conventions, a shared vocabulary for attribute names like http.route. Following them keeps your data readable across tools.

And when one service calls another over HTTP, the instrumentation passes the trace context along in headers. Both services then show up in one trace. That's context propagation, and it's the feature that makes tracing really shine across a system.

Where to go next

The OpenTelemetry Demo. A multi-service shop with telemetry already wired in. It's the best place to see tracing across services.
Manual instrumentation for Python. More on spans, events, links and metric instruments.
Collector processors. Filter, transform and sample data before it leaves.
More libraries. Add httpx, SQLAlchemy or a database driver, then rerun opentelemetry-bootstrap -a install. It picks up new libraries on its own.

Recap

OpenTelemetry produces telemetry. A backend stores and shows it.
Traces show one request's journey, metrics show trends, logs tell the story. Their power comes from being linked.
opentelemetry-instrument gives you request spans and log shipping for free. You add spans and metrics for your own business logic.
Set OTEL_SERVICE_NAME, and shorten the metric interval while you're learning.
Keep metric attributes low-cardinality. Put the detail on spans.
The otel-lgtm image is a great sandbox, not a production backend.

Instrument, export, then follow one request across all three signals. Everything else builds on that.

Details checked against the OpenTelemetry documentation and the grafana/docker-otel-lgtm project on October 25, 2026. Tooling moves quickly, so if a command or menu behaves differently on your version, the official docs win.

Sources

Published via ZyVOP — Write once in Markdown, auto-backup to GitHub, and syndicate to Dev.to, Medium & Hashnode in 1 click.

Passkey Account Recovery: Designing for Lost Devices

DevStories — Tue, 20 Oct 2026 11:39:16 +0000

Passkeys make signing in safer, but they move the hard problem to the day a user loses their phone. Sign-in is the easy half. Recovery decides whether your system is actually secure, because an attacker does not need to beat your passkeys if they can talk their way through the recovery flow instead.

This guide designs and builds that recovery path for the Express app from the passkeys guide. It follows NIST SP 800-63B-4, the current US standard for authenticators and account recovery, and says plainly where we go beyond it or fall short of it. By the end you will have:

A readiness check that finds at-risk accounts and tells your UI what to nudge
Passkey management endpoints with re-authentication and a last-passkey guard
Single-use recovery codes, stored as salted hashes and replaced after use
A recovery flow that needs an emailed link plus a recovery code, with a delayed fallback for users who saved nothing
Full cleanup after recovery: old passkeys revoked, other sessions signed out, and the owner notified

This guide assumes the code from the passkeys guide (config.js, store.js, and server.js with startCeremony, takeCeremony, and logIn). It also assumes your signup already collects and verifies an email address. An unverified address is a hole in recovery, so add that first if you do not have it.

How people actually lose access

What happens when a device disappears depends on what kind of passkey the user had:

Situation	Synced passkey	Device-bound passkey
One of several devices is lost	Still works on the others	Works if a second passkey is registered
The only device is lost	Can be restored on a new device through the platform or password manager account	Locked out
The platform account itself is lost	Locked out	Not affected
The device is stolen	The thief still needs the biometric or PIN	Same

The user's ecosystem matters too. A passkey saved in one platform's keychain does not automatically follow them to a phone from another ecosystem, which is why a cross-platform password manager or a second passkey keeps coming up as the answer.

You cannot see which situation a user is in, but at registration you stored two clues. deviceType is multiDevice when the authenticator says the passkey can be backed up and synced, and singleDevice when it cannot. backedUp says whether it currently is. Those two fields are enough to decide who most urgently needs a nudge.

The design: prevent, recover, escalate

Think in three layers, from cheapest and safest to most expensive and riskiest.

Prevent lockouts. Get users to register a second passkey, save recovery codes, and confirm an email address while they still have a working device. NIST tells services to encourage at least two separate means of authentication so that recovery is rarely needed.
Recover by themselves. Recovery needs two independent proofs, never one. For an account that can sign in at NIST's AAL2 level (a passkey with a biometric or PIN qualifies), NIST accepts two recovery codes obtained by different methods, one recovery code plus a single-factor authenticator already bound to the account, or repeated identity proofing. We use an emailed link plus a saved recovery code, which is two different methods.
Escalate. Users with neither a second passkey nor a code need a slower path. We build a delayed email fallback, and note where high-value accounts should add identity verification instead.

Each recovery method has a different failure mode, so it helps to see them side by side:

Method	Best for	Weak spot
Second passkey	Everyone; instant, no email involved	Users have to set it up before they need it
Recovery codes	Users who save them somewhere safe	Never saved, lost, or left in a screenshot
Emailed link plus a recovery code	Strong self-service recovery	Needs both pieces
Email only, after a delay	Users who saved nothing	Only as strong as the mailbox, and an attacker can wait
Support or identity verification	High-value accounts	Slow, costly, and a favourite target for social engineering

Skip security questions and SMS codes as your only fallback. NIST treats SMS and voice delivery as a restricted method, and its password rules prohibit security questions, because both are easy to social-engineer.

These rules run through every piece of code below:

Recovery is an account-takeover path. An account is only as strong as its easiest way back in.
Always notify. Every recovery, every new passkey, and every new set of recovery codes sends an email to the existing address, with a way to say it was not them. NIST requires notification for recovery and for newly bound authenticators.
Treat a lost authenticator as stolen. After recovery we revoke every old passkey and sign out every old session, as NIST advises for compromised authenticators.
Recovery codes are credentials. At least 64 random bits, stored only as salted hashes, throttled, single use, and replaced after use.
Emailed links are single use and short lived. NIST allows at most 24 hours for email. We use 30 minutes on the fast path.
Never reveal whether an account exists. Every recovery request gets the same answer.

NIST is a US federal guideline, not a law that binds your app. Use it as a well-reasoned checklist, and write down any place you choose to depart from it.

Data model changes

Users need a verified email and a sessionVersion counter. Bumping the counter signs out every existing session at once, which we need after a recovery. Passkeys get a friendly name so users can tell their devices apart. Recovery codes and recovery requests get their own tables.

ALTER TABLE users
  ADD COLUMN email           TEXT UNIQUE,            -- store lowercase
  ADD COLUMN email_verified  BOOLEAN NOT NULL DEFAULT false,
  ADD COLUMN session_version INTEGER NOT NULL DEFAULT 0;

ALTER TABLE passkeys ADD COLUMN name TEXT NOT NULL DEFAULT 'Passkey';

CREATE TABLE recovery_codes (
  id      BIGSERIAL PRIMARY KEY,
  user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
  salt    BYTEA NOT NULL,
  hash    BYTEA NOT NULL,
  used_at TIMESTAMPTZ
);

CREATE TABLE recovery_requests (
  id         TEXT PRIMARY KEY,   -- random UUID, also the cancel handle
  user_id    TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
  method     TEXT NOT NULL,      -- 'email+code' or 'email+delay'
  status     TEXT NOT NULL,      -- pending, released, used, cancelled
  token_hash TEXT UNIQUE,        -- SHA-256 of the emailed token
  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
  release_at TIMESTAMPTZ NOT NULL,
  expires_at TIMESTAMPTZ
);

For the in-memory demo store, add the following to store.js and replace createUser so new accounts get the new fields:

// store.js - replace createUser, then add the rest
export function createUser(user) {
  if (usersByName.has(user.username)) return false;
  const record = { email: null, emailVerified: false, sessionVersion: 0, ...user };
  usersByName.set(record.username, record);
  usersById.set(record.id, record);
  return true;
}

export function updateUser(id, changes) {
  const user = usersById.get(id);
  if (user) Object.assign(user, changes);
  return user;
}

export const deletePasskey = (id) => passkeys.delete(id);

const recoveryCodes = new Map(); // userId -> [{ salt, hash, usedAt }]
export const listRecoveryCodes = (userId) => recoveryCodes.get(userId) ?? [];
export const replaceRecoveryCodes = (userId, records) => recoveryCodes.set(userId, records);

// Check and set in one synchronous step, so a code can never be spent twice.
export function consumeRecoveryCode(userId, index) {
  const record = recoveryCodes.get(userId)?.[index];
  if (!record || record.usedAt) return false;
  record.usedAt = Date.now();
  return true;
}

const recoveryRequests = new Map(); // id -> request
export const saveRecoveryRequest = (request) => recoveryRequests.set(request.id, request);
export const findRecoveryRequest = (id) => recoveryRequests.get(id);
export const listRecoveryRequests = () => [...recoveryRequests.values()];
export const findRecoveryRequestByTokenHash = (hash) =>
  [...recoveryRequests.values()].find((r) => r.tokenHash === hash);

Add these values to the config object in config.js:

recoveryLinkTtlMs: 30 * 60 * 1000, // emailed link on the fast path
  recoveryDelayedLinkTtlMs: 24 * 60 * 60 * 1000, // NIST's maximum for email
  recoveryDelayMs: Number(process.env.RECOVERY_DELAY_MS ?? 24 * 60 * 60 * 1000),
  recoverySessionTtlMs: 15 * 60 * 1000,
  reauthMaxAgeMs: 5 * 60 * 1000,

recoveryDelayMs is the waiting period for users who have no recovery code. Set it low while testing, for example RECOVERY_DELAY_MS=60000.

Session helpers

Replace logIn in server.js and add the helpers below. logIn keeps its signature, so the existing calls in the registration and login handlers keep working. It now also records the user's sessionVersion and the time of the passkey check.

function logIn(req, userId) {
  const user = store.findUserById(userId);
  return new Promise((resolve, reject) => {
    req.session.regenerate((err) => {
      if (err) return reject(err);
      req.session.userId = user.id;
      req.session.sessionVersion = user.sessionVersion; // lets us sign out every session at once
      req.session.authenticatedAt = Date.now(); // for step-up checks
      req.session.save((err2) => (err2 ? reject(err2) : resolve()));
    });
  });
}

// The signed-in user, unless their session predates a recovery or sign-out-everywhere.
function currentUser(req) {
  const user = req.session.userId ? store.findUserById(req.session.userId) : null;
  return user && req.session.sessionVersion === user.sessionVersion ? user : null;
}

// A limited session created by a verified recovery link. It can only add a passkey.
function recoveryUser(req) {
  const recovery = req.session.recovery;
  if (!recovery || recovery.expiresAt < Date.now()) return null;
  return store.findUserById(recovery.userId) ?? null;
}

function requireAuth(req, res, next) {
  req.user = currentUser(req);
  if (!req.user) return res.status(401).json({ error: 'Not signed in.' });
  next();
}

// Sensitive actions need a passkey check from the last few minutes.
function requireRecentAuth(req, res, next) {
  if (Date.now() - (req.session.authenticatedAt ?? 0) > config.reauthMaxAgeMs) {
    return res
      .status(403)
      .json({ error: 'Please confirm with your passkey.', code: 'reauth_required' });
  }
  next();
}

The recovery session is deliberately weak. It is not a login: currentUser ignores it, and the only thing the server lets it do is start one passkey registration.

Email helper

Create mail.js. This demo version prints emails to the console so you can follow the whole flow without a mail provider. Replace sendMail with your real provider before shipping.

// mail.js
export async function sendMail(to, subject, text) {
  console.log(`\n--- email to ${to} ---\n${subject}\n\n${text}\n`);
}

// Tell the account owner about a security event, if they have an email on file.
export async function notify(user, subject, text) {
  if (user?.email) await sendMail(user.email, subject, text);
}

Add import { sendMail, notify } from './mail.js'; to the top of server.js.

Prevent lockouts: the readiness check

The readiness check turns the stored deviceType and backedUp fields into a nudge. A user with one synced passkey can survive losing a device, so the prompt is gentle. A user with a single device-bound passkey is one accident away from a lockout, so it is urgent.

function recoveryReadiness(user) {
  const passkeys = store.listPasskeys(user.id);
  const syncedPasskey = passkeys.some((p) => p.deviceType === 'multiDevice' && p.backedUp);
  const unusedCodes = store.listRecoveryCodes(user.id).filter((c) => !c.usedAt).length;

  const issues = [];
  if (passkeys.length < 2) {
    issues.push({ code: 'add_second_passkey', urgent: !syncedPasskey });
  }
  if (unusedCodes === 0) issues.push({ code: 'create_recovery_codes', urgent: true });
  if (!user.emailVerified) issues.push({ code: 'verify_email', urgent: true });

  return { status: issues.length === 0 ? 'ready' : 'at_risk', unusedCodes, issues };
}

app.get('/api/me', requireAuth, (req, res) => {
  const passkeys = store.listPasskeys(req.user.id).map((p) => ({
    id: p.id,
    name: p.name ?? 'Passkey',
    deviceType: p.deviceType,
    backedUp: p.backedUp,
    createdAt: p.createdAt,
    lastUsedAt: p.lastUsedAt,
  }));

  res.json({
    username: req.user.username,
    rpID: config.rpID,
    webauthnUserID: Buffer.from(req.user.id, 'utf8').toString('base64url'),
    passkeys,
    readiness: recoveryReadiness(req.user),
  });
});

This replaces the /api/me handler from the passkeys guide. Besides the readiness result it returns two values the browser needs later for the Signal API: the rpID and the WebAuthn user handle (the user's ID, base64url-encoded exactly as it was when we registered the passkey). Your frontend can map each issue code to a message and a button. Show the urgent ones right after sign-in, while the user still has a working device.

Manage passkeys safely

Users need to see their passkeys, name them, and remove old ones. Removal is the dangerous part, so it gets two guards: a passkey check from the last five minutes, and a refusal to delete the last passkey.

const cleanName = (value) => String(value ?? '').trim().slice(0, 40);

app.patch('/api/passkeys/:id', requireAuth, (req, res) => {
  const passkey = store.findPasskey(req.params.id);
  const name = cleanName(req.body?.name);
  if (!passkey || passkey.userId !== req.user.id) {
    return res.status(404).json({ error: 'Passkey not found.' });
  }
  if (!name) return res.status(400).json({ error: 'Give the passkey a name.' });

  store.updatePasskey(passkey.id, { name });
  res.json({ ok: true });
});

app.delete('/api/passkeys/:id', requireAuth, requireRecentAuth, async (req, res) => {
  const passkey = store.findPasskey(req.params.id);
  if (!passkey || passkey.userId !== req.user.id) {
    return res.status(404).json({ error: 'Passkey not found.' });
  }
  if (store.listPasskeys(req.user.id).length <= 1) {
    return res.status(409).json({ error: 'Add another passkey before removing your last one.' });
  }

  store.deletePasskey(passkey.id);
  await notify(
    req.user,
    'A passkey was removed from your account',
    `The passkey named ${passkey.name ?? 'Passkey'} was removed. If this was not you, secure your account now.`
  );
  res.json({ ok: true });
});

Both handlers check passkey.userId !== req.user.id and answer with the same not-found error, so one user can never probe or modify another user's credentials by guessing IDs. The step-up check matters because a hijacked session should not be able to quietly strip the real owner's passkeys. When the server answers with reauth_required, the frontend runs the normal passkey sign-in and retries; the frontend section shows how.

Recovery codes

Recovery codes are the second proof on the fast path. Each code carries 80 bits of randomness (16 symbols from a 32-symbol alphabet that drops look-alikes such as 0, O, 1, and I), comfortably above NIST's 64-bit minimum. We store only a salted scrypt hash of each code, so a database leak does not expose usable codes, and we show the plaintext to the user exactly once.

// recoveryCodes.js
import crypto from 'node:crypto';
import { promisify } from 'node:util';
import * as store from './store.js';

const scrypt = promisify(crypto.scrypt);
const ALPHABET = '23456789ABCDEFGHJKLMNPQRSTUVWXYZ'; // 32 symbols, no 0/O/1/I

const normalize = (input) => String(input).toUpperCase().replace(/[^A-Z0-9]/g, '');

function generateCode() {
  // 16 symbols x 5 bits = 80 bits. 256 is a multiple of 32, so b & 31 has no bias.
  const raw = [...crypto.randomBytes(16)].map((b) => ALPHABET[b & 31]).join('');
  return raw.match(/.{4}/g).join('-');
}

async function hashCode(code) {
  const salt = crypto.randomBytes(16);
  const hash = await scrypt(normalize(code), salt, 32);
  return { salt, hash, usedAt: null };
}

async function matches(code, record) {
  const hash = await scrypt(normalize(code), record.salt, 32);
  return crypto.timingSafeEqual(hash, record.hash);
}

// Replaces the user's whole set. Returns the plaintext codes: show them once, never store them.
export async function issueRecoveryCodes(userId, count = 10) {
  const codes = Array.from({ length: count }, generateCode);
  store.replaceRecoveryCodes(userId, await Promise.all(codes.map(hashCode)));
  return codes;
}

// Returns true if the code was valid and has now been spent.
export async function spendRecoveryCode(userId, input) {
  if (normalize(input).length !== 16) return false; // skip the slow hash for junk

  const records = store.listRecoveryCodes(userId);
  for (let i = 0; i < records.length; i++) {
    if (records[i].usedAt) continue;
    if (await matches(input, records[i])) return store.consumeRecoveryCode(userId, i);
  }
  return false;
}

Two details matter. spendRecoveryCode runs scrypt against each unused code, which is deliberately slow, so rate-limit every endpoint that calls it. And the final consumeRecoveryCode call happens synchronously after the check, so two simultaneous requests cannot spend the same code twice.

Next, an endpoint that lets a signed-in user create a set. A new set replaces the old one entirely, and NIST treats issuing a replacement code as a recovery event, so it triggers a notification.

app.post('/api/recovery-codes', requireAuth, requireRecentAuth, async (req, res) => {
  const codes = await issueRecoveryCodes(req.user.id);
  await notify(
    req.user,
    'New recovery codes were created',
    'A new set of recovery codes was created. Older codes no longer work. If this was not you, secure your account now.'
  );
  res.json({ codes }); // the only time the plaintext is ever shown
});

Add import { issueRecoveryCodes, spendRecoveryCode } from './recoveryCodes.js'; to the top of server.js. Tell users to keep the codes in a password manager or print them. Never email them, and keep them out of logs and error reports.

Let a recovery session add a passkey

In the passkeys guide, POST /api/register/options decided who it was serving from the session. Recovery adds a third case: a signed-out visitor holding a verified recovery session. Three changes are needed in the registration routes.

In POST /api/register/options, replace the first two lines of the handler, the excludeCredentials option, and the startCeremony call:

// 1. Replace the lines that set `user` and `isNew`:
  const signedIn = currentUser(req);
  const recovering = signedIn ? null : recoveryUser(req);
  let user = signedIn ?? recovering;
  let isNew = false;

// 2. Replace the excludeCredentials option:
    // During recovery every old passkey is about to be revoked, so exclude nothing.
    excludeCredentials: recovering
      ? []
      : store.listPasskeys(user.id).map((p) => ({ id: p.id, transports: p.transports })),

// 3. Replace the startCeremony call:
  startCeremony(req, {
    type: 'registration',
    challenge: options.challenge,
    user,
    isNew,
    recovering: Boolean(recovering),
  });

In POST /api/register/verify, check that the recovery session is still alive right after the ceremony is taken, and replace the last two lines (logIn and res.json):

// Right after: const ceremony = takeCeremony(req, 'registration'); and its null check
  if (ceremony.recovering && !recoveryUser(req)) {
    return res.status(403).json({ error: 'Your recovery session expired. Please start again.' });
  }

// Replace the final logIn and res.json lines with:
  let recoveryCodes = null;
  if (ceremony.recovering) {
    recoveryCodes = await completeRecovery(ceremony.user, credential.id);
  } else if (!ceremony.isNew) {
    await notify(
      store.findUserById(ceremony.user.id),
      'A passkey was added to your account',
      'A new passkey was added. If this was not you, remove it and secure your account now.'
    );
  }

  await logIn(req, ceremony.user.id);
  res.json({ verified: true, recoveryCodes });

The recovering flag lives in the server-side ceremony, set only when the options request arrived under a real recovery session, so a client cannot claim it. The final logIn regenerates the session, which also discards the recovery session. Adding a passkey to an existing account now sends a notification, which NIST requires for any newly bound authenticator.

Recovery, step 1: request a link

There are two entry points behind one endpoint. A user with a recovery code sends their username and a code, and gets a link right away. A user without a code sends only a username, and the link is held back for a waiting period while the real owner is warned.

import crypto from 'node:crypto'; // already imported in server.js

const sha256 = (value) => crypto.createHash('sha256').update(value).digest('hex');
const humanize = (ms) =>
  ms >= 3600000 ? `${Math.round(ms / 3600000)} hours` : `${Math.round(ms / 60000)} minutes`;

async function releaseRecoveryLink(request, ttlMs) {
  const user = store.findUserById(request.userId);
  const token = crypto.randomBytes(32).toString('base64url');

  request.tokenHash = sha256(token); // only the hash is stored
  request.expiresAt = Date.now() + ttlMs;
  request.status = 'released';

  // The token travels in the URL fragment, so it never reaches server logs or Referer headers.
  await sendMail(
    user.email,
    'Finish recovering your account',
    `Open this link to add a new passkey. It works once and expires in ${humanize(ttlMs)}:\n\n` +
      `${config.origin}/recover.html#token=${token}\n\n` +
      'If you did not ask for this, you can ignore this email.'
  );
}

async function processRecoveryStart(username, code) {
  const user = username ? store.findUserByUsername(username) : null;
  if (!user || !user.emailVerified) return;

  // A wrong code stops here. The caller already received the same generic answer.
  if (code && !(await spendRecoveryCode(user.id, code))) return;

  const now = Date.now();
  const active = store
    .listRecoveryRequests()
    .filter(
      (r) =>
        r.userId === user.id &&
        (r.status === 'pending' || (r.status === 'released' && r.expiresAt > now))
    );

  // Repeat requests must not reset a waiting timer. A code-backed request replaces any waiting one.
  if (!code && active.length > 0) return;
  for (const r of active) r.status = 'cancelled';

  const request = {
    id: crypto.randomUUID(),
    userId: user.id,
    method: code ? 'email+code' : 'email+delay',
    status: 'pending',
    createdAt: now,
    releaseAt: code ? now : now + config.recoveryDelayMs,
    tokenHash: null,
    expiresAt: null,
  };
  store.saveRecoveryRequest(request);

  if (code) {
    await releaseRecoveryLink(request, config.recoveryLinkTtlMs);
    await notify(
      user,
      'Account recovery started',
      'A recovery code was used to start recovering your account. If this was not you, secure your account now and contact support.'
    );
  } else {
    await sendMail(
      user.email,
      'Account recovery requested',
      `Someone asked to recover your account without a recovery code. If it was you, do nothing: we will email a link in about ${humanize(config.recoveryDelayMs)}.\n\n` +
        `If it was not you, cancel the request here:\n${config.origin}/recover.html#cancel=${request.id}`
    );
  }
}

app.post('/api/recovery/start', (req, res) => {
  const username = normalizeUsername(req.body?.username);
  const code = typeof req.body?.code === 'string' && req.body.code.trim() ? req.body.code : null;

  // Answer first and work afterwards, so neither the response nor its timing
  // reveals whether the account exists or the code was right.
  res.status(202).json({ ok: true });
  processRecoveryStart(username, code).catch((err) => console.error('Recovery start failed:', err));
});

Three behaviours are worth calling out:

The answer never changes. Unknown username, unverified email, wrong code, and success all return the same 202, so the form cannot be used to find out who has an account.
A wrong code ends quietly. It does not silently drop the user into the slow path, and it sends no email.
A waiting request cannot be reset. Without this rule, an attacker could keep a victim's timer from ever finishing, or restart it forever.

The waiting path needs something to release links when the delay ends, plus an endpoint for the real owner to cancel. In production use a proper scheduler or job queue. A timer is enough for the demo:

// Release links whose waiting period is over.
setInterval(async () => {
  for (const request of store.listRecoveryRequests()) {
    if (request.status !== 'pending' || request.releaseAt > Date.now()) continue;
    try {
      await releaseRecoveryLink(request, config.recoveryDelayedLinkTtlMs);
    } catch (err) {
      console.error('Could not release a recovery link:', err);
    }
  }
}, 60 * 1000).unref();

app.post('/api/recovery/cancel', (req, res) => {
  // The request ID is a random UUID that was only ever emailed to the account owner.
  const request = store.findRecoveryRequest(req.body?.id);
  if (request && (request.status === 'pending' || request.status === 'released')) {
    request.status = 'cancelled';
  }
  res.json({ ok: true }); // same answer whether or not anything was cancelled
});

The cancel link is the reason the delay is worth having. It gives the real owner a window to shut down an attacker's request, but only if they read the email, so also notify any second address you hold. Be clear about the trade-off: this path relies on a single recovery method, so it falls short of NIST's AAL2 rule of two. Offer it only where that risk is acceptable, and remove it for high-value accounts.

Recovery, step 2: verify the link

app.post('/api/recovery/verify', async (req, res) => {
  const token = req.body?.token;
  const request =
    typeof token === 'string' ? store.findRecoveryRequestByTokenHash(sha256(token)) : null;

  if (!request || request.status !== 'released' || request.expiresAt < Date.now()) {
    return res.status(400).json({ error: 'This recovery link is invalid or has expired.' });
  }
  request.status = 'used'; // single use: flipped before any await

  await new Promise((resolve, reject) => {
    req.session.regenerate((err) => {
      if (err) return reject(err);
      req.session.recovery = {
        userId: request.userId,
        expiresAt: Date.now() + config.recoverySessionTtlMs,
      };
      req.session.save((err2) => (err2 ? reject(err2) : resolve()));
    });
  });
  res.json({ ok: true });
});

The result is the limited recovery session from earlier, not a login. The recovery page reads the token from the URL fragment and only sends it after the user clicks Continue. That keeps it out of logs, and it means mail scanners that open links cannot use it up.

Recovery, step 3: add a new passkey and clean up

The user now registers a passkey through the routes we modified. When that registration verifies, completeRecovery does the part most tutorials forget:

async function completeRecovery(userRef, newPasskeyId) {
  const user = store.findUserById(userRef.id);

  // 1. A lost authenticator is assumed stolen: revoke every other passkey.
  for (const passkey of store.listPasskeys(user.id)) {
    if (passkey.id !== newPasskeyId) store.deletePasskey(passkey.id);
  }

  // 2. Sign out every earlier session (logIn re-reads this value).
  store.updateUser(user.id, { sessionVersion: user.sessionVersion + 1 });

  // 3. Close any other open recovery request, such as an attacker's waiting one.
  for (const r of store.listRecoveryRequests()) {
    if (r.userId === user.id && (r.status === 'pending' || r.status === 'released')) {
      r.status = 'cancelled';
    }
  }

  // 4. Replace the recovery codes: the old set may be on the lost device or in the wrong hands.
  const codes = await issueRecoveryCodes(user.id);

  // 5. Tell the owner.
  await notify(
    user,
    'Your account was recovered',
    'A new passkey was added and all earlier passkeys and sessions were removed. If this was not you, contact support immediately.'
  );

  return codes;
}

Each step answers a specific attack:

Revoking old passkeys means a thief holding the lost phone cannot sign in after the owner has recovered.
Bumping sessionVersion kills sessions the thief may already have open. Without it, recovery would add a new door and leave the old one unlocked.
Closing other requests stops an attacker's waiting request from firing after the real owner has already recovered.
New codes are returned to the page once, which is why the registration response carries recoveryCodes.
The notification is the owner's alarm if someone else ran the whole flow.

Keep the user's devices honest with the Signal API

Revoking a passkey on your server does not remove it from the user's password manager. The next time they tap the stale passkey, sign-in fails with a confusing error. The WebAuthn Signal API lets your site tell credential managers which passkeys are still valid, so they can hide the rest.

It is best effort. As of mid-2026, Chrome and Edge 132 or newer, recent Chrome on Android, and Safari 26 support it. Firefox does not, and a credential manager is free to ignore the signal. Treat it as polish on top of the server-side revocation above, never as a replacement for it.

We send two signals. After sign-in and after any passkey change, allAcceptedCredentials lists every passkey the server still accepts. After a failed sign-in with an unknown passkey, unknownCredential names the stale one. The second needs one small server change in POST /api/login/verify, right after the findPasskey line:

if (!passkey) {
    // Lets the browser ask the user's credential manager to hide this stale passkey.
    return res
      .status(400)
      .json({ error: 'Passkey not recognised.', unknownCredential: response?.id });
  }

On the client, add sendSignal to the existing import from @simplewebauthn/browser, then add the reconcile helper and update login():

// Call this from refresh() after it loads /api/me
async function reconcilePasskeys(me) {
  try {
    await sendSignal({
      signalName: 'allAcceptedCredentials',
      rpID: me.rpID,
      userID: me.webauthnUserID,
      allAcceptedCredentialIDs: me.passkeys.map((p) => p.id),
    });
  } catch {
    // Unsupported browser, or the signal was ignored. Nothing to do.
  }
}

async function login({ autofill = false } = {}) {
  const optionsJSON = await api('/api/login/options');
  const response = await startAuthentication({ optionsJSON, useBrowserAutofill: autofill });
  try {
    await api('/api/login/verify', { response });
  } catch (err) {
    if (typeof err.data?.unknownCredential === 'string') {
      sendSignal({
        signalName: 'unknownCredential',
        rpID: optionsJSON.rpId,
        credentialID: err.data.unknownCredential,
      }).catch(() => {});
    }
    throw err;
  }
}

The userID must be exactly the value that was sent as the user handle when the passkey was created. That is why /api/me returns webauthnUserID encoded the same way as our registration options.

Frontend changes

The recovery page

Create public/recover.html. It has five states, and the script shows one at a time depending on whether the URL carries a recovery token, a cancel handle, or neither.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Recover your account</title>
  </head>
  <body>
    <main>
      <h1>Recover your account</h1>

      <section id="start">
        <label for="username">Username</label>
        <input id="username" autocomplete="username" />
        <label for="code">Recovery code (optional, skips the waiting period)</label>
        <input id="code" autocomplete="off" spellcheck="false" />
        <button id="send">Send recovery email</button>
      </section>

      <section id="confirm" hidden>
        <p>Continue to add a new passkey to your account.</p>
        <button id="continue">Continue</button>
      </section>

      <section id="finish" hidden>
        <p>Link verified. Create a new passkey on this device to finish.</p>
        <button id="create">Create new passkey</button>
      </section>

      <section id="done" hidden>
        <p>
          Your account is recovered and your old passkeys were removed. Save these new recovery
          codes now. They are shown only once.
        </p>
        <pre id="codes"></pre>
      </section>

      <section id="cancel" hidden>
        <p>Cancel the recovery request for your account?</p>
        <button id="cancel-btn">Yes, cancel it</button>
      </section>

      <p id="status" role="status"></p>
    </main>
    <script type="module" src="/recover.js"></script>
  </body>
</html>

Then public/recover.js:

import { startRegistration } from 'https://cdn.jsdelivr.net/npm/@simplewebauthn/browser@14/+esm';

const $ = (id) => document.getElementById(id);
const SECTIONS = ['start', 'confirm', 'finish', 'done', 'cancel'];
const show = (name) => SECTIONS.forEach((id) => ($(id).hidden = id !== name));

function setStatus(message, isError = false) {
  $('status').textContent = message;
  $('status').style.color = isError ? 'crimson' : 'inherit';
}

async function post(path, body = {}) {
  const res = await fetch(path, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(body),
  });
  const data = await res.json().catch(() => ({}));
  if (!res.ok) throw new Error(data.error ?? 'Request failed.');
  return data;
}

async function run(action) {
  try {
    setStatus('');
    await action();
  } catch (err) {
    setStatus(err.message, true);
  }
}

// Read the secret from the URL fragment, then remove it from the address bar and history.
const params = new URLSearchParams(location.hash.slice(1));
history.replaceState(null, '', location.pathname);

$('send').onclick = () =>
  run(async () => {
    await post('/api/recovery/start', { username: $('username').value, code: $('code').value });
    setStatus('If that account can be recovered, an email is on its way.');
  });

$('continue').onclick = () =>
  run(async () => {
    await post('/api/recovery/verify', { token: params.get('token') });
    show('finish');
  });

$('create').onclick = () =>
  run(async () => {
    const optionsJSON = await post('/api/register/options');
    const response = await startRegistration({ optionsJSON });
    const { recoveryCodes } = await post('/api/register/verify', { response });
    $('codes').textContent = recoveryCodes.join('\n');
    show('done');
  });

$('cancel-btn').onclick = () =>
  run(async () => {
    await post('/api/recovery/cancel', { id: params.get('cancel') });
    setStatus('Recovery cancelled. Sign in and review your passkeys.');
  });

show(params.has('token') ? 'confirm' : params.has('cancel') ? 'cancel' : 'start');

Both the token and the cancel handle wait for a button click before anything is sent. A mail scanner that opens the link, even one that runs JavaScript, cannot consume a token or cancel a request on its own.

Changes to the main app

In public/app.js, extend api() so callers can read the server's error code and payload, and add a helper that retries an action once after a fresh passkey check:

async function api(path, body = {}, method = 'POST') {
  const res = await fetch(path, {
    method,
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(body),
  });
  const data = await res.json().catch(() => ({}));
  if (!res.ok) {
    const err = new Error(data.error ?? 'Request failed.');
    err.code = data.code;
    err.data = data;
    throw err;
  }
  return data;
}

// Retry once after a fresh passkey check when the server asks for one.
async function withReauth(action) {
  try {
    return await action();
  } catch (err) {
    if (err.code !== 'reauth_required') throw err;
    await login();
    return action();
  }
}

const NUDGES = {
  add_second_passkey: 'Add a second passkey so losing one device cannot lock you out.',
  create_recovery_codes: 'Create recovery codes and keep them somewhere safe.',
  verify_email: 'Verify your email address so you can recover your account.',
};

// Needs an empty <ul id="nudges"></ul> in the signed-in section of index.html
function renderReadiness(readiness) {
  $('nudges').replaceChildren(
    ...readiness.issues.map(({ code, urgent }) => {
      const li = document.createElement('li');
      li.textContent = (urgent ? 'Important: ' : '') + NUDGES[code];
      return li;
    })
  );
}

Call renderReadiness(me.readiness) and reconcilePasskeys(me) from refresh() once /api/me has loaded. Then wire the buttons you need. Removing a passkey is withReauth(() => api('/api/passkeys/' + id, {}, 'DELETE')), renaming is api('/api/passkeys/' + id, { name }, 'PATCH'), and creating recovery codes is withReauth(() => api('/api/recovery-codes')). Show the returned codes once, with copy and download buttons, and tell the user plainly what they are for.

Test the lost-device scenarios

The demo has no email-verification step. For testing only, change the defaults in createUser so every account gets a verified address, and emails print to the server console:

// store.js, demo only
const record = {
  email: `${user.username}@example.test`,
  emailVerified: true,
  sessionVersion: 0,
  ...user,
};

The fast path (recovery code plus emailed link):

In Chrome DevTools, open More tools > WebAuthn, enable a virtual authenticator, and create an account on http://localhost:3000.
You just signed in, so the step-up check passes. In the page console, create recovery codes and copy one: await (await fetch('/api/recovery-codes', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: '{}' })).json()
Simulate losing the device: remove that virtual authenticator, then open a private window and add a new one.
Open /recover.html, enter the username and the code, and send. The server console prints the email with the link. Open it, click Continue, then Create new passkey.
Check the results. The page shows ten new codes. The original window's next request returns 401, because its session predates the recovery. The old code no longer works. The console shows the notification emails.

The waiting path: restart the server with RECOVERY_DELAY_MS=60000. Request recovery with a username and no code. The console prints a cancel link. Cancel once and confirm that no recovery link ever arrives. Request again and wait one to two minutes: the recovery link prints.

Things that must fail:

Opening a recovery link a second time, or after it expires
Spending the same recovery code twice
A wrong code, or an unknown username: both return the same response and print nothing
Deleting your only passkey: refused
Deleting a passkey more than five minutes after signing in: you are asked to confirm with your passkey first

Before you ship

Use a real mail provider with SPF, DKIM, and DMARC set up, and let users add a second notification address. A notification nobody reads protects nobody.
Rate-limit the recovery endpoints per IP and per account, and cap failed code attempts per account well below NIST's upper bound of 100. A starting point with express-rate-limit is below.
Keep tokens and codes out of logs, analytics, and error reports. Treat them as credentials.
Store recovery requests in your database and release links from a real scheduler or queue, not a timer in the web process. Make the release step safe to run twice.
Write an audit trail for every security event, and give support staff the same state machine as users. A support button that skips the flow is the easiest account takeover you can build.
Treat email changes as recovery events. Require a fresh passkey check, notify the old address, and consider a waiting period, because whoever controls the address controls the delayed path.
Raise the bar for high-value accounts. Remove the email-only path and require identity verification or hardware security keys. Note that NIST does not allow synced passkeys at its highest assurance level, AAL3.
Test the whole loss matrix: one device lost, all devices lost, platform account lost, ecosystem switch, and email lost too.

import rateLimit from 'express-rate-limit';

const recoveryLimiter = rateLimit({
  windowMs: 15 * 60 * 1000,
  limit: 10,
  standardHeaders: true,
  legacyHeaders: false,
});
app.use('/api/recovery', recoveryLimiter);
app.use('/api/recovery-codes', recoveryLimiter);

FAQ

Why not let users reset with just an email link?

Because then your account security is exactly the security of the mailbox, and a mailbox is usually protected by something weaker than a passkey. If you accept that trade-off for low-risk accounts, add a waiting period and notifications, as the delayed path here does. Otherwise require a second proof such as a recovery code.

How many passkeys should I ask users to register?

Two, on different devices or in different ecosystems, plus a set of saved recovery codes. One synced passkey is a reasonable minimum, but it still depends on a single platform account.

Do synced passkeys solve recovery on their own?

Partly. They survive the loss of a single device while the platform or password manager account is intact. They do not help if that account is lost, if the user moves to a different ecosystem, or if the user registered a device-bound passkey. Use the stored deviceType and backedUp fields to see which case you are dealing with.

What if the user lost their email access too?

Recovery codes are the answer, and for users with neither you need a human process that verifies identity before changing anything. Do not let that process bypass the notifications and revocation steps above.

Should I keep passwords as a backup sign-in method?

It is tempting, but a password fallback makes your account only as strong as the password, and it brings back phishing. If you do keep passwords during migration, plan to retire them, and never use the password path to skip the recovery rules.

Published via ZyVOP — Write once in Markdown, auto-backup to GitHub, and syndicate to Dev.to, Medium & Hashnode in 1 click.

ngrok, Explained: From Localhost Tunnel to Programmable Ingress

DevStories — Sun, 18 Oct 2026 15:57:00 +0000

Every developer hits the same wall eventually. Your app runs perfectly on localhost:3000. Then Stripe needs somewhere to send a webhook, a teammate wants to try the new checkout flow, or an OAuth provider insists on a public HTTPS callback URL. Your laptop sits behind a router, a NAT, and maybe a corporate firewall. The internet can't reach it.

For over a decade, the answer has been one line:

ngrok http 3000

Thirty seconds later you have a public https:// URL pointing at your machine. That trick made ngrok famous. But the product behind it has grown well past 'localhost tunnel', and understanding the bigger model is what separates people who use ngrok occasionally from people who use it well. This post covers both: the fast path first, then the deeper picture.

How it works: the mental model

There are three moving parts:

The agent. A small program (or an SDK embedded in your own app) that runs next to the service you want to expose.
The ngrok cloud. The edge that receives public traffic, terminates TLS, and decides what to do with each request.
The endpoint. A public address plus the rules for handling traffic that arrives there.

The key design choice is that the agent opens an outbound, encrypted connection to ngrok's cloud. When a request hits your public URL, the cloud sends it down that already-open connection, your agent hands it to the local service, and the response travels back the same way.

Browser / Stripe / teammate
        |   https://your-name.ngrok.app
        v
   ngrok cloud   -- applies Traffic Policy (auth, rate limits, rewrites)
        |   (existing outbound connection)
        v
   ngrok agent   -->   localhost:3000

Because the connection starts from your side, you need no port forwarding, no firewall exceptions, and no static IP. Your machine never accepts inbound connections from the internet. ngrok's edge does.

Quickstart in three commands

Install the agent (Homebrew, a Windows package, apt, or a direct download from ngrok.com) and create an account.
Connect the agent to your account with your authtoken:

ngrok config add-authtoken <YOUR_TOKEN>

Expose a local port:

ngrok http 3000

The terminal shows your public forwarding URL. It also tells you about a local web interface, normally at http://127.0.0.1:4040, which turns out to be one of ngrok's best features (more on that below).

Not everything is HTTP. The same idea works for raw TCP, such as SSH into a box behind a NAT:

ngrok tcp 22

Where ngrok earns its keep

Webhook development. Stripe, GitHub, Slack, Twilio, Shopify: they all need a public URL to call. This is the single most common use.
OAuth and OIDC callbacks. Many identity providers require an HTTPS redirect URI that isn't localhost.
Demos and feedback. Send a client or teammate a link to the thing running on your laptop right now, with no deploy.
Real-device testing. Point a phone or an IoT prototype at your dev API without fiddling with LAN addresses.
Local AI tooling. Hosted tools that need a URL for a local model server or MCP server can reach it through a tunnel. Lock it down first (see the security section).
Home labs. Reach a service on a Raspberry Pi or home server without opening ports on your router.

The webhook loop: ten minutes that save hours

Run ngrok http, paste the URL into your provider's webhook settings, and open the inspector at http://127.0.0.1:4040.

Every request and response that passes through the tunnel is recorded there: method, headers, body, status, timing. The part that changes how you work is replay. When your handler throws on the fifth line, you fix the bug and replay the exact same request with one click, instead of triggering another test payment, another push, or another form submission. Debugging a flaky webhook handler goes from a ten-step ritual to edit, save, replay.

Two habits make this loop better:

Verify webhook signatures even in development, so the code you ship is the code you tested. ngrok can also check signatures from several popular providers at the edge through a Traffic Policy action, which means forged requests never reach your laptop. See the action list in the docs for supported providers.
Keep your URL stable, which brings us to the next point.

Give it a permanent address

With a random URL, every restart means re-pasting webhook settings into three dashboards. Use a reserved domain instead:

ngrok http 3000 --url https://your-name.ngrok.app

Reserved domains can be ngrok-provided or your own custom domain. Plan limits on how many domains you get have changed over time, so check the current pricing page rather than trusting a blog post, including this one.

The bigger picture: endpoints and Traffic Policy

Modern ngrok is built around endpoints, and there are three kinds worth knowing:

Type	Where it lives	Good for
Agent endpoint	Created by an agent, SDK, or the Kubernetes Operator, and forwards traffic to an upstream you choose	Development, quick sharing, getting started
Cloud endpoint	Lives in the ngrok cloud. Persistent and always on, managed from the dashboard or API, and does not forward to an agent by default	A stable public front door with centrally managed policy
Internal endpoint	Private. Receives traffic only when another endpoint forwards to it with the forward-internal action	Backends that should never be publicly reachable

A very common production pattern combines all three: a public cloud endpoint holds the policy, then routes by hostname, path, or header to internal agent endpoints. Developers and services come and go behind it; the front door and its rules stay put.

What ties it together is Traffic Policy, a rules engine you write in YAML or JSON. Rules run in phases (when a TCP connection opens, when an HTTP request arrives, when a response goes out). Each rule has optional expressions (conditions) and one or more actions (what to do). Here is a policy that puts a staging site behind Google login and admits only people with a company email address, with zero auth code in your app:

on_http_request:
  - actions:
      - type: oauth
        config:
          provider: google
  - expressions:
      - "!actions.ngrok.oauth.identity.email.endsWith('@yourcompany.com')"
    actions:
      - type: deny
        config:
          status_code: 403

Apply it to a quick tunnel from a file:

ngrok http 3000 --traffic-policy-file policy.yml

The same policy language covers rate limiting, IP allowlists, JWT validation, header and URL rewriting, redirects, custom responses, and routing between endpoints. Action names and options evolve, so treat the Traffic Policy docs as the source of truth when you write your own.

Build it into your own code

You don't have to run the CLI at all. ngrok maintains SDKs for Go, JavaScript, Python, and Rust, so your application can create its own endpoint on startup. In Node it looks like this:

const ngrok = require('@ngrok/ngrok');

(async () => {
  const listener = await ngrok.forward({ addr: 8080, authtoken_from_env: true });
  console.log('Public URL: ' + listener.url());
})();

This is handy for integration tests that need a real public URL, internal tools that hand out temporary links, and dev servers that should come up already reachable.

From laptop to cluster

If you run Kubernetes, the ngrok Operator brings the same model to your cluster. Standard Ingress resources work with ingressClassName: ngrok, and custom resources such as AgentEndpoint and CloudEndpoint give you direct control over endpoints and their Traffic Policy. One detail worth knowing: because cloud endpoints live in ngrok's cloud, they stay reachable as a front door even if the cluster running your Operator goes down.

Sharp edges: a security checklist

A tunnel is a public door to whatever sits behind it. Most ngrok horror stories are not ngrok bugs; they are exposed things nobody meant to expose.

Don't tunnel what you wouldn't put on the internet. Databases, admin panels, debug consoles, and notebooks with code execution are the classics.
Add authentication at the edge for anything beyond a throwaway demo: OAuth, basic auth, JWT validation, or an IP allowlist, all configurable through Traffic Policy.
Treat your authtoken like a password. Keep it out of git, load it from an environment variable in CI, use separate tokens for separate machines and purposes, and rotate it if it leaks.
Shut tunnels down when you are done. Check the dashboard for endpoints you forgot about.
Mind your organization's rules. Some companies prohibit tunnels outright; team and organization accounts exist so that usage can be visible and governed.
Expect a browser warning page on free plans. Free HTTP endpoints can show visitors an interstitial before your app, partly because free tunnels have historically been abused for phishing. If it gets in the way of your own tooling, send the ngrok-skip-browser-warning request header, or use a paid plan.

Honest alternatives

ngrok is not the only way to do this, and sometimes it isn't the best:

Cloudflare Tunnel (cloudflared) is a strong choice if your domains already live on Cloudflare and you want long-lived named tunnels.
Tailscale Funnel fits neatly if your team already lives on a tailnet.
Self-hosted options such as frp, bore, and zrok suit people who want to run the infrastructure themselves.
SSH-based services such as localhost.run need no install at all, with fewer features.

A fair rule of thumb: ngrok wins on speed to first URL, the inspector and replay workflow, and a built-in policy engine. Alternatives may win on price, self-hosting, or fit with infrastructure you already run.

Cheat sheet

# one-time setup
ngrok config add-authtoken <YOUR_TOKEN>

# expose a local web app
ngrok http 3000

# stable address
ngrok http 3000 --url https://your-name.ngrok.app

# add rules (auth, rate limits, deny lists)
ngrok http 3000 --traffic-policy-file policy.yml

# raw TCP, e.g. SSH
ngrok tcp 22

# inspect and replay traffic
# open http://127.0.0.1:4040

The takeaway

ngrok started as a clever way to show your laptop to the world. It has become a way to put a programmable, secure front door on anything, whether that service runs on your desk, in a cluster, or inside an application you are shipping. Start with ngrok http. Graduate to a reserved domain when re-pasting URLs gets old. Add Traffic Policy the moment anyone besides you can reach the URL. And when a project outgrows the laptop, look at cloud endpoints.

Pricing, plan limits, and some product names change often, so confirm the details at ngrok.com/docs and the pricing page before you build on them.

Published via ZyVOP — Write once in Markdown, auto-backup to GitHub, and syndicate to Dev.to, Medium & Hashnode in 1 click.

Kubernetes in 2026: What It Is, How It Works, and a Production Baseline You Can Apply Today

DevStories — Fri, 16 Oct 2026 10:00:13 +0000

Kubernetes is the system most teams now use to run containers in production. In the CNCF annual survey announced on January 20, 2026, 82% of container users reported running Kubernetes in production, up from 66% in 2023. Operating it well is now a core engineering skill, and this post teaches it in three layers.

The first layer explains what Kubernetes is, the problem it solves, and the objects you work with every day. The second shows how a cluster is built and what happens between typing kubectl apply and a running container. The third is a production baseline for a stateless HTTP service: seven manifests, each explained, plus the 2026 changes that can break a cluster you have not touched in a year.

Kubernetes 1.37 shipped on August 26, 2026, and the project now supports three minor versions at once. Every feature below carries its maturity level and the version that set it. Where a claim comes from a release note, a blog post or a survey, it links to that source. Where the baseline depends on something your cluster must provide, such as a Gateway API controller or a CNI plugin that enforces NetworkPolicy, the text says so.

What Kubernetes is, and the problem it solves

In the project's own words, Kubernetes is a portable, extensible, open source platform for managing containerized workloads and services, with both declarative configuration and automation. The name comes from the Greek word for helmsman or pilot, and K8s abbreviates it by counting the eight letters between the K and the s. Google open sourced the project in 2014, and it combines over 15 years of Google's experience running production workloads at scale with ideas from the community.

To see why it exists, follow how deployment changed. Teams first ran applications on physical servers, where one application could take most of a machine's resources and starve the others. Virtual machines fixed that by isolating applications, but each VM runs a full operating system. Containers relax that isolation and share the host operating system, so they are lighter and portable across clouds and Linux distributions.

Containers solve packaging, not operations. In production something must restart a container that dies, spread containers across many machines, send traffic only to the healthy ones, and roll out new versions without downtime. The overview puts it plainly: if a container goes down, another container needs to start, and it would be easier if a system handled that. Kubernetes is that system.

The overview lists what you get from it, summarized here.

Capability	What it does
Service discovery and load balancing	Exposes a container by DNS name or IP address and spreads traffic across copies
Storage orchestration	Mounts the storage system you choose, from local disks to public cloud storage
Automated rollouts and rollbacks	Moves the actual state to the state you describe, at a controlled rate
Automatic bin packing	Places containers on nodes using the CPU and memory you declare for each
Self-healing	Restarts failed containers and withholds traffic until a container is ready
Secret and configuration management	Updates secrets and configuration without rebuilding images
Batch execution	Runs batch and CI workloads and replaces failed containers if you want
Horizontal scaling	Scales up or down by command, in a UI, or automatically on CPU usage

It also helps to know what Kubernetes leaves out. It is not an all-inclusive platform as a service: it does not build your code, run your CI/CD pipeline, or ship databases, message buses and caches as built-in services, and it does not choose your logging or monitoring tools. It is also not orchestration in the strict sense of running step A, then B, then C. It is a set of independent control processes that keep driving the current state toward the state you declared.

The core idea: you declare, controllers converge

Everything in Kubernetes is an object, a persistent record in the cluster. The objects documentation calls an object a record of intent: once you create it, the system works constantly to make it exist. Almost every object has a spec, which is the state you want, and a status, which Kubernetes fills in with the state it observes.

Take a Deployment whose spec asks for three replicas. Kubernetes reads the spec and starts three instances. If one fails, the status no longer matches the spec, and Kubernetes starts a replacement. The component doing this work is a controller, which runs a control loop, a non-terminating loop that regulates the state of a system. The docs compare it to a thermostat that switches equipment on and off to bring a room toward the temperature you set.

The practical consequence is that you rarely issue instructions such as "start this container". You change the declared state, and controllers work out the steps. That is why this post is built from YAML files you apply, not scripts you run.

The objects you use every day

A handful of object types cover most applications. The table lists them in the order you meet them.

Object	What it is	How you use it
Pod	The smallest deployable unit: one or more tightly coupled containers with shared storage and network	The unit that actually runs, normally created through a workload resource and not by hand
ReplicaSet	Keeps a stable set of replica Pods running	Rarely touched directly, because a Deployment manages it for you
Deployment	Declarative updates for Pods and ReplicaSets, usually for apps that keep no state	Running and updating a stateless service
Service	A stable network endpoint for a changing set of Pods	Giving clients one name and address to call
ConfigMap	Non-confidential configuration stored as key-value pairs	Settings consumed as environment variables, arguments or files
Secret	A small amount of sensitive data such as a password, token or key	Credentials kept out of images and Pod specs
Namespace	A scope that isolates groups of resources inside one cluster	Separating teams or projects, since names must be unique only within a namespace
Node	A worker machine, virtual or physical, that runs Pods	The capacity underneath everything, managed for you by the control plane

Other workload resources cover other shapes of work. A StatefulSet gives each Pod a sticky identity for applications that need persistent storage or a stable network identity. A DaemonSet runs node-local facilities such as a networking helper. A Job runs a one-off task to completion.

Pods are ephemeral. The Service documentation says you should not expect any individual Pod to be reliable or durable, because Pods are created and destroyed to match the desired state. Each Pod gets its own IP address, but the set of healthy Pods keeps changing. That is the reason Services exist: clients need one stable name in front of Pods that come and go.

One caution about Secrets. By default they are stored unencrypted in etcd, and anyone with API access can read them, as can anyone allowed to create a Pod in the namespace. The Secret documentation tells you to enable encryption at rest and to restrict access with RBAC. A ConfigMap provides no secrecy at all.

Here is a minimal Deployment, the object you will write most often.

# hello.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: hello-node
spec:
  replicas: 2
  selector:
    matchLabels:
      app: hello-node
  template:
    metadata:
      labels:
        app: hello-node
    spec:
      containers:
        - name: agnhost
          image: registry.k8s.io/e2e-test-images/agnhost:2.53
          command: ["/agnhost", "netexec", "--http-port=8080"]
          ports:
            - containerPort: 8080

Read it from the top. apiVersion and kind name the API and the object type, and metadata.name names the object. Everything under spec is desired state: two replicas of a Pod built from the template. The selector tells the Deployment which Pods it owns by matching the template's labels, and the Deployment documentation says the API rejects a Deployment whose two do not match. Labels are plain key-value pairs that Services, Deployments and policies use to find Pods.

How a cluster is built

A cluster has a control plane and one or more worker nodes. The components overview says the control plane components manage the overall state of the cluster, and the node components run on every node, maintaining running Pods and providing the runtime environment.

Component	Runs on	Job
kube-apiserver	Control plane	Serves the Kubernetes HTTP API as the front end of the control plane, and scales horizontally by running more instances
etcd	Control plane	Consistent, highly available key-value store for all cluster data, which you need a backup plan for
kube-scheduler	Control plane	Watches for newly created Pods with no node and selects a node for each
kube-controller-manager	Control plane	Runs the controller processes, compiled into one binary and run as one process
cloud-controller-manager	Control plane, optional	Integrates with the underlying cloud provider
kubelet	Every node	Makes sure the containers described in PodSpecs are running and healthy, and ignores containers Kubernetes did not create
kube-proxy	Every node, optional	Maintains the network rules that implement Services
Container runtime	Every node	The software that actually runs containers

Every arrow runs through the API server. The Kubernetes API documentation says users, the different parts of your cluster and external components all communicate with one another through it. The scheduler, the controllers and the kubelets never call each other. Each watches the API for work and writes its results back, so a component that restarts can read the current state again.

Three consequences shape every manifest in this post. The scheduler reads requests, so wrong requests mean wrong placement. The kubelet enforces limits, so wrong limits mean CPU throttling or out-of-memory kills. Controllers retry forever, so a bad rollout never fixes itself unless a probe tells the truth.

What happens when you run kubectl apply

Follow one command through the system. The CLI turns your file into API calls, as the objects documentation describes, and from there the work passes between components without any of them calling another directly.

A chain of hand-offs turns that file into running containers. The API server accepts and stores the Deployment. The Deployment controller creates a ReplicaSet, and the ReplicaSet creates the Pods, which the Deployment documentation describes as happening in the background. The scheduler sees Pods without a node and picks one for each. The kubelet on that node starts the containers through the runtime and reports status back.

Try it on a local cluster

You need a cluster and kubectl. The learning environment page lists kind, which runs cluster nodes as Docker containers, and minikube, which runs a single-node cluster on your machine, among other options. Install one of them and kubectl, then confirm that kubectl get nodes shows a node in the Ready state.

kubectl apply -f hello.yaml
kubectl get deployments
kubectl get pods

kubectl scale deployment/hello-node --replicas=4
kubectl get pods

kubectl delete pod <one-of-the-pod-names>
kubectl get pods

kubectl get events
kubectl port-forward deployment/hello-node 8080:8080

Run them in order. The first creates the Deployment and, through it, two Pods. Scaling to four changes the desired state, and Kubernetes starts two more. Deleting a Pod does not lower the count: the ReplicaSet notices the gap and creates a replacement, the behavior the docs list as replica replacement under self-healing. kubectl get events shows the hand-offs from the previous section as they happened.

The port-forward command tunnels local port 8080 to a Pod, so you can open http://localhost:8080 and see the test image echo your request back, the same image the official Hello Minikube tutorial uses. It does not return until you stop it with Ctrl+C. When you are done, run kubectl delete -f hello.yaml to remove the Deployment and its Pods.

Where Kubernetes stands in October 2026

That demo skipped everything production needs: pinned versions, resource limits, probes, security controls and a safe way to take traffic. The rest of this post adds them, starting with the versions you can choose from.

The project maintains release branches for the three most recent minor releases and supports each patch series for roughly fourteen months: twelve in the standard period, then two in maintenance mode, when new releases cover only CVE fixes, dependency issues and critical core component issues. As of October 10, 2026, the releases page lists the following.

Minor	Latest patch listed	End of life
1.37	1.37.1 (September 15, 2026)	October 28, 2027
1.36	1.36.5	June 28, 2027
1.35	1.35.9	February 28, 2027
1.34	1.34.12	October 27, 2026

The next patch releases for all four lines are scheduled for October 13, 2026, so the patch numbers above will be stale within days. The fourth row, 1.34, is in maintenance mode, which began on August 27, 2026, and its end of life is under three weeks away. Plan the move to 1.35 or later now, and upgrade one minor version at a time, because kubeadm does not support skipping minor versions.

The last two releases were large. Kubernetes 1.36 (Haru), released April 22, 2026, had 70 enhancements: 18 Stable, 25 Beta and 25 Alpha. Kubernetes 1.37 (Garhwal) had 67: 16 Stable, 23 Beta, 27 Alpha and one deprecation or removal. You do not need most of them. You need the handful that change how you write manifests.

The baseline, one manifest at a time

The target is one service called api in a namespace called shop, behind a shared Gateway, with three replicas spread across zones. Replace the names, the host, the image digest and the GatewayClass. Everything else is meant to be applied as written.

Save each block below as its own file, in order, using the file name in the first comment line.

1. Namespace: enforce Pod Security Admission

# 00-namespace.yaml
apiVersion: v1
kind: Namespace
metadata:
  name: shop
  labels:
    pod-security.kubernetes.io/enforce: restricted
    pod-security.kubernetes.io/enforce-version: latest
    pod-security.kubernetes.io/warn: restricted
    pod-security.kubernetes.io/audit: restricted
    shared-gateway-access: "true"

Pod Security Admission has been stable since 1.25. The restricted profile rejects Pods that run as root, allow privilege escalation, keep default Linux capabilities or lack a seccomp profile. Setting enforce, warn and audit together means you see violations in three places. The last label is used by the Gateway in step 4.

2. Deployment

# 01-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: api
  namespace: shop
  labels:
    app.kubernetes.io/name: api
spec:
  # replicas is omitted on purpose: the HPA in step 6 owns it
  revisionHistoryLimit: 3
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxUnavailable: 0
      maxSurge: 1
  selector:
    matchLabels:
      app.kubernetes.io/name: api
  template:
    metadata:
      labels:
        app.kubernetes.io/name: api
    spec:
      hostUsers: false
      automountServiceAccountToken: false
      terminationGracePeriodSeconds: 45
      securityContext:
        runAsNonRoot: true
        runAsUser: 10001
        runAsGroup: 10001
        seccompProfile:
          type: RuntimeDefault
      topologySpreadConstraints:
        - maxSkew: 1
          topologyKey: topology.kubernetes.io/zone
          whenUnsatisfiable: ScheduleAnyway
          labelSelector:
            matchLabels:
              app.kubernetes.io/name: api
      containers:
        - name: api
          # Pin by digest. Replace this placeholder with your real image digest.
          image: registry.example.com/shop/api@sha256:0000000000000000000000000000000000000000000000000000000000000000
          ports:
            - name: http
              containerPort: 8080
          resources:
            requests:
              cpu: 250m
              memory: 256Mi
            limits:
              memory: 256Mi
          resizePolicy:
            - resourceName: cpu
              restartPolicy: NotRequired
            - resourceName: memory
              restartPolicy: RestartContainer
          securityContext:
            allowPrivilegeEscalation: false
            readOnlyRootFilesystem: true
            capabilities:
              drop: ["ALL"]
          startupProbe:
            httpGet:
              path: /healthz
              port: http
            periodSeconds: 2
            failureThreshold: 30
          readinessProbe:
            httpGet:
              path: /readyz
              port: http
            periodSeconds: 5
            failureThreshold: 2
          livenessProbe:
            httpGet:
              path: /healthz
              port: http
            periodSeconds: 10
            failureThreshold: 3
          lifecycle:
            preStop:
              sleep:
                seconds: 10
          volumeMounts:
            - name: tmp
              mountPath: /tmp
      volumes:
        - name: tmp
          emptyDir:
            sizeLimit: 64Mi

Four settings carry most of the weight. hostUsers: false puts the Pod in its own user namespace, so root inside the container maps to an unprivileged user on the node. User namespaces reached GA in 1.36 and are Linux-only. The concept page lists the node requirements: Linux 6.3 or later for idmap mounts on tmpfs, runc 1.2 or later or crun 1.9 or later, and containerd 2.0 or later or CRI-O 1.25 or later. Check your nodes before relying on the setting.

maxUnavailable: 0 with maxSurge: 1 makes a rollout add one new Pod and wait for it to be Ready before removing an old one. The topology spread constraint keeps replicas balanced across zones. ScheduleAnyway means a zone outage does not leave Pods Pending. Switch to DoNotSchedule only if imbalance is worse than reduced capacity for your service.

The three probes answer three different questions. The startup probe allows a slow boot of up to 60 seconds (30 failures at 2 second intervals) before the other probes begin. Readiness decides whether the Pod receives traffic, and should check dependencies you cannot serve without. Liveness should check only that the process is not wedged. Never make liveness depend on a database, or a database outage becomes a restart storm.

The preStop sleep and the 45 second grace period solve a race. Endpoint removal and SIGTERM happen at about the same time, so for a few seconds a terminating Pod can still receive requests. Sleeping 10 seconds before SIGTERM gives proxies time to stop sending traffic. Your application must still handle SIGTERM by finishing in-flight requests inside the remaining 35 seconds.

The sleep hook action is Stable since 1.34, when the PodLifecycleSleepAction feature gate became locked on, so every supported minor has it. The lifecycle hooks page lists it beside the exec and HTTP handlers. The kubelet runs it, so your image needs no sleep binary.

Memory request equals memory limit, and there is no CPU limit. Memory cannot be compressed, so an equal limit makes OOM behavior predictable. CPU can be throttled, and a CPU limit often throttles bursts the node could have served. The Pod still gets a CPU guarantee through its request. Revisit this choice if you run a multi-tenant cluster that needs hard caps.

3. Service

# 02-service.yaml
apiVersion: v1
kind: Service
metadata:
  name: api
  namespace: shop
spec:
  type: ClusterIP
  selector:
    app.kubernetes.io/name: api
  ports:
    - name: http
      port: 80
      targetPort: http

The Service gives the Pods one stable virtual IP and a DNS name, api.shop.svc. It is ClusterIP on purpose. Traffic from outside the cluster enters through the Gateway, not through a Service of type LoadBalancer per application, and not through the deprecated externalIPs field covered later.

4. Gateway and HTTPRoute

# 03-gateway-and-route.yaml
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: public
  namespace: gateway-system
spec:
  gatewayClassName: example-gateway-class
  listeners:
    - name: https
      protocol: HTTPS
      port: 443
      hostname: api.example.com
      tls:
        mode: Terminate
        certificateRefs:
          - kind: Secret
            name: api-example-com-tls
      allowedRoutes:
        namespaces:
          from: Selector
          selector:
            matchLabels:
              shared-gateway-access: "true"
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: api
  namespace: shop
spec:
  parentRefs:
    - name: public
      namespace: gateway-system
      sectionName: https
  hostnames:
    - api.example.com
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      backendRefs:
        - name: api
          port: 80

Gateway API splits ownership. The platform team owns the Gateway and its listeners, and application teams own the routes that attach to it. Gateway and HTTPRoute have been GA since Gateway API v1.0. Gateway API v1.6.0, released June 30, 2026, also moved TCPRoute and UDPRoute to the Standard channel at API version v1.

Gateway API is not built into the API server. You install its CRDs and a controller that implements your GatewayClass, and example-gateway-class is a placeholder for that controller's class name. The allowedRoutes selector is why step 1 labeled the shop namespace: a route from an unlabeled namespace is not allowed to attach.

The manifest assumes two objects already exist: the gateway-system namespace, and a kubernetes.io/tls Secret named api-example-com-tls inside it. Per the Gateway CRD at v1.6.0, a certificate reference into another namespace is invalid unless a ReferenceGrant allows it, and the listener then reports ResolvedRefs as False with the reason RefNotPermitted. Create both before you apply this file.

5. PodDisruptionBudget

# 04-pdb.yaml
apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  name: api
  namespace: shop
spec:
  maxUnavailable: 1
  selector:
    matchLabels:
      app.kubernetes.io/name: api

A PodDisruptionBudget limits voluntary evictions, such as a node drain during an upgrade. With it, a drain can take one api Pod at a time and must wait for the replacement to be Ready. It does not protect against crashes or node failures. Prefer maxUnavailable over minAvailable, so the budget keeps working when the HPA changes the replica count.

6. HorizontalPodAutoscaler

# 05-hpa.yaml
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: api
  namespace: shop
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: api
  minReplicas: 3
  maxReplicas: 12
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 70
  behavior:
    scaleDown:
      stabilizationWindowSeconds: 300
      policies:
        - type: Percent
          value: 25
          periodSeconds: 60

Leaving spec.replicas out of the Deployment makes the HPA the only writer of the replica count. If both write, every kubectl apply resets it. On the first apply the Deployment starts at one replica until the HPA raises it to minReplicas, so apply both in the same command. CPU utilization is measured against the request, which is why requests must be honest.

Resource metrics come from the metrics.k8s.io API, usually served by metrics-server. That API graduated to Stable in 1.37 after nearly nine years in Beta. The scale-down policy above removes at most 25% of replicas per minute, and only after five minutes of consistently lower demand, which avoids flapping on spiky traffic.

7. NetworkPolicy

# 06-networkpolicy.yaml
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: default-deny
  namespace: shop
spec:
  podSelector: {}
  policyTypes:
    - Ingress
    - Egress
---
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: allow-gateway-to-api
  namespace: shop
spec:
  podSelector:
    matchLabels:
      app.kubernetes.io/name: api
  policyTypes:
    - Ingress
  ingress:
    - from:
        - namespaceSelector:
            matchLabels:
              kubernetes.io/metadata.name: gateway-system
      ports:
        - protocol: TCP
          port: 8080
---
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: allow-dns-egress
  namespace: shop
spec:
  podSelector: {}
  policyTypes:
    - Egress
  egress:
    - to:
        - namespaceSelector:
            matchLabels:
              kubernetes.io/metadata.name: kube-system
      ports:
        - protocol: UDP
          port: 53
        - protocol: TCP
          port: 53

NetworkPolicy objects are enforced only if your CNI plugin implements them. On a plugin that does not, these manifests are accepted and silently do nothing, so test with a throwaway Pod that should be blocked. Default-deny egress also blocks your database and every external API, so add one allow rule per destination before you ship. Some Gateway controllers run their data plane in a namespace other than gateway-system; adjust the selector to match.

Apply and verify

kubectl apply --dry-run=server -f 00-namespace.yaml
kubectl apply -f 00-namespace.yaml
kubectl apply --dry-run=server -f 01-deployment.yaml -f 02-service.yaml -f 04-pdb.yaml -f 05-hpa.yaml -f 06-networkpolicy.yaml
kubectl apply -f 01-deployment.yaml -f 02-service.yaml -f 04-pdb.yaml -f 05-hpa.yaml -f 06-networkpolicy.yaml
kubectl apply -f 03-gateway-and-route.yaml

kubectl -n shop rollout status deploy/api
kubectl -n shop get deploy,hpa,pdb,pods -o wide
kubectl -n shop get httproute api -o jsonpath='{.status.parents[*].conditions[*].type}{"\n"}'

The server-side dry run catches schema errors and admission rejections, including Pod Security violations, without creating anything. The last command prints the route's status condition types; look for Accepted and ResolvedRefs, and read each condition's status field when either is missing.

Resize a running Pod without restarting it

In-place Pod resize reached Stable in 1.35, after starting as Alpha in 1.27. A container's resources are now the desired state, the Pod status shows what is actually applied, and you change the desired values through the Pod's resize subresource. Per the task documentation, the server must be at 1.33 or later and kubectl at 1.32 or later.

kubectl -n shop patch pod <pod-name> --subresource resize --patch \
  '{"spec":{"containers":[{"name":"api","resources":{"requests":{"cpu":"500m"}}}]}}'

kubectl -n shop get pod <pod-name> \
  -o jsonpath='{.status.containerStatuses[0].resources}{"\n"}'

The resizePolicy in step 2 decides the cost. With CPU set to NotRequired, the container keeps running while the kubelet applies the change. With memory set to RestartContainer, a memory change restarts that container, because many runtimes cannot change their heap bounds on the fly. If one patch changes both, the container restarts, as the documentation states.

A resize edits one Pod. The Deployment template still holds the old values, so replacement Pods start with them. Use resize for emergency relief and for autoscalers, since the Vertical Pod Autoscaler's InPlaceOrRecreate mode, which the same post reports as Beta and built on this feature, and change the template for anything lasting.

Scale a worker to zero

HorizontalPodAutoscaler scale to zero reached Beta in 1.37 and is on by default: the HPAScaleToZero feature gate is enabled on both the kube-apiserver and the kube-controller-manager. It works only with an object metric or an external metric. CPU and memory come from running Pods, and at zero replicas there is nothing left to measure, so there would be no signal to scale back up.

# queue-worker-hpa.yaml
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: queue-worker
  namespace: shop
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: queue-worker
  minReplicas: 0
  maxReplicas: 10
  metrics:
    - type: External
      external:
        metric:
          name: queue_consumer_lag
          selector:
            matchLabels:
              name: worker_tasks
        target:
          type: AverageValue
          averageValue: "30"

This HPA asks for one replica per 30 queued tasks and drops to zero when the queue is empty. The external metric must be served through the External Metrics API by an adapter such as Prometheus Adapter, and you can confirm Kubernetes can read it with kubectl get --raw before creating the HPA.

The target type matters. The release post's example uses Value, but in the controller source at v1.37.1 a Value target multiplies the metric-to-target ratio by the number of ready Pods, so a queue that stays long keeps multiplying the replica count. AverageValue computes the queue length divided by 30, rounded up, and the HPA walkthrough uses it for its own queue example.

Start the Deployment with at least one replica. The release post says manually setting a Deployment to zero has always paused autoscaling, and a workload at zero is resumed only if the HPA itself scaled it down and recorded the ScaledToZero condition.

Do not use this for the api service. The release notes are explicit that Kubernetes Services do not buffer requests while no Pods are ready, so request-driven HTTP workloads need a separate buffering layer. Scale to zero fits work that can wait in a durable queue, where a cold start costs seconds of latency and nobody is waiting on a socket.

What to fix before you upgrade

Four 2026 changes can bite a cluster that has been quiet. This script covers the two you can detect from the API. The other two need a look at your nodes and your release notes.

#!/usr/bin/env bash
# preflight.sh: run with cluster-admin credentials
set -euo pipefail

echo "== 1. Is ingress-nginx still running?"
kubectl get pods --all-namespaces --selector app.kubernetes.io/name=ingress-nginx

echo "== 2. Services that still set spec.externalIPs"
kubectl get svc --all-namespaces -o json \
  | jq -r '.items[]
           | select((.spec.externalIPs // []) | length > 0)
           | "\(.metadata.namespace)/\(.metadata.name)"'

echo "== 3. Client and server versions"
kubectl version

Ingress NGINX is retired

The Kubernetes project said best-effort maintenance of Ingress NGINX would continue until March 2026. After that there would be no releases, no bug fixes and no security updates, although existing deployments keep working. That date has passed, and the GitHub repository now shows it as archived on March 24, 2026 and read-only. A statement from the Steering and Security Response Committees, citing internal Datadog research, put its use at about 50% of cloud native environments.

The statement is blunt about the cost of waiting: staying on a retired controller leaves you and your users vulnerable to attack, and none of the alternatives is a direct drop-in replacement. Install a Gateway API controller next to Ingress NGINX, translate your routes (the project's ingress2gateway tool reached 1.0 in March 2026), test, then move traffic over gradually.

Review the translated output by hand. The ingress2gateway 1.0 post shows the tool warning that it does not support the configuration-snippet annotation, and the retirement notice names the "snippets" annotations, which add arbitrary NGINX configuration directives, as an option now considered a serious security flaw. Rebuild what each snippet did with Gateway API features instead of copying it across.

Service externalIPs is deprecated

The .spec.externalIPs field was formally deprecated in 1.36 because it assumes every user in the cluster is trusted, which enables the attacks described in CVE-2020-8554. A future minor release will drop the behavior from kube-proxy and require conformant implementations not to support it.

If the preflight script prints anything, plan a replacement. The same post calls a hand-assigned LoadBalancer IP the easiest option and also the worst, because users who may set it can still replicate the CVE. It lists two better routes: a load balancer controller such as MetalLB, or a Gateway whose address you set in .spec.addresses. As a precaution, enable the DenyServiceExternalIPs admission controller so nobody adds new uses.

cgroup v1 nodes will not start

Support for cgroup v2 has been stable since 1.25, and cgroup v1 went into maintenance mode in 1.31. Starting with 1.35, the kubelet option failCgroupV1 defaults to true, so the kubelet refuses to start on a cgroup v1 node unless you set it to false, a temporary override while removal is tracked in KEP-5573. On each node, stat -fc %T /sys/fs/cgroup prints cgroup2fs for v2 and tmpfs for v1. Fix every v1 node before the upgrade, not during it.

SELinux volume labeling changes

In 1.37 the SELinuxMount and SELinuxChangePolicy features reached Stable and are enabled by default. Volumes then mount with one SELinux context instead of being relabeled recursively, but only for CSI drivers that opt in with .spec.seLinuxMount: true. Pods with different SELinux labels that share a volume on one node can therefore fail to start.

The release notes advise setting .spec.seLinuxChangePolicy to Recursive on a Pod to keep the old behavior, and they say clusters without SELinux see no effect. If your nodes enforce SELinux, as on the RHEL family, read the project's post on SELinux volume label changes and their implications in 1.37 before upgrading, and test any workload where Pods share a volume.

Where AI workloads fit

The same CNCF survey found that 66% of organizations hosting generative AI models use Kubernetes for some or all of their inference. It also found that only 7% of organizations deploy models daily and that 44% do not yet run AI or ML workloads on Kubernetes. Most teams are early, which makes the platform choices you make now easy to get right and expensive to redo.

The baseline in this post is the right foundation for an inference service, with one change: GPUs and other devices should be requested through Dynamic Resource Allocation, not through the old device-plugin counters. DRA reached GA in 1.34, and in 1.37 the ResourceClaim .status.devices field graduated to Stable, which lets drivers report device-specific status. Read the DRA concept pages before designing GPU scheduling.

A seven-day rollout plan

Day	Do this	Done when
1	Run preflight.sh, check node cgroup versions, list your supported-version dates	You know which of the four 2026 changes apply to you
2	Apply steps 1 to 3 and 5 to 6 in a staging namespace	rollout status succeeds and the HPA reports metrics
3	Install a Gateway API controller in staging, create gateway-system and the TLS Secret, then apply step 4	The HTTPRoute shows Accepted and ResolvedRefs
4	Apply step 7 and add one egress rule per real dependency	A blocked test Pod fails and the app still works
5	Enable hostUsers: false on one workload	The Pod starts and passes its probes
6	Drain a node and watch the PodDisruptionBudget	Drain completes with at most one api Pod down at a time
7	Upgrade staging one minor version, then production	Both clusters pass preflight.sh on the new version

Closing notes

None of this requires a new tool. Every manifest above is plain Kubernetes, and every feature labeled Stable is safe to depend on. Features labeled Beta, such as HPA scale to zero, are on by default in 1.37, but they can still change, so pin your cluster version and read the release notes before each upgrade.

Managed Kubernetes services often lag the upstream release by weeks or months. Run kubectl version and check your provider's release calendar before assuming a 1.37 feature is available to you. The upstream support dates in this post apply to the community project, and your provider may set its own.

Published via ZyVOP — Write once in Markdown, auto-backup to GitHub, and syndicate to Dev.to, Medium & Hashnode in 1 click.

Googlebook: Google's Biggest Laptop Bet Since the Chromebook

DevStories — Fri, 16 Oct 2026 09:59:51 +0000

Fifteen years ago, Google convinced the world that a laptop could be little more than a browser. It was cheap, it booted in seconds, and it quietly took over classrooms. Now the company is asking for belief in a very different idea: a laptop whose most important feature isn't the chip, the screen, or even the operating system. It's the cursor.

Meet the Googlebook. It was announced on May 12 at The Android Show, opened for pre-order on September 21, and went on sale in the US on October 4, with Canada, the UK, Ireland, France, Germany and Australia following on October 5. The hardware is here. The real question is whether the idea behind it is any good.

A quick note on sources: what follows rests on Google's own announcements, partner details and early press coverage. Independent, long-term testing is still thin, so treat the big promises accordingly.

What a Googlebook actually is

A Googlebook is a laptop that runs Googlebook OS, a new Android-based system that Google says blends the best of Android with the best of ChromeOS. From Android it takes the Google Play app catalog and a modern, AI-ready foundation. From ChromeOS it takes Chrome and its extension ecosystem.

Google's own framing is revealing. Its pitch is that computing is moving from an operating system to an intelligence system, the same way the Chromebook once represented a shift to cloud-first computing. In plain terms: the Chromebook assumed the cloud did the work. The Googlebook assumes an AI model sits next to everything you do and helps in real time.

It's also a break in Google's hardware strategy. Google's last laptop under its own name was the Pixelbook Go, roughly six and a half years ago. This time Google leads on software and design language, and partners build the machines.

The cursor is the product

If you remember one feature, make it Magic Pointer. Google built it with its DeepMind team, and the idea is disarmingly simple: wiggle your cursor, and Gemini looks at whatever you're pointing at and offers to help.

The examples Google has shown are deliberately mundane, which is exactly why they matter:

Point at a date inside an email, and Gemini offers to set up a meeting.
Select two images, and Gemini offers to compare or combine them.
Use ask, compare and combine actions across whatever is on screen, without opening a separate chatbot window.

This is a genuinely different interaction model. Most AI on laptops today lives in a sidebar or a dedicated key: you stop what you're doing, switch context, explain your situation, and paste things back and forth. Magic Pointer flips that. The context is already on screen, so the pointer carries it for you.

There are two companions. Create My Widget lets you describe a dashboard in natural language and have Gemini assemble it from the web, Gmail and Calendar. And early launch coverage describes Rambler, a dedicated key that turns speech into structured text in real time.

If these work as shown, they remove friction that has quietly annoyed everyone for years. If they don't, the Googlebook is a Chromebook with a nicer chassis.

The phone is the other half of the pitch

The most underrated part of this launch isn't AI at all. It's continuity.

Google is positioning the Googlebook as the natural partner for an Android phone, much like a Mac relates to an iPhone:

Quick Access lets you browse, search and insert files from your phone directly in the laptop's file browser, with no manual transfers.
Cast My Apps streams your phone's apps onto the laptop screen.
Continue On lets you pick up phone activity on the laptop.
Setup brings over your saved passwords, Wi-Fi networks and settings when you sign in.

Apple has owned this story for over a decade, and it's a big reason people stay inside its ecosystem. Android has had pieces of it, but never a laptop that treats the phone as a first-class citizen from the first boot. That is Google's real opening. A billion-plus Android owners are a far larger audience than people who actively want an AI laptop.

The hardware: five makers, one glowing strip

The launch lineup comes from Acer, ASUS, Dell, HP and Lenovo, using Intel and Qualcomm chips with neural processing units for on-device AI. Every model carries the Glowbar, an illuminated strip on the exterior that works as a deliberate brand signature, the way the Chromebook's logo did for the last decade.

Here's the lineup based on launch reports, with US starting prices:

Acer Googlebook 14 from $899: the entry point, with Intel Core Ultra 5 or 7, 16 GB of RAM and a 14-inch 2.8K OLED convertible display.
Dell XPS Googlebook from $1,199: a 13.4-inch 2.5K touchscreen in a machined aluminum chassis, with Snapdragon X Elite.
HP Googlebook 14 from $1,299: Snapdragon X Elite and a 14-inch 2.8K OLED panel.
ASUS Googlebook 14 from $1,299: Intel-powered, with a 32 GB option and a haptic touchpad.
Lenovo Googlebook 15: the large-screen option, with a 15.3-inch OLED display. Reported pricing varies between sources, so check the retailer.

The price floor is the clearest signal of Google's intent. At $899 and up, this is not a cheap-and-cheerful Chromebook. Google is aiming at premium buyers and putting itself next to Apple's low-cost MacBooks and Windows Copilot+ PCs. Launch coverage also mentions bundled extras, including a year of Google AI Pro, though bundles can differ by region and retailer, so verify before you buy.

So, is the Chromebook dead?

Google has been careful here. It describes the Googlebook as a new category, not a Chromebook replacement, and it has said existing Chromebooks will keep receiving updates through their current support commitments. In practice, most observers read it as the Chromebook's premium successor, and it's hard to argue otherwise: the naming, the Glowbar and the Chrome-plus-Android DNA all point the same way.

What's still unclear is the lower end. The Chromebook's superpower was never prestige. It was a $250 machine that made computers affordable for schools and families. A product that starts at $899 doesn't serve that audience, and Google hasn't yet explained who will.

Where the Googlebook will be judged

Four tests will decide whether this launch matters.

1. Does Magic Pointer survive real life? Demos are curated. The real test is a messy inbox, a crowded desktop and a half-finished document. If the pointer suggests the right thing most of the time, it becomes a habit. If it interrupts, people will switch it off within a week.

2. Do Android apps feel native on a big screen? Google is already pushing developers to design for desktop-class screens, with better information density, full keyboard, mouse, trackpad, stylus and controller support, custom cursors, plus proper file handling and printing. That's the right list. But Android apps stretched onto a laptop have a poor track record, and the Googlebook's value depends on apps that look and behave like they belong.

3. Does the value math work? Memory and component costs are high in 2026, and the Googlebook has to justify its premium against mature alternatives. Features that only help if you already live in Google's ecosystem will narrow the audience.

4. Do the gaps get filled? Early comparison pieces note practical limits, such as no direct OneDrive support in the Files app, and questions about how freely you can run multiple instances of the same app. Availability is also limited for now to the seven launch markets, which leaves much of the world waiting.

Who should care right now

Android power users who already juggle files and messages between phone and laptop will feel the benefit first.
Gemini and Google Workspace regulars get the most from Magic Pointer, since the best examples lean on Gmail, Calendar and Google apps.
Developers should treat this as a nudge to polish large-screen and input handling. Googlebook support is also good for the wider Android tablet and foldable experience.
Cautious buyers should wait for independent reviews. A first-generation platform with a headline AI feature is the classic case where the second batch of reviews is more useful than the first.

The bottom line

The Googlebook is the most ambitious thing Google has done in personal computing in years, and it's ambitious in the right place. Rather than bolting a chatbot onto a laptop, Google is rethinking the most basic interaction on the machine, pointing at things, and pairing it with a phone relationship that rivals can't easily copy.

Whether it becomes as significant as the Chromebook did in 2011 depends on one thing: whether Gemini feels useful when you're not watching a keynote. If the pointer earns its place in your daily routine, Google has a new category. If it doesn't, it has an expensive Chromebook with a glowing stripe.

We'll know within a few months. For now, it's the most interesting laptop launch of the year, and a reminder that the next big shift in computing may not come from a new screen or chip, but from the humble cursor.

Published via ZyVOP — Write once in Markdown, auto-backup to GitHub, and syndicate to Dev.to, Medium & Hashnode in 1 click.