Document the policy store API

Marcos Rocharequested to merge
mc_rocha-add-api-policy-store into master

What does this MR do and why?

This MR adds doc/api/policy_store.md, a new page covering all eight Policy Store REST endpoints, plus a row in doc/api/api_resources.md. It is the last piece of https://gitlab.com/gitlab-org/gitlab/-/work_items/606971, whose endpoints have all merged.

The MR was rebuilt onto master. It previously carried the entire pre-split branch, 48 files across 12 commits, 11 of which merged separately as their own MRs. It is now the single documentation commit on top of master, touching 2 files. That is what resolved the conflicts.

The page was deliberately written after the endpoints, so one page describes the finished surface instead of each endpoint MR editing the same file and conflicting with the next. The cost is that the API moved while the page sat, so the page needed correcting before it could merge.

These are the corrections the endpoint development made necessary:

  • lifecycle_state values: the page said active or inactive. The enum on Govern::Policy is { active: 0, disabled: 1 }, so the correct values are active and disabled. Corrected in !249155 (merged).
  • The rules and actions count limits did not exist: the page claimed a maximum of 10 entries for both. MAX_RULES was dropped during development and nothing bounds either array today. A bound is tracked in https://gitlab.com/gitlab-org/gitlab/-/work_items/612905.
  • The scope_rego examples showed import rego.v1: the scope transpiler stopped emitting it in !250046 (merged), so both JSON examples now show the real second line of the generated program.
  • The list endpoint gained a trigger_type filter: added in !249439 (merged), and missing from the supported attributes table.
  • The scope_rego limit applies as authored, not only after compilation: Grape's limit: validator bounds the parameter at 4096 characters, and a policy_scope that compiles past 4096 characters is separately rejected. Both are now stated. See !250050 (merged).
  • Not every update raises version: the page said each update raises it by one. A request that restates the stored values changes nothing and leaves version as it is.

Beyond the corrections, three things were added:

  • A "Rules and actions" section: documents the type and value shape of an entry, because a reader could not build a rules entry from the parent table row alone. It also records that a request replaces the whole array.
  • A note on content type: rules and actions have to be sent as JSON with a Content-Type: application/json header, since a form-encoded body cannot express nested arrays.
  • US English: "Catalogues" became "Catalogs".

How to set up and validate locally

  1. Run markdownlint:
markdownlint-cli2 doc/api/policy_store.md doc/api/api_resources.md

This reports 0 errors.

  1. Run Vale at warning level:
vale --minAlertLevel warning doc/api/policy_store.md

This reports 0 errors and 0 warnings.

  1. Confirm the OpenAPI definition needs no regeneration:
bin/rake gitlab:openapi:v3:check_docs

This reports OpenAPI v3 documentation is up to date. The definition renders from the Grape route definitions rather than from the Markdown under doc/api/, and this MR changes no Ruby, so the generated specification cannot move.

  1. Cross-check the attribute tables against the params blocks in ee/lib/api/govern/policies.rb, which is where the values, the length limits, and the required attributes are declared. The values: constraints on trigger_type, mode, and lifecycle_state are the ones worth reading closely, since those are what drifted.

  2. Optionally, exercise the endpoints against a local GDK. Three gates must all pass, since the endpoints answer 404 or 403 otherwise: the security_policies_v2 feature flag, the Policy Store experiment application setting under Admin > Settings > Security and compliance, and an Ultimate licence. Policies are held in memory today, so they do not survive a restart. The ActiveRecord backing is https://gitlab.com/gitlab-org/gitlab/-/work_items/606969.

References

Edited by Marcos Rocha

Merge request reports