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
- If downloading data to transfer to an air-gapped network: curl, unzip, and docker
- A Kubernetes cluster
- Atlas is supported on active versions of Kubernetes.
- 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.
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.
|Platform||Official Support||Beta Support||Not Supported|
|AWS Elastic Kubernetes Service||x|
|Azure Kubernetes Service||x|
|Google Kubernetes Engine (GCP GKE)||x|
|Kubernetes Operations (KOPS)||x|
|Mesosphere Kubernetes Engine||x|
|AWS Elastic Container Service / Fargate||x|
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.
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
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 "https://api.mapbox.com/v2/software/charts?access_token=$MAPBOX_ACCESS_TOKEN"
# 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=<http[s]://external-hostname-for-Atlas>,global.platform=<minikube|eks|openshift|aks|other>"
# Pulls images into local Docker context $ ./atlas pull_images # Pushes images to custom Docker registry $ ./atlas push_images <your-custom-registry.com> # Pulls images and saves them to a tarball in the downloads/docker directory $ ./atlas save_images
If you have purchased Atlas Search or Atlas Navigation, set the
navigation=true environment variables before pulling and pushing images:
# Pulls images, including for Atlas Search, into local Docker context $ geocoding=true ./atlas pull_images # Pushes images, including for Atlas Search, to custom Docker registry $ geocoding=true ./atlas push_images <your-custom-registry.com> # Pulls images, including for Atlas Navigation, and saves them to a tarball in the downloads/docker directory $ navigation=true ./atlas save_images
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.
$ minikube config set memory 8192 $ minikube config set disk-size 100g $ minikube config set cpus 4 $ minikube start $ minikube addons enable ingress
$ 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.
Follow the directions above, and once all pods are ready open Atlas in your browser:
$ open http://atlas.local
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
If you have purchased Atlas Search, enable the Search feature in your deployment by setting the
api-geocoder.enabled value to
true. For example,
By default, Atlas installs with development data. To install Atlas with production data, follow these instructions:
The Atlas Helm charts set default volume sizes that are appropriate for most deployments, and are enough to store production data for Mapbox Terrain v2, Mapbox Streets v8, and Mapbox Satellite. If you plan to download the Terrain-RGB tileset, or if you have purchased high-resolution terrain or satellite tilesets, change the storage requested by the
atlas-mbtiles persistent volume claim based on the size of your data (refer to the System requirements section).
helm install you will need to specify commands to download production tilesets and production geocoding data.
--set "atlas-backend.dataStrategy=script" --set "atlas-backend.dataScriptArgs=prod" --set "global.accessToken=$MAPBOX_ACCESS_TOKEN"
--set "api-geocoder.dataStrategy=script" --set "api-geocoder.dataScriptArgs=prod" --set "global.accessToken=$MAPBOX_ACCESS_TOKEN"
api-geocoder will download data during the
initContainer phase and will only start once their respective data is downloaded.
Download production data using the
- Download tilesets
- Download geocoding data
- Download tilesets
Upload data to a network location accessible from your pods.
Download production tilesets from your network location
- Update the download scripts in
charts/atlas-backend/files/download-tilesets.shto download the tilesets from your network location.
- When installing specify
--set "atlas-backend.dataStrategy=script" --set "atlas-backend.dataScriptArgs=prod"
- Update the download scripts in
Download production geocoding data from your network location
Update the download scripts in
charts/api-geocoder/files/download-data.shto download the tilesets from your network location.
When installing specify
--set "api-geocoder.dataStrategy=script" --set "api-geocoder.dataScriptArgs=prod"
api-geocoderwill download data during the
initContainerphase and will only start once their respective data is downloaded.
To change the password used to login to the Atlas Account page, Studio, and other resources, update its value:
helm upgrade <atlas-release> . --reuse-values --set password=<new-password>
- Recreate the
atlas-backendpod to use the new password (for example,
kubectl rollout restart deploy atlas-backend).
If you are using the TLS option with the
atlas Ingress defined in the Helm chart, deploy a certificate and enable TLS:
When running in EKS with the AWS Load Balancer Ingress Controller, use AWS Certificate Manager to store the TLS certificate. Before starting this section, confirm that you have a valid certificate in ACM and that you know its ARN.
- Confirm that the
true, which are the defaults in the
eks.values.yamlexample file. Confirm your
- Set the
acmARNvalue to the ARN of the certificate.
- Deploy the changes with
- Get a certificate and key. Contact a certificate authority to get a TLS certificate and private key appropriate for your deployment.
- In the namespace of your Atlas installation, create a TLS Secret named
atlas-secret-tlswith the certificate and key.
- Either in the
values.yamlfile or during deployment, set the
trueand update the
global.atlasURLto start with
- Deploy the changes with
If your Atlas license includes access to high-resolution terrain data, set keys in the
global.maxzoomOverrides value to enable access to these tilesets. After reviewing volume sizes and downloading terrain data, set the value either at the command line or in a
helm upgrade <atlas-release> . --reuse-values --set global.maxzoomOverrides.mapbox_terrain_v2=15 --set global.maxzoomOverrides.terrain_rgb=14
global: maxzoomOverrides: mapbox_terrain_v2: 15 terrain_rgb: 14
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. We always recommend that administrators create and test backups of their Atlas data, as well as running in a test environment, before deploying an upgrade to production.
$ helm upgrade <your-release-name> .
When upgrading data (including upgrading from development to production data), use the
dataOverwrite value to instruct the download script to replace existing data with the latest version:
$ helm upgrade <your-release-name> . --reuse-values --set atlas-backend.dataOverwrite=true --set api-geocoder.dataOverwrite=true
Once the data has finished downloading and pods are online, set the value to
false to avoid re-downloading data if a pod restarts:
$ helm upgrade <your-release-name> . --reuse-values --set atlas-backend.dataOverwrite=false --set api-geocoder.dataOverwrite=false
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
If you have any issues while installing or running Atlas, the following troubleshooting strategies may help you diagnose and fix the problem.
The token in the
regcred secret is valid for 12 hours. If it has been more than 12 hours since you ran
./atlas create_docker_secret, run it again to refresh the token.
- Added a
.helmignoreto the chart, addressing an issue where the context sometimes included downloaded image data
- Added new search data, including address coverage for several European countries
- Removed a default setting for
ingressClass; if an environment requires a non-default ingress, set the
- Ingress now supports Kubernetes v1.22+; Ingress support for Kubernetes versions below v1.19 is dropped
- Docker images are now identified by sha256 digest rather than by image tag
- Resolved an error that could occur when changing fonts in Studio
- Resolved an issue where preview thumbnails for tilesets did not appear
- Added schema validation for common parameter values
- Added the
atlasLogLevelglobal parameter to adjust verbosity
- Added the
- Data in PVCs can now be overwritten with the
- Added support for the
maxzoomOverridesglobal value, to support high-resolution tilesets
- Improved OpenShift compatibility by removing UID/GID overrides
- Updated the
download-tilesets.shscript to reflect updated tileset IDs and Boundaries v3
- Updated all internal services to listen on TCP port 8000
- Search data PVC is now versioned to improve stability during upgrades
fsGroupis now specified only if not running on Openshift, as specified by the
- Increased size of
atlas-mbtilesPVC to 600 GB to account for higher Mapbox Streets resolution
- Updated chart to
apiVersion: 2, dropping compatibility with Helm versions before Helm 3
- Removed the
- Fixed an issue where setting the
replicasvalue had no effect
- Fixed an issue affecting deployments with custom rate limits
- Fixed a regression where some pods would not roll if settings were updated
- 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-routerpods automatically roll on upgrade to support license refresh
atlas-datavolume and PVC are now more accurately named
atlas-search-dataPVC 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-s3container now returns status code 200 instead of 304
dataScriptArgsvalue is now properly handled for production data
- Marked the
atlas-enterpriseHelm chart as deprecated
- Chart is now available under the
- Added missing
s3-data-creationimage to helper script
Initial public release