Test proxy data source against Kernel

[IlyaasK]

Summary

• create a uniquely named managed datacenter proxy fixture
• test kernel_proxy lookup by canonical ID and exact name
• test explicit resource scope and provider-default project scope
• verify only durable masked metadata reaches Terraform state
• require an empty follow-up plan
• add the proxy package to the manual acceptance workflow

Why this is v0 work

This closes the live coverage gap for the existing v0 kernel_proxy data source without adding a Terraform proxy resource or any runtime proxy operations.

Tests

• go test -short -timeout=2m ./...
• go test -race -short -timeout=2m ./internal/datasources/proxy ./internal/acctest ./internal/kernelclient
• opt-out test proving the acceptance test skips before network access
• go vet ./...
• go mod verify
• go mod tidy -diff
• terraform fmt -check -recursive examples
• bash scripts/check-markdown-links.sh
• bash scripts/check-docs.sh
• git diff --check
• gofmt -l cmd internal

Acceptance status

The live API path was not run locally because real Kernel credentials were not available to this worktree. It is available through the manual Acceptance workflow and requires TF_ACC=1, KERNEL_ACC=1, KERNEL_API_KEY, and KERNEL_PROJECT_ID.

Intentionally unsupported

• no Terraform proxy resource
• no custom proxy credential management
• no proxy health checks
• no runtime status, IP address, or credential fields in Terraform state
• no browser/session runtime operations

---

Note

Low Risk
Changes are limited to acceptance tests and CI matrix configuration; no provider runtime or data-handling logic is modified.

Overview
Adds live acceptance coverage for the existing kernel_proxy data source and wires it into the manual Acceptance workflow.

TestAccProxyDataSourceByIDAndName provisions a unique datacenter proxy via the Kernel API, then asserts lookups by id + project_id and by name (provider-default project) return durable fields (type, protocol, etc.) while credentials, status, and ip_address stay out of state. A plan-only step checks for drift after apply.

Fixture helpers register acctest.CleanupProxy and post-test verification that the proxy is gone.

^{Reviewed by Cursor Bugbot for commit f41e8d5. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 8435357. Configure here.}

[linear-code]

KERNEL-1559 Terraform provider v1: production-ready durable Kernel configuration

tldr

Ship v1 of the Kernel Terraform provider so a user can describe their durable Kernel platform config — project, browser infra, profiles, proxies, extensions, deployments, and carefully-scoped API keys — entirely in Terraform. Durable desired-state only; runtime/session activity is explicitly out of scope. Start from the merged v0 state, produce a scope-audit + plan before coding, and ship in small per-resource PRs.

Current groundwork already done

API-contract prerequisites and the security hardening surfaced while auditing them are in flight as draft PRs on kernel/kernel. v0 of the provider is merged; provider resource code should begin after these land and one batched Stainless SDK regen + kernel-go-sdk bump.

API contract prep (draft PRs):

• #2599 — reject API key self-deletion (a key can't delete the key authenticating the request)
• #2600 — document name uniqueness + list query match semantics
• #2602 — browser pool reads echo resolved profile_id / extension_ids (stable references for state)
• #2603 — make the browser pool OpenAPI contract truthful (PATCH clear sentinels, validation bounds, defaults)
• #2604 — exact-match name= filter on list endpoints (stacked on #2600)
• #2607 — store + return a sha256 checksum for uploaded extensions (drift detection)
• #2608 — persist + echo deployment source identity (repo/ref/path/checksum; write-only source becomes importable)
• #2624 — document env var redaction on deployment/app reads (values redacted for API-key auth) — mergeable

Security fixes surfaced during the audit (draft PRs):

• #2629 — getSession cross-project scope: a project-scoped key could reach sibling projects' live browser sessions (fs/process/computer/CDP/curl) — now 404
• #2632 — block project-scoped keys from org-level mutations (org limits, credential providers)
• #2633 — enforce project scope on the projects endpoints: scoped keys can read + rename their own project only; create/delete/status/limits stay org-key-only

Open decisions before the late phases:

• API key resource state design (plaintext-once, rotation, self-delete) — phase 8 gated on acceptance
• #24 force_destroy and #25 tfplugingen codegen dispositions (see below)
• One batched SDK regen sequences all of the above into the provider

---

v1 product definition

v1 should manage durable Kernel platform configuration.

core v1 resources:

• kernel_project
• kernel_browser_pool
• kernel_profile
• kernel_proxy
• kernel_extension
• kernel_deployment
• kernel_api_key, if safe state semantics are designed and accepted

core v1 data sources:

• kernel_project
• kernel_browser_pool
• kernel_profile
• kernel_proxy
• kernel_extension
• kernel_deployment
• kernel_app
• kernel_api_key metadata lookup, masked only

important adjustment:

• kernel_app should probably be a data source, not a resource, unless the API exposes apps as first-class mutable durable objects separate from deployments.
• app invocations are runtime and must not be Terraform resources.
• app logs are observability/runtime and must not be Terraform resources.
• standalone kernel_secret should not be added unless Kernel exposes a dedicated durable secrets API with safe write-only or masked-read semantics.
• app env vars belong on kernel_deployment; mark them sensitive.

explicit non-goals

do not add Terraform resources for temporary/runtime activity:

• browser sessions
• acquire/release
• browser pool flush
• app invocation
• invocation status updates
• invocation browser cleanup
• logs
• screenshots
• live view
• telemetry streams
• runtime counters
• leased browser state
• session recovery
• managed runtime browser updates

do not add these unless explicitly approved later:

• billing resources
• org membership resources
• audit log resources
• managed-auth credentials/connections
• standalone secret store resources without a real Kernel secret API
• internal-only admin controls
• dashboard-only or integration-specific objects such as Vercel resources

do not manually edit generated files.

do not include private Slack, Linear, customer, or internal discussion context in code, comments, commits, branches, docs, or PR bodies.

required first step: v1 scope audit

before writing code, inspect:

• current openapi/stainless/sdk surface in kernel/kernel
• current v0 provider architecture in kernel/terraform-provider-kernel
• current docs in kernel/docs
• open github issues in kernel/terraform-provider-kernel
• docs/concerns.md
• v0 acceptance tests and release docs

produce a concise v1 implementation plan before coding.

the plan must classify every candidate resource as:

• in v1 core
• v1 optional/late
• v1 non-goal
• blocked on API contract

github issues to resolve in v1

handle these explicitly:

#24 force_destroy

evaluate whether force_destroy belongs in v1.

default position:

• keep it out unless there is a concrete user workflow that needs Terraform to delete in-use browser pools.
• if added:
  • default must be false
  • behavior must be opt-in
  • docs must explain that it can terminate live browser work
  • tests must cover default false and true-when-set
  • state preservation must avoid perpetual drift
  • architecture docs must record the exception

#25 tfplugingen-framework codegen

evaluate before adding many new schemas.

preferred v1 approach:

• if codegen is accepted, do it early.
• generate only mechanical Terraform shape:
  • schema structs
  • model structs
  • nested attribute helpers
  • basic validators from durable API contract
• keep behavior handwritten:
  • CRUD
  • import
  • update/clear semantics
  • exact lookup behavior
  • sensitive handling
  • browser pool flatten/expand decisions
  • chrome policy normalization
• add a CI drift check if generated files are introduced.
• never generate runtime/session APIs into Terraform.

if codegen is not implemented, document why in docs/concerns.md or architecture docs and close/defer the issue accordingly.

architecture requirements

Terraform manages durable desired state only.

all resources must obey:

• create/read/update/delete where supported
• import where possible
• exact lookup data sources
• stable project scoping
• no runtime fields in desired state
• sensitive values marked sensitive
• no secret values logged
• delete semantics documented
• update-vs-replace semantics explicit
• clear/null/empty semantics explicit
• acceptance tests for real API behavior

project scoping rules:

• provider-level project_id remains default.
• resource-level project_id overrides provider default where supported.
• changing project_id should force replacement unless the API explicitly supports moving the resource.
• unscoped/org-wide resources must be clearly modeled.

runtime fields:

• omit if not useful for Terraform.
• computed-only if they help users inspect state and do not cause drift.
• never use volatile runtime fields to drive diffs.

sensitive fields:

• api_key, proxy credentials, deployment env vars, GitHub tokens, and created API key plaintext must be sensitive.
• avoid reading secret values back into state.
• if API returns secrets in read responses, document the state risk and mark fields sensitive.
• prefer masked metadata on reads.

resource design expectations

kernel_project

include if API supports project lifecycle.

likely fields:

• id
• name
• durable limits if API treats them as project-owned config
• created/updated timestamps computed-only if useful

requirements:

• exact lookup by id/name
• import by id
• test create/update/delete/import
• decide whether project limits are nested fields or separate kernel_project_limits

kernel_profile

include durable profile ownership.

requirements:

• create/read/update/delete/import if API supports it
• exact lookup by id/name
• omit runtime usage fields such as last_used_at unless computed-only
• profile archive upload/download only if API semantics are stable
• no browser-session save behavior as Terraform action

kernel_proxy

include durable proxy config if API supports user-owned proxy records.

requirements:

• credentials sensitive
• health/check status computed-only or omitted
• changing immutable connection fields should replace
• exact lookup by id/name
• import support

kernel_extension

include durable extension records.

requirements:

• support uploaded extension/package if API supports it
• support Chrome Web Store/reference flow only if API treats it as durable config
• use file hash/source hash to detect package changes
• browser pool owns extension_ids ordering
• exact lookup by id/name
• import support

kernel_browser_pool

harden v0.

requirements:

• preserve durable-only model
• expand acceptance coverage
• verify update/clear behavior for profile/proxy/extensions/chrome_policy/start_url/viewport
• resolve or explicitly defer force_destroy
• no runtime/session state

kernel_deployment

include for app platform v1.

model deployments, not invocations.

likely fields:

• id
• version
• source block for GitHub deploys
• file/archive path only if Terraform can produce stable reproducible diffs
• entrypoint_rel_path
• region
• force
• env_vars, sensitive
• app_name/actions/status computed from API
• deployment status computed-only

requirements:

• create/read/delete
• update probably replace unless API supports mutation
• import by deployment id
• do not stream deployment events as Terraform state
• do not model logs
• do not invoke apps
• private GitHub token sensitive and preferably not persisted after create if API does not store it

kernel_app

default to data source only.

requirements:

• exact lookup by app name/version
• expose deployment id, version, actions, region, maybe env var keys but not secret values if avoidable
• no app resource unless API exposes app-level create/update/delete separate from deployment lifecycle

kernel_api_key

include late in v1 only after state design is accepted.

requirements:

• create/list/get/update/delete/rotate are API-supported.
• plaintext key is returned once on create/rotate.
• Terraform resource must expose plaintext key as sensitive computed only when created/rotated.
• reads must use masked metadata.
• import must import metadata only, never recover plaintext.
• rotation must be explicit:
  • either a separate action-like pattern is avoided
  • or rotation is triggered by an explicit rotate_on_change/keeper-like field
• support project-scoped keys.
• do not let the provider accidentally destroy the API key it is currently using unless clearly documented.

api/sdk contract requirements

before implementing each resource, verify:

• exact create/read/update/delete endpoints exist
• SDK exposes the endpoint or provider can safely wrap generated client
• read response includes stable ids
• list pagination is documented
• exact lookup can distinguish zero and multiple matches
• update clear semantics are documented:
  • omitted
  • null
  • empty string
  • empty array
  • empty object
• server defaults are documented
• validation bounds match API behavior
• sensitive fields are masked or safely handled
• import behavior is possible
• project scoping behavior is clear
• delete behavior is safe and idempotent enough for Terraform

if any gap blocks implementation, log it in docs/concerns.md and do not guess.

preferred PR phases

prefer small PRs. split anything large.

phase 0: v1 architecture and scope PR

• update architecture docs for v1 target surface
• update docs/concerns.md
• classify open issues
• decide codegen approach
• no large implementation yet

phase 1: codegen/drift decision PR

• implement tfplugingen workflow only if accepted
• add CI drift check if generated files exist
• otherwise document why v1 remains handwritten

phase 2: project resource PR

• kernel_project
• project data-source hardening
• import
• acceptance tests

phase 3: durable browser support PRs
split by resource:

• kernel_profile
• kernel_proxy
• kernel_extension
• browser pool hardening

phase 4: apps/deployments PRs
split into:

• kernel_deployment
• kernel_app data source
• env var sensitive handling
• examples

phase 5: api keys PR
only after sensitive state design is accepted:

• kernel_api_key
• kernel_api_key data source
• rotation/import semantics
• docs warning

phase 6: v1 release readiness PR

• docs
• examples
• acceptance matrix
• changelog
• migration notes from v0
• registry/release automation
• final v1 checklist

implementation process

for each PR:

1. read the relevant API docs/openapi/sdk/code.
2. write a small resource design note in the PR body or docs.
3. implement the smallest coherent vertical slice.
4. add focused unit tests.
5. add acceptance tests behind explicit env gates.
6. update generated docs.
7. update examples.
8. run review gates.
9. open a draft PR.

do not implement multiple resources in one PR unless one is a tiny shared helper needed by the other.

testing requirements

always run:

• gofmt -l cmd internal
• go test -short -timeout=2m ./...
• go vet ./...

when terraform is available:

• terraform fmt -check -recursive examples
• bash scripts/check-docs.sh
• any example validation script

for each resource:

• schema tests
• expand/flatten tests
• CRUD behavior tests with fake client
• import tests
• project-scope tests
• sensitive field tests
• acceptance test

acceptance tests:

• opt-in only
• unique names
• cleanup registered early
• no runtime/session operations unless testing deployment creation itself
• no force deletion unless explicitly testing accepted force_destroy

follow fast-test discipline:

• focused unit tests first
• integration tests only where unit tests cannot prove behavior
• docker/start-heavy tests only where necessary
• keep setup fast
• use eblog.fly.dev's test fast / docker fast / start fast guidance as the testing philosophy

required review gates

run these gates for every PR before push.

gate 1: deslop

• inspect git diff <base>...HEAD.
• remove ai-looking comments, needless defensive checks, dead code, style drift, and casts that avoid real type work.
• preserve comments that document real invariants.

gate 2: auto incremental self-pr review

• review the diff in small logical chunks.
• do this autonomously.
• maintain an internal action-item list:
  • correctness
  • terraform semantics
  • state drift
  • sensitive data
  • project scoping
  • import behavior
  • acceptance coverage
  • docs/examples
  • scope creep
• fix accepted findings before the next gate.

gate 3: autoreview

• run structured autoreview against the branch/pr diff.
• verify every finding in code.
• fix accepted/actionable findings.
• reject speculative or over-broad findings explicitly.

gate 4: final agreement pass

• review gates run linearly, not in parallel.
• each review sees the fixed result from prior reviews.
• if reviewers disagree, choose the simpler safer design that preserves Terraform semantics and durable-only scope.
• final summary must state:
  • findings fixed
  • findings rejected and why
  • remaining risks
  • final clean review result

subagent coordination rules

implementation agents:

• use only when work can be split by resource or file ownership.
• assign disjoint write sets.
• tell agents they are not alone in the codebase.
• avoid parallel edits to shared provider registration or shared helpers unless one agent owns that layer.

review agents:

• never run in parallel.
• run linearly:
  1. deslop reviewer
  2. incremental self-reviewer
  3. autoreview reviewer
  4. final agreement pass
• do not run expensive review panels unless explicitly requested.

PR requirements

every PR must include:

• summary
• resource/data-source scope
• API contract notes
• Terraform state semantics
• sensitive field handling
• import behavior
• tests run
• acceptance status
• known deferred concerns
• whether the PR resolves any GitHub issues

open draft PRs by default.

save branch and PR artifacts after pushing/opening.

v1 done criteria

v1 is complete when:

• all core durable resources are implemented or explicitly deferred with documented API blockers.
• every resource has import support or a documented reason it cannot.
• every resource has unit tests and acceptance tests.
• generated docs are current.
• examples cover common production use.
• sensitive values are handled deliberately.
• API key semantics are safe or API keys are deferred.
• deployment env vars are sensitive and documented.
• app invocations/logs/runtime browser operations are not Terraform resources.
• #24 is resolved by implementation or explicit documented rejection.
• #25 is resolved by implementation or explicit documented rejection.
• ci and release workflows are production-ready.
• v0 users have clear migration notes.

required PR breakdown

keep PRs small. one PR should usually cover one resource capability or one shared concern. if a PR crosses resource boundaries, split it.

target size:

• ideal: one resource/data-source vertical slice or one shared helper
• avoid: multiple new resources in one PR
• avoid: schema + CRUD + import + acceptance + docs for several resources together
• if a PR is hard to review in one sitting, split it

phase 0: v1 planning and issue disposition

PR 0.1: v1 scope and architecture

• update architecture docs for v1 target surface
• define durable-only boundary
• list v1 core resources and non-goals
• no implementation

PR 0.2: concerns and github issue disposition

• update docs/concerns.md
• classify open issues
• explicitly decide expected handling for #24 and #25
• no implementation

phase 1: codegen decision

PR 1.1: codegen decision doc

• evaluate tfplugingen-framework
• decide generated vs handwritten ownership
• document whether v1 will adopt codegen

if codegen is accepted:

PR 1.2: generator tooling skeleton

• add pinned generator command/script
• generate one low-risk schema/model only
• no broad migration

PR 1.3: codegen drift check

• add CI drift check
• document regeneration workflow

if codegen is rejected/deferred:

PR 1.2-alt: close codegen loop

• document why handwritten remains v1 path
• update docs/concerns.md
• mark #25 resolved/deferred

phase 2: projects

PR 2.1: project API/client wrapper

• add durable project client methods
• tests only around client/wrapper behavior

PR 2.2: kernel_project resource create/read

• schema/model
• create/read
• focused tests

PR 2.3: kernel_project update/delete/import

• update semantics
• delete semantics
• import
• tests

PR 2.4: project limits

• either nested project limits or separate kernel_project_limits
• only if API semantics are stable
• tests/docs

PR 2.5: project acceptance/docs/examples

• acceptance tests
• generated docs
• examples

phase 3: profiles

PR 3.1: profile client + schema/model

• durable profile API wrapper
• schema/model
• tests

PR 3.2: kernel_profile create/read

• create/read only
• tests

PR 3.3: kernel_profile update/delete/import

• update semantics
• delete semantics
• import
• tests

PR 3.4: profile data source hardening

• exact lookup behavior
• pagination/ambiguity handling
• tests

PR 3.5: profile acceptance/docs/examples

phase 4: proxies

PR 4.1: proxy client + schema/model

• sensitive credential design
• tests

PR 4.2: kernel_proxy create/read

• create/read only
• tests

PR 4.3: kernel_proxy update/delete/import

• update vs replace
• delete/import
• tests

PR 4.4: proxy data source hardening

• exact lookup
• masked/sensitive fields
• tests

PR 4.5: proxy acceptance/docs/examples

phase 5: extensions

PR 5.1: extension client + schema/model

• decide upload vs reference semantics
• file/hash design if uploads are supported
• tests

PR 5.2: kernel_extension create/read

• create/read only
• tests

PR 5.3: kernel_extension update/delete/import

• package/hash update behavior
• delete/import
• tests

PR 5.4: extension data source hardening

• exact lookup
• tests

PR 5.5: extension acceptance/docs/examples

phase 6: browser pool v1 hardening

PR 6.1: browser pool update/clear contract tests

• profile/proxy/extensions/chrome_policy/start_url/viewport semantics
• no feature expansion

PR 6.2: browser pool data source

• add kernel_browser_pool data source if missing
• exact lookup/import docs

PR 6.3: force_destroy decision

• if rejected: docs/tests confirming default safe delete
• if accepted: schema/model + default false only

PR 6.4: force_destroy implementation, only if accepted

• delete plumbing
• drift handling
• acceptance coverage
• docs warning

phase 7: apps/deployments

PR 7.1: deployment state design doc

• decide source types
• decide env var sensitivity
• decide replace/update behavior
• no implementation

PR 7.2: deployment client wrapper

• create/list/get/delete methods
• tests

PR 7.3: kernel_app data source

• list/filter exact lookup
• actions/version/deployment metadata
• tests

PR 7.4: kernel_deployment create/read/delete

• GitHub source path first
• no local archive unless separately approved
• tests

PR 7.5: deployment env vars and sensitive handling

• sensitive map behavior
• state risk docs
• tests

PR 7.6: deployment import/replace semantics

• import by deployment id
• replace-on-change rules
• tests

PR 7.7: deployment acceptance/docs/examples

optional:

PR 7.8: local archive deployment source

• only if Terraform can model diffs safely
• otherwise defer

phase 8: api keys

PR 8.1: api key Terraform state design

• plaintext-once behavior
• import limitations
• rotation semantics
• provider-self-delete warning
• no implementation

PR 8.2: api key client wrapper

• create/list/get/update/delete/rotate
• tests

PR 8.3: kernel_api_key data source

• masked metadata only
• exact lookup
• tests

PR 8.4: kernel_api_key create/read/update/delete

• sensitive computed key on create only
• metadata reads
• tests

PR 8.5: api key rotation

• explicit rotation trigger only
• sensitive computed replacement key
• tests

PR 8.6: api key acceptance/docs/examples

phase 9: v1 release readiness

PR 9.1: v1 acceptance matrix

• document required acceptance tests per resource
• add manual workflow updates if needed

PR 9.2: ci/release hardening

• generated docs check
• example validation
• link check
• release workflow/signing if not already present

PR 9.3: v1 docs and examples

• complete generated docs
• production examples
• migration notes from v0

PR 9.4: v1 changelog/release checklist

• final release checklist
• known limitations
• deferred v1.x items

PR splitting rule

before opening each PR, estimate review scope.

split the PR if it does more than one of:

• introduces a new resource
• introduces a new data source
• changes shared provider architecture
• adds release/ci infrastructure
• adds acceptance infrastructure
• resolves a cross-cutting sensitive-state design

tests and docs for the same resource may stay with that resource PR. shared helpers should be separate when more than one resource depends on them.