This reference documents all CRD types exposed by the Nebari Operator. For configuration examples and usage guides, see the Configuration Reference.
Package v1 contains API Schema definitions for the reconcilers v1 API group.
AuthConfig specifies authentication/authorization configuration.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
enabled boolean |
Enabled determines whether authentication should be enforced for this application. When true, users must authenticate via OIDC before accessing the application. |
false | Optional: {} |
provider string |
Provider specifies the OIDC authentication provider to use. Supported values: keycloak, generic-oidc |
keycloak | Enum: [keycloak generic-oidc] Optional: {} |
redirectURI string |
RedirectURI specifies the OAuth2 callback path for the application. If not specified, defaults to "/oauth2/callback" which is the Envoy Gateway default. For application-level auth handling, specify the app's callback path (e.g., "/auth/callback"). The full redirect URL will be: https:// |
Optional: {} |
|
clientSecretRef string |
ClientSecretRef references a Kubernetes Secret containing OIDC client credentials. The secret must be in the same namespace as the NebariApp and contain: - client-id: The OIDC client ID - client-secret: The OIDC client secret If not specified and ProvisionClient is enabled, the operator will create a secret named "-oidc-client". |
Optional: {} |
|
scopes string array |
Scopes defines the OIDC scopes to request during authentication. Common scopes: openid, profile, email, roles, groups If not specified, defaults to: ["openid", "profile", "email"] |
Optional: {} |
|
groups string array |
Groups specifies the list of groups that should have access to this application. When specified, only users belonging to these groups will be authorized. Group matching is case-sensitive and depends on the OIDC provider's group claim. |
Optional: {} |
|
provisionClient boolean |
ProvisionClient determines whether the operator should automatically provision an OIDC client in the provider. When true, the operator will create a client (e.g., in Keycloak) and store the credentials in a Secret. Only supported for provider="keycloak". Defaults to true if not specified. |
true | Optional: {} |
enforceAtGateway boolean |
EnforceAtGateway determines whether the operator should create an Envoy Gateway SecurityPolicy to enforce authentication at the gateway level. When true (default), the operator creates a SecurityPolicy that handles the OIDC flow at the gateway before requests reach the application. When false, the operator provisions the OIDC client and stores credentials in a Secret, but does NOT create a SecurityPolicy - the application is expected to handle OAuth natively (e.g., Grafana's built-in generic_oauth). |
true | Optional: {} |
forwardAccessToken boolean |
ForwardAccessToken instructs the gateway-enforced OIDC filter to forward the user's OAuth2 access token to the upstream service via the Authorization: Bearer <token> header. Use this when the applicationneeds to read the JWT itself - for example to extract the user's groups claim and apply per-user authorization decisions on top of the gateway's authentication. By default the gateway only stores the token in an encrypted session cookie that backends cannot decode. Only applies when enforceAtGateway is true. |
Optional: {} |
|
denyRedirect DenyRedirectHeader array |
DenyRedirect configures headers that, when matched, prevent the OIDC filter from redirecting to the identity provider. Instead, matching requests receive a 401 response. This prevents PKCE race conditions when SPAs fire multiple requests on page load (e.g., the main page and AJAX calls simultaneously), each of which would otherwise start a separate OAuth flow and overwrite each other's state cookies. Only applies when enforceAtGateway is true. |
Optional: {} |
|
issuerURL string |
IssuerURL specifies the OIDC issuer URL for generic-oidc provider. Required when provider="generic-oidc", ignored for other providers. Example: https://accounts.google.com, https://login.microsoftonline.com//v2.0 |
Optional: {} |
|
spaClient SPAClientConfig |
SPAClient configures a public OIDC client for browser-based authentication. When enabled, the operator provisions a separate public client for Single-Page Applications that use PKCE flows (e.g., React apps with keycloak-js). This is distinct from the confidential client used for server-side auth (oauth2-proxy). The public client is configured with: - publicClient: true (no client secret, safe for browser) - Redirect URIs: https:///* and https:// - PKCE enforcement (S256) Only supported for provider="keycloak". |
Optional: {} |
|
deviceFlowClient DeviceFlowClientConfig |
DeviceFlowClient configures a public OIDC client for CLI/native app authentication using the OAuth2 Device Authorization Grant (RFC 8628). When enabled, the operator provisions a separate public client configured for device flow. The device flow client ID is written to the OIDC client Secret under key "device-client-id". Only supported for provider="keycloak". |
Optional: {} |
|
keycloakConfig KeycloakClientConfig |
KeycloakConfig provides Keycloak-specific configuration for fine-grained control over realm resources like groups, client scopes, and protocol mappers. Only used when provider="keycloak" and provisionClient=true; silently ignored for other providers (e.g., generic-oidc). |
Optional: {} |
|
tokenExchange TokenExchangeConfig |
TokenExchange configures OAuth 2.0 Token Exchange (RFC 8693) for this client. When enabled, other NebariApp OIDC clients in the same Keycloak realm can exchange their access tokens for tokens with this client's audience. Requires KC_FEATURES=token-exchange on the Keycloak server. Only supported for provider="keycloak". |
Optional: {} |
DenyRedirectHeader defines a header match rule for preventing OIDC redirects. Requests matching any of these headers will receive a 401 instead of being redirected to the identity provider.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
name string |
Name is the header name to match against. | MinLength: 1 Required: {} |
|
type string |
Type specifies how to match the header value. Valid values: Exact, Prefix, Suffix, RegularExpression |
Exact | Enum: [Exact Prefix Suffix RegularExpression] Optional: {} |
value string |
Value is the header value to match. | MinLength: 1 Required: {} |
DeviceFlowClientConfig specifies configuration for provisioning a public OIDC client for CLI and native application authentication using the OAuth2 Device Authorization Grant.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
enabled boolean |
Enabled determines whether a public OIDC client should be provisioned for device flow. When true, the operator creates a Keycloak client configured with: - publicClient: true (no secret needed for CLI usage) - OAuth2 Device Authorization Grant enabled - standardFlowEnabled: false The device flow client ID is written to the OIDC secret for runtime consumption. |
false | Optional: {} |
GatewayReference identifies a Gateway resource.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
name string |
Name of the Gateway. | ||
namespace string |
Namespace of the Gateway. |
HealthCheckConfig defines health check parameters for a service.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
enabled boolean |
Enabled determines if health checks are performed. | false | |
path string |
Path is the HTTP path to check for health status. Common paths: /health, /healthz, /api/health |
/health | Optional: {} |
port integer |
Port is the port number to use for health checks. If not specified, defaults to the service port defined in spec.service.port. |
Maximum: 65535 Minimum: 1 Optional: {} |
|
intervalSeconds integer |
IntervalSeconds is how often to perform health checks (in seconds). | 30 | Maximum: 300 Minimum: 10 Optional: {} |
timeoutSeconds integer |
TimeoutSeconds is the request timeout for health checks (in seconds). | 5 | Maximum: 30 Minimum: 1 Optional: {} |
KeycloakClientConfig provides Keycloak-specific configuration for managing realm resources associated with a NebariApp's OIDC client.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
groups KeycloakGroup array |
Groups defines Keycloak groups to ensure exist in the realm, with optional user membership assignments. |
Optional: {} |
|
protocolMappers KeycloakProtocolMapperConfig array |
ProtocolMappers defines client-level protocol mappers to configure on the OIDC client. These are applied directly to the client (not to shared client scopes), so each NebariApp gets isolated mapper configuration. When specified, the operator's default mappers (e.g., group-membership) are not auto-created - the user's configuration takes full control. |
Optional: {} |
KeycloakGroup defines a Keycloak group to create in the realm with optional member assignments.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
name string |
Name is the group name to create in Keycloak. | MinLength: 1 Required: {} |
|
members string array |
Members is a list of Keycloak usernames that should be members of this group. Membership sync is additive-only: users in this list will be added to the group, but existing group members not in this list will NOT be removed. Users that don't exist in Keycloak will be logged as warnings but won't cause errors. |
Optional: {} |
KeycloakProtocolMapperConfig defines a protocol mapper with arbitrary configuration.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
name string |
Name of the protocol mapper. | MinLength: 1 Required: {} |
|
protocolMapper string |
ProtocolMapper is the mapper type identifier. Example: "oidc-group-membership-mapper", "oidc-usermodel-attribute-mapper" |
MinLength: 1 Required: {} |
|
config object (keys:string, values:string) |
Config is the mapper configuration as arbitrary key-value pairs. Keys and values are specific to the mapper type. Example for group-membership mapper: {"claim.name": "groups", "full.path": "false"} |
Optional: {} |
LandingPageConfig defines how a service appears on the Nebari landing page.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
enabled boolean |
Enabled determines if this service appears on the landing page. When false, the service is not shown on the landing page. |
false | |
displayName string |
DisplayName is the human-readable name shown on the landing page. Required when Enabled is true. |
MaxLength: 64 Optional: {} |
|
description string |
Description provides additional context about the service. Shown as supplementary text on the service card. |
MaxLength: 256 Optional: {} |
|
icon string |
Icon is an identifier for the service icon (e.g., "jupyter", "grafana") or a URL to a custom icon image. Supported built-in icons: jupyter, grafana, prometheus, keycloak, argocd, kubernetes |
Optional: {} |
|
category string |
Category groups related services together on the landing page. Common categories: Development, Monitoring, Platform, Data Science |
Optional: {} |
|
priority integer |
Priority determines sort order within a category (lower number = higher priority). Services are displayed in ascending priority order within each category. |
100 | Maximum: 1000 Minimum: 0 Optional: {} |
externalUrl string |
ExternalUrl overrides the default URL derived from the hostname. Use this when the service URL differs from https:// |
Optional: {} |
|
healthCheck HealthCheckConfig |
HealthCheck configures health status monitoring for this service. | Optional: {} |
NebariApp is the Schema for the nebariapps API It represents an application onboarding intent, specifying how an application should be exposed (routing), secured (TLS), and protected (authentication).
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string |
reconcilers.nebari.dev/v1 |
||
kind string |
NebariApp |
||
metadata ObjectMeta |
Refer to Kubernetes API documentation for fields of metadata. |
Optional: {} |
|
spec NebariAppSpec |
spec defines the desired state of NebariApp | Required: {} |
|
status NebariAppStatus |
status defines the observed state of NebariApp | Optional: {} |
NebariAppList contains a list of NebariApp
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string |
reconcilers.nebari.dev/v1 |
||
kind string |
NebariAppList |
||
metadata ListMeta |
Refer to Kubernetes API documentation for fields of metadata. |
||
items NebariApp array |
NebariAppSpec defines the desired state of NebariApp
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
hostname string |
Hostname is the fully qualified domain name where the application should be accessible. This will be used to generate HTTPRoute. Example: "myapp.nebari.local" or "api.example.com" |
MinLength: 1 Pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$ Required: {} |
|
service ServiceReference |
Service defines the backend Kubernetes Service that should receive traffic. | Required: {} |
|
routing RoutingConfig |
Routing configures routing behavior including path-based rules and TLS. | Optional: {} |
|
auth AuthConfig |
Auth configures authentication/authorization for the application. When enabled, the application will require OIDC authentication via supporting OIDC Provider. |
Optional: {} |
|
gateway string |
Gateway specifies which shared Gateway to use for routing. Valid values are "public" (default) or "internal". |
public | Enum: [public internal] Optional: {} |
serviceAccountName string |
ServiceAccountName is the name of the Kubernetes ServiceAccount used by the app's pods. Used for RBAC scoping of OIDC secrets so only the app's pods can read its credentials. Defaults to the NebariApp's name if omitted. |
MinLength: 1 Optional: {} |
|
landingPage LandingPageConfig |
LandingPage configures how this service appears on the Nebari landing page. When enabled, the service will be discoverable through the landing page portal. |
Optional: {} |
NebariAppStatus defines the observed state of NebariApp.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
conditions Condition array |
Conditions represent the current state of the NebariApp resource. Standard condition types: - "RoutingReady": HTTPRoute has been created and is functioning - "TLSReady": TLS certificate is available and configured - "AuthReady": Authentication policy is configured (if auth is enabled) - "Ready": All components are ready (aggregate condition) |
Optional: {} |
|
observedGeneration integer |
ObservedGeneration is the most recent generation observed for this NebariApp. It corresponds to the NebariApp's generation, which is updated on mutation by the API Server. |
Optional: {} |
|
hostname string |
Hostname is the actual hostname where the application is accessible. This mirrors the spec.hostname for easy reference. |
Optional: {} |
|
gatewayRef GatewayReference |
GatewayRef identifies the Gateway resource that routes traffic to this application. | Optional: {} |
|
clientSecretRef ResourceReference |
ClientSecretRef identifies the Secret containing OIDC client credentials. | Optional: {} |
|
authConfigHash string |
AuthConfigHash stores a SHA-256 hash of the last successfully provisioned OIDC client configuration. When this matches the hash of the current spec, and the AuthReady condition is True, ProvisionClient is skipped to avoid unnecessary external API calls on every reconcile cycle. To force re-provisioning, set the nebari.dev/force-reprovision annotation on the NebariApp. The annotation is automatically removed after the forced re-provisioning completes. |
Optional: {} |
|
serviceDiscovery ServiceDiscoveryStatus |
ServiceDiscovery is the computed service discovery descriptor. The controller populates this after reconciling spec.landingPage so the webapi watcher can consume a pre-validated, URL-resolved view via status.serviceDiscovery.* without re-deriving it from spec. |
Optional: {} |
ResourceReference identifies a Kubernetes resource.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
name string |
Name of the resource. | ||
namespace string |
Namespace of the resource (if namespaced). | Optional: {} |
RouteMatch defines a path-based routing rule.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
pathPrefix string |
PathPrefix specifies the path prefix to match for routing. Traffic matching this prefix will be routed to the service. Must start with "/". Example: "/app-1", "/api/v1" |
Pattern: ^/.* Required: {} |
|
pathType string |
PathType specifies how the path should be matched. Valid values: - "PathPrefix": Match requests with the specified path prefix - "Exact": Match requests with the exact path When used in routing.routes, defaults to "PathPrefix". When used in routing.publicRoutes, defaults to "Exact" (safer for auth bypass). |
Enum: [PathPrefix Exact] Optional: {} |
RoutingConfig configures routing behavior for the application. To disable operator-managed routing entirely (e.g., for externally managed Ingress/HTTPRoute), omit the routing field from the NebariApp spec. The operator will skip HTTPRoute creation and cleanup any previously created HTTPRoutes. When routing is nil, TLS is also considered disabled, and the operator will not provision certificates or Gateway listeners.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
routes RouteMatch array |
Routes defines path-based routing rules for the application. If not specified, all traffic to the hostname will be routed to the service. When specified, only traffic matching these path prefixes will be routed. Example: ["/app-1", "/api/v1"] |
Optional: {} |
|
publicRoutes RouteMatch array |
PublicRoutes specifies paths that should bypass OIDC authentication. When auth is enabled and these are specified, these paths will be routed via a separate HTTPRoute that is not protected by the SecurityPolicy. Each entry uses the same RouteMatch format as routes, supporting both PathPrefix (default) and Exact matching via the pathType field. Example: [{pathPrefix: "/api/v1/health", pathType: "Exact"}] |
Optional: {} |
|
tls RoutingTLSConfig |
TLS configures TLS certificate management and termination behavior. When TLS is enabled (the default), the operator creates a cert-manager Certificate for the application's hostname and adds a per-app HTTPS listener to the shared Gateway. |
Optional: {} |
|
annotations object (keys:string, values:string) |
Annotations defines additional annotations to merge onto the generated HTTPRoute. Useful for tools like ArgoCD that track resources via annotations (e.g. argocd.argoproj.io/tracking-id). These annotations are merged with any operator-managed annotations; operator annotations always take precedence to avoid breaking internal behaviour. |
Optional: {} |
RoutingTLSConfig controls TLS termination for the HTTPRoute.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
enabled boolean |
Enabled determines whether TLS termination should be used. When nil or true, the operator will create a cert-manager Certificate for the application's hostname and configure a per-app Gateway HTTPS listener. When explicitly set to false, only HTTP listeners will be used. |
true | Optional: {} |
SPAClientConfig specifies configuration for provisioning a public OIDC client for Single-Page Applications (SPA) that use browser-based authentication with PKCE. This client is separate from the confidential client used by oauth2-proxy or similar server-side auth handlers.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
enabled boolean |
Enabled determines whether a public OIDC client should be provisioned for SPA use. When true, the operator creates a second Keycloak client configured as: - publicClient: true (no client secret, safe for browser) - Redirect URIs: https:///* and https:// - PKCE enforcement with S256 code challenge method The public client ID will be written to a ConfigMap or the OIDC secret for runtime consumption by the frontend application. |
false | Optional: {} |
clientId string |
ClientID optionally overrides the generated client ID for the SPA client. If not specified, defaults to: --spa This allows custom client naming for organizational conventions. |
Optional: {} |
ServiceDiscoveryStatus is the service discovery descriptor computed by the controller and written to status. The webapi watcher reads this field via the unstructured client (status.serviceDiscovery.*) to get the controller's authoritative, URL-resolved view of each service without re-deriving it from spec.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
enabled boolean |
Enabled mirrors spec.landingPage.enabled at the time of last reconciliation. | ||
displayName string |
DisplayName is the human-readable name shown on the landing page. | Optional: {} |
|
description string |
Description is supplementary text for the service card. | Optional: {} |
|
url string |
URL is the effective service URL (derived from spec.hostname or spec.landingPage.externalUrl by the controller). |
Optional: {} |
|
icon string |
Icon identifies the service icon. | Optional: {} |
|
category string |
Category groups related services on the landing page. | Optional: {} |
|
priority integer |
Priority controls sort order within a category (lower = higher priority). | Maximum: 1000 Minimum: 0 Optional: {} |
|
visibility string |
Visibility controls who can see this service (public/private). | Optional: {} |
|
requiredGroups string array |
RequiredGroups lists groups required when visibility is "private". | Optional: {} |
ServiceReference identifies the Kubernetes Service that backs this application.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
name string |
Name is the name of the Kubernetes Service in the same namespace. | MinLength: 1 Required: {} |
|
port integer |
Port is the port number on the Service to route traffic to. | Maximum: 65535 Minimum: 1 Required: {} |
|
namespace string |
Namespace is the namespace of the Service (if different from the NebariApp). If not specified, defaults to the NebariApp's namespace. This allows referencing services in other namespaces for centralized service architectures. Note: The operator has cluster-scoped permissions to read Services across all namespaces. |
MinLength: 1 Optional: {} |
TokenExchangeConfig controls OAuth 2.0 Token Exchange (RFC 8693) for this client.
Appears in:
| Field | Description | Default | Validation |
|---|---|---|---|
enabled boolean |
Enabled determines whether token exchange should be configured for this client. When true, the operator enables authorization services on the Keycloak client and creates policies allowing all other NebariApp clients in the same realm to exchange tokens for this client's audience. |
false | Optional: {} |