Skip to main content

MongoDB Atlas Network Configuration - Troubleshooting Guide

For general troubleshooting, see Troubleshooting. This guide covers MongoDB-specific network configuration issues.

Overview​

The SmartRunning application connects to MongoDB Atlas, a cloud-hosted database service. Network configuration, particularly IP whitelisting, is critical for successful connections from deployed applications.

Common Issue: IP Whitelisting​

Problem: SSL/TLS handshake errors in cloud deployments (but not local Docker)

Root Cause: MongoDB Atlas IP whitelist blocking connections, NOT SSL certificate issues

Key Understanding:

  1. Load Balancer IP ≠ Egress IP for outbound database connections
  2. Cloud platforms use managed NAT that may change IPs between deployments

Troubleshooting Steps​

If SSL/TLS Errors Occur After Deployments​

  1. Check Current Egress IP:

    kubectl exec -it deployment/your-app -- \
      python -c "import urllib.request; print('Current Egress IP:', urllib.request.urlopen('https://api.ipify.org').read().decode())"

  2. Compare with MongoDB Atlas Whitelist:

    • Go to MongoDB Atlas → Network Access
    • Verify the current egress IP is whitelisted
    • Format should be: X.X.X.X/32

  3. If IP Changed, Add to Whitelist:

    • Add the new IP with /32 suffix
    • Keep existing working IPs until confirmed stable
    • Test connection after adding

  4. Verify Application Logs:

    kubectl logs deployment/your-app --tail=10

    Look for connection success/failure messages

Cloud Platform NAT Behavior​

  • Custom Cloud NAT: May be created but not used by managed services
  • Managed NAT: Cloud platforms use their own NAT gateways
  • IP Stability: Egress IPs can change between deployments
  • Solution: Use static IPs or whitelist range if supported

Emergency Fixes​

Quick Fix for Immediate Access​

If the application is down due to IP blocking:

# 1. Get current egress IP
kubectl exec -it deployment/your-app -- \
  python -c "import urllib.request; print(urllib.request.urlopen('https://api.ipify.org').read().decode())"

# 2. Add this IP to MongoDB Atlas Network Access with /32 suffix
# 3. Test connection
kubectl logs deployment/your-app --tail=5

Common Misconceptions​

  • ❌ Load Balancer IP is NOT used for MongoDB connections
  • ❌ SSL certificate issues are NOT typically the root cause
  • ✅ IP whitelist blocking is the actual problem
  • ✅ Local Docker works because it uses different network routing (check via ipinfo.io)

Best Practices​

For Production Deployments​

  1. Use Static IPs:

    • Reserve static external IPs in your cloud provider
    • Configure NAT gateway to use static IPs
    • Whitelist these static IPs in MongoDB Atlas

  2. Monitor IP Changes:

    • Set up alerts for connection failures
    • Log egress IP on application startup
    • Document current working IPs

  3. Maintain IP Documentation:

    • Keep record of whitelisted IPs
    • Note which environment uses which IP
    • Update documentation when IPs change

For Development/Testing​

  1. Whitelist Development IPs:

    • Add your local development machine IP
    • Add CI/CD pipeline IPs if applicable
    • Use /32 suffix for single IPs

  2. Temporary Access:

    • MongoDB Atlas allows temporary whitelist entries
    • Set expiration times for development IPs
    • Remove unused IPs regularly

Security Considerations​

  1. Avoid 0.0.0.0/0:

    • Never whitelist all IPs in production
    • Use specific IPs or narrow IP ranges
    • Principle of least privilege

  2. Regular Audits:

    • Review whitelisted IPs monthly
    • Remove IPs no longer in use
    • Verify ownership of all IPs

  3. Network Segmentation:

    • Use different MongoDB clusters for dev/staging/prod
    • Apply different whitelist rules per environment
    • Limit production access strictly

SSL/TLS Configuration​

Docker Configuration​

The application Docker image includes:

  • ca-certificates package
  • openssl package
  • certifi Python package for SSL certificate management

Environment Variables​

Required SSL configuration:

SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt
REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt

These are typically set automatically in the Dockerfile.

Connection String Format​

MongoDB Atlas connection strings should use:

mongodb+srv://username:password@cluster.mongodb.net/database?retryWrites=true&w=majority

Security Notes:

  • Never commit connection strings to version control
  • Use environment variables for credentials
  • Rotate passwords regularly

Kubernetes-Specific Issues​

Pod-to-Pod vs Pod-to-External​

  • Internal cluster communication uses cluster IPs
  • External MongoDB connections use node/NAT egress IPs
  • These are different IP addresses

Network Policies​

If using Kubernetes Network Policies:

  • Allow egress to MongoDB Atlas IP ranges
  • Check if policies are blocking database connections
  • Verify DNS resolution is allowed

Service Mesh Considerations​

If using Istio, Linkerd, or similar:

  • Egress traffic may be proxied
  • Check service mesh egress gateway IPs
  • Configure MongoDB Atlas whitelist accordingly

Testing Connections​

From Local Machine​

# Test DNS resolution
nslookup cluster.mongodb.net

# Test connection with mongosh
mongosh "mongodb+srv://cluster.mongodb.net/database"

From Kubernetes Pod​

# Test from running pod
kubectl exec -it deployment/your-app -- \
  python -c "from pymongo import MongoClient; \
  client = MongoClient('mongodb+srv://...'); \
  print('Connected:', client.server_info())"

Verify Egress IP​

# Check what IP MongoDB Atlas sees
kubectl exec -it deployment/your-app -- \
  curl https://api.ipify.org

Document Version: 2.0 (Public - Sanitized)

Note: This document provides general guidance for MongoDB Atlas network configuration. Specific cluster addresses, IP addresses, and connection strings have been redacted for security.