Scaling Team Tooling Repository

A collection of tools and scripts for managing infrastructure, databases, and related services for the Scaling Team.

Overview

This repository contains automation scripts, documentation, and tooling for common operational tasks. The repository is organized to scale as new tools are added.

Quick Start

Passwordless CockroachDB Login

The most common task - setting up passwordless authentication for CockroachDB:

# Complete automated setup (recommended)
./scripts/cockroachdb/auth/setup-passwordless-login.sh --username your-username

# Or step-by-step:
# 1. Configure user
./scripts/cockroachdb/auth/configure-user-passwordless.sh --username your-username

# 2. Generate certificate
./scripts/cockroachdb/certificates/generate-client-cert.sh --username your-username --ca amazingbadger

# 3. Connect
./scripts/cockroachdb/auth/connect-cockroachdb.sh --username your-username

See Passwordless Login Setup Guide for detailed instructions.

Upload CA Certificate

Upload a CA certificate to CockroachDB Cloud:

export COCKROACH_API_KEY='<your-api-key>'
./scripts/cockroachdb/certificates/upload-ca-cert-to-cockroachdb.sh \
  --cluster <cluster-id> \
  --certificate path/to/ca.crt

See CA Certificate Upload Guide for detailed instructions.

Directory Structure

.
├── scripts/                      # All executable scripts
│   ├── cockroachdb/             # CockroachDB-specific scripts
│   │   ├── auth/                # Authentication & user management
│   │   ├── certificates/        # Certificate management
│   │   └── vault/               # Vault PKI integration
│   └── teleport/                # Teleport-specific scripts
├── docs/                        # All documentation
│   ├── getting-started/         # User-facing guides
│   ├── reference/               # Reference documentation
│   │   ├── scripts/             # Script documentation
│   │   └── concepts/           # Conceptual docs
│   └── archive/                 # Historical/legacy docs
├── certificates/                # Certificate storage (gitignored)
├── templates/                   # Script templates for new tools
└── README.md                    # This file

Available Tools

CockroachDB Tools

Authentication & User Management (scripts/cockroachdb/auth/)

• setup-passwordless-login.sh - Complete end-to-end setup for passwordless authentication
• configure-user-passwordless.sh - Configure users with PASSWORD NULL for certificate-only authentication
• connect-cockroachdb.sh - Connection helper that automatically includes client certificates

Certificate Management (scripts/cockroachdb/certificates/)

• generate-client-cert.sh - Generate client certificates signed by trusted CAs
  • Supports: amazingduck, amazingbadger, teleport, vault
• check-cockroachdb-ca-cert.sh - Check existing client CA certificates configured in CockroachDB Cloud
• upload-ca-cert-to-cockroachdb.sh - Upload CA certificates to CockroachDB Cloud (with backup and concatenation support)

Vault PKI Integration (scripts/cockroachdb/vault/)

• setup-vault-pki-cockroachdb.sh - Set up Vault PKI secrets engine and generate root CA (one-time per environment)
• extract-vault-pki-ca.sh - Extract CA certificate from Vault PKI for upload to CockroachDB Cloud

Teleport Tools (scripts/teleport/)

• extract-teleport-ca-cert.sh - Extract Teleport CA certificate from Kubernetes

Documentation

Getting Started Guides

Start here for step-by-step instructions:

• Passwordless Login Setup - Complete guide for passwordless authentication
• Certificate Generation Walkthrough - Manual certificate generation commands
• CA Certificate Upload - Upload CA certificates to CockroachDB Cloud
• Login Instructions - Quick reference for connections
• Create API Key Guide - How to create CockroachDB Cloud API keys

Reference Documentation

Detailed reference material:

• Documentation Index - Complete documentation navigation
• Reference Documentation - Script and concept references
• CA Certificate Behavior - How CA certificate uploads work

Archive

Historical documentation preserved for reference:

• Archive - Historical guides, support requests, and decision records

Common Workflows

Setting Up Passwordless Login for a New User

# Option 1: Automated (recommended)
./scripts/cockroachdb/auth/setup-passwordless-login.sh --username newuser

# Option 2: Manual steps
./scripts/cockroachdb/auth/configure-user-passwordless.sh --username newuser
./scripts/cockroachdb/certificates/generate-client-cert.sh --username newuser --ca amazingbadger
./scripts/cockroachdb/auth/connect-cockroachdb.sh --username newuser

Using Vault PKI

# 1. Set up Vault PKI (one-time per environment)
./scripts/cockroachdb/vault/setup-vault-pki-cockroachdb.sh --environment dev

# 2. Upload CA to CockroachDB Cloud
./scripts/cockroachdb/certificates/upload-ca-cert-to-cockroachdb.sh \
  --cluster <cluster-id> \
  --vault-extract \
  --vault-environment dev

# 3. Generate certificate and configure user
./scripts/cockroachdb/auth/setup-passwordless-login.sh \
  --username frameio-dev-service \
  --ca vault \
  --environment dev

Uploading a New CA Certificate

# Check existing certificates
./scripts/cockroachdb/certificates/check-cockroachdb-ca-cert.sh <cluster-id>

# Upload new certificate (with automatic backup)
./scripts/cockroachdb/certificates/upload-ca-cert-to-cockroachdb.sh \
  --cluster <cluster-id> \
  --certificate path/to/new-ca.crt

Prerequisites

Most scripts require:

• bash (version 4+)
• openssl (for certificate operations)
• kubectl (for Kubernetes CA options)
• cockroach CLI or psql (for database connections)
• vault CLI (for Vault PKI options)
• jq (optional, for JSON parsing)

Security Notes

⚠️ Important Security Practices:

• Never commit private keys (.key files) to git - they are automatically excluded
• Delete CA private keys after generating client certificates
• Set proper permissions: chmod 600 certificates/clients/*.key
• Rotate certificates periodically (default validity: 365 days)
• Use environment variables for sensitive values (API keys, tokens)

Contributing

When adding new tools:

1. Organize by category - Place scripts in appropriate subdirectories under scripts/
2. Follow naming conventions - Use lowercase with hyphens for scripts and docs
3. Document thoroughly - Add getting started guides and reference docs
4. Use the template - Start from templates/script-template.sh for consistency
5. Update this README - Add new tools to the appropriate sections

See templates/script-template.sh for script development guidelines.

Related Resources

• GitOps Repository - Infrastructure configuration managed in gitops repository
• CockroachDB Cloud Console - https://cockroachlabs.cloud
• CockroachDB Documentation - https://www.cockroachlabs.com/docs/

Support

If you encounter issues:

1. Check the troubleshooting sections in the relevant getting started guide
2. Review reference documentation for detailed information
3. Check archive for historical context on similar issues
4. Contact the Scaling Team

---

Repository Structure: This repository is organized to scale as new tools are added. Scripts are categorized by service/tool, and documentation is separated into getting started guides and reference material.