Feedback, votes and roadmap, built in.
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
- Design: Platform Feedback: Architecture
- Tracking: datum-cloud/enhancements#889, service and API epic #943
The CRDs are defined. The operator sets owners and reviewers in admission, reconciles votes, follows and submission reviews, and stores attachments. Triage, security reports and digests are tracked as sub-issues of the epic.
| Resource | Who writes it | Who reads it |
|---|---|---|
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 |
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). 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.
The owner admission webhook sets spec.userRef on every user-owned kind
from the request: in a user's own context it is always that user. Only the
operator creates them for someone else, and the Security Team logs reports
for external reporters with no owner. The reviewer webhook records who
decided on a SubmissionReview.
- Admission (
votewebhook). A vote or follow needs a post that exists, isn't hidden and isn't merged. A vote also needs a verified email address. votereconciler. It follows the post for each new voter, then setsstatus.subscribedso a follow the voter deletes isn't recreated. It records the voter's organizations and linked GitHub username in the vote's status; these Milo lookups are best effort. Votes on a deleted post are marked withfeedback.miloapis.com/orphaned-atand deleted after 30 days unless the post returns.post-votesreconciler. It counts a post's votes from the cache (indexed byspec.postRef.name) and appliesstatus.votes.{total,datum,linked,trendingScore}with server-side apply asfeedback-operator.githubandgithubReactionsbelong tofeedback-sync.total = datum + github - linked, wherelinkedcounts people whose 👍 comes from the GitHub account linked to their vote. Posts with a trending score are re-tallied hourly as votes age.mergereconciler. Whenstatus.mergedIntois set, it gives each voter and follower the same on the target post, unless they already have one, and deletes the old one.
- Admission (
submissionwebhook): the sender's email must be verified, and each user can send at most--submission-limit(default 5) per--submission-window(default 10 minutes), counted from the cache. AMergedreview decision must name a post that exists, isn't hidden and isn't merged (submissionreviewwebhook). submissionreconciler. It creates each submission'sSubmissionReview, owned by the submission so Milo's garbage collector deletes it with the submission, and sets the phase toPendingReview.submission-reviewreconciler. It carries out the staff decision:Rejectedcopies the reason to the submission.Mergedhas the submitter follow (reason: merged) and vote on the post.Approvedwaits until feedback-sync creates the GitHub issue and syncs a post annotatedfeedback.miloapis.com/submission: <name>. It then links the submission to that post and has the submitter follow (reason: submitted) and vote.- The
Appliedcondition andstatus.appliedrecord when the decision has been fully carried out.
CRDs can't take file uploads, so feedback uploads (the feedback-uploads Deployment) handles them. Clients use the same bearer token they use for Milo.
POST /users/{user}/uploads/{submissions|securityreports}?name=shot.png (body: the file, with its Content-Type)
GET /users/{user}/{submissions|securityreports}/{name}/attachments/{ref} (the owner)
GET /{submissions|securityreports}/{name}/attachments/{ref} (staff)
- Checking the caller. A Milo
TokenReviewidentifies the caller. ASubjectAccessReviewchecks that they may create (to upload) or get (to download) that resource in the context the path names. In a user's context, the service also checks that the object is theirs. - Files accepted. Files are type-checked against their content: PNG, JPEG, GIF, WebP, PDF, text and JSON only. The size limit is 10 MiB by default, and each user gets a per-minute upload limit.
- Storage. Files land under
uploads/<purpose>/<user>/in the bucket. - Limits per replica. Downloads stream from the bucket. Each upload is buffered, up to the size limit, to check its type.
--max-concurrent-uploads(default 4) and--max-concurrent-downloads(default 32) cap transfers on one replica; past them it answers 503 withRetry-After. One user may hold at most--max-concurrent-uploads-per-user(default 2) and--max-concurrent-downloads-per-user(default 8) of them, so slow requests from one user can't keep everyone else out; past that they get 429 withRetry-After. Each transfer gets a deadline sized for its file, at 64 KiB/s plus 30 seconds. - Attaching. The
attachmentsmutating webhook checks everyuploadRefon a new submission or report is the owner's upload for that purpose, and sets its name and type from the upload. - Keeping and deleting. The operator copies attached files under
submissions/<name>/as soon as the submission exists, and adds thefeedback.miloapis.com/attachmentsfinalizer. Deleting the submission deletes its files. - Lifecycle rule. The bucket's lifecycle rule should delete
uploads/after a day. - Configuration. Set the bucket in the
feedback-configConfigMap (attachments-bucket). The operator and the upload service share it.
| Role | For |
|---|---|
feedback.miloapis.com-user |
every signed-in user, in their own context, through Milo's iam-user-self-manage |
feedback.miloapis.com-public-reader |
the datum.net service account |
feedback.miloapis.com-viewer, -editor, -reviewer, -admin |
staff |
feedback.miloapis.com-security-team |
the Security Team only; the only role that reads every report and their triage |
The service's components (system:feedback-operator, system:feedback-sync,
system:feedback-uploads, all @feedback.miloapis.com) authenticate with
client certificates and get Kubernetes RBAC in Milo (config/milo/rbac).
cmd/feedback/ operator, uploads and version commands
internal/attachments/ the attachments bucket
internal/controller/ reconcilers
internal/identity/ who a request comes from, from Milo's user info
internal/index/ cache field indexes shared by reconcilers and webhooks
internal/milo/ voter lookups in Milo
internal/ratelimit/ per-user token bucket
internal/uploads/ the feedback-uploads HTTP service
internal/webhook/ admission webhooks Milo calls
pkg/apis/feedback/ feedback.miloapis.com/v1alpha1 types (CRDs)
config/crd/ generated CRDs, installed in Milo
config/base/ operator and uploads Deployments, Services, leader election RBAC
config/components/ milo-integration: Milo kubeconfig, client and webhook certificates
config/milo/ applied to Milo: IAM (iam/), RBAC for the service's
components (rbac/), webhook config (webhook/), and
optional role bindings (bindings/)
config/samples/ an example of every resource
test/config/ checks config/ against the CRDs
task build # bin/feedback
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-buildRun the operator against a Milo you can reach, in a container:
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/certsThese ship outside this repository and must be live in an environment before users can reach the feedback API there:
- Audit policy. Milo's audit policy logs
Submission,SubmissionReview,SecurityReport,SecurityReportTriageandFeedbackDigestatMetadataonly (datum-cloud/infra#9437). Without it, private submission and report content would be written to audit logs. - Owner filtering in Milo (milo-os/milo#1017), released to that Milo. Without it, a user listing votes or submissions would see everyone's.
- User and public-reader bindings. The
feedback.miloapis.com-userrole bound to every signed-in user in their own context (through Milo'siam-user-self-manage), andfeedback.miloapis.com-public-readerbound to the datum.net service account. Without them, users and the website have no access. - The operator is ready before its webhooks are registered. The webhook configurations fail closed, so apply them after the operator's readiness check passes.