MongoDB Atlas Manual Setup Guide¶

Overview¶

This guide covers the one-time manual setup for production and staging MongoDB database users. These users are intentionally created manually (not via automation) to protect critical data from accidental deletion.

Related Documents:

Technical Plan - Full implementation strategy

Atlas Operator Setup - PR preview automation

Security Model - Defense-in-depth architecture

Why Manual Setup?¶

Environment	User Management	Rationale
Production	Manual	Critical data - must not be accidentally deleted by automation
Staging	Manual	Long-lived environment - no benefit from automation
PR Preview	Automated	Ephemeral, per-PR isolation, auto-cleanup needed

Key Safety Principle: Production and staging users are completely isolated from any Kubernetes automation. The Atlas Kubernetes Operator only manages PR preview users.

Required Users¶

User	Database Access	Purpose
`syrf_prod_app`	`syrftest` (readWrite)	Production application access
`syrf_staging_app`	`syrf_staging` (readWrite)	Staging application access

Step 1: Create Production User¶

WARNING: This user accesses production data. Handle credentials with extreme care.

Login to MongoDB Atlas: https://cloud.mongodb.com/
Navigate to: Project → Database Access → Add New Database User
Configure user:
Username: syrf_prod_app
Authentication Method: Password (SCRAM)
Password: Generate secure 32+ character password
Set Database User Privileges:
Select "Specific Privileges" (not Built-in Role)
Click "Add Specific Privilege"
Role: readWrite
Database: syrftest
Click "Add User"
Copy the password - you'll need it for the next step

Why Password (SCRAM) Authentication?¶

Simplicity: No certificate management or X.509 infrastructure required
Broad Compatibility: Works with all MongoDB drivers and connection methods
Kubernetes Friendly: Passwords can be stored in Kubernetes Secrets
Industry Standard: SCRAM-SHA-256 provides secure challenge-response authentication

Step 2: Create Staging User¶

Return to: Project → Database Access → Add New Database User
Configure user:
Username: syrf_staging_app
Authentication Method: Password (SCRAM)
Password: Generate secure password
Set Database User Privileges:
Select "Specific Privileges"
Click "Add Specific Privilege"
Role: readWrite
Database: syrf_staging
Click "Add User"
Copy the password for the next step

Step 3: Store Credentials in GCP Secret Manager¶

Store credentials securely in GCP Secret Manager for External Secrets Operator to sync to Kubernetes.

Create Production Secret¶

# Create the secret
gcloud secrets create syrf-prod-mongodb \
  --replication-policy="automatic" \
  --project=camarades-net

# Add the secret value
gcloud secrets versions add syrf-prod-mongodb \
  --data-file=- \
  --project=camarades-net << 'EOF'
{
  "username": "syrf_prod_app",
  "password": "YOUR_GENERATED_PASSWORD"
}
EOF

Create Staging Secret¶

# Create the secret
gcloud secrets create syrf-staging-mongodb \
  --replication-policy="automatic" \
  --project=camarades-net

# Add the secret value
gcloud secrets versions add syrf-staging-mongodb \
  --data-file=- \
  --project=camarades-net << 'EOF'
{
  "username": "syrf_staging_app",
  "password": "YOUR_GENERATED_PASSWORD"
}
EOF

Step 4: Update ExternalSecrets Configuration¶

The cluster uses an extra-secrets Helm chart to manage ExternalSecrets. Update the values files to point to the new GCP secrets.

Update Staging Configuration¶

Edit cluster-gitops/plugins/local/extra-secrets-staging/values.yaml:

secrets:
  # ... other secrets ...

  mongo-db:
    - name: username
      key: syrf-staging-mongodb
      property: username
    - name: password
      key: syrf-staging-mongodb
      property: password

This replaces the previous shorthand format that used camarades-mongo-db.

Update Production Configuration¶

Edit cluster-gitops/plugins/local/extra-secrets-production/values.yaml:

secrets:
  # ... other secrets ...

  mongo-db:
    - name: username
      key: syrf-prod-mongodb
      property: username
    - name: password
      key: syrf-prod-mongodb
      property: password

How It Works¶

The extra-secrets Helm chart generates ExternalSecret resources from values files:

Values File	Target Namespace	GCP Secret
`extra-secrets-staging/values.yaml`	`syrf-staging`	`syrf-staging-mongodb`
`extra-secrets-production/values.yaml`	`syrf-production`	`syrf-prod-mongodb`

The chart supports two formats:

Shorthand: - propertyName → fetches from camarades-{secretName}
Custom key: - name: ..., key: ..., property: ... → fetches from specified GCP secret

Commit and Push¶

cd cluster-gitops
git add plugins/local/extra-secrets-staging/values.yaml
git add plugins/local/extra-secrets-production/values.yaml
git commit -m "feat(secrets): update mongodb credentials to use dedicated staging/prod secrets"
git push

ArgoCD will automatically sync the changes and create the Kubernetes secrets.

Step 5: Verify Setup¶

Check Secret Sync¶

# Verify production secret exists
kubectl get secret mongo-db -n production -o jsonpath='{.data.username}' | base64 -d

# Verify staging secret exists
kubectl get secret mongo-db -n staging -o jsonpath='{.data.username}' | base64 -d

Test Connection¶

Deploy the API service and check logs for successful MongoDB connection:

kubectl logs -n staging deployment/syrf-api | grep -i mongo

Expected: No authentication errors, successful connection.

Credential Rotation¶

To rotate credentials:

Create new password in Atlas Console (Database Access → Edit User)
Update GCP Secret:

gcloud secrets versions add syrf-staging-mongodb \
  --data-file=- \
  --project=camarades-net << 'EOF'
{
  "username": "syrf_staging_app",
  "password": "NEW_PASSWORD_HERE"
}
EOF

Wait for sync (up to 1 hour based on refreshInterval)
Rolling restart pods to pick up new credentials:

kubectl rollout restart deployment/syrf-api -n staging

Troubleshooting¶

Authentication Failed¶

Verify username/password in Atlas Console matches GCP Secret
Check secret sync: kubectl get externalsecret -n staging
Verify Kubernetes secret content: kubectl get secret mongo-db -n staging -o yaml

Network Access Denied¶

Add GKE cluster IP ranges to Atlas Network Access whitelist
Check if using correct cluster address in connection string

Database Not Found¶

Verify database name matches: syrf_staging for staging, syrftest for production
Check Helm values: mongoDb.databaseName should be set correctly

Checklist¶

Production User¶

Create syrf_prod_app user in Atlas Console
Set readWrite on syrftest only
Store credentials in GCP Secret Manager
Create ExternalSecret in cluster-gitops
Verify secret syncs to Kubernetes
Test production deployment

Staging User¶

Create syrf_staging_app user in Atlas Console
Set readWrite on syrf_staging only
Store credentials in GCP Secret Manager
Create ExternalSecret in cluster-gitops
Verify secret syncs to Kubernetes
Test staging deployment with new database