Documentation
¶
Overview ¶
Package hub implements the faros hub server.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrAnonymousProviderCaller = errors.New("anonymous caller")
ErrAnonymousProviderCaller is returned by the tenant resolver when the caller carries no bearer token. The backend proxy treats this as a non-error "forward without identity headers" so unauthenticated probes (health checks, smoke tests) work without provider auth.
Functions ¶
func NewScheme ¶
NewScheme builds a runtime.Scheme containing all types needed by the multicluster manager: core k8s types, faros CRDs, tenancy CRDs, and the kcp SDK types required by multicluster-provider internals.
func WithPortalSecurityHeaders ¶
WithPortalSecurityHeaders wraps a portal handler to set a Content-Security- Policy permitting provider iframes proxied through the hub. The policy allows same-origin frames (every /ui/providers/{name}/* path is hub-proxied, so same-origin from the browser's perspective) and optional platform-owned frame sources such as App Studio preview hosts.
Applied to both the embedded portal SPA and the --portal-dev-url proxy so the dev experience matches production.
Types ¶
type Options ¶
type Options struct {
DataDir string
ListenAddr string
Kubeconfig string
ExternalKCPKubeconfig string
IDPIssuerURL string
// IDPBrowserAuthURL optionally overrides only the OIDC authorization
// endpoint placed in browser redirects. Discovery, token exchange, JWKS,
// and issuer validation continue to use IDPIssuerURL.
IDPBrowserAuthURL string
IDPClientID string
// DisableTokenLogin removes the interactive static-token login: the
// /auth/token-login endpoint is not registered and /healthz advertises
// tokenLogin=false so the portal hides its token form. Static bearer
// tokens keep authenticating API/MCP/CLI calls — only the browser login
// path is disabled. Use with OIDC so humans sign in with a username and
// password at the IdP.
DisableTokenLogin bool
// PublishedAppsDomain is the DNS zone published template instances are
// served under (e.g. "apps.faros.example"). When set, the hub mounts the
// login-time published-app authorize/exchange endpoints and only ever
// redirects sign-ins back to hosts directly under this zone. Empty
// disables published-app auth entirely.
PublishedAppsDomain string
// IDPCAFile is a path to a PEM-encoded CA bundle used to verify the IdP's
// TLS certificate. Required when IDPIssuerURL is https and uses a cert
// not signed by a system trust anchor (e.g. the dev Dex deployment).
IDPCAFile string
ServingCertFile string
ServingKeyFile string
HubExternalURL string
HubInternalURL string // Internal URL for kcp mount resolution (avoids CDN/proxy loops)
// ProviderInternalURL, when set, is the server URL baked into the minted
// provider kubeconfig instead of HubExternalURL. Use it when provider pods
// reach the hub front-proxy at a different address than browsers do — e.g.
// a kind pod dialing https://host.docker.internal:9443 while browsers use
// https://localhost:9443.
ProviderInternalURL string
DevMode bool
StaticAuthTokens []string
// AdminUsers is the allowlist of platform-admin identities permitted to
// reach the /api/admin/* surface and the portal's /bonkers area. Each entry
// matches a User CR by name, email, or rbacIdentity (case-insensitive).
// Empty disables the admin surface entirely.
AdminUsers []string
// Providers is the list of first-party builtin providers to materialize
// into root:faros:providers at bootstrap. The flag accepts a comma-
// separated list or repeats; see cmd/faros-hub/main.go for the default.
// Empty/nil enables every known builtin (kcp.BuiltinProviderNames()).
// Dependencies between builtins are validated at hub startup — see
// pkg/hub/kcp.builtinEntries[].Requires.
Providers []string
// GraphQLAddr is the address of an external GraphQL gateway to proxy /graphql/ requests to.
// If empty and EmbeddedGraphQL is false, the graphql proxy is disabled.
GraphQLAddr string
// EmbeddedGraphQL runs the GraphQL listener+gateway in-process alongside the hub.
// When true, GraphQLAddr is ignored.
EmbeddedGraphQL bool
// GraphQL listener options (used when EmbeddedGraphQL is true).
GraphQLAPIExportSliceName string // APIExportEndpointSlice name (default: "core.faros.sh")
GraphQLAPIExportLogicalCluster string // logical cluster of that endpointslice (default: "root:faros:providers")
GraphQLGRPCAddr string // in-process gRPC address (default: "localhost:50051")
GraphQLPlayground bool // enable playground UI
GraphQLPort int // port for the embedded GraphQL HTTP server; 0 = serve via hub mux only
// PortalDevURL, when set, reverse-proxies /ui/* to this URL (typically
// a Vite dev server, e.g. http://localhost:3000). Takes precedence over the
// embedded portal dist (if built with -tags portal_embed).
PortalDevURL string
// PortalFrameSources are additional CSP frame-src source expressions allowed
// by the portal. Keep this narrow; provider UIs are still same-origin through
// the hub, while platform-owned preview hosts can be added explicitly.
PortalFrameSources []string
// Embedded kcp options
EmbeddedKCP bool // Enable embedded kcp server
KCPRootDir string // Root directory for kcp data (default: <DataDir>/kcp)
KCPSecurePort int // Secure port for kcp API server (default: 6443)
KCPBindAddress string // Bind address for kcp API server (default: "127.0.0.1")
KCPBatteriesInclude string // Comma-separated list of batteries to include (default: "admin,user")
KCPTLSCertFile string // TLS certificate file for kcp API server
KCPTLSKeyFile string // TLS key file for kcp API server
// KCPShardExternalURL is the URL kcp publishes into APIExportEndpointSlice
// and CachedResourceEndpointSlice statuses for outside consumers to dial.
// Empty defaults to kcp's auto-detected external address, which for an
// embedded kcp bound to 127.0.0.1 is "https://127.0.0.1:6443" — fine for
// host-side clients, broken for clients running in a kind pod (they
// resolve 127.0.0.1 to the pod itself). Override with e.g.
// "https://host.docker.internal:6443" for kind-based dev setups.
KCPShardExternalURL string
// KCPShardVirtualWorkspaceURL must be set alongside KCPShardExternalURL.
// The two URLs cover different slots in Shard.spec — externalURL feeds
// generic outside-clients discovery, virtualWorkspaceURL is what
// APIExportEndpointSlice / CachedResourceEndpointSlice publish in their
// status.endpoints[]. For a single-shard embedded dev setup both want
// the same value.
KCPShardVirtualWorkspaceURL string
}
Options holds configuration for the hub server.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package admin implements the platform-admin surface mounted at /api/admin/* and surfaced in the portal's gated /bonkers area.
|
Package admin implements the platform-admin surface mounted at /api/admin/* and surfaced in the portal's gated /bonkers area. |
|
Package appauth is the hub's login-time authorization endpoint for published applications.
|
Package appauth is the hub's login-time authorization endpoint for published applications. |
|
Package bootstrap embeds bootstrap resources for hub initialization.
|
Package bootstrap embeds bootstrap resources for hub initialization. |
|
controllers
|
|
|
mcpserver
Package mcpserver reconciles MCPServer objects.
|
Package mcpserver reconciles MCPServer objects. |
|
organization
Package organization implements the bootstrap controller that gives every User a personal Organization on creation (per docs/organizations.md §Personal Org).
|
Package organization implements the bootstrap controller that gives every User a personal Organization on creation (per docs/organizations.md §Personal Org). |
|
softdelete
Package softdelete implements roadmap step 8: the soft-delete reconciler that honours the 30-day grace window from docs/organizations.md decisions O-8 (User delete) and O-13 (Org + Workspace delete).
|
Package softdelete implements roadmap step 8: the soft-delete reconciler that honours the 30-day grace window from docs/organizations.md decisions O-8 (User delete) and O-13 (Org + Workspace delete). |
|
Package kcp bootstraps kcp API resources.
|
Package kcp bootstraps kcp API resources. |
|
Package mcpaggregate serves the hub's always-on aggregate MCP endpoint.
|
Package mcpaggregate serves the hub's always-on aggregate MCP endpoint. |
|
Package providers backs the hub's pluggable-provider extension surface: an in-memory routing table, reverse proxies for /ui/providers/{name}/* and /services/providers/{name}/*, and the controller that keeps the table in sync with ProviderCatalogEntry resources.
|
Package providers backs the hub's pluggable-provider extension surface: an in-memory routing table, reverse proxies for /ui/providers/{name}/* and /services/providers/{name}/*, and the controller that keeps the table in sync with ProviderCatalogEntry resources. |
|
Package quota implements the quota checks pinned by decisions O-5 (Org quota = soft cap, admin-overridable per User; default 10) and O-6 (Workspace quota = soft cap, admin-overridable per Org; default 50) in docs/organizations.md.
|
Package quota implements the quota checks pinned by decisions O-5 (Org quota = soft cap, admin-overridable per User; default 10) and O-6 (Workspace quota = soft cap, admin-overridable per Org; default 50) in docs/organizations.md. |
|
Package restapi implements roadmap step 10: the hub-mediated REST surface for Org / Workspace / Membership / User CRUD per docs/organizations.md decision O-10 ("Org workspaces are hub-mediated only"), plus the undelete actions wired to PR #212's soft-delete reconciler, the self-leave / role PATCH from O-12, and the ?cascade=true shortcut from O-9.
|
Package restapi implements roadmap step 10: the hub-mediated REST surface for Org / Workspace / Membership / User CRUD per docs/organizations.md decision O-10 ("Org workspaces are hub-mediated only"), plus the undelete actions wired to PR #212's soft-delete reconciler, the self-leave / role PATCH from O-12, and the ?cascade=true shortcut from O-9. |
|
Package serviceaccounts implements roadmap step 9 (O-14): bot identity for child Workspaces via native kube `core/v1.ServiceAccount`s marked with faros annotations.
|
Package serviceaccounts implements roadmap step 9 (O-14): bot identity for child Workspaces via native kube `core/v1.ServiceAccount`s marked with faros annotations. |
|
Package tenant implements the hub-side tenant middleware described in docs/organizations.md §Switch the active context.
|
Package tenant implements the hub-side tenant middleware described in docs/organizations.md §Switch the active context. |
|
Package workloadidentity owns the production provider-action workload capability exchange.
|
Package workloadidentity owns the production provider-action workload capability exchange. |