Kayra
Kayra is the authentication, namespace creation and IAM policy service,
built on infrapi/lib. Cluster-wide
API registrations, per-tenant namespaces and the
subscriptions linking them sit behind one bearer-auth and
cluster-RBAC model, with a separate kayra reconciler process turning
disabled records active.
Where to start#
| I want to… | Go to |
|---|---|
| Run Kayra for the first time | Getting started |
| Understand how the pieces fit together | Architecture overview |
| See who can authenticate and who can manage what | RBAC & auth |
| Create or update an API registration | API registrations |
| Create or update a tenant | Namespaces |
| Subscribe a tenant to an API registration, or trigger reconcile | Subscriptions & reconciliation |
Run a command (serve, reconciler, cache clean, token mint) or use kayra-cli | CLI |
Look up one internal/* package’s API | Packages |
| Build, test, or work on the docs themselves | Development |
Packages#
Package-by-domain, not package-by-layer: each package below owns its own types, storage and HTTP handlers together.
| Package | Owns |
|---|---|
internal/config | Loading and validating kayra.yaml |
internal/store | etcd / local storage backend |
internal/crypto | PAT encryption, self-signed JWT signing |
internal/oidc | Discovery/JWKS fetch, caching, own endpoints |
internal/authn | Verifying a bearer token, resolving its user id |
internal/authz | Resolving a user id to groups/attributes (LDAP or fixture) |
internal/middleware | The two gin auth middlewares (general + sysadmin) |
internal/rbac | Group/Role/RoleBinding, cluster + namespace scoped |
internal/catalog | ApiRegistration/Namespace/Subscription + the reconciler (see API registrations, Namespaces, Subscriptions & reconciliation) |
internal/tokenapi | Personal access token issuance |
internal/oauth2broker | Server-side relay for kayra-cli login’s browser-based OAuth2 flow |
internal/httpapi | RFC 9457 error response helper |
internal/apiserver | Wires every package above onto one gin engine |
cmd/kayra wires all of it together; cmd/cli depends on none of it.
The client side has its own two packages, used only by cmd/cli:
| Package | Owns |
|---|---|
internal/oauth2login | The CLI-side half of the browser-based OAuth2 login flow |
internal/clicontext | cmd/cli’s own ~/.config/kayra/config (kubeconfig-style contexts) |