Orchestrated container deployment (Kots)

Deploy CARTO Self-hosted using Kubernetes and Kots

Estimated time: Completing this deployment guide is expected to take approximately 2 hours. This estimate may vary based on individual familiarity with the technology stack involved and the complexity of your organization's environment.

This guide provides step-by-step instructions for deploying CARTO Self-Hosted on a Kubernetes cluster using Kots.

1. Prerequisites

Before you begin, ensure you have the following tools and assets ready.

To deploy CARTO Self-Hosted on Kubernetes, you need:

1.2 Required Tools

• A working installation of kubectl. To install kubectl, see documentation on Google Cloud Platform, AWS, and Azure.

• Kubectl installed on your CLI.

• A working installation of Helm v3 on version 3.6.0 or later.

• Troubleshoot.sh installed to run the preflight checks (view step 4.)

1.3 Required assets

• CARTO Installation Package: You should have received a package from CARTO support containing two key files:

  • carto-values.yaml: Contains the base configuration.

  • carto-secrets.yaml: Contains your license and private credentials.

  • If you don't have it yet, you can ask for it at [email protected].

• Kubernetes Cluster: A running cluster that meets CARTO's hardware and software requirements.

  • To create a cluster, see documentation on Google Cloud Platform, AWS, and Azure. This cluster must fit our hardware and software requirements for Kubernetes.

• External PostgreSQL Database: A running PostgreSQL instance accessible from your cluster.

• Cloud Storage Buckets: Pre-configured storage buckets on a supported provider (GCS, S3, or Azure Blob). You must visit the guide: Configure your own buckets (Helm)

• DNS name and Certificate: You'll need a domain you own, to which you can add a DNS record.

2. Install Kots plugin for kubectl

Type this command to install the Kots plugin:

curl https://kots.io/install | sudo bash

3. Install CARTO

Check that your cluster meets the deployment requirements and use the following command to install the CARTO Admin Console in your Kubernetes cluster:

kubectl kots install carto -n <namespace>

Throughout the installation process, you will be prompted to set a password for accessing the Admin Console. This Admin Console serves as the central hub for managing your CARTO Self-Hosted deployment.

Once the Admin Console is successfully deployed, you will find a link within the console interface itself. Click on this link to navigate to the Kots console, where you will be able to upload your license file and further configure your CARTO Self-Hosted deployment.

Click on the "Continue" button to upload the license of your CARTO Self-Hosted installation and start configuring the different settings of your platform.

4. Login to the Admin Console

The Admin Console is a web-based UI for managing your CARTO installation, including configuration, updates, and license management.

1. Forward the Admin Console port to your local machine. This command creates a secure tunnel to the console running in your cluster. Replace <namespace> with the namespace you used during installation.

   kubectl kots admin-console --namespace <namespace>

2. You'll have a result like this:

kubectl kots admin-console -n <namespace>
  • Press Ctrl+C to exit
  • Go to http://localhost:8800 to access the Admin Console

1. Open your web browser and navigate to: http://localhost:<port>

2. Log in using the password you created during the installation step.

5. Setup metadata database connection

At this point, we are setting up the configuration of the external database. You need to provide a PostgreSQL user and a database that can be used by that user to configure the metadata database used by CARTO platform.

If you already have a PostgreSQL deployment that can be used by your CARTO Self-Hosted platform, you'll have to create a new database for CARTO platform and a user with enough permissions to use that database.

In order to enable TLS connections, you'll also have to provide the SSL certificate of your PostgreSQL database.

Mutual TLS connections between the external database and the APIs are not supported, so client certificates can't be configured on your external database

Azure PostgreSQL Flexible Server:

• Make sure you add ownership over the carto database and all privileges over the schema.

• Extensions must be allowlisted before creation. Run az postgres flexible-server parameter set --name azure.extensions --value "pgcrypto" then create the extension as the admin user. See Azure docs.

6. Setup access to CARTO

Configure your CARTO Self-Hosted domain to my.domain.com.

A full domain is required. You cannot install CARTO in a domain path like https://my.domain.com/carto

Depending on your Kubernetes provider, you'll find the following options to configure the access to CARTO Self-Hosted platform:

GKE

Default access mode

With the default access option we'll setup a standard gke-l7-global-external-managed load balancer service within your cluster to expose the platform through a public IP. Take into account that it's mandatory to enable the Gateway API option of your cluster.

To configure the load balancer you'll have to provide the name of a valid SSL certificate managed on GCP.

You can configure/request your SSL certificate in GCP by navigating to Security > Data protection > Certificate Manager > Classic certificates. In this panel you'll be able to both add a custom SSL certificate or request a certificate managed by GCP.

If you don't have a valid certificate yet for the domain of your Self-hosted, you might be interested in using a self signed one. You can generate a self-signed cert valid for GCP with the following command:

openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -sha256 -days 365

Take into account that you'll have to generate a new key without a passphrase after generating your custom certificate:

openssl rsa -in key.pem -out key_without_pass.pem

If you don't provide a static IP address for your CARTO Self-Hosted platform, the gateway deployed on your GKE will used an automatically assigned one.

Custom access mode

If you'd like to configure your own load balancer, you can select this mode and connect it to the CARTO router service.

Please refer to the "Other providers" tab to obtain more information about how to configure the access to CARTO platform.

EKS

Other providers

7. Setup cloud storage buckets configurations

CARTO Self-hosted platform needs access to some storage buckets to save some resources needed by the platform. These buckets are in charge of storing assets such as imported datasets, map snapshots and custom markers.

You can create and use your own storage buckets in any of the following supported storage providers:

• Google Cloud Storage

• AWS S3

• Azure Blob Storage

And in order to configure them, there is a detailed guide available that you should follow to complete the Self-Hosted configuration process.

8. Run preflight checks and deploy

After saving your configuration, you'll be taken to the Admin Console dashboard to begin the deployment.

8.1 Review preflight checks

The dashboard will automatically run a series of preflight checks to validate that your cluster is ready for CARTO. Review the results carefully to identify and resolve any failures before proceeding.

There are some anomalies in the preflight checks within clusters in GKE with Autopilot enabled that may cause unnecessary alerts or warnings during your deployment process. Please ignore any alerts and proceed with your deployment as usual

Once your CARTO Self-Hosted platform deployment is complete, it's important to ensure all the Kubernetes pods are up and running. You can check clicking in the details link if all the services are running correctly.

Once all of them are in a healthy status, you'll have to find the IP of your deployment and configure your DNS to point to the right IP. In case you selected the default access mode, you can find the IP executing the following commands depending on your cloud vendor:

8.2 Deploy the platform

Once all checks pass, click the Deploy button to begin the installation. This process may take several minutes to complete. After the deployment is finished, you can monitor the status of all Kubernetes pods directly from the dashboard. Click the details link to ensure all services show a healthy and running status.

8.3 Configure your DNS

The final step is to point your DNS record to the application's external IP address. If you selected the default access mode, you can find the IP by running the command corresponding to your cloud provider:

GKE

Obtain the IP of the Gateway deployed for CARTO router:

kubectl get gateway -n <namespace> -o jsonpath="{.items[0].status.addresses[0].value}"

EKS

If you selected the custom access mode or using other provider, then you'll have to obtain that IP depending on the way you configured the access to CARTO Self-Hosted platform.

9. Post-installation checks

In order to verify CARTO Self Hosted was correctly installed, and it's functional, we recommend performing the following checks:

1. Sign in to your Self Hosted, create a user and a new organization.

2. Go to the Connections page, in the left-hand menu, create a new connection to one of the available providers.

3. Go to the Data Explorer page, click on the Upload button right next to the Connections panel. Import a dataset from a local file.

4. Go back to the Maps page, and create a new map.

5. In this new map, add a new layer from a table using the connection created in step 3.

6. Create a new layer from a SQL Query to the same table. You can use a simple query like:

SELECT * FROM <dataset_name.table_name> LIMIT 100;

1. Create a new layer from the dataset imported in step 4.

2. Make the map public, copy the sharing URL and open it in a new incognito window.

3. Go back to the Maps page, and verify your map appears there, and the map thumbnail represents the latest changes you made to the map.

Congrats! Once you've configured your custom buckets, you should have a production-ready deployment of CARTO Self-Hosted at https://my.domain.com

You may notice that the onboarding experience (demo maps, demo workflows...) and the Data Observatory-automated features (subscriptions, enrichment...) are disabled by default in your new organization, because the CARTO Data Warehouse is not enabled.

If you'd like to enable the onboarding experience and the Data Observatory features, follow the guide to enable the CARTO Data Warehouse or contact [email protected].

If you prefer not to enable the CARTO Data Warehouse, you can still use the Data Observatory without the UI features: after getting in touch, our team can deliver the data (both premium and public subscriptions) manually to your data warehouse.

9.1 Analytics Toolbox in CARTO Self-Hosted

To fully leverage CARTO's capabilities you need to gain access to the Analytics Toolbox functions. This step is crucial to fully leverage CARTO's capabilities. Please refer to the documentation of your data warehouse provider for detailed instructions:

• Google BigQuery

• Amazon Redshift

• Snowflake

• PostgreSQL

Troubleshooting

From the Admin Console you'll be able to analyze your CARTO installation by clicking on the Troubleshoot section. You can generate a support bundle from this view, that will collect all the required information to check the status of your deployment.

For further assistance, check our Support page.