Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

nais diff: show what an apply would change

Đang mở
  • Có gì không ổn?
#779 0 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
4/5
Thời gian dự kiến
3-5 ngày
Mức phù hợp với người mới
45/100
Loại issue
Tính năng
Độ rõ ràng
Đặc tả rõ ràng
Mức độ hoạt động
Sôi nổi
Công nghệ
go, kubernetes
Lĩnh vực
backend-api-design, cli

Hướng nghiên cứu

Start by examining the existing apply logic in nais/cli/internal/naisapi/apply.go to add the ChangedFields field to ResourceResult. Then, look at nais/api/internal/apply/ to understand the diff generation in diff.go and how to add a dry-run query parameter to the apply endpoint. The goal is to produce a deterministic diff output that can be rendered in the CLI, matching the behavior of the existing apply command.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

Background

Today nais apply is a one-way door: you send manifests and find out what happened
afterwards. There is no way to see what would change before changing it — neither
interactively nor in a pull request. A nais diff command would close that gap and
make manifest changes reviewable.

The good news: most of it already exists server-side

Verified in nais/api (internal/apply/):

  • ApplyResource (client.go) does a real Kubernetes server-side apply
    (types.ApplyPatchType, FieldManager: "nais-api", Force: true), and it already
    fetches the object before patching, returning {Before, After, Created}.
  • Diff(before, after) (diff.go) already produces a structured, deterministically
    sorted     field diff — []ResourceChangedField{Field, OldValue, NewValue} — with
    server-managed noise (status, managedFields, resourceVersion, uid,
    creationTimestamp, …) filtered out.
  • changedFields is already part of the HTTP response contract
    (model.go: ResourceResult.ChangedFields).

So the diff engine exists. It is currently only used to write activity log entries.

What is missing

nais/api:

  1. No dry-run. PatchOptions has no DryRun: []string{metav1.DryRunAll}, and the
    handler (apply.go) reads no query parameter for it.
  2. Activity log writing must be skipped when dry-running.

nais/cli:
3. internal/naisapi/apply.go ResourceResult does not even declare ChangedFields —
the server sends the diff and the client throws it away.
4. No rendering of changed fields, and no diff command.

Proposed scope

  1. Show changes in nais apply today. Add ChangedFields to the CLI's
    ResourceResult and print them after a successful apply. Requires no API change —
    the data is already on the wire. Good standalone first step.
  2. Dry-run in nais/api. Accept ?dryRun=true on
    POST /api/v1/teams/{team}/environments/{env}/apply, pass DryRunAll through to
    PatchOptions, skip the activity log, return the same changedFields.
  3. nais diff in the CLI. Same argument and flag handling as nais apply — a
    positional <path> that is a single file or a directory, --team/--environment,
    and the same mixin semantics: <base>.<env>.yaml auto-loaded per file in directory
    mode, --mixin/--set accepted only for a single file. Calls the endpoint with
    dryRun=true and renders the result.

Parity with apply matters: the whole point is that you can swap apply for diff
in a command line and have it work. That includes rendering the manifests through the
exact same mixin path, so the diff reflects what apply would actually send.

Why server-side and not client-side

A client-side diff was considered and rejected:

  • The native Valkey/OpenSearch path uses bespoke GraphQL mutations with
    replace semantics (UpdateValkeyInput requires tier and memory, the rest are
    nullable pointers), while the read query GetAllValkeys only returns
    name/memory/tier/maxMemoryPolicy/state — not databases, notifyKeyspaceEvents,
    persistenceDisabled or labels. A client-side diff would be systematically
    incomplete and would need API changes anyway.
  • A server-side dry-run reflects reality: CRD defaulting, mutating/validating webhooks
    and admission errors are all included. A client-side reconstruction is a guess.

CI/PR usage (the main motivation)

- run: nais diff .nais --team pensjon --environment prod-gcp > diff.txt
- uses: marocchino/sticky-pull-request-comment@v2
  with: { path: diff.txt }

where .nais/ holds valkey.yaml, valkey.prod-gcp.yaml, postgres.yaml, … and the
per-environment mixins are auto-loaded,

giving a reviewable comment on the PR:

Valkey valkey-pensjon-cache (prod-gcp)
  ~ spec.memory:  1GB → 4GB
  ~ spec.tier:    HighAvailability → SingleNode

Postgres pensjon-db (prod-gcp)
  + spec.extensions: [postgis]

Valkey valkey-pensjon-sessions (prod-gcp)
  + will be created

This catches things nothing else does today: that a change silently lowers
availability, that a PR creates a resource in prod nobody mentioned, and — when run
periodically on main — drift introduced outside of git.

Design notes / open questions

  • Exit code. Exit 0 even when there is a diff, with an opt-in --exit-code for
    gating (same convention as git diff --exit-code / terraform plan -detailed-exitcode). Failing the job on every change would get the check disabled.
  • Deterministic output. Diff already sorts by field path; keep it that way or
    sticky PR comments will churn on every push.
  • Auth. diff needs authentication against nais-api, unlike schema validation in
    nais apply --dry-run which needs no credentials. That difference matters for fork
    PRs and is a reason to keep both.
  • Coverage. whitelist.go in nais-api allows many kinds; diff quality is bounded
    by what SSA returns, which is fine, but dry-run does not catch asynchronous failures
    in the operators (Aiven capacity etc.). Should be communicated in output.
  • Native manifest shape. The diff is computed on the CRD object. Field paths will
    read as spec.memory etc., which maps closely to the nais manifest spec, but it is
    worth checking how it reads for the flat native envelope before settling on the
    rendering.
  • Naming of the flag/command relative to nais apply --dry-run, which does local
    schema validation without contacting the API.
Ngôn ngữ chính
Go
Star
2
Fork
5
Merge trung bình
16 giờ 50 phút
Pull request đã merge (30 ngày)
23

Chuẩn bị môi trường

Dự án này không cung cấp dev container, Dockerfile hay hướng dẫn đóng góp, nên bạn cần tự thiết lập môi trường: hãy bắt đầu từ README và xem hướng dẫn đóng góp lần đầu của chúng tôi để biết các bước chung.

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của nais/cli

Tất cả issue của nais/cli

Issue tương tự

Thêm issue về Go

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.