Atlas for Kubernetes | Atlas | Mapbox Docs

Introduction

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.

Dependencies

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 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.

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.

Platform	Official Support	Beta Support	Not Supported
AWS Elastic Kubernetes Service	x
Minikube	Dev only
OpenShift	x
Azure Kubernetes Service		x
Google Kubernetes Engine (GCP GKE)		x
Kubernetes Operations (KOPS)		x
Mesosphere Kubernetes Engine		x
OpenStack Magnum		x
VMWare Tanzu		x
AWS Elastic Container Service / Fargate			x
VMWare vSphere			x

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 "https://api.mapbox.com/v2/software/charts?access_token=$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)

# Set password 
$ ./atlas set_redis_password <your-redis-password>

# 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>"

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 <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 geocoding=true or 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

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 atlas.local host entry for ARM-based Macbooks (M1, M2)


$ bash -c 'echo "127.0.0.1 atlas.local" | sudo tee -a /etc/hosts'

On ARM-based Macs, running minikube tunnel is required


minikube tunnel

Add atlas.local host entry for other machines


$ 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.

Enable Atlas Search

If you have purchased Atlas Search, enable the Search feature in your deployment by setting the api-geocoder.enabled value to true. For example,


--set "api-geocoder.enabled=true"

Download production data

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

Review volume sizes

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).

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 "global.accessToken=$MAPBOX_ACCESS_TOKEN"

Download production geocoding data


--set "api-geocoder.dataStrategy=script" --set "api-geocoder.dataScriptArgs=prod" --set "global.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

Download production data using the atlas script commands:
- Download tilesets ./atlas download_tilesets
- Download geocoding data ./atlas download_search_data
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.sh to download the tilesets from your network location.
- When installing specify --set "atlas-backend.dataStrategy=script" --set "atlas-backend.dataScriptArgs=prod"
Download production geocoding data from your network location
- Update the download scripts in charts/api-geocoder/files/download-data.sh to download the tilesets from your network location.
- When installing specify --set "api-geocoder.dataStrategy=script" --set "api-geocoder.dataScriptArgs=prod"
Both atlas-backend and api-geocoder will download data during the initContainer phase and will only start once their respective data is downloaded.

Configure Atlas password

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-backend pod to use the new password (for example, kubectl rollout restart deploy atlas-backend).

Configure TLS certificate

If you are using the TLS option with the atlas Ingress defined in the Helm chart, deploy a certificate and enable TLS:

Configure TLS certificate on EKS with the AWS Load Balancer

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 ingressClass value is alb and that enableTLS is true, which are the defaults in the eks.values.yaml example file. Confirm your atlasURL starts with https://.
Set the acmARN value to the ARN of the certificate.
Deploy the changes with helm upgrade.

Configure TLS certificate on other platforms

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-tls with the certificate and key.
Either in the values.yaml file or during deployment, set the enableTLS value to true and update the global.atlasURL to start with https://.
Deploy the changes with helm upgrade.

Enable high-resolution tilesets

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 values.yaml file:


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

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. 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> .

Upgrade data

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

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

Troubleshoot your Atlas installation

If you have any issues while installing or running Atlas, the following troubleshooting strategies may help you diagnose and fix the problem.

Ingress is created but not accessible

If you are using Atlas with TLS enabled (with the enableTLS value), confirm that the atlas-secret-tls Secret exists and follows the Kubernetes TLS Secret format. Refer to Configure TLS Certificate.

`ImagePullError` occurs on deployment

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.

Release notes

2.9.3

Security

High Vulnerabilities: 101 vulnerabilities resolved for multiple services.
Medium, Low, Negligible, and Unknown Vulnerabilities: Also addressed with varying degrees of resolution.

2.9.0

Updated

Search: The Atlas Geocoder API is now updated to the current Mapbox version as of April 2024.
Navigation: Includes the latest Mapbox Navigation data update.
Streets V8: Refreshed with the latest streets data.

Security

Addressing new security vulnerabilities is an ongoing effort. This release focuses on reducing critical and high vulnerabilities, with notable progress:

Critical Vulnerabilities: From 71 found, 1 remains unresolved, marking a 99% resolution rate.
High Vulnerabilities: Out of 159 found, 25 remain, achieving an 84% resolution rate.
Medium, Low, Negligible, and Unknown Vulnerabilities: Also addressed with varying degrees of resolution.

Unresolved Critical Issue

Vulnerability: underscore | GHSA-cf4h-3jhx-xvhq | Critical | 1.6.0
Component: atlas-api-geocoder
Status: Not Resolved - Won't Fix
Reason: Inclusion in jsonlint-lines, a deprecated service, within an internal library.

2.8.4

Fixed

Fixed Openshift's permission issues for multiple containers
Resolved several Critical/High security vulnerabilities

2.8.3

Added

Added functionality to set password for the Redis server.

Fixed

Permission issues for atlas-ddb container

2.8.2

Fixed

Resolved several critical/high security vulnerability issues

2.8.1

Added

Added a .helmignore to the chart, addressing an issue where the context sometimes included downloaded image data
Added new search data, including address coverage for several European countries

Changed

Removed a default setting for ingressClass; if an environment requires a non-default ingress, set the ingressClass value
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

Fixed

Resolved an error that could occur when changing fonts in Studio
Resolved an issue where preview thumbnails for tilesets did not appear

2.8.0

Added

Added schema validation for common parameter values
Added the atlasLogLevel global parameter to adjust verbosity
Added the api-fonts subchart
Data in PVCs can now be overwritten with the dataOverwrite subchart values
Added support for the maxzoomOverrides global value, to support high-resolution tilesets

Changed

Improved OpenShift compatibility by removing UID/GID overrides
Updated the download-tilesets.sh script 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
The fsGroup is now specified only if not running on Openshift, as specified by the global.platform value
Increased size of atlas-mbtiles PVC to 600 GB to account for higher Mapbox Streets resolution
Updated chart to apiVersion: 2, dropping compatibility with Helm versions before Helm 3

Removed

Removed the api-maps subchart

Fixed

Fixed an issue where setting the replicas value 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

2.7.0

Added

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

Changed

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

Fixed

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

2.6.2

Deprecated

Marked the atlas-enterprise Helm chart as deprecated

2.6.1

Added

Chart is now available under the mapbox-atlas chart name

Fixed

Added missing s3-data-creation image to helper script

2.6.0

Initial public release

追加の開発者リソース

このpageは役に立ちましたか？

Introduction​

Dependencies​

Supported platforms​

Install Atlas​

Add the Mapbox Helm repository​

Get the Helm chart​

Get the Helm chart and images for offline use​

Get Atlas Search or Atlas Navigation images​

Test on Minikube​

Configure and start Minikube​

Add atlas.local host entry for ARM-based Macbooks (M1, M2)​

Add atlas.local host entry for other machines​

Install the Helm chart​

Configure Atlas​

Enable Atlas Search​

Download production data​

Review volume sizes​

For deployments on networks with internet access​

Download production tilesets and data​

Download production tilesets​

Download production geocoding data​

For deployments on networks without internet access​

Configure Atlas password​

Configure TLS certificate​

Configure TLS certificate on EKS with the AWS Load Balancer​

Configure TLS certificate on other platforms​

Enable high-resolution tilesets​

Upgrade Atlas​

Upgrade data​

Renew license​

Troubleshoot your Atlas installation​

Ingress is created but not accessible​

ImagePullError occurs on deployment​

Release notes​

2.9.3​

Security​

2.9.0​

Updated​

Security​

2.8.4​

Fixed​

2.8.3​

Added​

Fixed​

2.8.2​

Fixed​

2.8.1​

Added​

Changed​

Fixed​

2.8.0​

Added​

Changed​

Removed​

Fixed​

2.7.0​

Added​

Changed​

Fixed​

2.6.2​

Deprecated​

2.6.1​

Added​

Fixed​

2.6.0​

Introduction

Dependencies

Supported platforms

Install Atlas

Add the Mapbox Helm repository

Get the Helm chart

Get the Helm chart and images for offline use

Get Atlas Search or Atlas Navigation images

Test on Minikube

Configure and start Minikube

Add atlas.local host entry for ARM-based Macbooks (M1, M2)

Add atlas.local host entry for other machines

Install the Helm chart

Configure Atlas

Enable Atlas Search

Download production data

Review volume sizes

For deployments on networks with internet access

Download production tilesets and data

Download production tilesets

Download production geocoding data

For deployments on networks without internet access

Configure Atlas password

Configure TLS certificate

Configure TLS certificate on EKS with the AWS Load Balancer

Configure TLS certificate on other platforms

Enable high-resolution tilesets

Upgrade Atlas

Upgrade data

Renew license

Troubleshoot your Atlas installation

Ingress is created but not accessible

`ImagePullError` occurs on deployment

Release notes

2.9.3

Security

2.9.0

Updated

Security

2.8.4

Fixed

2.8.3

Added

Fixed

2.8.2

Fixed

2.8.1

Added

Changed

Fixed

2.8.0

Added

Changed

Removed

Fixed

2.7.0

Added

Changed

Fixed

2.6.2

Deprecated

2.6.1

Added

Fixed

2.6.0