docs: cover undocumented API features and fix inaccuracies#22
Merged
Conversation
Audit the docs against the api repo's interface contract and close the user-facing gaps, plus correct several factual errors verified against api/ and apiserver/ source. New coverage: - WAF rate limiting (limits, keys, shadow mode, waf.limitMetrics) - GitHub link management in the API catalog - project.metrics / project.storageMetrics, disk.metrics - registry.get / getProjectStorage / metrics examples - IPFS/IPNS/DNSLink route targets (API-only) - cache override priority/mode fields Corrections: - audit log: outcomes are success/failure (not forbidden/error); denials are not logged (authz returns before recordAudit); filters are after/before + lowercase resourceType, no action filter; retention is a 1-year TTL, not project lifetime - roles permission table: rewritten from the lowercase catalog; removed non-grantable strings, added missing namespaces, fixed casing - sidecars: only the Cloud SQL Auth Proxy is supported, not generic containers Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
Preview deleted (PR closed). |
These content-addressed schemes are deprecated; don't document them. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Audits the docs against the
apirepo's interface contract (andapiserverenforcement) and closes the user-facing gaps, while correcting several factual errors. Every claim was traced to source before writing.New coverage
networking/waf.md) — a whole shipped feature that was absent: limits, bucket keys (ip/host/asn/country/header/cookie), window/algorithm/mode/status/filter, the 20-limit cap, shadow-mode rollout, andwaf.limitMetrics.api/conventions.md) — new catalog section forgithub.link/unlink/update/list, plus a note on the OIDCexchangeToken/notifypath; also addedcache.*,waf.limitMetrics, andemail.sendrows.access/projects.md) —project.metricsandproject.storageMetricstime-series.storage/disks.md) —disk.metrics(usage + size).registry/overview.md) —registry.get/getProjectStorage/metricsAPI examples.networking/cache.md) —priorityandmodefield bullets (rest was already covered).Corrections (docs were wrong, not just incomplete)
access/audit-log.md):success/failure— notsuccess/forbidden/error.iam.Authorizedreturns beforerecordAudit, so the old "queryoutcome: forbiddento find blocked access" guidance returned nothing and was conceptually wrong.failuremeans an authorized call that errored mid-execution.after/before(notfrom/to),resourceTypeis lowercase and exact-match, there's noactionfilter, andactor/limitexist.actionis a verb (deploy,create, …); actor type isUser/ServiceAccount.access/roles.md) — rewritten from the authoritative lowercase catalog inrole.go. Removed strings that aren't grantable permissions (project.update/usage,deployment.pause/resume/rollback/metrics/revisions,registry.delete/deleteManifest/untag), added 8 missing namespaces (WAF, Cache, Env group, Workload identity, GitHub, Email, Dropbox, Static sites), fixed camelCase→lowercase (matching is exact and case-sensitive, soserviceAccount.createKeygranted nothing), and noted billing is account-ownership-gated.deployments/configuration.md) — only the Cloud SQL Auth Proxy (cloudSqlProxy) is supported; the doc had described generic name/image/command/env sidecars that don't exist.Verification
Hugo builds clean (
hugo --gc), all pages render. Claims checked againstapi/request/response structs andapiserver/(iam permission matching, audit recording, route/deployer materialization, schema TTL).🤖 Generated with Claude Code