Skip to main content
Version: Next

Mapbox Integration

Mapbox is a mapping and geospatial data platform used by Apache Superset for map-based chart types. When users work with geographic data — sales by region, customer locations, logistics routes, or any dataset with spatial dimensions — map charts in Superset require a Mapbox API key to render.

Without a Mapbox API key, map chart types in Superset are unavailable. If your users analyze geographic data, enabling this integration is strongly recommended.

How It Works​

The Mapbox access token is never stored in the Custom Resource. It is provided as a pre-created Kubernetes Secret; the Operator reads it and passes it to Superset as part of its configuration — you do not need to configure Superset directly.

Prerequisites​

  1. A Mapbox account — create one at mapbox.com
  2. A Mapbox public access token — created in your Mapbox account dashboard under Tokens

Mapbox offers a free tier that covers typical evaluation and low-volume production usage. Check mapbox.com/pricing for current limits.

Configuration​

Mapbox configuration is a two-part process: create a Kubernetes Secret with your access token, then enable the integration in the Custom Resource. The CR only ever carries a boolean — the token itself is never written to the CR or checked into any YAML file.

Step 1 — Create the Mapbox secret​

kubectl create secret generic lhc-superset-mapbox-secret \
  -n <instance-namespace> \
  --from-literal=MAPBOX_API_KEY=pk.YOUR_MAPBOX_TOKEN

Or with the helper script shipped in the operator repository:

NAMESPACE=<instance-namespace> MAPBOX_API_KEY=pk.YOUR_MAPBOX_TOKEN \
  ./cli/create-mapbox-secret.sh

Step 2 — Enable Mapbox in the Custom Resource​

Add the following to the superset section of your Lakehousecat Custom Resource:

superset:
  mapbox:
    enabled: true   # token comes from secret lhc-superset-mapbox-secret

Full example in context​

apiVersion: lhc.lakehousecat.com/v1alpha2
kind: Lakehousecat
metadata:
  name: my-instance
spec:
  # ... other configuration ...

  superset:
    replicaCount: 1
    resources:
      requests:
        cpu: "250m"
        memory: "256Mi"
      limits:
        cpu: "1"
        memory: "6Gi"

    mapbox:
      enabled: true

Apply the updated CR:

kubectl apply -f lakehousecat-instance.yaml

The Operator reconciles the change, reads the token from lhc-superset-mapbox-secret, and restarts Superset with the Mapbox key registered. No manual Superset configuration is required.

Graceful degradation

If mapbox.enabled: true is set but the secret is missing or incomplete, Mapbox is treated as not configured — the instance deploys normally and map charts simply stay unavailable until the secret is created and the CR is reconciled again.

Disabling Mapbox​

To disable the integration, set enabled: false or remove the mapbox block from the superset section:

superset:
  mapbox:
    enabled: false

Verifying the Integration​

After applying the configuration:

  1. Open a session using a Custom Model connected to geographic data
  2. Ask a question involving location data (e.g., "Show sales by country on a map")
  3. The system should generate a World Map or Deck.gl map chart — if Mapbox is active, the map tiles will load correctly

If map tiles do not load, check:

  • That the API key is a valid public Mapbox token (starts with pk.)
  • That your cluster has outbound HTTPS access to api.mapbox.com
  • The Superset pod logs for Mapbox-related errors: kubectl logs -n <namespace> <superset-pod>