Update to CockroachDB

{
  "description": "Guides initial CockroachDB cluster provisioning and production deployment. Self-Hosted covers cockroach start/init, Kubernetes deployment (Operator, Helm), hardware sizing, and production configuration. Advanced/BYOC covers Cloud Console, API, and Terraform provisioning with production settings. Standard covers cluster creation and provisioned compute selection. Basic covers cluster creation and spending limits. Use when creating a new cluster, preparing for production go-live, or validating deployment configuration.",
  "included_files": [
    {
      "relative_path": "references/hardware-and-infrastructure.md",
      "size_in_bytes": 5717
    },
    {
      "relative_path": "references/production-deployment-checklist.md",
      "size_in_bytes": 6033
    }
  ],
  "name": "provision-prod-cluster",
  "skill_md_contents": "---\nname: provision-prod-cluster\ndescription: Guides initial CockroachDB cluster provisioning and production deployment. Self-Hosted covers cockroach start/init, Kubernetes deployment (Operator, Helm), hardware sizing, and production configuration. Advanced/BYOC covers Cloud Console, API, and Terraform provisioning with production settings. Standard covers cluster creation and provisioned compute selection. Basic covers cluster creation and spending limits. Use when creating a new cluster, preparing for production go-live, or validating deployment configuration.\ncompatibility: Self-Hosted requires CLI access and infrastructure provisioning. Advanced/BYOC requires Cloud Console with Org Admin role. Standard requires Cloud Console. Basic requires Cloud Console.\n---\n\n# Provisioning Cluster for Production\n\nGuides CockroachDB cluster creation and production deployment configuration. Before providing procedures, this skill gathers context to deliver tier-appropriate provisioning steps and production hardening guidance.\n\n## When to Use This Skill\n\n- Creating a new CockroachDB cluster\n- Preparing a development/staging cluster for production go-live\n- Validating hardware and configuration for production readiness\n- Choosing the right deployment tier and sizing\n\n**For post-deployment health checks:** Use [reviewing-cluster-health](../reviewing-cluster-health/SKILL.md).\n**For ongoing settings management:** Use [managing-cluster-settings](../managing-cluster-settings/SKILL.md).\n**For capacity changes after deployment:** Use [managing-cluster-capacity](../managing-cluster-capacity/SKILL.md).\n\n---\n\n## Step 1: Gather Context\n\n### Required Context\n\n| Question | Options | Why It Matters |\n|----------|---------|----------------|\n| **Deployment tier?** | Self-Hosted, Advanced, BYOC, Standard, Basic | Completely different provisioning procedures |\n| **Environment?** | Production, Staging, Development | Determines hardware sizing and configuration rigor |\n\n### Additional Context (by tier)\n\n**If Self-Hosted:**\n\n| Question | Options | Why It Matters |\n|----------|---------|----------------|\n| **Platform?** | Bare metal, VMs (AWS/GCP/Azure), Kubernetes | Changes installation and start commands |\n| **If Kubernetes?** | Operator (recommended), Helm, Manual StatefulSet | Determines deployment method |\n| **Node count?** | 3 (minimum), 5, 9+ | Affects topology and replication |\n| **Multi-region?** | Yes (how many regions), No | Requires locality flags and topology planning |\n| **Expected workload?** | OLTP, mixed OLTP/analytics, write-heavy | Affects hardware sizing |\n| **Security requirements?** | TLS required, encryption at rest, CMEK | Determines certificate and encryption setup |\n\n**If Advanced or BYOC:**\n\n| Question | Options | Why It Matters |\n|----------|---------|----------------|\n| **Provisioning method?** | Cloud Console, Cloud API, Terraform | Determines procedure |\n| **Cloud provider?** | AWS, GCP, Azure | Affects region selection and networking |\n| **Node count and size?** | e.g., 3 nodes x 8 vCPUs | Determines initial capacity |\n\n**If Standard:** Gather expected workload size (vCPUs) and storage estimate.\n\n**If Basic:** Gather expected usage pattern and monthly budget.\n\n### Context-Driven Routing\n\n| Tier | Go To |\n|------|-------|\n| Self-Hosted | [Self-Hosted Provisioning](#self-hosted-provisioning) |\n| Advanced | [Advanced Provisioning](#advanced-provisioning) |\n| BYOC | [BYOC Provisioning](#byoc-provisioning) |\n| Standard | [Standard Provisioning](#standard-provisioning) |\n| Basic | [Basic Provisioning](#basic-provisioning) |\n\n---\n\n## Self-Hosted Provisioning\n\n**Applies when:** Tier = Self-Hosted\n\n### Hardware Sizing\n\n| Component | Minimum | Production Recommended |\n|-----------|---------|----------------------|\n| Nodes | 3 | 3+ (odd number per failure domain) |\n| CPU | 4 vCPUs (non-burstable) | 8+ vCPUs |\n| RAM | 16 GB | 32+ GB |\n| Storage | 150 GB SSD | 500+ GB NVMe SSD |\n| Network | 1 Gbps | 10 Gbps |\n\n**Memory formula:** `--cache + --max-sql-memory <= 75% of total RAM`\nRecommended: `--cache=.25 --max-sql-memory=.25`\n\n**Never use:** burstable instances, HDDs, network-attached HDD, shared CPU.\n\nSee [hardware-and-infrastructure reference](references/hardware-and-infrastructure.md) for cloud instance recommendations.\n\n### Deploy on VMs / Bare Metal\n\n**Step 1: Install CockroachDB on each node**\n```bash\ncurl https://binaries.cockroachdb.com/cockroach-v<version>.linux-amd64.tgz | tar -xz\ncp cockroach-v<version>.linux-amd64/cockroach /usr/local/bin/\n```\n\n**Step 2: Generate certificates**\n```bash\ncockroach cert create-ca --certs-dir=certs --ca-key=my-safe-directory/ca.key\ncockroach cert create-node <node-hostname> <node-ip> localhost 127.0.0.1 \\\n  --certs-dir=certs --ca-key=my-safe-directory/ca.key\ncockroach cert create-client root --certs-dir=certs --ca-key=my-safe-directory/ca.key\n```\n\n**Step 3: Start nodes (repeat on each node)**\n```bash\ncockroach start \\\n  --certs-dir=certs \\\n  --store=path=<store-path> \\\n  --listen-addr=<node-address>:26257 \\\n  --http-addr=<node-address>:8080 \\\n  --join=<node1-address>,<node2-address>,<node3-address> \\\n  --locality=region=<region>,zone=<zone> \\\n  --cache=.25 \\\n  --max-sql-memory=.25 \\\n  --background\n```\n\n**Step 4: Initialize cluster (once, from any node)**\n```bash\ncockroach init --certs-dir=certs --host=<any-node-address>\n```\n\n**Step 5: Verify**\n```bash\ncockroach node status --certs-dir=certs --host=<any-node-address>\n```\nEvery node started in step 3 should appear with `is_live = true` and the expected `locality`.\n\n### Deploy on Kubernetes\n\n**Operator (recommended):**\n```bash\nkubectl apply -f https://raw.githubusercontent.com/cockroachdb/cockroach-operator/master/install/crds.yaml\nkubectl apply -f https://raw.githubusercontent.com/cockroachdb/cockroach-operator/master/install/operator.yaml\n# Apply CrdbCluster manifest with node count, resources, and storage\n```\n\n**Helm:**\n```bash\nhelm repo add cockroachdb https://charts.cockroachdb.com/\nhelm install cockroachdb cockroachdb/cockroachdb \\\n  --set statefulset.replicas=3 \\\n  --set storage.persistentVolume.size=100Gi\n```\n\n### Production Configuration (Self-Hosted)\n\nAfter cluster is running, apply production settings:\n\n```sql\n-- Enable critical features\nSET CLUSTER SETTING kv.rangefeed.enabled = true;\nSET CLUSTER SETTING sql.stats.automatic_collection.enabled = true;\nSET CLUSTER SETTING admission.kv.enabled = true;\n\n-- Set timeouts\nSET CLUSTER SETTING sql.defaults.idle_in_transaction_session_timeout = '300s';\nSET CLUSTER SETTING sql.defaults.statement_timeout = '30s';\n\n-- Install enterprise license (if applicable)\nSET CLUSTER SETTING cluster.organization = '<org-name>';\nSET CLUSTER SETTING enterprise.license = '<license-key>';\n```\n\n**Create ballast files on each node:**\n```bash\ncockroach debug ballast <store-path>/auxiliary/EMERGENCY_BALLAST --size=1GiB\n```\n\n**Configure load balancer:** Point to all nodes with health check on `/health?ready=1`.\n\nSee [production-deployment-checklist reference](references/production-deployment-checklist.md) for the full go-live checklist.\n\n---\n\n## Advanced Provisioning\n\n**Applies when:** Tier = Advanced\n\n### Via Cloud Console\n\n1. **cockroachlabs.cloud → Create Cluster**\n2. Select **Advanced** plan\n3. Choose cloud provider (AWS, GCP, Azure)\n4. Select region(s)\n5. Configure node count (minimum 3) and machine size (vCPUs per node)\n6. Configure storage\n7. Review and create\n\n### Via Cloud API\n\n```bash\ncurl -X POST -H \"Authorization: Bearer $COCKROACH_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"<cluster-name>\",\n    \"provider\": \"AWS\",\n    \"spec\": {\n      \"dedicated\": {\n        \"region_nodes\": {\"us-east-1\": 3},\n        \"machine_type\": \"m6i.xlarge\",\n        \"storage_gib\": 150\n      }\n    }\n  }' \\\n  \"https://cockroachlabs.cloud/api/v1/clusters\"\n```\n\n### Via Terraform\n\n```hcl\nresource \"cockroach_cluster\" \"production\" {\n  name           = \"production\"\n  cloud_provider = \"AWS\"\n\n  dedicated {\n    num_virtual_cpus = 8\n    storage_gib      = 150\n    num_nodes        = 3\n  }\n\n  regions = [{\n    name = \"us-east-1\"\n  }]\n}\n```\n\n### Post-Provisioning\n\n- Configure IP allowlists or VPC Peering/PrivateLink\n- Create SQL users and databases\n- Set maintenance window (see [performing-cluster-maintenance](../perform-cluster-maintenance/SKILL.md))\n- Configure metrics export to Datadog/Prometheus if needed\n\n---\n\n## BYOC Provisioning\n\n**Applies when:** Tier = BYOC\n\nFollow [Advanced Provisioning](#advanced-provisioning) steps — BYOC uses the same Cloud Console, API, and Terraform interfaces.\n\n**Additional BYOC steps:**\n- Ensure your cloud account meets CRL prerequisites (service account, VPC, IAM roles)\n- Configure PrivateLink/PSC for private connectivity\n- Verify CRL service account permissions\n\n---\n\n## Standard Provisioning\n\n**Applies when:** Tier = Standard\n\n1. **cockroachlabs.cloud → Create Cluster**\n2. Select **Standard** plan\n3. Choose cloud provider and region\n4. Set provisioned compute (vCPUs) based on expected workload\n5. Create\n\n**Post-provisioning:**\n- Create SQL users and databases\n- Configure IP allowlists\n- Set session-level defaults:\n  ```sql\n  ALTER ROLE ALL SET statement_timeout = '30s';\n  ALTER ROLE ALL SET idle_in_transaction_session_timeout = '300s';\n  ```\n\n---\n\n## Basic Provisioning\n\n**Applies when:** Tier = Basic\n\n1. **cockroachlabs.cloud → Create Cluster**\n2. Select **Basic** plan\n3. Choose cloud provider and region\n4. Create (auto-scales, no sizing needed)\n\n**Post-provisioning:**\n- Set spending limits (Cloud Console → Cluster → Settings)\n- Create SQL users and databases\n- Configure IP allowlists\n\n---\n\n## Safety Considerations\n\n| Operation | Tier | Risk |\n|-----------|------|------|\n| `cockroach init` | SH | Safe — only runs once; subsequent calls are no-ops |\n| Certificate generation | SH | Store CA key securely — loss means no new certs |\n| Cloud cluster creation | ADV/BYOC/STD/BAS | Safe — can be deleted if misconfigured |\n| Production settings changes | SH | See [managing-cluster-settings](../managing-cluster-settings/SKILL.md) |\n\n**Critical (Self-Hosted):**\n- Never use `--insecure` in production — always use TLS\n- Never use burstable instances for production workloads\n- Always set `--locality` flags for multi-node clusters\n- Always configure `--cache` and `--max-sql-memory` (defaults are too low)\n- Always create ballast files before going to production\n\n## Troubleshooting\n\n| Issue | Tier | Fix |\n|-------|------|-----|\n| `cockroach init` fails | SH | Check all nodes are started and reachable on port 26257 |\n| Node won't join cluster | SH | Verify `--join` addresses; check firewall rules for ports 26257, 8080 |\n| \"clock offset\" error | SH | Sync clocks with NTP; check `--max-offset` setting |\n| TLS handshake failure | SH | Verify certs match; check CA is the same across all nodes |\n| Cloud cluster stuck in \"Creating\" | ADV/BYOC | Wait 15 min; contact support if no progress |\n| Cannot connect after creation | ALL | Check IP allowlist; verify connection string; try with root user |\n\n## References\n\n**Skill references:**\n- [Hardware and infrastructure](references/hardware-and-infrastructure.md)\n- [Production deployment checklist](references/production-deployment-checklist.md)\n\n**Related skills:**\n- [reviewing-cluster-health](../reviewing-cluster-health/SKILL.md) — Post-deployment health check\n- [managing-cluster-settings](../managing-cluster-settings/SKILL.md) — Production settings\n- [managing-certificates-and-encryption](../manage-certs-and-encryption/SKILL.md) — TLS setup\n- [managing-cluster-capacity](../managing-cluster-capacity/SKILL.md) — Scaling after deployment\n\n**Official CockroachDB Documentation:**\n- [Install CockroachDB](https://www.cockroachlabs.com/docs/stable/install-cockroachdb)\n- [Start a Cluster](https://www.cockroachlabs.com/docs/stable/start-a-local-cluster)\n- [Deploy on Kubernetes](https://www.cockroachlabs.com/docs/stable/deploy-cockroachdb-with-kubernetes)\n- [Production Checklist](https://www.cockroachlabs.com/docs/stable/recommended-production-settings)\n- [Create an Advanced Cluster](https://www.cockroachlabs.com/docs/cockroachcloud/create-an-advanced-cluster)\n- [Cloud API](https://www.cockroachlabs.com/docs/cockroachcloud/cloud-api)\n"
}