Private Locations CLI Integration

Integrate Private Locations with Checkly CLI and monitoring-as-code workflows. Define Private Locations in your TypeScript and JavaScript projects.

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

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']
})

JavaScript

const { ApiCheck, BrowserCheck } = require('checkly/constructs')

// API check for internal service
new ApiCheck('database-health-check', {
  name: 'Database Connection Health',
  request: {
    method: 'GET',
    url: 'http://db-proxy.internal:8080/health'
  },
  privateLocations: ['internal-network'],
  assertions: [
    { source: 'STATUS_CODE', comparison: 'EQUALS', target: 200 }
  ]
})

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

Version Control

• Store Private Location configurations in version control
• Use environment-specific configuration files
• Document Private Location dependencies
• Include deployment scripts in your repository

Security

• 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

Testing

• Test Private Location configurations locally
• Validate check configurations before deployment
• Use staging environments for testing
• Implement rollback procedures

Monitoring

• 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.