system:serviceaccount:billingprefixkubernetes service accountProduction cluster · 2 routers · inferenceMachine Identity
BindingsEnterprise
Naming the callers that may use an issuer's tokens, and the routers each may reach.
A binding connects a caller, identified by the subject in its tokens, to the routers it may use. Bindings belong to an organization and are managed under Machine identity bindings in that organization's settings; bindings on the account's own routers are on the Bindings tab in Account Settings. An organization creates bindings on issuers it is authorized for.
Creating a binding
A binding is created in six steps:
- In the organization, open Settings, then Machine identity, and select Add binding.
- Choose the Issuer, and the Caller type: Kubernetes service account or CI job.
- Choose the Match, This exact subject or Anything under a prefix, and enter the Subject.
- Under Routers this binding may use, add one or more routers.
- Under What this binding allows, Send inference requests is always granted; turn on List available models when the caller lists models.
- Select Create binding.
Subjects
The subject is the token's sub value, which names the caller. Its form depends on the platform:
| Platform | Subject example |
|---|---|
| Kubernetes | system:serviceaccount:payments:api |
| GitHub Actions, a branch | repo:example-co/billing:ref:refs/heads/main |
| GitHub Actions, a job with an environment | repo:example-co/billing:environment:production |
| GitHub Actions, a pull request | repo:example-co/billing:pull_request |
Subjects are case sensitive, up to 700 bytes, with no surrounding spaces. A GitHub job that declares an environment uses the environment form, so a binding for a branch matches jobs without one; an organization that customizes GitHub's subject format uses its own form.
Matching
A binding matches subjects in one of two ways:
| Match | Matches | Available on |
|---|---|---|
| This exact subject | One subject. | Every issuer. |
| Anything under a prefix | The prefix itself, and subjects that continue it after a colon. | Cluster issuers and GitHub Actions. |
Prefixes follow these rules:
| Issuer | Prefix rule | Example |
|---|---|---|
| Cluster | Stops after the namespace, and covers every service account in it. | system:serviceaccount:payments |
| GitHub Actions | Starts with a complete owner and repository, and can go deeper. | repo:example-co/billing |
Prefixes match at the colon between parts, so repo:example-co/billing covers repo:example-co/billing:ref:refs/heads/main and leaves repo:example-co/billing-v2 out. Prefixes are literal text, without wildcards such as *. When several bindings in an organization match a subject, an exact binding wins, then the longest prefix, and the binding chosen applies even when it is disabled.
Routers
A binding names 1 to 100 routers of its organization, by router id rather than alias. With one router, a caller sends only the base URL and its token, and requests go to that router. With several, each request names its router in the model field as multi-router/rt_9Hk3Ws7PzQ or in the x-mr-router header; when both are present, the model field wins.
Permissions
A binding allows inference, and optionally listing models:
| Permission | Scope | Allows |
|---|---|---|
| Send inference requests | inference | Requests to the binding's routers. Always on. |
| List available models | models:read | GET /v1/models, listing the models of the binding's router, or of the router named in x-mr-router when it has several. |
Bindings across organizations
A subject belongs to one organization: a binding that overlaps another organization's binding, as the same subject or one prefix inside another, is refused with a message naming the organization. Within one organization, overlapping bindings are allowed and resolved by the matching order above, and each subject and match pair is bound once.
Kubernetes UID changes
For an exact Kubernetes binding, Multi-Router remembers the service account's unique id from its first token. When a later token carries a different id, the binding shows UID changed, meaning the service account was deleted and recreated, or the name now belongs to something else. Requests keep being served; review the binding and disable it if the change was unexpected.
Editing and deleting
Editing a binding changes everything except its issuer. Binding enabled turns it off and on, and deleting it stops the caller from authenticating. Changes take effect across Multi-Router within about a minute. An issuer holds up to 1,000 bindings.