All pages
Powered by GitBook
1 of 1

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 domain you own, to which you can add a DNS record.

1. Install Kots plugin for kubectl

Type this command to install the Kots plugin:

2. Install CARTO

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

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:

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.

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.

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.

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:

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:

Obtain the IP of the Gateway deployed for CARTO router:

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

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

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.