All docsAtlasGuidesAtlas for Kubernetes

Atlas for Kubernetes


Atlas supports Kubernetes, an open-source container orchestrator that lets developers automate the process of deploying, scaling, and managing containerized applications. Atlas for Kubernetes provides features for organizations that need enterprise-level availability, scalability, and disaster recovery. Kubernetes also makes Atlas easier to install, manage, and upgrade.


To download and set up Atlas for Kubernetes, you need to download several dependencies first:

  • Helm 3
  • jq
  • tar
  • If downloading data to transfer to an air-gapped network: curl, unzip, and docker
  • A Kubernetes cluster
    • Atlas is supported on Kubernetes versions 1.14 and higher.
    • A properly configured Ingress controller.
    • For development, Atlas for Kubernetes requires a cluster with 4 CPUs, 8 GB RAM, and 100 GB of disk space. Production clusters can vary in size based on capacity and scaling factor, but the minimum requirements are 8 CPUs, 16 GB RAM, and 1 TB of disk space.

Supported platforms

Atlas can run on a variety of Kubernetes platforms. On platforms with Beta Support, you may have to make changes to Helm charts to achieve full compatibility.

PlatformOfficial SupportBeta SupportNot Supported
AWS Elastic Kubernetes Servicex
MinikubeDev only
Azure Kubernetes Servicex
Google Kubernetes Engine (GCP GKE)x
Kubernetes Operations (KOPS)x
Mesosphere Kubernetes Enginex
OpenStack Magnumx
VMWare Tanzux
AWS Elastic Container Service / Fargatex
VMWare vSpherex

Install Atlas

This guide will walk you through the following components of the Atlas for Kubernetes installation:

  • Adding the Mapbox Helm repository.
  • Fetching the Helm chart.
  • Testing on Minikube.
Documentation conventions

Some examples use <angle-brackets> as a convention to show places where you will need to specify your own details.

Additionally, commands run from a shell will begin with $, for example $ ls -al

Add the Mapbox Helm repository

You will need a Mapbox token with atlas:read scope to add the Mapbox Helm repository. See Access Token for instructions on how to create this token.

# Add the Mapbox Helm repository
$ export MAPBOX_ACCESS_TOKEN=<your-atlas-sk-token>
$ helm repo add mapbox "$MAPBOX_ACCESS_TOKEN"

Get the Helm chart

# Pre-fetch the latest version of the chart
$ helm fetch mapbox/mapbox-atlas

# or pre-fetch a specific version of the chart
$ helm repo update
$ helm search repo mapbox --versions --devel
$ helm fetch mapbox/mapbox-atlas --version <chart version>

# Extract archived files
$ tar -xvzf mapbox-atlas-<version>.tgz
$ cd mapbox-atlas

# Fetch docker auth token (valid for 12 hours) and create regcred docker-registry secret
$ chmod u+x ./atlas
$ ./atlas create_docker_secret

# Export your Atlas license to your environment
$ eval $(./atlas export_license)

# Install the chart (helm 3)
$ helm install atlas.local . --set "password=<some-password>,atlasLicense=$ATLAS_LICENSE,global.atlasURL=<external-DNS-for-Atlas>"

Get the Helm chart and images for offline use

# Pulls images into local Docker context
$ ./atlas pull_images

# Pushes images to custom Docker registry
$ ./atlas push_images <>

# Pulls images and saves them to a tarball in the downloads/docker directory
$ ./atlas save_images

Test on Minikube

If you are installing Atlas for evaluation purposes or want to get familiar with how Atlas works on Kubernetes, we recommend installing Atlas on Minikube. The default values are the ones required for Minikube with an NGINX ingress. These instructions assume that Helm is installed and working.

Configure and start Minikube

$ minikube config set memory 8192
$ minikube config set disk-size 100g
$ minikube config set cpus 4
$ minikube start
$ minikube addons enable ingress
Add hosts entry to point atlas.local to Minikube
$ bash -c 'echo "$(minikube ip) atlas.local" | sudo tee -a /etc/hosts'

Note: Each time a cluster is deleted and recreated, a new ip is generated. If you ran this command on your machine before and have since deleted and recreated your cluster, you may have an outdated atlas.local entry in your hosts file. If you see more than one, remove them all and then run this command again.

Install the Helm chart

Follow the directions above, and once all pods are ready open Atlas in your browser:

$ open http://atlas.local

Configure Atlas

Most settings for Atlas are dynamic and can be changed at any time by passing the --set <key>=<value> to the helm upgrade command. You can also change the default values in the top-level values.yaml file.

By default, Atlas installs with development data. To install Atlas with production data follow these instructions.

For deployments on networks with internet access

Download production tilesets and data

When running helm install you will need to specify commands to download production tilesets and production geocoding data.

Download production tilesets
--set "atlas-backend.dataStrategy=script" --set "atlas-backend.dataScriptArgs=prod" --set "atlas-backend.accessToken=$MAPBOX_ACCESS_TOKEN"
Download production geocoding data
--set "api-geocoder.dataStrategy=script" --set "api-geocoder.dataScriptArgs=prod" --set "api-geocoder.accessToken=$MAPBOX_ACCESS_TOKEN"

Both atlas-backend and api-geocoder will download data during the initContainer phase and will only start once their respective data is downloaded.

For deployments on networks without internet access

  1. Download production data using the atlas script commands:

    • Download tilesets ./atlas download_tilesets
    • Download geocoding data ./atlas download_search_data
  2. Upload data to a network location accessible from your pods.

  3. Download production tilesets from your network location

    • Update the download scripts in charts/atlas-backend/files/ to download the tilesets from your network location.
    • When installing specify --set "atlas-backend.dataStrategy=script" --set "atlas-backend.dataScriptArgs=prod"
  4. Download production geocoding data from your network location

    • Update the download scripts in charts/api-geocoder/files/ to download the tilesets from your network location.

    • When installing specify --set "api-geocoder.dataStrategy=script" --set "api-geocoder.dataScriptArgs=prod"

  5. Both atlas-backend and api-geocoder will download data during the initContainer phase and will only start once their respective data is downloaded.

Upgrade Atlas

When a new version of Atlas for Kubernetes is available, download an updated Helm Chart and pull new container images from the registry. Use Helm to automatically update the existing deployment. With Kubernetes, often you can apply rolling updates of Atlas without taking downtime.

$ helm upgrade <your-release-name> . --reuse-values

Renew license

First, get your updated license by running:

$ eval $(./atlas export_license)

Then run the following upgrade command:

$ helm upgrade <your-release-name> . --reuse-values --set atlasLicense=$ATLAS_LICENSE

Release notes



  • Improved UI for license expiration
  • Updated Kubernetes APIs for 1.16+ compatibility
  • Added geocoding data for Belarus, Cambodia, Canada, and France
  • Added support for the Atlas Navigation preview


  • atlas-core and atlas-router pods automatically roll on upgrade to support license refresh
  • atlas-data volume and PVC are now more accurately named atlas-search-data
  • atlas-search-data PVC is only created if geocoding is enabled
  • Updated EKS example resource reservations for improved performance
  • Removed obsolete subchart ConfigMaps and extraneous values


  • Health check for atlas-s3 container now returns status code 200 instead of 304
  • dataScriptArgs value is now properly handled for production data



  • Marked the atlas-enterprise Helm chart as deprecated



  • Chart is now available under the mapbox-atlas chart name


  • Added missing s3-data-creation image to helper script


Initial public release