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.

Requirements

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

• A CARTO Self-Hosted installation package containing your a license key. The package has a YAML file containing the required information to deploy your Self-Hosted platform. If you don't have it yet, you can ask for it at [e-mail].

• A domain you own, to which you can add a DNS record.

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

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

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

1. Install Kots plugin for kubectl

Type this command to install the Kots plugin:

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

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

If you need to access the Admin Console at a later date, you can do so by running the following command:

kubectl kots admin-console -n <namespace>

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

Metadata database

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

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

Default access mode

With the default access option we'll setup a standard load balancer service within your cluster to expose the platform through a public IP.

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

You can request your SSL certificate or import a self-signed certificate in AWS by navigating to the AWS Certificate Manager.

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 AKS will used an automatically assigned one. Please, take into account that AWS will automatically assign a domain to your load balancer, but you'll just be able to access CARTO platform from the domain you configured before.

In case you want to avoid providing a static IP for your load balancer, you'll have to configure your domain to point to the load balancer. There is more information explaining how to proceed with the needed changes available here.

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.

Other providers

Configuring the access to CARTO platform involves multiple steps, particularly regarding networking and security considerations. CARTO supports HTTPs only, which means any deployment must ensure secure communication over HTTPS.

You'll have to deploy your own load balancer. This load balancer will handle incoming HTTPS traffic and direct it to the appropriate services within your Kubernetes cluster.

CARTO likely has a service responsible for routing incoming requests to the appropriate components within its deployment. You'll need to ensure that your custom load balancer is connected to the router service so that it can correctly forward incoming requests to CARTO.

Since CARTO requires HTTPS, you'll need to configure SSL certificates for securing communication. TLS termination can be configured at different levels within the deployment:

• Terminate TLS inside CARTO application: You can configure SSL certificates directly at the router service level. This ensures that all incoming traffic to the CARTO platform is encrypted right at the entry point.

• Terminate TLS in a higher layer and connect to CARTO over HTTP: Alternatively, SSL certificates can be configured at a higher layer, such as the Load Balancer level. In this setup, the Load Balancer terminates SSL connections and forwards decrypted traffic to the router service and other components of the CARTO platform within the Kubernetes cluster. This approach offloads SSL termination from individual components within the Kubernetes cluster, simplifying their configuration.

By following these steps, you can deploy the CARTO platform ensuring secure and efficient communication using HTTPS while accommodating customers' SSL certificate requirements.

Ingress testing mode

When configuring the access to CARTO platform you can enable the ingress testing mode by selecting the following option:

This will deploy the minimum needed components of CARTO platform to ensure that the layers that you configure on top of CARTO are working as expected. If everything is correctly configured, you should see the following static website when navigating to CARTO platform:

Once you can see that website, this means that CARTO platform access mode is correctly configured and you just have to disable the ingress testing mode and apply the change to start using the application.

Cloud Storage

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.

Deploy CARTO Self-Hosted platform

After finalizing your configuration, proceed by clicking the “Continue” button, which will direct you to the Dashboard of your CARTO Admin Console. Here, you'll observe a series of checks being performed to verify the readiness of your environment for hosting the CARTO platform.

It's essential to review the results of these checks to identify any failures. If all checks pass successfully, you can proceed by clicking the “Deploy” button to initiate the installation process of your Self-Hosted platform. Please, note that deployment completion may take a few minutes.

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:

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

Obtain the IP of the Load Balancer service deployed for CARTO router:

kubectl get svc --namespace {{ .Release.Namespace }} {{ include "carto.router.fullname" . }} -o jsonpath='{.status.loadBalancer.ingress.*.ip}

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.

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 [e-mail].

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.

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.