Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions .github/workflows/ci.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -11,3 +11,15 @@ permissions:
jobs:
ci:
uses: datum-cloud/actions/.github/workflows/ci-basic.yaml@v1.28.0

envtest:
# ci-basic runs go test without an API server, so the CRD tests skip
# there. This job runs them against envtest.
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- uses: actions/setup-go@v7
with:
go-version-file: 'go.mod'
- uses: go-task/setup-task@v2
- run: task test
43 changes: 26 additions & 17 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,35 +4,44 @@ Guidance for agents working in this repository.

## What this is

`feedback-apiserver`: an aggregated Kubernetes API server for
`feedback.miloapis.com/v1alpha1`, registered with Milo through an
`APIService`. It follows `milo-os/activity` and `milo-os/search`; look there
first for patterns (OpenAPI naming, registry strategies, Milo IAM config).
`feedback`: the `feedback.miloapis.com/v1alpha1` CRDs, installed in Milo, and
the operator that reconciles them and serves their admission webhooks. It
follows `milo-os/billing` and `datum-cloud/compute`; look there first for
patterns (kubebuilder markers, controller-runtime, Milo integration).

The design is `architecture/design/feedback/README.md` in
`datum-cloud/enhancements`. Work is tracked in epic
datum-cloud/enhancements#943.

## Rules that shape the code

- `FeedbackSource` is stored in etcd through the generic registry. Every other
resource uses custom `rest.Storage` backed by Postgres.
- The apiserver is the only component that connects to Postgres. Side effects
of a request (e.g. the `Subscription` created with a `Vote`) are written in
the same transaction.
- GitHub-derived fields live in `status` and are written only by the
`feedback-sync` service account. Staff can only patch `spec.hidden` on posts.
- `Submission` and `SecurityReport` are audited at `Metadata` only. Security
reports are never embedded, indexed, synced or sent to the AI gateway.
- Migrations in `migrations/` are forward-only. Never edit an applied one.
- Every resource is a cluster-scoped CRD in Milo's etcd. There is no
database and no aggregated API server.
- User-owned kinds carry `spec.userRef`, declare
`iam.miloapis.com/owner-field` and make it a selectable field. Milo limits
user-context requests to the caller's objects; the admission webhook sets
`spec.userRef` from the request. Never trust a client-supplied owner.
- Vote and Subscription names are `<post>.<user>` (`v1alpha1.OwnedName`), so
there is one per user per post.
- Anything a submitter or reporter must not see goes on a staff-only kind
(`SubmissionReview`, `SecurityReportTriage`), not on a field.
- Side effects are reconciled by the operator, not done in the request.
Every reconcile step must be idempotent and keyed on deterministic names.
- GitHub-derived fields live in `status` and are written only by
`feedback-sync`. The operator owns post `votes` and `delivery`; both use
server-side apply with their own field manager. Staff can only patch
`spec.hidden` on posts.
- `Submission`, `SubmissionReview`, `SecurityReport` and
`SecurityReportTriage` are audited at `Metadata` only (a Milo audit policy
rule). Security reports are never indexed, synced or sent to the AI gateway.

## Commands

```bash
task build
task test
task generate # deepcopy, clientset, OpenAPI; CI fails if out of date
task test # needs network once, to fetch envtest binaries
task generate # deepcopy and CRDs; CI fails if out of date
task vet
```

Run long-lived processes (Postgres, the server) in containers, not on the host.
Run long-lived processes (the operator) in containers, not on the host.
1 change: 0 additions & 1 deletion Dockerfile
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,6 @@ RUN go mod download

COPY cmd/ cmd/
COPY internal/ internal/
COPY migrations/ migrations/
COPY pkg/ pkg/

RUN CGO_ENABLED=0 GOOS=linux go build \
Expand Down
111 changes: 67 additions & 44 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,12 @@

Feedback, votes and roadmap, built in.

`feedback` serves the `feedback.miloapis.com` API: public roadmap posts synced
from GitHub, votes, submissions, security reports, releases and changelog
entries. It runs as an aggregated API server under Milo, like
[activity](https://github.com/milo-os/activity) and
[search](https://github.com/milo-os/search), so the website, cloud portal,
`datumctl`, Patch and the staff portal all use one API.
`feedback` defines the `feedback.miloapis.com` resources: public roadmap
posts synced from GitHub, votes, submissions, security reports, releases and
changelog entries. They are CRDs installed in Milo, like billing's, so the
website, cloud portal, `datumctl`, Patch and the staff portal all use Milo's
API. The `feedback` operator reconciles them and serves their admission
webhooks.

- Product: [Platform Feedback](https://github.com/datum-cloud/enhancements/blob/main/enhancements/platform/feedback/README.md)
- Design: [Platform Feedback: Architecture](https://github.com/datum-cloud/enhancements/pull/925)
Expand All @@ -16,63 +16,86 @@ entries. It runs as an aggregated API server under Milo, like

## Status

Early scaffold. The server runs and serves `FeedbackSource`. The other
resources in the design are tracked as sub-issues of the epic.
The CRDs are defined and the operator starts. Admission webhooks and
reconcilers are tracked as sub-issues of the epic.

| Resource | Storage | State |
| Resource | Who writes it | Who reads it |
| --- | --- | --- |
| `FeedbackSource` | etcd | served |
| `Post`, `PostQuery`, `Release`, `ChangelogEntry` | Postgres | planned |
| `Vote`, `Subscription` | Postgres | planned |
| `Submission`, `SecurityReport`, `SecurityAcknowledgement` | Postgres | planned |
| `FeedbackSource` | staff | `feedback-sync` |
| `Post`, `Release`, `ChangelogEntry` | `feedback-sync`; the operator writes post votes and delivery | everyone |
| `Vote`, `Subscription`, `FeedbackProfile` | users, for themselves; the operator | the owner, staff |
| `Submission` | users, for themselves; the operator writes status | the owner, staff |
| `SubmissionReview` | staff decide; the operator writes triage | staff |
| `SecurityReport` | users, for themselves; the Security Team writes status | the owner, the Security Team |
| `SecurityReportTriage` | the Security Team | the Security Team |
| `SecurityAcknowledgement`, `FeedbackDigest` | the operator | staff, the website |

## Who sees what

Milo stores user-owned resources in one platform-wide collection. Each
user-owned CRD names its owner field with the `iam.miloapis.com/owner-field`
annotation, and Milo limits user-context requests to the caller's objects
([milo-os/milo#1017](https://github.com/milo-os/milo/pull/1017)). `Post`
names `spec.hidden` with `iam.miloapis.com/hidden-field`, so hidden posts are
invisible to anyone without `get` on `posts/hidden`. Fields only staff may
see live on separate staff-only kinds (`SubmissionReview`,
`SecurityReportTriage`), since a CRD can't hide a field from some readers.

Vote and Subscription names are `<post>.<user>`, which gives one per user per
post across the shared collection.

## Layout

```
cmd/feedback/ serve, migrate and version commands
internal/apiserver/ server wiring and API group installation
internal/postgres/ connection pool, readiness check, migrations runner
internal/registry/ REST storage, one package per resource
migrations/ forward-only SQL migrations (embedded)
pkg/apis/feedback/ feedback.miloapis.com/v1alpha1 types
pkg/generated/ generated clientset and OpenAPI (task generate)
config/base/ apiserver Deployment, Service, RBAC
config/components/ APIService registration
config/milo/ Milo IAM ProtectedResources, Roles, discovery
config/samples/ example resources
cmd/feedback/ operator and version commands
pkg/apis/feedback/ feedback.miloapis.com/v1alpha1 types (CRDs)
config/crd/ generated CRDs, installed in Milo
config/base/ operator Deployment, Services, leader election RBAC
config/components/ milo-integration: Milo kubeconfig, client and webhook certificates
config/milo/ Milo IAM ProtectedResources and Roles
config/samples/ an example of every resource
```

## Postgres

The apiserver is the only component that connects to Postgres. Other
components (`feedback-sync`, `feedback-controller`) write through the API so
every change is authorized in one place and reaches the audit log.

The DSN comes from `--postgres-dsn` or `FEEDBACK_POSTGRES_DSN`. In a cluster
it is read from the `dsn` key of the `feedback-postgres` Secret, which the
environment provides. The database needs the `vector` extension available.

Migrations are forward-only. `feedback migrate` applies them; the Deployment
runs it as an init container, and a Postgres session lock keeps replicas from
migrating at the same time. Add a migration as the next numbered file in
`migrations/`.

## Development

```bash
task build # bin/feedback
task test
task generate # after changing types in pkg/apis
task test # unit tests, plus CRD tests against an envtest API server
task generate # after changing types in pkg/apis: deepcopy and CRDs
task docker-build
```

Run Postgres with pgvector and apply migrations locally:
Run the operator against a Milo you can reach, in a container:

```bash
docker run -d --name feedback-pg -e POSTGRES_PASSWORD=feedback -p 127.0.0.1:5432:5432 pgvector/pgvector:pg17
FEEDBACK_POSTGRES_DSN=postgres://postgres:feedback@127.0.0.1:5432/postgres bin/feedback migrate
docker run --rm -v "$PWD:/src" -v "$HOME/.milo:/milo:ro" -w /src golang:1.27 \
go run ./cmd/feedback operator --milo-kubeconfig=/milo/kubeconfig --webhook-cert-dir=/tmp/certs
```

## Before enabling for users

These ship outside this repository and must be live in an environment before
users can reach the feedback API there:

1. **Audit policy.** Milo's audit policy logs `Submission`,
`SubmissionReview`, `SecurityReport`, `SecurityReportTriage` and
`FeedbackDigest` at `Metadata` only
([datum-cloud/infra#9437](https://github.com/datum-cloud/infra/pull/9437)).
Without it, private submission and report content would be written to
audit logs.
2. **Owner filtering in Milo**
([milo-os/milo#1017](https://github.com/milo-os/milo/pull/1017)), released
to that Milo. Without it, a user listing votes or submissions would see
everyone's.
3. **User and public-reader bindings.** The `feedback.miloapis.com-user` role
bound to every signed-in user in their own context (through Milo's
`iam-user-self-manage`), and `feedback.miloapis.com-public-reader` bound to
the datum.net service account. Without them, users and the website have no
access.
4. **The operator is ready before its webhooks are registered.** The webhook
configurations fail closed, so apply them after the operator's readiness
check passes.

## License

[AGPL-3.0](LICENSE)
25 changes: 21 additions & 4 deletions Taskfile.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,9 @@ vars:
IMAGE_NAME: "ghcr.io/milo-os/feedback"
IMAGE_TAG: "dev"
MODULE: "go.miloapis.com/feedback"
CONTROLLER_TOOLS_VERSION: "v0.22.0"
ENVTEST_VERSION: "release-0.25"
ENVTEST_K8S_VERSION: "1.37.x"

tasks:
default:
Expand Down Expand Up @@ -34,9 +37,21 @@ tasks:
silent: true

generate:
desc: Generate deepcopy, clientset and OpenAPI code
desc: Generate deepcopy code and the CRD manifests
deps: [install-tools]
cmds:
- ./hack/update-codegen.sh
- "{{.TOOL_DIR}}/controller-gen object:headerFile=hack/boilerplate.go.txt paths=./pkg/apis/..."
- "{{.TOOL_DIR}}/controller-gen crd paths=./pkg/apis/... output:crd:artifacts:config=config/crd/bases"

install-tools:
desc: Install code generators into bin/
status:
- test -x {{.TOOL_DIR}}/controller-gen-{{.CONTROLLER_TOOLS_VERSION}}
cmds:
- mkdir -p {{.TOOL_DIR}}
- GOBIN={{.TOOL_DIR}} go install sigs.k8s.io/controller-tools/cmd/controller-gen@{{.CONTROLLER_TOOLS_VERSION}}
- mv {{.TOOL_DIR}}/controller-gen {{.TOOL_DIR}}/controller-gen-{{.CONTROLLER_TOOLS_VERSION}}
- ln -sf {{.TOOL_DIR}}/controller-gen-{{.CONTROLLER_TOOLS_VERSION}} {{.TOOL_DIR}}/controller-gen

fmt:
desc: Format Go code
Expand All @@ -49,9 +64,11 @@ tasks:
- go vet ./...

test:
desc: Run unit tests
desc: Run unit tests, with an envtest API server for the CRD tests
cmds:
- go test ./... {{.CLI_ARGS}}
- |
KUBEBUILDER_ASSETS="$(go run sigs.k8s.io/controller-runtime/tools/setup-envtest@{{.ENVTEST_VERSION}} use {{.ENVTEST_K8S_VERSION}} --bin-dir {{.TOOL_DIR}}/envtest -p path)" \
go test ./... {{.CLI_ARGS}}

docker-build:
desc: Build the container image
Expand Down
Loading
Loading