Skip to main content

Installation

Install and configure a self-hosted (self-managed) Primary Site.

Prerequisites​

  • Kubernetes cluster, version 1.30 or later
  • Kubectl - Kubernetes command line tool
  • Helm - Kubernetes package manager, version 3.12 or later
tip

For AWS EKS deployments, we recommend Kubernetes version 1.32 for optimal compatibility with AWS services and longer support windows.

To deploy your Primary Site in the cloud, create an account with a supported provider (AWS, Azure, or GCP) or choose to self-host Kubernetes with an S3-compatible object store like MinIO

info

We've tested the S3-compatible setup with MinIO. Other compatible services may work. Object creation events are required to process files from your inbox.

Provision storage buckets, a Kubernetes cluster, and cloud credentials before installing the Primary Site. There are no region restrictions if your cloud provider supports these resources.

Foxglove provides a set of Terraform examples to help with these initial provisioning steps in a supported cloud provider.

On AWS, you can use the AWS Terraform examples to provision your buckets and cluster. An example cost estimate is provided. Pricing will vary based on your specific data storage needs and access patterns.

This process should take about an hour, depending on your infrastructure configuration.

Create storage buckets​

note

This only applies to the query-optimized storage mode. For index-in-place storage mode, you can use an existing bucket.

Create two storage buckets for your Primary Site:

  • inbox – Temporary staging area for all file uploads
  • lake – Long-term storage for processed and indexed data (contains the same data as inbox files, but split and reorganized for efficient access)

Create Kubernetes cluster​

Create a Kubernetes cluster to run your site workloads (for example, processing inbox data, servicing data access requests from the lake) – we recommend doing this in the same region as your storage buckets, to reduce access latency and cost.

Create a foxglove namespace in your cluster:

kubectl create namespace foxglove

Configure cloud credentials​

Create a service account with read and write access to the storage buckets. The Kubernetes workloads will use this service account.

See Configure cloud credentials for details on how to provide this credential to the deployment. This section also covers configuration of S3-compatible object storage.

Create a Primary Site and site token​

You must be an organization admin to complete these steps.

  1. Create a new Primary Site from the Sites settings page:
    • Click "Create site" in the top right corner
    • Choose "Primary Site" as the site type
    • Name your site (e.g., "Custom Primary Site")
    • Click "Create"
important

You cannot create site tokens for the default "Foxglove Cloud" site. You must create a new self-hosted Primary Site to generate site tokens for your infrastructure.

  1. Create a site token for your new Primary Site:
    • Click into your newly created Primary Site's details
    • Click "Create new token"
    • Copy the generated token (starts with fox_st_...)

You may also create a site token via the Foxglove API. On the API key settings page, create an API key with the appropriate siteToken capabilities (list, create, etc), and use it to create a token via the site tokens API endpoint.

Create secret with site token​

Install a Secret named foxglove-site-token into the foxglove namespace containing your site token:

kubectl create secret generic foxglove-site-token --from-literal=FOXGLOVE_SITE_TOKEN="fox_st_..." --namespace foxglove

There are multiple other ways to create secrets that may be preferable. See Create a Secret for more info.

Install the release​

Install your Primary Site using Helm.

Prepare a values file​

Create a values.yaml file to configure the installation. Include a storageProvider (aws, azure, google_cloud, or s3_compatible) and the names of your lake and inbox buckets:

globals:
  lake:
    storageProvider: google_cloud
    bucketName: foxglove-lake
  inbox:
    storageProvider: google_cloud
    bucketName: foxglove-inbox

Install​

Helm will install the Primary Site deployment to your current Kubernetes context.

tip

Find the latest Helm charts and releases at github.com/foxglove/helm-charts/releases.

helm repo add foxglove https://helm-charts.foxglove.dev
helm repo update
helm upgrade --install foxglove-primary-site foxglove/primary-site \
    --values ./values.yaml  \
    --namespace foxglove \
    --create-namespace

View info about the deployment:

helm list -n foxglove

Ingress for data streaming​

The deployment installs an Ingress, exposing a query service HTTP endpoint to download available data from your lake bucket.

To reach the ingress from outside the cluster, assign a DNS name and HTTPS endpoint. Ensure that the HTTP endpoint is reachable from your organization's network or any network needing access to the site data. This does not necessarily need to be exposed to the public internet; for example, if all clients will download data from within a VPN.

note

How to assign a DNS name and HTTPS endpoint to the ingress is specific to your organization and cloud environment.

You can configure the ingress using your values file. Below are the default values.

ingress:
  enabled: true
  className:
  annotations: {}

To completely disable the Ingress, set ingress.enabled to false. However, you must provide an Ingress for the site to function.

Some cloud providers require configuring annotations for HTTPS certificates. Here's an example values file for AWS.

ingress:
  annotations:
    kubernetes.io/ingress.class: "alb"
    alb.ingress.kubernetes.io/scheme: internet-facing
    alb.ingress.kubernetes.io/target-type: ip
    alb.ingress.kubernetes.io/backend-protocol: HTTP
    alb.ingress.kubernetes.io/listen-ports: '[{"HTTPS":443}]'
    alb.ingress.kubernetes.io/certificate-arn: arn:aws:acm:us-west-1:xxxxxxxxxxxx:certificate/EXAMPLE-xxxx-xxxx-xxxx-xxxxxxxxxxxx

To check your HTTPS endpoint is correctly configured, make a request to the root / path. You should see a 200 OK response with a JSON body:

{
  "success": true,
  "version": "<your installed helm chart version>"
}

Configure Foxglove​

Once the site's ingress public URL is known, you can configure it on a Site page, linked from the "Sites" settings page.

Under Site URL, enter the HTTPS URL you've assigned to the Ingress.

Bucket push notification​

The site needs to know when new files are uploaded. To notify of new uploads, configure a push notification to the appropriate Foxglove notifications endpoint. For query-optimized storage mode, the notification should be configured on the inbox bucket.

Configuring a push notification for new file uploads is specific to your cloud provider (or S3-compatible service).

The Foxglove Terraform examples for cloud providers configure these resources for you. For manual setup, or for more information, see the documentation below.

tip

Org admins can find the notification endpoint on the Sites settings page.

Troubleshooting​

If you encounter issues during setup:

Kubernetes version errors:

  • If you see unsupported Kubernetes version errors, check your cloud provider's supported versions
  • For AWS EKS, use version 1.32 or later for optimal compatibility
  • If you see AMI type errors (e.g., "AMI Type AL2_x86_64 is only supported for kubernetes versions 1.32 or earlier"), update both your Kubernetes version and AMI type to match

Site token creation errors:

  • If you get site-tokens cannot be created for this site when using the API, ensure you're creating tokens for a self-hosted Primary Site, not the default "Foxglove Cloud" site
  • Create a new Primary Site first, then generate tokens for that site

EKS cluster creation time:

  • EKS cluster creation typically takes 8-10 minutes
  • If it takes longer, check AWS service status and ensure you have sufficient permissions

Support​

For additional support contact us at [email protected].