logfire

Helm chart for self-hosted Pydantic Logfire

This repository and the chart source it contains are licensed under the MIT License. Deploying the official self-hosted Pydantic Logfire product requires separate commercial access to private container images. Self-hosted Logfire is an Enterprise offering that requires a contract and payment. Please contact sales@pydantic.dev to discuss setting up a contract and pricing.

Use this README for the chart-level install flow and values reference. Use the Self-Hosted Production Requirements for background, architecture, and provider-specific procedures.

Choose one path:

• Local evaluation: use values.dev.yaml. It deploys development-grade PostgreSQL, RustFS, and MailDev in the cluster.
• Production: start from values.prod.yaml, replace the placeholders for your external services and routing, and adjust the sizing preset if needed.

Warning: values.dev.yaml is only for local evaluation and testing. Do not use it for production deployments.

helm repo add pydantic https://charts.pydantic.dev/
helm repo update

Logfire images are private. Contact sales@pydantic.dev to get the key.json file for your image pull credentials.

Create the namespace before creating the secret:

kubectl create namespace logfire
kubectl -n logfire create secret docker-registry logfire-image-key \
  --docker-server=us-docker.pkg.dev \
  --docker-username=_json_key \
  --docker-password="$(cat key.json)" \
  --docker-email=YOUR-EMAIL@example.com

Reference the secret from your values file:

imagePullSecrets:
  - logfire-image-key

If you mirror Logfire images into your own registry, keep the chart version and mirrored image tags aligned. By default, workload images use the chart appVersion tag unless you explicitly override tags in values.

From the chart repository package:

helm pull pydantic/logfire --untar
helm upgrade --install logfire ./logfire \
  -f ./logfire/values.dev.yaml \
  --namespace logfire

Or from this source repository:

helm dependency build charts/logfire
helm upgrade --install logfire charts/logfire \
  -f charts/logfire/values.dev.yaml \
  --namespace logfire

Then port-forward Logfire and MailDev in separate terminals:

kubectl -n logfire port-forward svc/logfire-service 8080:8080
kubectl -n logfire port-forward svc/logfire-maildev 1080:1080

Open Logfire at http://localhost:8080 and MailDev at http://localhost:1080. MailDev is available for testing local email flows. Use the first-access step below to log in to the meta project.

Chart versions before 0.13.48 deployed MinIO for local evaluation. 0.13.48 and later deploy RustFS instead. The upgrade deletes the old logfire-minio resources, including its PersistentVolumeClaim, so local evaluation data is not carried over.

Values files that still set dev.deployMinio: true keep working: the chart deploys RustFS behind the same logfire-minio Service name and uses the credentials from minio.auth, or from objectStore.env.AWS_ACCESS_KEY_ID and objectStore.env.AWS_SECRET_ACCESS_KEY when minio.auth is not set, so Logfire keeps authenticating. minio.persistence.existingClaim is not carried over: RustFS always starts from its own claim, or from an emptyDir when persistence is disabled.

To move to the new names, set dev.deployRustfs: true, remove dev.deployMinio, point objectStore.env.AWS_ENDPOINT at http://logfire-rustfs:9000, and set rustfs.auth.accessKey and rustfs.auth.secretKey to the same credentials as objectStore.env.

When installing from this source repository, run helm dependency build charts/logfire after pulling so the removed MinIO subchart does not linger in charts/.

A minimal production overlay is checked in at values.prod.yaml. Use it as a starting point for production installs and replace the placeholder hostnames, credentials, and provider-specific settings.

The starter uses Gateway API, but the chart supports both Gateway API and Ingress. Use whichever routing interface your cluster standardizes on. The core shape is:

imagePullSecrets:
  - logfire-image-key

sizingPreset: standard
adminEmail: sre@example.com

# Optional: set a StorageClass for chart-managed PVCs:
# defaultStorageClassName: fast-storage

ingress:
  enabled: false

gateway:
  enabled: true
  gatewayClassName: nginx
  tls: true
  hostnames:
    - logfire.example.com

postgresDsn: postgresql://logfire_crud:PASSWORD@postgres.example.com:5432/crud
postgresFFDsn: postgresql://logfire_ff:PASSWORD@postgres.example.com:5432/ff

logfire-dex:
  config:
    enablePasswordDB: false
    storage:
      type: postgres
      config:
        host: postgres.example.com
        port: 5432
        user: logfire_dex
        database: dex
        password: PASSWORD
        ssl:
          mode: require

objectStore:
  uri: s3://logfire-prod
  env:
    AWS_DEFAULT_REGION: us-east-1

logfire-redis:
  enabled: false

redisDsn: redis://redis.example.com:6379

Configure an identity provider under logfire-dex.config.connectors; see Authentication.

Before installing in production, confirm that you have:

• Image pull credentials configured through imagePullSecrets.
• Public hostname and TLS values set through ingress.* or gateway.*, even if you expose the Service another way.
• External PostgreSQL databases for crud, ff, and dex.
• Object storage using s3://, gs://, or az://.
• A managed Redis endpoint configured through redisDsn.
• A Dex connector configured for your identity provider.
• HorizontalPodAutoscaler metrics available in the cluster when using a sizing preset.
• StorageClass behavior chosen for chart-managed PVCs: use the cluster default, or set defaultStorageClassName in values.prod.yaml.

Install with your production values file:

helm upgrade --install logfire pydantic/logfire \
  -f values.prod.yaml \
  --namespace logfire

On first install, the chart creates the logfire-meta organization and stores a frontend access token in a Kubernetes Secret:

kubectl -n logfire get secret logfire-meta-frontend-token \
  -o "jsonpath={.data.logfire-meta-frontend-token}" | base64 -d

Open the meta project with your hostname and token:

https://logfire.example.com/logfire-meta/logfire-meta#token=LOGFIRE_META_FRONTEND_TOKEN

For local evaluation with the port-forward above, use http://localhost:8080/logfire-meta/logfire-meta#token=LOGFIRE_META_FRONTEND_TOKEN.

After you have access, create an invite link from Settings > Invite and assign the Admin organization role.

Set at least one public hostname so the chart can generate correct public URLs and CORS settings. The hostname and TLS values are used by the application even when you expose logfire-service with infrastructure outside this chart.

For a standard Ingress:

ingress:
  enabled: true
  tls: true
  hostnames:
    - logfire.example.com
  ingressClassName: nginx

Logfire Live View requires WebSocket support. Ensure every proxy in front of logfire-service preserves the WebSocket upgrade and Sec-WebSocket-Protocol headers. Some ingress controllers require an explicit annotation. For the F5 NGINX Ingress Controller:

ingress:
  annotations:
    nginx.org/websocket-services: logfire-service

A successful WebSocket handshake normally returns 101 Switching Protocols. The annotation above is specific to the F5 controller; use the configuration required by your ingress or gateway implementation.

If you expose logfire-service directly instead of rendering an Ingress or Gateway, keep ingress.enabled: false and still set the public hostname and TLS behavior:

ingress:
  enabled: false
  tls: true
  hostnames:
    - logfire.example.com

Gateway API is supported through gateway.enabled. Set gateway.create: true to create a Gateway, or gateway.create: false to attach the HTTPRoute to an existing Gateway.

Dex is used as the identity service for Logfire. When creating an OAuth app in your provider, set the redirect URI to <logfire_url>/auth-api/callback, for example https://logfire.example.com/auth-api/callback. Connector configuration is passed through to Dex; see the Dex connector overview for supported providers and settings.

Example GitHub connector using Kubernetes Secret references:

logfire-dex:
  env:
    - name: GITHUB_CLIENT_ID
      valueFrom:
        secretKeyRef:
          name: my-github-secret
          key: client-id
    - name: GITHUB_CLIENT_SECRET
      valueFrom:
        secretKeyRef:
          name: my-github-secret
          key: client-secret
  config:
    connectors:
      - type: github
        id: github
        name: GitHub
        config:
          clientID: $GITHUB_CLIENT_ID
          clientSecret: $GITHUB_CLIENT_SECRET
          getUserInfo: true

Use groupOrganizationMapping to grant Logfire organization and project roles from identity-provider group IDs:

groupOrganizationMapping:
  - group_id: engineering
    organization_roles:
      - organization_name: logfire-meta
        role: member
        project_roles:
          - project_name: logfire-meta
            role: write

The mapping is authoritative for the organizations and projects it lists and is reconciled when a user signs in. Access in those scopes may be changed or removed; unlisted organizations and projects are left unchanged, and personal organization membership is preserved. When multiple matching groups grant roles in the same scope, the most permissive role is applied.

Setting groupOrganizationMapping overrides mappings managed through the public Group Mappings API. The API reports api_mapping_status: overridden_by_environment, and update requests return HTTP 409.

Logfire requires object storage for data. Supported URI schemes are s3://, gs://, and az://. Provider credentials can come from objectStore.env, mounted secrets, or the Kubernetes service account used by Logfire.

For local evaluation, dev.deployRustfs (or the deprecated dev.deployMinio) deploys RustFS and fills in any missing objectStore.uri, AWS_ENDPOINT, and AWS credential environment variables, so the workloads reach the in-cluster bucket. An s3:// objectStore.uri also determines the bucket RustFS creates.

Do not enable bucket versioning. Logfire manages its own data lifecycle, and bucket versioning can increase cost and interfere with lifecycle behavior.

Logfire requires three separate PostgreSQL databases: crud, ff, and dex. They may run on the same PostgreSQL instance, but they must be separate databases to avoid schema collisions. Each database user needs owner permissions so migrations can run.

Pydantic Logfire AI features can be enabled by setting the ai configuration in your values file:

ai:
  model: provider:model-name
  openAi:
    apiKey: openai-api-key

Start with a sizing preset instead of hand-sizing every workload:

sizingPreset: standard

Use large for higher-throughput deployments, standard for general production deployments, small for lower-traffic deployments that still need ingest and query headroom, or tiny for the smallest production footprint. Presets apply workload resources, autoscaling, PDBs, and best-effort topology spreading for HA-sensitive workloads. FusionFire derives its execution settings from the effective resources. They do not configure environment-specific prerequisites such as hostnames, TLS, PostgreSQL, object storage, image pull secrets, or StorageClasses.

Query API capacity is resource-oriented:

Query cost capacity defaults to the effective execution-worker CPU rounded up to a whole core. With separate query workers enabled, both the dispatcher and workers derive it from query-worker CPU. Advanced installations can override it with logfire-ff-query-api.maxQueryCostPerPod.

The standard preset keeps the public request path, query API, and ingest path at a minimum of three replicas. The large preset inherits standard and increases selected FusionFire worker, ingest processor, and byte-cache capacity. The small preset keeps ingest and the edge service more available while preserving a smaller footprint. The tiny preset intentionally favors the smallest resource footprint over high availability.

If you do not set a sizing preset or per-workload resources, the chart does not render Kubernetes CPU/memory requests or limits. FusionFire still needs internal execution limits, so those derived settings use the tiny preset resource baseline without rendering the preset's Kubernetes resources. This increases some no-preset FusionFire budgets compared with earlier chart versions. Operators running constrained clusters should select a sizing preset or configure explicit workload resources.

Override individual workloads only after selecting a preset:

sizingPreset: standard

logfire-worker:
  resources:
    cpu: "500m"
    memory: "1Gi"
    ephemeralStorage: "1Gi"

Nested resources.requests do not add mandatory limits, allowing workloads to use spare node capacity. The legacy flat resource shorthand continues to use the configured values for both requests and limits.

For Argo CD deployments, use the chart's existing-Secret options with an external secret controller. Updating a Kubernetes Secret does not restart pods that consume its values through environment variables, so configure a reload controller such as Reloader as well.

Add the reload controller's workload annotations to the relevant Secret values. The chart copies them only to workloads that consume that Secret and omits its Helm checksum annotations, leaving rotation to the reload controller:

postgresSecret:
  enabled: true
  name: logfire-postgres
  annotations:
    reloader.stakater.com/auto: "true"

The same annotations pattern is supported by existingSecret, adminSecret, and existingGatewaySecret. The chart does not install a reload controller.

inClusterTls.enabled switches supported in-cluster service-to-service traffic to HTTPS with certificate verification. This is independent from public ingress.tls or gateway.tls.

Certificate verification uses inClusterTls.caBundle.*, or the chart-created CA Secret when using cert-manager auto-Issuer mode.

CA bundle requirements by mode:

• inClusterTls.certs.mode=certManager with empty issuerRef.name: CA bundle is optional.
• inClusterTls.certs.mode=certManager with custom issuerRef.name: set exactly one of inClusterTls.caBundle.existingConfigMap or inClusterTls.caBundle.existingSecret.
• inClusterTls.certs.mode=existingSecrets: set exactly one of inClusterTls.caBundle.existingConfigMap or inClusterTls.caBundle.existingSecret.

Cache consumers dial the headless logfire-ff-cache-byte-internal service directly and verify that hostname, so the service certificate must include the bare logfire-ff-cache-byte-internal DNS name. Keep the logfire-ff-cache-byte names and the namespace and cluster-domain variants as well: existing certificates already carry them, and they keep the certificate valid if you roll back to a chart that still runs the cache proxy.

The cache loads its certificate at startup, so after rotating the Secret restart deployment/logfire-ff-cache-byte so the pods serve the new certificate, or configure a reload controller as described in External Secrets and Automatic Reloads.

For Kind or local development, you can optionally deploy cert-manager as a Helm dependency with dev.deployCertManager. When working from this repository, run helm dependency update charts/logfire to fetch dependency charts.

Chart-owned containers default to the controls a restricted Pod Security Standards namespace requires: a non-root identity, no privilege escalation, all capabilities dropped, RuntimeDefault seccomp, and a read-only root with the writable paths mounted.

Containers this chart takes from other projects (Redis, Dex, MailDev, the OTel collector, RustFS, and the check-db-ready init container) keep the chart-wide securityContext; supply it or per-workload values for them. HAProxy defaults to a restricted-compatible haproxy.securityContext. ci/restricted-values.yaml is an example that the integration tests install into a namespace labeled pod-security.kubernetes.io/enforce=restricted.

If you run Istio and see protocol or mTLS sidecar issues on HAProxy, migration, or infrastructure workloads, enable:

istio:
  disableSidecarOnKnownWorkloads: true

This sets sidecar.istio.io/inject: "false" on known-sensitive workloads. You can still override labels per workload using <workload>.podLabels.

Once your self-hosted instance is running, configure client SDKs to send data to your endpoint:

import logfire

logfire.configure(
    token='<your_logfire_token>',
    advanced=logfire.AdvancedOptions(base_url="https://logfire.example.com")
)
logfire.info('Hello, {place}!', place='World')

Before diving deeper, verify these common configuration issues:

• Object Storage Permissions: Ensure the ServiceAccount (configured via serviceAccount.annotations) has read/write access to your object storage bucket. For AWS, this means the IAM role needs s3:GetObject, s3:PutObject, s3:DeleteObject, and s3:ListBucket permissions. For GCP, the service account needs the Storage Object Admin role on the bucket.

• StorageClass Exists: If you set defaultStorageClassName or any per-workload storageClassName, verify the StorageClass exists in your cluster:

  kubectl get storageclass

  If omitted, Kubernetes uses the cluster's default StorageClass.

• Image Pull Secrets: Ensure the secret exists in the same namespace as the release and is correctly referenced in imagePullSecrets.

• Troubleshooting Guide: If you encounter issues, your first stop should be the Troubleshooting Self-Hosted guide, which includes common issues and steps for accessing internal logs.

• GitHub Issues: If your issue persists, please open up an issue with details about your deployment (Chart version, Kubernetes version, values file, any relevant error logs).

• Enterprise Support: For commercial support, contact us at sales@pydantic.dev.

Autogenerated from chart metadata using helm-docs v1.14.2