Skip to main content
Version: V1-Next

Generic Remote/Cloud Cluster Setup

This guide covers the requirements and setup for deploying CIVITAS/CORE on remote Kubernetes clusters (cloud providers, on-premises, etc.).

Overview​

Remote deployments assume you have an existing Kubernetes cluster accessible via kubeconfig. The platform will be installed using automated certificates from Let's Encrypt and requires internet-accessible domains.

Prerequisites​

Kubernetes Cluster Requirements​

Your Kubernetes cluster must meet these requirements:

  • Kubernetes Version: 1.21 or higher
  • Cluster Access: kubectl access with cluster-admin permissions
  • Resources: Minimum 4 CPU cores, 16GB RAM available
  • Storage: Dynamic volume provisioning support
  • Ingress: kubernetes ingress-nginx Ingress Controller installed and configured
  • Internet Access: Cluster nodes can access internet for image pulls
  • Load Balancer: LoadBalancer service type support (cloud provider or MetalLB)

Domain and DNS Requirements​

  • Domain: A (sub)domain pointing to your cluster's external IP
    • Wildcard DNS record recommended (e.g., *.example.com → <cluster-ip>)
    • Individual records acceptable (requires manual DNS entry for each service)
  • SSL Certificates: There are two options
    1. Use Let's Encrypt which will automatically provision certificates. Note: Domains must be reachable from internet for Let's Encrypt validation
    2. You can use your own CA as well

Network Requirements​

  • Ingress Controller: NGINX Ingress Controller with external LoadBalancer
  • Firewall:
    • HTTP: Ports 80 (HTTP) and 443 (HTTPS) accessible from internet
    • MQTT (only when enabled): 8883 (MQTTS) and 9876 (WSS) For more details have a look at: MQTTS
  • Email: Port 587 (SMTP) for outbound email if using email features

Control System Requirements​

The machine from which you run the installation must have:

Software Requirements​

  • curl
  • git
  • sshpass
  • openssl
  • Python >= 3.8
  • helm
  • kubectl

Python Dependencies​

Install via pip:

pip install cc-cli

Or install individual components:

pip install ansible.core>=2.13 openshift==0.12.1 kubernetes==12.0.1 ansible-lint>=5.0 docker>=5.0 jmespath

Ansible Collections​

ansible-galaxy collection install kubernetes.core>=2.2
ansible-galaxy collection install community.grafana
ansible-galaxy collection install community.mongodb==1.3.2

Cluster Configuration​

1. Kubeconfig Setup​

Ensure your kubeconfig is properly configured:

# Verify cluster access
kubectl cluster-info

# List available contexts
kubectl config get-contexts

# Use appropriate context
kubectl config use-context <your-cluster-context>

2. Ingress Controller Verification​

Verify NGINX Ingress is installed and has external IP:

kubectl get svc -n ingress-nginx

You should see a LoadBalancer service with an EXTERNAL-IP.

3. Storage Classes​

Verify available storage classes:

kubectl get storageclass

Note the storage class names for your inventory configuration.

4. Cert-Manager (Optional)​

If not already installed, cert-manager will be installed automatically. To install manually:

helm repo add jetstack https://charts.jetstack.io
helm repo update
helm upgrade cert-manager jetstack/cert-manager --install --namespace cert-manager --create-namespace --set installCRDs=true

Next Steps​

Once your cluster meets these requirements:

  1. Customize Inventory: Use the Inventory Configuration Guide
  2. Configure Platform: Follow Platform Installation Guide

Troubleshooting​

Common Issues​

DNS Resolution Problems

  • Verify domain points to correct IP: nslookup your-domain.com
  • Check LoadBalancer external IP: kubectl get svc -n ingress-nginx

Certificate Issues

  • Let's Encrypt requires domain to be internet-accessible
  • Check cert-manager logs: kubectl logs -n cert-manager deployment/cert-manager

Resource Constraints

  • Monitor resource usage: kubectl top nodes
  • Scale cluster if needed before installation

Ingress Controller Issues

  • Verify NGINX Ingress status: kubectl get pods -n ingress-nginx
  • Check LoadBalancer service: kubectl get svc -n ingress-nginx

Cloud Provider Specific Guides​

For detailed setup instructions for specific cloud providers:

  • Azure AKS Setup - Complete Azure AKS cluster setup with Azure CLI
  • AWS EKS - (Coming soon)
  • Google GKE - (Coming soon)

For detailed troubleshooting, see the main Deployment Guide.