t1k:web:devops:core
| Field | Value |
|---|---|
| Module | devops |
| Version | 1.31.4 |
| Effort | medium |
| Tools | — |
Keywords: CI/CD, Cloudflare Workers, devops, docker, GCP, kubernetes, neon, serverless
How to invoke
Section titled “How to invoke”/t1k:web:devops:core[platform] [task]DevOps Skill
Section titled “DevOps Skill”Deploy and manage cloud infrastructure across Cloudflare, Docker, Google Cloud, and Kubernetes.
When to Use
Section titled “When to Use”- Deploy serverless apps to Cloudflare Workers/Pages
- Containerize apps with Docker, Docker Compose
- Manage GCP with gcloud CLI (Cloud Run, GKE, Cloud SQL)
- Kubernetes cluster management (kubectl, Helm)
- GitOps workflows (Argo CD, Flux)
- CI/CD pipelines, multi-region deployments
- Security audits, RBAC, network policies
- Putting a system behind a login → see “Auth — studio-auth first” below
GitHub Actions Runner
Section titled “GitHub Actions Runner”Repo CI runs on our ARC pool, selected by org variable — never by label, never hosted.
ubuntu-latest, windows-* and macos-* are not used in this org.
runs-on: ${{ fromJSON(vars.RUNNER_CI_MEDIUM) }} # SMALL for lint/gates, LARGE for heavy builds⚠️ Never inline a label array ([self-hosted, ...]), not even one that matches today: a literal no
runner carries queues the job forever with no error — no failed check, no scheduler error, just a
job that never starts. The variable’s value is set by scripts/set-runner-vars.sh in
The1Studio/arc-github-runners; a new lane is a change there, not in the workflow. Deploys use
${{ fromJSON(vars.RUNNER_CD) }}.
The pool is Linux x64 with sudo apt working (our image the1studio/actions-runner:https-apt
patches the sources to HTTPS — port 80 outbound is blocked from k3s pods) and a Docker-in-Docker
sidecar. Its pod memory ceiling measured 4 GiB with memory.oom.group=1 (2026-08-22), so keep
worker counts modest on heavy Next/Playwright builds.
GitHub-hosted is correct only for a job that genuinely needs a clean public IP or a non-Linux OS
— and then say why in a comment on the runs-on: line. Where a workflow splits, put that one job
hosted and everything else on ARC. Tier reasoning (Jenkins vs ARC, and why) and the migration
playbook: t1k-web-devops-placement → references/runner-tiers.md.
⚠️ Never enable GitHub caching on ARC — no setup-node cache:, no actions/cache step.
Upload runs ~0.6–0.8 MB/s from a pod and the ARC image has no zstd, so a .tgz save can never hit
a hosted run’s .tzst under the same key: every job pays the upload and never reads it back. Cold
installs are far cheaper (bun install --frozen-lockfile ~8 s). Measured evidence:
references/github-actions-self-hosted.md § “GitHub cache is net-negative on ARC”.
Monorepo CI — affected-only build/test and deploy scope
Section titled “Monorepo CI — affected-only build/test and deploy scope”Never run every workspace’s build and test on every push, and never derive deploy targets from the changed path alone — the affected-only shape, the dependency-graph rule and the fail-safe cases are in references/monorepo-ci-scope.md (authoring rules: core’s rules/ci-cd-trigger-design.md).
Cost Is The Gate
Section titled “Cost Is The Gate”Budget is the first-class constraint in provisioning, not a review-time afterthought. Infrastructure decisions compound: a container that could have been a Worker bills every month it runs, and nobody revisits it. Before provisioning anything, state what it costs at today’s load and at 10x, and whether a cheaper tier holds the same workload.
The table below selects on capability. Capability narrows the field; cost picks from what’s left. Two rows that both satisfy the need are not equivalent — GKE and Cloudflare Workers differ by orders of magnitude, and the table alone will not tell you that.
Where a decision is genuinely between our own hardware and the edge, the thresholds live in
/t1k:web:devops:placement — use them rather than estimating.
Cost reporting is mandatory. Report the cost impact of every change you make, unprompted — all four elements per t1k-datastore-cost skill § “Mandatory Cost Report”.
Auth — studio-auth first
Section titled “Auth — studio-auth first”A NEW system that needs a login uses studio-auth (docs/studio-auth.md in theonekit-core), not a new Cloudflare
Access app, a Google OAuth client or its own GitHub-token check. Existing GitHub org-token checks
(ccs-auth-proxy.mjs in theonekit-model-router: /user then /orgs/The1Studio/members/<login>, cached,
fail-closed) stay with their apps; a new app does not copy one. Google sign-in or a Google API need: the order in
docs/studio-auth.md § “Google identity and Google APIs” (reuse the studio Google OAuth client from the vault first; a new
client is the last resort, after the studio-auth exception).
- Never send a broad
ghtoken to a server; a host’s Access status and org 2FA are checked live, never inferred. ⚠️200 []fromGET /access/appsis not proof of no Access gate; a membership check alone admits members without 2FA. - Caller types (machine, staff without GitHub), Access legacy status and the 2FA re-read commands:
references/studio-auth-policy.md.
Existing Access hosts: /t1k:web:devops:selfhost-cloudflare → references/cloudflare-access.md (legacy).
Platform Selection
Section titled “Platform Selection”Capability fit first; then take the cheapest row that still satisfies the need.
| Need | Choose | Cost shape |
|---|---|---|
| Sub-50ms latency globally | Cloudflare Workers | Free to 100K req/day; $5/mo for 10M. Static assets free + unlimited |
| Large file storage (zero egress) | Cloudflare R2 | 10GB free; no egress fees — the reason to prefer it over S3 |
| SQL database (global reads) | Cloudflare D1 | Generous free tier; scales with rows read/written |
| SQL database, Postgres features | Neon (managed Postgres) | No monthly minimum; bills per CU-hour while active. Costed head-to-head against D1 in references/d1-vs-neon-cost.md |
| Containerized workloads | Docker + Cloud Run/GKE | Cloud Run scales to zero; GKE bills a control plane 24/7 |
| Enterprise Kubernetes | GKE | Highest fixed floor here — justify before choosing |
| Managed relational DB | Cloud SQL | Bills continuously, idle or not; no scale-to-zero |
Database default: SQLite (studio decision, 2026-10-04). New storage defaults to SQLite —
drizzle sqlite-core with portable SQL (no Postgres-only types or functions) — because it maps
1:1 onto Cloudflare D1, so a self-hosted service can move to the edge later without a schema
rewrite. Reach for Postgres only for a need SQLite/D1 cannot meet (heavy concurrent writers,
extensions such as pgvector), and say why in the PR.
The three costed options are SQLite/D1, Neon (managed Postgres) and self-hosted Postgres on
hardware you already pay for ($0 marginal). D1 is the serving copy of sealed aggregates (each DB
<=10 GB, cap not raisable); Neon is the choice when you need real Postgres features (jsonb,
INSERT ... SELECT aggregation, heavy concurrent writers) or cannot rewrite existing Postgres SQL.
A D1 database cannot host Postgres-SQL writers. Full comparison, cost formulas and worked numbers:
references/d1-vs-neon-cost.md.
The three rows on the right half of that table that bill while idle — GKE, Cloud SQL, and any always-on container — are where unreviewed spend accumulates. Prefer scale-to-zero unless the workload genuinely cannot tolerate a cold start. | Static site + API | Cloudflare Workers Static Assets (Pages legacy) | | Container orchestration | Kubernetes | | Package management for K8s | Helm |
Quick Start
Section titled “Quick Start”# Cloudflare Workercf init my-worker && cd my-worker && cf deploy # `cf` is the only Cloudflare CLI
# Dockerdocker build -t myapp . && docker run -p 3000:3000 myapp
# GCP Cloud Rungcloud run deploy my-service --image gcr.io/project/image --region us-central1
# Kuberneteskubectl apply -f manifests/ && kubectl get podsReference Navigation
Section titled “Reference Navigation”Cloudflare Platform
Section titled “Cloudflare Platform”cloudflare-platform.md- Edge computing overviewcloudflare-workers-basics.md- Handler types, patternscloudflare-workers-advanced.md- Performance, optimizationcloudflare-workers-apis.md- Runtime APIs, bindingscloudflare-r2-storage.md- Object storage, S3 compatibilitycloudflare-d1-kv.md- D1 SQLite, KV storebrowser-rendering.md- Puppeteer automation
Docker
Section titled “Docker”docker-basics.md- Dockerfile, images, containersdocker-compose.md- Multi-container apps
Google Cloud
Section titled “Google Cloud”gcloud-platform.md- gcloud CLI, authenticationgcloud-services.md- Compute Engine, GKE, Cloud Run, App Engine, Cloud SQL, Storage, plus deployment guides: docker-compose→GCE VM, Cloud Run service migration, stateful-store mapping, cost sizing & committed-use discounts
Managed Databases
Section titled “Managed Databases”d1-vs-neon-cost.md- D1 vs Neon vs self-hosted Postgres, costed: decision rules, pricing formulas (Cloudflare D1 + Neon Launch/Scale), the $10-budget threshold, a worked The1Platform example, and the D1 write-amplification gotchamanaged-postgres-economics.md- where the bill actually goes (compute, not storage), why “typical spend” assumes an idle database, why moving app compute local does NOT cut managed-DB cost, measured latency, and why dump/restore cannot reach parity on a live write workload
CI/CD & Self-Hosted Deploy
Section titled “CI/CD & Self-Hosted Deploy”docker-build-cache.md- Slow build / low cache hit: measure by operation first (export vs install vs build), install-from-manifests layer order, one shared Dockerfile, why CI on ephemeral ARC has no cache, report shapegithub-actions-self-hosted.md- Our ARC runner set first (labels, image, 4 GiB pod ceiling), then plain systemd + ARC how-to, deploy.yml template, runner security
Kubernetes
Section titled “Kubernetes”kubernetes-basics.md- Core concepts, architecture, workloadskubernetes-kubectl.md- Essential commands, debugging workflowkubernetes-helm.md/kubernetes-helm-advanced.md- Helm charts, templateskubernetes-security.md/kubernetes-security-advanced.md- RBAC, secretskubernetes-workflows.md/kubernetes-workflows-advanced.md- GitOps, CI/CDkubernetes-troubleshooting.md/kubernetes-troubleshooting-advanced.md- Debug
Scripts
Section titled “Scripts”scripts/cloudflare_deploy.py- Automate Worker deploymentsscripts/docker_optimize.py- Analyze Dockerfiles (flags an install that runs after a source COPY: run it on every Dockerfile)scripts/buildkit_cache_report.py- BuildKit log: cached vs executed steps and seconds by operation (read before blaming the cache hit rate or the compiler); method inreferences/docker-build-cache.md
Best Practices
Section titled “Best Practices”Security: Non-root containers, RBAC, secrets in env vars, image scanning
Config: growth-driven values (allow-lists, consumers, tenants, flags) are table rows read at request time, not env vars or JSON: t1k:web:devops:deploy § “Config Is Data, Not Deploy Config”
Performance: Multi-stage builds, edge caching, resource limits
Cost: R2 for large egress, caching, right-size resources
Development: Docker Compose local dev, cf dev, version control IaC
Resources
Section titled “Resources”- Cloudflare: https://developers.cloudflare.com
- Docker: https://docs.docker.com
- GCP: https://cloud.google.com/docs
- Kubernetes: https://kubernetes.io/docs
- Helm: https://helm.sh/docs
Hard rules
Section titled “Hard rules”Learned the hard way on a real self-hosted → Cloudflare assessment. Every one of these reads as “working” until it doesn’t.
- An Access-gated endpoint returns HTTP 200 to an unauthenticated probe. The body is the
Cloudflare Access login page, not your API. Any health check, uptime monitor, or migration
script that asserts on status code alone will report a gated API as healthy and reachable.
Assert on
content-type/ body shape, or on the absence of alocation:to*.cloudflareaccess.com— never on200by itself. - Workers cannot reach a Docker-internal host (
postgres:5432) — but that does NOT mean you must expose the database. Hyperdrive connects to a private database two ways: Workers VPC (recommended — a TCP VPC Service over an existing Cloudflare Tunnel, no Access application and no service token) or Tunnel + Access. Path:Worker → Hyperdrive → VPC Service → Tunnel → private DB. Requirescloudflaredrunning in the private network and the Connectivity Directory Admin role. Do not assume the public-endpoint default is the only option — that assumption kills otherwise-viable migrations, and the widely-repeated “Hyperdrive needs a public Postgres” is false. Docs: developers.cloudflare.com/hyperdrive/configuration/connect-to-private-database-vpc/ - Still sequence data before compute where the data itself must move. A private-DB Hyperdrive
hop adds
Worker → Cloudflare → tunnel → originlatency versus a same-box call, so moving an API to Workers while its database stays on-premise can be slower than leaving it. Measure before committing; “it’s on the edge” is not automatically faster when the data is not. - An Access service token bypasses Access for the ENTIRE application, not one route. Minting one
so a Pages Function can proxy
/api/*hands full unauthenticated API access to whatever can read that env var. Weigh it as a credential with the blast radius of the whole app. - Cross-origin credentialed cookies inside iframes break under third-party-cookie partitioning.
If a shell composes sub-apps via
<iframe>, “just enable CORS on the Access app” fails intermittently and un-debuggably in Chrome/Safari. Same-origin is not a legacy constraint there — it is what makes the iframe composition work at all. - R2 rejects AWS Signature v2. Hand-rolled
Authorization: AWS key:sig(HMAC-SHA1) and V2 query presigning both fail against R2 while working fine against MinIO — so “MinIO is S3-compatible, just swap the endpoint” is false. Use SigV4 (@aws-sdk/client-s3); MinIO speaks it too, so one code path serves both and the cutover becomes config-only. - AWS SDK v3 ≥ 3.729 attaches CRC32 flexible checksums by default and R2 rejects them. Set
requestChecksumCalculation: 'WHEN_REQUIRED'. This is the most common “works on MinIO, 400s on R2” cause. - Never write an API token as a bash default.
CF_API_TOKEN="${ENV_VAR:-<literal>}"looks like a safe fallback and is a committed credential; once pushed it is in git history, so deleting the line does not revoke it — only rotation does. Fail loudly on a missing token instead. - Fail loudly when a provider is misconfigured. Silently falling back to the old backend when
e.g.
R2_ACCOUNT_IDis unset hides a broken deploy behind a green startup.