Jumpstarter¶
operator.jumpstarter.dev/v1alpha1
Jumpstarter is the Schema for the jumpstarters API.
Spec¶
Field |
Type |
Description |
|---|---|---|
|
object |
Authentication configuration for client and exporter authentication. Supports multiple authentication methods including internal tokens, Kubernetes tokens, and JWT. |
|
object |
Automatic user provisioning configuration, this is useful for creating users authenticated by external identity providers in Jumpstarter. |
|
boolean |
Enable auto provisioning. When disabled, users authenticated by external identity providers will not be automatically created in Jumpstarter. (default: |
|
object |
Internal authentication configuration. Built-in authenticator that issues tokens for clients and exporters. This is the simplest authentication method and is enabled by default. |
|
boolean |
Enable the internal authentication method. When disabled, clients cannot use internal tokens for authentication. (default: |
|
string |
Prefix to add to the subject claim of issued tokens. Helps distinguish internal tokens from other authentication methods. Example: “internal:” will result in subjects like “internal:user123” (default: |
|
string |
Token validity duration for issued tokens. After this duration, tokens expire and must be renewed. (default: |
|
array |
JWT authentication configuration. Enables authentication using external JWT tokens from OIDC providers. Supports multiple JWT authenticators for different identity providers. Each entry may optionally reference a CA certificate from a Kubernetes Secret or ConfigMap instead of inlining the PEM content. |
|
object |
CertificateAuthorityConfigMap references a Kubernetes ConfigMap containing the CA certificate PEM for the OIDC issuer. The operator reads the specified key and injects the PEM content as the certificateAuthority for this authenticator. When the ConfigMap changes, the operator reconciles and updates the ConfigMap. |
|
object |
CertificateAuthoritySecret references a Kubernetes Secret containing the CA certificate PEM for the OIDC issuer. The operator reads the specified key and injects the PEM content as the certificateAuthority for this authenticator. When the Secret changes, the operator reconciles and updates the ConfigMap. Takes precedence over CertificateAuthorityConfigMap when both are set. |
|
object |
claimMappings points claims of a token to be treated as user attributes. |
|
array |
claimValidationRules are rules that are applied to validate token claims to authenticate users. |
|
object |
issuer contains the basic OIDC provider connection options. |
|
array |
userValidationRules are rules that are applied to final user before completing authentication. These allow invariants to be applied to incoming identities such as preventing the use of the system: prefix that is commonly used by Kubernetes components. The validation rules are logically ANDed together and must all return true for the validation to pass. |
|
object |
Kubernetes authentication configuration. Enables authentication using Kubernetes service account tokens. Useful for integrating with existing Kubernetes RBAC policies. |
|
boolean |
Enable Kubernetes authentication. When enabled, clients can authenticate using Kubernetes service account tokens. (default: |
|
string |
Base domain used to construct FQDNs for all service endpoints. This domain will be used to generate the default hostnames for Routes, Ingresses, and certificates. Example: “example.com” will generate endpoints like “grpc.example.com”, “router.example.com” |
|
object |
CertManager configuration for automatic TLS certificate management. When enabled, jumpstarter will interact with cert-manager to automatically provision and renew TLS certificates for all endpoints. Requires cert-manager to be installed in the cluster. |
|
boolean |
Enable cert-manager integration for automatic TLS certificate management. When disabled, TLS certificates must be provided manually via secrets. (default: |
|
object |
Server certificate configuration for controller and router endpoints. Defines how server TLS certificates are issued. |
|
object |
Reference an existing cert-manager Issuer or ClusterIssuer. Use this to integrate with existing PKI infrastructure (ACME, Vault, etc.). This overrides the default selfSigned.enabled=true setting. |
|
object |
Create a self-signed CA managed by the operator. The operator will create a self-signed Issuer and CA certificate, then use that CA to issue server certificates. |
|
object |
Controller configuration for the main Jumpstarter API and gRPC services. The controller handles gRPC and REST API requests from clients and exporters. (default: |
|
object |
Exporter options configuration. Controls how exporters connect and behave when communicating with the controller. |
|
string |
Offline timeout duration for exporters. After this duration without communication, an exporter is considered offline. This drives the online/offline status field of exporters, and offline exporters won’t be considered for leases. (default: |
|
object |
gRPC configuration for controller endpoints. Defines how controller gRPC services are exposed and configured. |
|
array |
List of gRPC endpoints to expose. Each endpoint can use different networking methods (Route, Ingress, NodePort, or LoadBalancer) based on your cluster setup. Example: Use Route for OpenShift, Ingress for standard Kubernetes. |
|
object |
Keepalive configuration for gRPC connections. Controls connection health checks and idle connection management. Helps maintain stable connections in load-balanced environments. |
|
object |
TLS configuration for secure gRPC communication. Requires a Kubernetes secret containing the TLS certificate and private key. If spec.certManager.enabled is true, this secret will be automatically managed and configured by cert-manager. |
|
string |
Container image for the controller pods in ‘registry/repository/image:tag’ format. If not specified, defaults to the latest stable version of the Jumpstarter controller. (default: |
|
|
Image pull policy for the controller container. Controls when the container image should be pulled from the registry. (default: |
|
object |
Login endpoint configuration for simplified CLI login. Provides authentication configuration discovery for the jmp login command. The login service runs on HTTP and expects TLS to be terminated at the Route/Ingress level. |
|
array |
List of login endpoints to expose. Each endpoint can use different networking methods (Route, Ingress, NodePort, or LoadBalancer) based on your cluster setup. Note: Unlike gRPC endpoints, login endpoints use edge TLS termination (not passthrough). |
|
object |
TLS configuration for the login endpoint. Specifies the Kubernetes secret containing the TLS certificate for edge termination. If not specified and certManager is enabled, a default secret name will be generated. |
|
object |
Custom annotations to add to controller pod templates. |
|
integer |
Number of controller replicas to run. Set to 0 to suspend the controller (Deployment stays but no pods run, all other resources are preserved). Currently only 1 running replica is supported because the controller uses in-memory state for gRPC stream coordination (Dial/Listen). Values greater than 1 will be clamped to 1 with a warning. See https://github.com/jumpstarter-dev/jumpstarter/issues/1013 for the tracking issue on HA controller support. (default: |
|
object |
Resource requirements for controller pods. Defines CPU and memory requests and limits for each controller pod. |
|
object |
REST API configuration for HTTP-based clients. Enables non-gRPC clients to interact with Jumpstarter for listing leases, managing exporters, and creating new leases. Use this when you need HTTP/JSON access. |
|
array |
List of REST API endpoints to expose. Each endpoint can use different networking methods (Route, Ingress, NodePort, or LoadBalancer) based on your cluster setup. |
|
object |
TLS configuration for secure HTTP communication. Requires a Kubernetes secret containing the TLS certificate and private key. |
|
object |
Deprecated labels configuration for warning users about label keys that should no longer be used. |
|
object |
Map of deprecated label keys to human-readable deprecation messages. When an exporter has any of these labels, clients will receive a deprecation warning with the corresponding message. |
|
object |
ExporterSets configuration for virtual scalable exporter provisioner controllers. When provisioners are listed and enabled, the operator creates a Deployment per provisioner using the same exporter-set-controller image with a –provisioner flag. |
|
string |
Image for all provisioner controller Deployments. (default: |
|
|
ImagePullPolicy for provisioner controller containers. (default: |
|
array |
Provisioners is the list of provisioner controllers to deploy. |
|
boolean |
Enabled controls whether a Deployment is created for this provisioner. (default: |
|
string |
Image overrides the global exporterSets.image for this provisioner. |
|
string |
Name is the provisioner identifier (e.g. “qemu.jumpstarter.dev”). Must be a DNS-subdomain-safe value: lowercase alphanumeric characters, ‘-’ or ‘.’, starting and ending with an alphanumeric character. |
|
integer |
Replicas for this provisioner controller Deployment. Set to 0 to suspend the provisioner (Deployment stays but no pods run). (default: |
|
object |
Resources overrides the global exporterSets.resources for this provisioner. |
|
object |
Resources for provisioner controller pods. |
|
object |
Hidden labels configuration for hiding specific label keys from exporter listings. (default: |
|
array |
List of exact label keys to hide from ListExporters/GetExporter responses. Clients can pass show_hidden_labels=true to see all labels. Hidden labels remain usable in label selectors. Defaults to the ExporterSet identity labels, which every pool member carries. Setting this field replaces the default list rather than adding to it; set it to [] to show every label. (default: |
|
object |
Lease policy configuration for controlling lease behavior. (default: |
|
integer |
Maximum number of user-defined tags allowed per lease. (default: |
|
object |
Router configuration for the Jumpstarter router service. Routers handle gRPC traffic routing and load balancing. (default: |
|
object |
gRPC configuration for router endpoints. Defines how router gRPC services are exposed and configured. |
|
array |
List of gRPC endpoints to expose. Each endpoint can use different networking methods (Route, Ingress, NodePort, or LoadBalancer) based on your cluster setup. Example: Use Route for OpenShift, Ingress for standard Kubernetes. |
|
object |
Keepalive configuration for gRPC connections. Controls connection health checks and idle connection management. Helps maintain stable connections in load-balanced environments. |
|
object |
TLS configuration for secure gRPC communication. Requires a Kubernetes secret containing the TLS certificate and private key. If spec.certManager.enabled is true, this secret will be automatically managed and configured by cert-manager. |
|
string |
Container image for the router pods in ‘registry/repository/image:tag’ format. If not specified, defaults to the latest stable version of the Jumpstarter router. (default: |
|
|
Image pull policy for the router container. Controls when the container image should be pulled from the registry. (default: |
|
object |
Custom annotations to add to router pod templates. |
|
integer |
Number of router replicas to run. Set to 0 to suspend all routers (existing Deployments are scaled to 0 pods, Services and certificates are preserved so the configuration can be restored without reconfiguration). Note: when replicas is 0, router entries are also removed from the controller ConfigMap, so the running controller will see no router endpoints. Any Dial/Listen attempt will fail until routers are resumed (replicas > 0) and the ConfigMap is reconciled again. Minimum recommended value is 3 for high availability. (default: |
|
object |
Resource requirements for router pods. Defines CPU and memory requests and limits for each router pod. |
|
array |
Topology spread constraints for router pod distribution. Ensures router pods are distributed evenly across nodes and zones. Useful for high availability and fault tolerance. |
|
object |
Telemetry configuration for the optional telemetry service. When enabled, the operator deploys a jumpstarter-telemetry service that receives structured log entries from exporters via gRPC. The controller advertises the telemetry endpoint to exporters so they can push logs without cluster credentials. |
|
object |
Backpressure configures the Loki log push ring buffer. |
|
integer |
Ring buffer depth for Loki log push. On overflow, dropped entries are replaced by a single drop-marker LogEntry. (default: |
|
boolean |
Enable the telemetry service deployment. When enabled, the operator deploys a jumpstarter-telemetry pod and a ClusterIP Service, and configures the controller to advertise the endpoint to exporters. (default: |
|
object |
gRPC configuration for the telemetry service. Use this to configure TLS when not using cert-manager. |
|
object |
TLS configuration for secure gRPC communication with the telemetry service. When spec.certManager.enabled is true, this is ignored and certificates are automatically managed by cert-manager. When spec.certManager.enabled is false, you can provide your own TLS secret here. |
|
string |
Container image for the telemetry pod in ‘registry/repository/image:tag’ format. (default: |
|
|
Image pull policy for the telemetry container. (default: |
|
object |
Logging configuration for the telemetry log ingestion path. |
|
object |
Filter controls which log entries are forwarded to the telemetry service. |
|
object |
Loki configures optional HTTP push of ingested logs to a Loki-compatible endpoint. When url is empty, telemetry runs metrics-only. |
|
string |
Secret with Loki credentials (username/password and/or token keys). Only the telemetry pod holds Loki credentials. |
|
object |
TLS settings for the Loki endpoint. |
|
string |
Loki push endpoint (http:// or https://). Optional — telemetry can run metrics-only without Loki. grpc:// is reserved but not implemented yet. |
|
object |
Metrics configures reverse-scrape fan-out and Prometheus exposition. |
|
array |
Allowed driver_type label values. Unlisted types are remapped to “other”. At most 16 entries (the default set plus site-specific categories), each at most 32 characters. (default: |
|
array |
Allowlist of keys to include in Prometheus exemplars. Unlisted keys are omitted. At most 16 keys. Each key is at most 32 characters, the same limit as Lease spec.context key names that may appear in this list. (default: |
|
string |
Max wait for parallel exporter MetricsStream responses during a /metrics fan-out. Should be lower than the Prometheus scrape_timeout. The default is 7s. 60s bounds the fan-out wait and the HTTP write timeout that grows with this value. (default: |
|
integer |
Number of telemetry replicas to run. Multiple replicas provide HA; each exporter connects to exactly one replica via a persistent MetricsStream, so Prometheus sum-by queries across replicas yield exact totals without double-counting. Set to 0 to suspend the telemetry deployment (Deployment stays but no pods run, Service and other resources are preserved). Note: when replicas is set to 0, the controller also removes the telemetry endpoint from the controller ConfigMap, so exporters will stop forwarding metric streams immediately. Any exporter that was already streaming metrics will lose its MetricsStream target until telemetry is resumed (replicas > 0) and the ConfigMap is reconciled again. (default: |
|
object |
Resource requirements for the telemetry pod. |
Status¶
Field |
Type |
Description |
|---|---|---|
|
array |
Conditions represent the latest available observations of the Jumpstarter state. Condition types include: - CertManagerAvailable: cert-manager CRDs are installed in the cluster - IssuerReady: The referenced or created issuer is ready to issue certificates - ControllerCertificateReady: Controller TLS certificate is issued and secret exists - RouterCertificatesReady: All router TLS certificates are issued and secrets exist - ControllerDeploymentReady: Controller deployment is available - RouterDeploymentsReady: All router deployments are available - Ready: Overall system ready (aggregates all other conditions) |
|
string |
lastTransitionTime is the last time the condition transitioned from one status to another. This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable. |
|
string |
message is a human readable message indicating details about the transition. This may be an empty string. |
|
integer |
observedGeneration represents the .metadata.generation that the condition was set based upon. For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date with respect to the current state of the instance. |
|
string |
reason contains a programmatic identifier indicating the reason for the condition’s last transition. Producers of specific condition types may define expected values and meanings for this field, and whether the values are considered a guaranteed API. The value should be a CamelCase string. This field may not be empty. |
|
|
status of the condition, one of True, False, Unknown. |
|
string |
type of condition in CamelCase or in foo.example.com/CamelCase. |