Upgrading to 0.20

​

What changes

• Reach without a policy widens. In 0.11 a project-scoped credential that resolved no policy was refused with no_policy. In 0.20 a request whose ladder links no pools reaches the host keys owned by its project, its team and the system, or for a personal account the user’s own and the system’s. Host keys created with the admin token are system-owned, so every such request can use them. To keep a team or project on specific keys, bind its account a policy that links the pools it should use; see Reach without a linking rung.
• Bindings on users apply to their member accounts. A 0.11 binding owned by a project and naming a user becomes a binding of that user’s member account in the project. It governs requests in that account: the user’s inference tokens for the project, and relay keys created in the account. The user’s existing keys run in the personal account and are not governed by it.
• Inference tokens run in a member account. A token runs in its user’s member account in the token’s project. A user who holds a role in that project directly, or whom a 0.11 project binding names, has one after the upgrade. A user whose access to the project comes only through a group or a team-level role has none until the next mint creates it: tokens minted before the upgrade answer 403 account_not_held, and the user mints new ones.
• Rate-limit and budget counters start over. They are now kept per account, so the counts and spend of the current windows and periods begin at zero at the upgrade.
• Every host key has an account. The upgrade puts each host key without one into an account per owner and host, marked groupedByRelay. A key saved later must name its account (400 account_required otherwise): create the account, then add keys. A 429 from the provider on a key in a grouped account still goes to that key’s breaker and the request fails over to the next key, as in 0.11; a 429 in any other account cools the account for the requested model. Set a grouped account’s orgId once you know its keys share one provider organization, or split its keys into an account per organization. See Accounts grouped by the upgrade.
• Deprecated models are granted like any other. A provider reference covers them, and a request whose ladder lists no models may call them.
• Usage events carry lane_account_id, the account the request ran in, and refusal on the requests Relay refused itself, which are now recorded with the status and message the caller received. policy_id records the innermost caller policy: the lane’s, else the project’s, else the team’s. See Usage.
• Proxy mode refuses a model that is not in the catalog, also for a key that had no policy, instead of forwarding it unpriced.
• Batch items run under the ladder as it is when each item runs, not as it was at submission.
• Error codes. no_policy, policy_not_found, policyless_disabled and project_unavailable are gone; subject_disabled, duplicate_binding, unpriced_under_budget, budget_exceeded, account_closed and account_not_held are new. A request whose every host key is out of rotation answers 503 no_healthy_keys, where 0.11 answered 502 upstream_error. Relay’s own refusals carry error.refusal (model_not_allowed, host_not_reachable or no_capacity). model_not_allowed names the rung and the policy that refused. A disabled, revoked, expired or rotated-out relay key answers 401 invalid api key. See Errors.

​

What the migrations do

migration 000035: a subject may be bound by one policy binding (a user by one per owner scope); remove the subject from all but one binding, then upgrade again: serviceaccount <id> in <binding>, <binding>

000036: dropping link: key "ci-runner" -> policy "ci"
000036: dropping link: host key "anthropic-main" -> tier policy "anthropic-start"
000036: dropping link: service account "legacy-api" -> policy "ci"
000036: dropping link: policy "ci" -> host key "anthropic-main"
000036: dropping link: policy "ci" -> model "claude-haiku-4-5"
000036: dropping link: policy "ci" -> rate limit "ci-rpm"
000036: dropping link: policy "anthropic-start" -> rate limit "anthropic-start-rl" for models anthropic/claude-opus-5-5, anthropic/claude-sonnet-5-5
000036: binding no longer applies: policy binding "project-default" (policy "users") -> group "system:authenticated"
000036: binding narrows to project tokens: policy binding "project-alice" (policy "users") -> user "alice" governs only tokens in project "dev", not personal keys

• Accounts. It creates a team account per team, a project account per project, a personal account per user and an account per service account, and a member account for each user an enabled role binding names directly at a team or project. They are named as in Accounts Relay makes.
• Relay keys. Every key gets accountId: a service account’s key its service account’s account, a user’s key the user’s personal account.
• Binding subjects become accounts. A service account becomes its account. A user named by a binding owned by a project becomes the user’s member account in that project, created when no role binding made one; such an account serves inference tokens only. A binding owned by a team, the system or the user fans a user out to every account of theirs it covered: the user’s member accounts in the team and its projects, the personal account and every member account, or the personal account alone. A team or project subject becomes its account, and a host key’s subject its provider account. Group subjects, and host key subjects whose key has no account, bind nothing and are dropped, each logged:
  000039: dropping policy-binding subject: binding "project-default" -> group "system:authenticated" (only accounts are bound)
  
  Bindings lose projectId and subjects and keep their owner.
• Policy models. @host is stripped from every reference in models and in rate-limit links’ models, duplicates are removed, and each policy whose models change is logged: 000039: policy "ci": models ["openai/gpt-4o-mini@openai", "openai/gpt-4o-mini"] become ["openai/gpt-4o-mini"]. A policy no binding uses that named only hosts is left with models: [], which allows every model its pools serve: set its models before you bind it.
• Links. Each budget link becomes a budgets entry, and every rate-limit and budget link is shared: true. A host key a policy linked directly becomes a pool of that one key, named after the key and owned like it, linked after the policy’s pools; each is logged as 000039: host key "<key>" linked directly by a policy is now pool "<pool>".
• Payload logging. Each account an enabled binding ties to a policy gets payloadLogging: on where the policy had payloadLoggingEnabled: true, and off where it did not, so the policy’s decision over the keys’ own flags stands. includeDeprecated, payloadLoggingEnabled, credentialIds and budgetIds are removed from every policy.

• A bound policy names only hosts in models (such as ["@ollama-self"]). Stripping the hosts would leave it allowing every model.
  migration 000039: these bound policies name only hosts in models, which would widen them to every model; name the providers or models they allow, then upgrade again: <policy>, <policy>
  
  Fix: replace the references with the providers or models the policy allows (ollama, ollama/llama-4), or unbind the policy.
• A bound policy pins a host for a provider served at other hosts (such as anthropic/claude-haiku-4-5@anthropic while the provider’s models are also bound at another host the policy can reach), and does not grant the same reference without the host. Dropping the pin would let it reach that provider elsewhere.
  migration 000039: policy models no longer pin a host, and these pinned refs would reach their provider at other hosts the policies reach; link pools at the pinned host only, or drop the refs, then upgrade again: policy <policy>: <ref>, <ref>
  
  Fix: remove the @host from the reference yourself, or the reference, and after the upgrade link the policy only to pools at that host; or unbind the policy before the upgrade and bind it again once its pools are set.
• Two bindings reach one account. For example, a binding owned by the system and the user’s own binding on one user both become the user’s personal account, and a team’s binding on a user and a binding of one of its projects on the same user both reach the user’s member account in that project. A 0.11 database cannot reach this case, since its bindings are owned by projects and name a user once per project.
  migration 000039: policy-binding subjects become accounts, and an account is bound by one policy binding; remove the subject from all but one of the bindings listed for each account, then upgrade again: account <account> in <binding>, <binding>
  
  Fix: remove the subject from all but one of the bindings listed.

000039: caller rate-limit and budget counters are now kept per account, so their counts start over at this upgrade
000039: a token runs in its user's member account in the token's project; a user granted the project only through a group or a team role has none until they mint a new token, so tokens minted before the upgrade are refused with account_not_held until then

​

Before you upgrade

1. Export the current configuration with the 0.11 CLI, as the reference for the rewrite:
   relay export --include-system -o before-0.20.yaml
   
2. Export the links migration 36 drops and the bindings it changes, by name. The query only reads; run it against the 0.11 database and keep the result for Re-creating the dropped links:
   SELECT 'key -> policy' AS link, k.name AS source, COALESCE(p.name, k.spec->>'policyId') AS target, NULL AS models
   FROM relay_keys k LEFT JOIN policies p ON p.id = k.spec->>'policyId'
   WHERE COALESCE(k.spec->>'policyId', '') <> ''
   UNION ALL
   SELECT 'host key -> tier policy', s.name, COALESCE(p.name, s.spec->>'policyId'), NULL
   FROM secrets s LEFT JOIN policies p ON p.id = s.spec->>'policyId'
   WHERE COALESCE(s.spec->>'policyId', '') <> ''
   UNION ALL
   SELECT 'service account -> policy', sa.name, COALESCE(p.name, sa.spec->>'policyId'), NULL
   FROM service_accounts sa LEFT JOIN policies p ON p.id = sa.spec->>'policyId'
   WHERE COALESCE(sa.spec->>'policyId', '') <> ''
   UNION ALL
   SELECT 'binding -> group (no longer applies)', b.name, s.subject_name, p.name
   FROM policy_binding_subjects s
   JOIN policy_bindings b ON b.id = s.binding_id
   JOIN policies p ON p.id = b.policy_id
   WHERE s.kind = 'group'
   UNION ALL
   SELECT 'binding -> user (member account in the project)', b.name, COALESCE(u.username, s.subject_id), pr.name
   FROM policy_binding_subjects s
   JOIN policy_bindings b ON b.id = s.binding_id
   JOIN policies p ON p.id = b.policy_id
   JOIN projects pr ON pr.id = b.project_id
   LEFT JOIN users u ON u.id = s.subject_id
   WHERE s.kind = 'user'
   UNION ALL
   SELECT 'policy -> host key', p.name, s.name, NULL
   FROM policy_host_keys l JOIN policies p ON p.id = l.policy_id JOIN secrets s ON s.id = l.host_key_id
   UNION ALL
   SELECT 'policy -> model', p.name, m.name, NULL
   FROM policy_models l JOIN policies p ON p.id = l.policy_id JOIN models m ON m.id = l.model_id
   UNION ALL
   SELECT 'policy -> rate limit', p.name, rl.name, NULL
   FROM policies p JOIN rate_limits rl ON rl.id = p.rate_limit_id
   UNION ALL
   SELECT 'policy -> rate limit for models', p.name, COALESCE(rl.name, b->>'rateLimitId'), b->>'models'
   FROM policies p
   CROSS JOIN LATERAL jsonb_array_elements(CASE WHEN jsonb_typeof(p.spec->'rlBindings') = 'array' THEN p.spec->'rlBindings' ELSE '[]' END) AS b
   LEFT JOIN rate_limits rl ON rl.id = b->>'rateLimitId'
   ORDER BY 1, 2, 3;
   
   With the query saved as dropped-links.sql:
   psql "$RELAY_PG_DSN" --csv -f dropped-links.sql > dropped-links.csv
   
   Host keys are the rows of the secrets table. For binding -> group and binding -> user rows the models column holds the policy name and project name; these bindings are not dropped but change: group subjects bind nothing after the upgrade, and a user subject becomes the user’s member account in that project. The migration logs the same dropped links as it drops them.
3. Back up Postgres. Rolling back needs it; see Rolling back.
4. Find subjects bound twice, which would stop migration 35. Run this against the 0.11 database; it lists what the migration would refuse:
   SELECT s.kind, s.subject_id, string_agg(b.name, ', ' ORDER BY b.name) AS bindings
   FROM policy_binding_subjects s
   JOIN policy_bindings b ON b.id = s.binding_id
   WHERE s.subject_id IS NOT NULL
   GROUP BY s.kind, s.subject_id, CASE WHEN s.kind = 'user' THEN b.project_id END
   HAVING count(*) > 1;
   
   For each row, decide which binding keeps the subject and remove it from the others, on 0.11, before upgrading.
5. Check for policies that migration 36 would refuse. A policy with rows in policy_models and an empty models field, or any rows in policy_host_keys (a 0.11 database has no pools or credentials to keep a restriction), would become unrestricted once those tables are dropped; if it is bound to a non-group subject—disabled bindings count—the migration stops. Run this against the 0.11 database to find them:
   SELECT p.name AS policy, l.lost AS would_lose, l.bindings
   FROM policies p
   CROSS JOIN LATERAL (
       SELECT concat_ws(' and ',
                  CASE WHEN EXISTS (SELECT 1 FROM policy_models pm WHERE pm.policy_id = p.id)
                        AND (CASE WHEN jsonb_typeof(p.models) = 'array' THEN jsonb_array_length(p.models) ELSE 0 END) = 0
                       THEN 'model ids' END,
                  CASE WHEN EXISTS (SELECT 1 FROM policy_host_keys phk WHERE phk.policy_id = p.id)
                       THEN 'host keys' END) AS lost,
              (SELECT string_agg(DISTINCT b.name, ', ' ORDER BY b.name)
               FROM policy_bindings b JOIN policy_binding_subjects s ON s.binding_id = b.id
               WHERE b.policy_id = p.id AND s.subject_id IS NOT NULL) AS bindings
   ) l
   WHERE l.lost <> '' AND l.bindings IS NOT NULL;
   
   For each row, the migration stops and reports: migration 000036: bound policies would lose their only model or host-key restriction and widen; …: policy <name> loses its <what> (bound by <bindings>). Adding models or pools before upgrading is not possible—the pools table exists only in 0.20. On the 0.11 database, delete those bindings or remove those policies from them, then upgrade. After upgrading, add models or pools following Re-creating the dropped links.
6. Check for policies that migration 39 would refuse: bound policies whose models name only hosts, and pinned references whose provider is served at another host. Run this against the 0.11 database:
   WITH bound AS (
       SELECT DISTINCT b.policy_id
       FROM policy_bindings b JOIN policy_binding_subjects s ON s.binding_id = b.id
       WHERE s.kind IN ('user', 'serviceaccount') AND s.subject_id IS NOT NULL
   ),
   refs AS (
       SELECT p.id, p.name, p.models, e.value AS ref
       FROM policies p JOIN bound ON bound.policy_id = p.id
       CROSS JOIN LATERAL jsonb_array_elements_text(CASE WHEN jsonb_typeof(p.models) = 'array' THEN p.models ELSE '[]' END) AS e(value)
   )
   SELECT name AS policy, 'names only hosts' AS problem, models::text AS refs
   FROM refs GROUP BY id, name, models
   HAVING bool_and(split_part(ref, '@', 1) = '')
   UNION ALL
   SELECT r.name, 'pins a host its provider is not limited to', string_agg(r.ref, ', ')
   FROM refs r
   WHERE r.ref LIKE '%_@%' AND NOT r.models ? split_part(r.ref, '@', 1)
     AND EXISTS (
         SELECT 1 FROM host_bindings hb
         JOIN models m ON m.id = hb.model_id
         JOIN providers pr ON pr.id = m.metadata->'owner'->>'id'
         WHERE pr.name = split_part(split_part(r.ref, '@', 1), '/', 1)
           AND hb.host_id IS DISTINCT FROM (SELECT id FROM hosts WHERE name = split_part(r.ref, '@', 2)))
   GROUP BY r.id, r.name
   ORDER BY 1, 2;
   
   Fix each row on 0.11 with PUT /api/policies/by-id/{id}, as described for each case under Migration 39, or unbind the policy. Callers stay off the inference port until your new pools are linked (step 1 of Upgrade steps), so dropping a pin before the upgrade does not widen live traffic.
7. Write the new manifests in relay.wyolet.dev/v1alpha3, from the exports; Re-creating the dropped links maps each dropped link to its replacement:
   • An Account for each provider organization, and account on each of its host keys. A key you leave without one stays in the account the upgrade grouped it into.
   • A PolicyBinding of a tier preset (or your own tier policy) on each provider account, replacing the host keys’ policyId. List a host’s presets with GET /api/hosts/{host}/policies.
   • A Pool for each set of host keys a policy listed, with the old keySelection as its selection.
   • Each policy with pools, rateLimits and, where you want spend caps, budgets ([{ref}] entries). models names providers and models, never hosts.
   • A Budget linked by the team’s or project’s policy in place of a team or project budget.
   • Policy bindings on the accounts the keys and service accounts pointed at, and on the team’s or project’s account in place of group and system:authenticated subjects. Bindings name accounts, with the owner in metadata.owner.
   • payloadLogging on the accounts whose traffic you capture, in place of a policy’s payloadLoggingEnabled.
   • No priority on bindings, and no policies or defaultPolicy on hosts.
   Policy examples shows each of these.
8. Pick the catalog release. Set RELAY_CATALOG_VERSION to the relay-catalog release with the v1alpha3 schema that is published for 0.20. A release in the older schema is refused by 0.20.

​

Upgrade steps

1. Keep callers off the inference port until step 5. Between the migration and your new bindings, accounts reach what their scopes own, which may be more than before.
2. Stop every 0.11 pod: scale the deployment to 0, as in Stop-and-start upgrades.
3. Deploy 0.20 with the new RELAY_CATALOG_VERSION. Migrations 35 to 39 run, and the catalog release is seeded. Keep the log of the pod that ran the migrations, or of relay migrate up if you migrate in a step of its own: it holds the 000036: dropping link and 000039: lines. A migration that stops applies nothing of itself but leaves its version marked dirty (see Recovering from a dirty schema version):
   • Migration 35 stopped: run relay migrate force 34, start the 0.11 image again, fix the bindings, and repeat.
   • Migration 39 stopped: migrations 35 to 38 are applied, and no image serves that schema. Either run relay migrate force 38, fix the listed rows in Postgres (for example UPDATE policies SET models = '["ollama"]' WHERE name = '<policy>';), and deploy 0.20 again; or restore the backup, fix the rows on 0.11, and repeat the upgrade.
4. Apply the manifests with the 0.20 CLI, dry run first:
   relay apply -f manifests/ --dry-run
   relay apply -f manifests/
   
5. Check representative credentials, then let callers back in:
   curl http://localhost:8080/v1/models -H "Authorization: Bearer <relay key>"
   curl -H "Authorization: Bearer $RELAY_ADMIN_TOKEN" http://localhost:8081/api/keys/<key>/limits
   curl -H "Authorization: Bearer $RELAY_ADMIN_TOKEN" http://localhost:8081/api/plan-issues
   
   Watch relay_inference_auth_rejected_total and the refusal values in the usage events for refusals you did not expect.
6. Re-run token revocations, see The state store. Tell users whose project access comes through a group or a team-level role to mint new inference tokens.

​

Re-creating the dropped links

​

A host key’s tier

apiVersion: relay.wyolet.dev/v1alpha3
kind: PolicyBinding
metadata:
  name: anthropic-tier
  owner: {kind: system}
spec:
  policy: anthropic-start
  accounts: [anthropic]

apiVersion: relay.wyolet.dev/v1alpha3
kind: Account
metadata:
  name: openai-build-org
  owner: {kind: system}
spec:
  host: openai
---
apiVersion: relay.wyolet.dev/v1alpha3
kind: HostKey
metadata:
  name: openai-build-key
  owner: {kind: system}
spec:
  hostId: openai
  account: openai-build-org
  valueFrom: {kind: env, env: OPENAI_BUILD_KEY}
---
apiVersion: relay.wyolet.dev/v1alpha3
kind: PolicyBinding
metadata:
  name: openai-build-org-tier
  owner: {kind: system}
spec:
  policy: openai-build
  accounts: [openai-build-org]

​

A relay key’s policy

apiVersion: relay.wyolet.dev/v1alpha3
kind: Pool
metadata:
  name: anthropic-main
  owner: {kind: system}
spec:
  host: anthropic
  credentials: [anthropic-main]
---
apiVersion: relay.wyolet.dev/v1alpha3
kind: Policy
metadata:
  name: ci
  owner: {kind: project, name: legacy}
spec:
  models: [anthropic/claude-haiku-4-5]
  pools: [anthropic-main]
---
apiVersion: relay.wyolet.dev/v1alpha3
kind: PolicyBinding
metadata:
  name: ci-runner
  owner: {kind: project, name: legacy}
spec:
  policy: ci
  accounts: [sa-legacy-ci-runner-0d9f1a2b]

apiVersion: relay.wyolet.dev/v1alpha3
kind: RateLimit
metadata:
  name: alice-rpm
  owner: {kind: system}
spec:
  rules:
    - {meter: requests, amount: 60, window: 1m, strategy: sliding-window}
---
apiVersion: relay.wyolet.dev/v1alpha3
kind: Policy
metadata:
  name: alice
  owner: {kind: system}
spec:
  models: [anthropic]
  rateLimits:
    - ref: alice-rpm
---
apiVersion: relay.wyolet.dev/v1alpha3
kind: PolicyBinding
metadata:
  name: alice
  owner: {kind: system}
spec:
  policy: alice
  accounts: [user-alice]

apiVersion: relay.wyolet.dev/v1alpha3
kind: PolicyBinding
metadata:
  name: alice-own
  owner: {kind: user, name: alice}
spec:
  policy: alice-bot
  accounts: [user-alice]

​

The state store

• Control-plane sessions end: users sign in again.
• Rate-limit windows and key breaker state start fresh.
• Revoked inference tokens are accepted again until they expire.

old="redis-cli -h <old store> -a <password>"
new="redis-cli -h <new store> -a <password>"
$new SET '{revoked}:tokens' "$($old --raw GET '{revoked}:tokens')" EX "$($old TTL '{revoked}:tokens')"

​

Rolling back