Skip to main content

​
Integration with Checkly CLI

Define Private Locations in your monitoring-as-code workflow using the Checkly CLI. This enables version-controlled, repeatable deployments of your monitoring infrastructure.

​
Basic Configuration

  • TypeScript
  • JavaScript
import { ApiCheck, BrowserCheck } from 'checkly/constructs'

// API check using private location
new ApiCheck('internal-api-check', {
  name: 'Internal API Health',
  request: {
    method: 'GET',
    url: 'http://internal-api.company.local/health'
  },
  privateLocations: ['company-datacenter-east'],
  maxResponseTime: 5000
})

// Browser check using private location  
new BrowserCheck('internal-app-check', {
  name: 'Internal App Login Flow',
  code: {
    entrypoint: './internal-app.spec.ts'
  },
  privateLocations: ['company-datacenter-east']
})

​
Advanced Configuration

​
Multiple Private Locations

Configure checks to run from multiple Private Locations for redundancy: 
new ApiCheck('critical-service-check', {
  name: 'Critical Service Health',
  request: {
    method: 'GET',
    url: 'http://critical-service.internal/health'
  },
  privateLocations: ['datacenter-primary', 'datacenter-secondary'],
  maxResponseTime: 3000,
  retryCount: 2
})

​
Environment-Specific Configuration

Use environment variables to configure Private Locations dynamically: 
// checkly.config.ts
import { defineConfig } from 'checkly/constructs'

export default defineConfig({
  projectName: 'Internal Monitoring',
  logicalId: 'internal-monitoring',
  checks: {
    locations: ['us-east-1', 'eu-west-1'],
    privateLocations: process.env.PRIVATE_LOCATIONS?.split(',') || [],
    tags: ['internal', process.env.ENVIRONMENT || 'development']
  }
})

​
Conditional Private Location Usage

Use conditional logic to determine Private Location usage: 
const usePrivateLocations = process.env.USE_PRIVATE_LOCATIONS === 'true'
const privateLocationNames = usePrivateLocations ? ['internal-network'] : []

new ApiCheck('service-health-check', {
  name: 'Service Health Check',
  request: {
    method: 'GET',
    url: process.env.SERVICE_URL || 'http://localhost:8080/health'
  },
  privateLocations: privateLocationNames,
  tags: usePrivateLocations ? ['private-location'] : ['public-location']
})

​
Deployment Workflows

​
CI/CD Integration

Integrate Private Location checks into your CI/CD pipeline: 
# .github/workflows/deploy-checks.yml
name: Deploy Monitoring Checks

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  deploy-checks:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
          
      - name: Install dependencies
        run: npm install
        
      - name: Deploy to Checkly
        env:
          CHECKLY_API_KEY: ${{ secrets.CHECKLY_API_KEY }}
          PRIVATE_LOCATIONS: ${{ secrets.PRIVATE_LOCATIONS }}
          ENVIRONMENT: production
        run: npx checkly deploy

​
Environment-Specific Deployments

Deploy different configurations for different environments: 
#!/bin/bash
# deploy-monitoring.sh

ENVIRONMENT=$1
PRIVATE_LOCATIONS=""

case $ENVIRONMENT in
  "production")
    PRIVATE_LOCATIONS="prod-datacenter-east,prod-datacenter-west"
    ;;
  "staging")
    PRIVATE_LOCATIONS="staging-datacenter"
    ;;
  "development")
    PRIVATE_LOCATIONS="dev-network"
    ;;
  *)
    echo "Unknown environment: $ENVIRONMENT"
    exit 1
    ;;
esac

export PRIVATE_LOCATIONS
export ENVIRONMENT

npx checkly deploy

​
Project Structure

Organize your monitoring-as-code project for Private Locations: 
monitoring-project/
├── checkly.config.ts
├── package.json
├── checks/
│   ├── api/
│   │   ├── internal-services.ts
│   │   └── database-health.ts
│   ├── browser/
│   │   ├── internal-apps.ts
│   │   └── admin-dashboards.ts
│   └── shared/
│       ├── assertions.ts
│       └── helpers.ts
├── environments/
│   ├── production.ts
│   ├── staging.ts
│   └── development.ts
└── scripts/
    ├── deploy.sh
    └── validate.sh

​
Configuration Files

checkly.config.ts: 
import { defineConfig } from 'checkly/constructs'
import { productionConfig } from './environments/production'
import { stagingConfig } from './environments/staging'

const config = process.env.ENVIRONMENT === 'production' 
  ? productionConfig 
  : stagingConfig

export default defineConfig(config)
environments/production.ts: 
import { ChecklyConfig } from 'checkly/constructs'

export const productionConfig: ChecklyConfig = {
  projectName: 'Production Internal Monitoring',
  logicalId: 'prod-internal-monitoring',
  checks: {
    privateLocations: ['prod-datacenter-east', 'prod-datacenter-west'],
    tags: ['production', 'internal'],
    runtimeId: '2023.09'
  },
  cli: {
    runParallel: true,
    runLocation: 'us-east-1'
  }
}

​
Best Practices

  • Store Private Location configurations in version control
  • Use environment-specific configuration files
  • Document Private Location dependencies
  • Include deployment scripts in your repository
  • Use environment variables for sensitive configuration
  • Never commit API keys or secrets
  • Implement least-privilege access for deployment
  • Use separate Private Locations for different environments
  • Test Private Location configurations locally
  • Validate check configurations before deployment
  • Use staging environments for testing
  • Implement rollback procedures
  • Monitor your monitoring deployment
  • Track Private Location agent health
  • Alert on deployment failures
  • Regular review of check configurations

​
Troubleshooting

​
Common Issues

Private Location Not Found: 
Error: Private location 'internal-network' not found
Solution: Ensure the Private Location exists in your Checkly account and the name matches exactly. Agent Not Connected: 
Warning: No agents connected to private location 'internal-network'
Solution: Verify that agents are running and connected to the Private Location. Deployment Failures: 
Error: Failed to deploy checks to private location
Solution: Check agent connectivity, API key validity, and network access.

​
Debugging Commands

# Validate configuration
npx checkly validate

# Test check execution
npx checkly test --location internal-network

# Check agent status
npx checkly whoami

# Deploy with verbose logging
npx checkly deploy --verbose

​
Next Steps

Agent Configuration

Learn advanced agent configuration options

Use Cases

Explore real-world deployment patterns

Kubernetes Deployment

Deploy at scale with Kubernetes

Scaling Guide

Plan for growth and redundancy
Start with a simple configuration and gradually add complexity as you become familiar with Private Location integration patterns.
⌘I