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
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@ their `go.mod`; each fails CI with a specific finding and says how to resolve it
| [`linkweight`](https://spin-stack.github.io/go-tools/linkweight/) | what each binary links and why: the bytes every module puts in it, the function that stops the linker dropping unused methods, the import whose cut drops the most, and a capability - exec, listen, mount, setuid - no line of the allowlist explains |
| [`proven`](https://spin-stack.github.io/go-tools/proven/) | what CI already proved about a commit, by its tree: the run that answers for it, what a run on main is of, whether it may be released, each test's time, which failed tests are flaky |
| [`exposure`](https://spin-stack.github.io/go-tools/exposure/) | what a repository would show if made public: secrets and private values in every ref's commits, pull request heads included, and in its issues, comments and releases |
| [`planguard`](https://spin-stack.github.io/go-tools/planguard/) | an OpenTofu plan that takes something away - a delete, a replacement, a forget - which an installation applying on a schedule leaves to a person, and applies the rest |
| [`task`](https://spin-stack.github.io/go-tools/start/) | not a check: Task at the version `versions.yaml` pins, with every other go-tools command on its `PATH`, the tools at their latest release - both downloaded as binaries; the one command a repository's `go.mod` takes, so neither Task's modules nor the tools' are compiled or cached |
| [`gencache`](https://spin-stack.github.io/go-tools/gencache/) | not a check: `go generate` with each mockgen directive answered from a cache when nothing its mock is made from has changed |
| [`ghatrace`](https://spin-stack.github.io/go-tools/ghatrace/) | not a check: where a GitHub Actions run's time went - the critical path, each job's wait for a runner, its steps and the spans inside them - as the run's summary, an HTML page and a Perfetto trace, with nothing hosted |
Expand Down
73 changes: 73 additions & 0 deletions cmd/planguard/main.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
// Command planguard says whether an OpenTofu plan may be applied without a person reading it
// (internal/planguard): nothing, apply - creates and in-place updates alone - or person, with each
// change that took something away. An installation applying on a schedule applies what says apply
// and opens a pull request for what says person.
//
// tofu plan -out=plan.bin && tofu show -json plan.bin > plan.json
// go tool planguard [-replaceable aws_launch_template,...] plan.json
//
// The verdict is the first line on stdout, the changes held after it; in a workflow it is also
// verdict=<it> in $GITHUB_OUTPUT. The exit status is 0 for any verdict and 2 for no answer, so a
// person's plan is not a failed step: what follows it is the workflow's choice.
package main

import (
"flag"
"fmt"
"io"
"os"
"strings"

"github.com/spin-stack/go-tools/internal/planguard"
)

func main() {
os.Exit(run(os.Args[1:], os.Stdout, os.Stderr)) // mutate-exempt: the process's own arguments; run is what the tests drive
}

func run(args []string, stdout, stderr io.Writer) int {
fs := flag.NewFlagSet("planguard", flag.ContinueOnError)
fs.SetOutput(stderr)
replaceable := fs.String("replaceable", "", "resource types that may be replaced unread, comma-separated")
if err := fs.Parse(args); err != nil {
return 2
}
if fs.NArg() != 1 {
say(stderr, "planguard: usage: planguard [-replaceable type,...] <plan.json>")
return 2
}
raw, err := os.ReadFile(fs.Arg(0))
if err != nil {
say(stderr, "planguard:", err)
return 2
}
var types []string
if *replaceable != "" {
types = strings.Split(*replaceable, ",")
}
d, err := planguard.Decide(raw, types)
if err != nil {
say(stderr, err)
return 2
}
say(stdout, d.Verdict)
for _, h := range d.Held {
say(stdout, " "+h)
}
if path := os.Getenv("GITHUB_OUTPUT"); path != "" {
f, err := os.OpenFile(path, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0o644) //nolint:gosec // the path the runner gives
if err != nil {
say(stderr, "planguard:", err)
return 2
}
_, werr := fmt.Fprintf(f, "verdict=%s\n", d.Verdict)
if err := f.Close(); werr != nil || err != nil {
say(stderr, "planguard: $GITHUB_OUTPUT:", werr, err)
return 2
}
}
return 0
}

// say writes one line. A line that cannot be written changes no exit status, which is the answer.
func say(w io.Writer, a ...any) { _, _ = fmt.Fprintln(w, a...) }
70 changes: 70 additions & 0 deletions cmd/planguard/main_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
package main

import (
"bytes"
"os"
"path/filepath"
"testing"
)

func write(t *testing.T, content string) string {
t.Helper()
p := filepath.Join(t.TempDir(), "plan.json")
if err := os.WriteFile(p, []byte(content), 0o600); err != nil {
t.Fatal(err)
}
return p
}

const (
applied = `{"format_version":"1.2","resource_changes":[{"address":"aws_launch_template.cp","type":"aws_launch_template","change":{"actions":["delete","create"]}}]}`
held = `{"format_version":"1.2","resource_changes":[{"address":"aws_s3_bucket.logs","type":"aws_s3_bucket","change":{"actions":["delete"]}}]}`
)

// The verdict is the first line, the changes held after it, and verdict=<it> in $GITHUB_OUTPUT;
// any verdict exits 0. A type named replaceable is replaced unread.
func TestTheVerdictIsSaidAndWrittenForTheWorkflow(t *testing.T) {
out := filepath.Join(t.TempDir(), "output")
t.Setenv("GITHUB_OUTPUT", out)
for _, tc := range []struct {
args []string
said, kept string
}{
{[]string{write(t, held)}, "person\n aws_s3_bucket.logs: delete\n", "verdict=person\n"},
{[]string{"-replaceable", "aws_instance,aws_launch_template", write(t, applied)}, "apply\n", "verdict=person\nverdict=apply\n"},
{[]string{write(t, applied)}, "person\n aws_launch_template.cp: delete, create\n", "verdict=person\nverdict=apply\nverdict=person\n"},
} {
var stdout, stderr bytes.Buffer
if code := run(tc.args, &stdout, &stderr); code != 0 || stdout.String() != tc.said {
t.Errorf("%v: %d, said %q (%s), want %q", tc.args, code, stdout.String(), stderr.String(), tc.said)
}
if got, err := os.ReadFile(out); err != nil || string(got) != tc.kept {
t.Errorf("%v: $GITHUB_OUTPUT has %q, %v; want %q", tc.args, got, err, tc.kept)
}
}
}

// No plan, two, one that cannot be read or is not a plan, an unknown flag, and a $GITHUB_OUTPUT that
// cannot be written are no answer: exit 2, nothing on stdout.
func TestWhatGivesNoAnswerExitsTwo(t *testing.T) {
t.Setenv("GITHUB_OUTPUT", "")
for name, args := range map[string][]string{
"no plan": nil,
"two": {write(t, held), write(t, held)},
"none there": {filepath.Join(t.TempDir(), "none.json")},
"not a plan": {write(t, "{}")},
"a flag not": {"-x", write(t, held)},
} {
var stdout, stderr bytes.Buffer
if code := run(args, &stdout, &stderr); code != 2 || stdout.Len() != 0 {
t.Errorf("%s: %d, said %q", name, code, stdout.String())
}
}
for what, path := range map[string]string{"a directory": t.TempDir(), "a file that takes no write": "/dev/full"} {
t.Setenv("GITHUB_OUTPUT", path)
var stdout, stderr bytes.Buffer
if code := run([]string{write(t, held)}, &stdout, &stderr); code != 2 {
t.Errorf("a $GITHUB_OUTPUT that is %s: %d", what, code)
}
}
}
104 changes: 104 additions & 0 deletions internal/planguard/planguard.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,104 @@
// Package planguard decides whether an OpenTofu or Terraform plan may be applied without a person
// reading it: what an installation that follows a channel or its module's main applies on a
// schedule, and what it opens a pull request for instead.
//
// A plan is applied unread only when nothing in it is taken away: every change creates a resource
// or updates one in place. A delete, a replacement - delete and create, either order - and a
// forget (state that stops tracking a resource it does not delete) are a person's, whatever the
// resource: the plan cannot say which resources hold data, and a replaced database, bucket or key
// is the kind of change no schedule should make. A resource type a caller names as made to be
// replaced - a launch template's version, an instance an autoscaling group refreshes anyway - may
// be replaced, never deleted alone.
package planguard

import (
"encoding/json"
"fmt"
"slices"
"strings"
)

// Verdict is what a plan asks for.
type Verdict string

const (
// Nothing is a plan with no change to a resource: nothing to apply.
Nothing Verdict = "nothing"
// Apply is a plan of creates and in-place updates alone, which may be applied unread.
Apply Verdict = "apply"
// Person is a plan that takes something away, which a person reads before it is applied.
Person Verdict = "person"
)

// Decision is a plan's verdict, and each change that made it a person's.
type Decision struct {
Verdict Verdict
// Held are the changes a person has to read, "<address>: <actions>", in the plan's order.
Held []string
// Changes is how many resources the plan changes.
Changes int
}

// plan is what `tofu show -json <plan>` says that this reads.
type plan struct {
FormatVersion string `json:"format_version"`
ResourceChanges []struct {
Address string `json:"address"`
Type string `json:"type"`
Mode string `json:"mode"`
Change struct {
Actions []string `json:"actions"`
} `json:"change"`
} `json:"resource_changes"`
}

// Decide reads a plan as `tofu show -json` writes it. replaceable are the resource types that
// may be replaced unread.
func Decide(raw []byte, replaceable []string) (Decision, error) {
var p plan
if err := json.Unmarshal(raw, &p); err != nil {
return Decision{}, fmt.Errorf("planguard: not a plan's JSON: %w", err)
}
// A file with no format is not a plan: an empty object would read as nothing to do.
if p.FormatVersion == "" {
return Decision{}, fmt.Errorf("planguard: no format_version: not what `tofu show -json <plan>` writes")
}
d := Decision{Verdict: Nothing}
for _, rc := range p.ResourceChanges {
actions := rc.Change.Actions
if len(actions) == 0 {
return Decision{}, fmt.Errorf("planguard: %s has no actions", rc.Address)
}
if changesNothing(actions) {
continue
}
d.Changes++
if !held(rc.Type, actions, replaceable) {
continue
}
d.Held = append(d.Held, rc.Address+": "+strings.Join(actions, ", "))
}
switch {
case len(d.Held) > 0:
d.Verdict = Person
case d.Changes > 0:
d.Verdict = Apply
}
return d, nil
}

// changesNothing is a change that touches no resource: none, or a data source read.
func changesNothing(actions []string) bool {
return slices.Equal(actions, []string{"no-op"}) || slices.Equal(actions, []string{"read"})
}

// held is a change a person reads: anything but a create or an in-place update - a delete, a
// forget, or an action this does not know - unless it is a replacement of a type made to be
// replaced.
func held(typ string, actions []string, replaceable []string) bool {
if slices.Equal(actions, []string{"create"}) || slices.Equal(actions, []string{"update"}) {
return false
}
replace := len(actions) == 2 && slices.Contains(actions, "create") && slices.Contains(actions, "delete")
return !replace || !slices.Contains(replaceable, typ)
}
68 changes: 68 additions & 0 deletions internal/planguard/planguard_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
package planguard

import (
"strings"
"testing"
)

// planOf is a plan's JSON with one resource change for each of changes, "<type>.<name> <action>,...".
func planOf(changes ...string) []byte {
var rcs []string
for _, c := range changes {
addr, acts, _ := strings.Cut(c, " ")
typ, _, _ := strings.Cut(addr, ".")
quoted := `"` + strings.ReplaceAll(acts, ",", `","`) + `"`
rcs = append(rcs, `{"address":"module.spin.`+addr+`","type":"`+typ+`","mode":"managed","change":{"actions":[`+quoted+`]}}`)
}
return []byte(`{"format_version":"1.2","resource_changes":[` + strings.Join(rcs, ",") + `]}`)
}

// A plan is nothing with no change to a resource, applied with creates and in-place updates alone,
// and a person's with anything taken away - a delete, a replacement, a forget, an action not known -
// unless it replaces a type named as made to be replaced; never a delete alone.
func TestAPlanIsAppliedUnreadOnlyWhenNothingIsTakenAway(t *testing.T) {
replaceable := []string{"aws_launch_template"}
for name, tc := range map[string]struct {
plan []byte
verdict Verdict
held []string
changes int
}{
"no changes": {planOf("aws_s3_bucket.logs no-op", "aws_ami.image read"), Nothing, nil, 0},
"none at all": {[]byte(`{"format_version":"1.2"}`), Nothing, nil, 0},
"creates and updates": {planOf("aws_launch_template.cp update", "aws_ssm_parameter.pcrs create", "aws_kms_key.cp update"), Apply, nil, 3},
"a delete": {planOf("aws_launch_template.cp update", "aws_s3_bucket.logs delete"), Person, []string{"module.spin.aws_s3_bucket.logs: delete"}, 2},
"a replacement": {planOf("aws_db_instance.state delete,create"), Person, []string{"module.spin.aws_db_instance.state: delete, create"}, 1},
"a create-first replace": {planOf("aws_kms_key.cp create,delete"), Person, []string{"module.spin.aws_kms_key.cp: create, delete"}, 1},
"a forget": {planOf("aws_route53_zone.z forget"), Person, []string{"module.spin.aws_route53_zone.z: forget"}, 1},
"an action not known": {planOf("aws_iam_role.r adopt"), Person, []string{"module.spin.aws_iam_role.r: adopt"}, 1},
"a replaceable replaced": {planOf("aws_launch_template.cp delete,create", "aws_launch_template.px create,delete"), Apply, nil, 2},
"a replaceable deleted": {planOf("aws_launch_template.cp delete"), Person, []string{"module.spin.aws_launch_template.cp: delete"}, 1},
"three actions": {planOf("aws_launch_template.cp delete,create,update"), Person, []string{"module.spin.aws_launch_template.cp: delete, create, update"}, 1},
} {
t.Run(name, func(t *testing.T) {
d, err := Decide(tc.plan, replaceable)
if err != nil {
t.Fatal(err)
}
if d.Verdict != tc.verdict || strings.Join(d.Held, ";") != strings.Join(tc.held, ";") || d.Changes != tc.changes {
t.Errorf("%+v, want %s held %v changes %d", d, tc.verdict, tc.held, tc.changes)
}
})
}
}

// What is not a plan's JSON - not JSON, an object with no format, a change with no actions - is
// an error, never nothing to do.
func TestWhatIsNotAPlanIsRefused(t *testing.T) {
for name, raw := range map[string]string{
"not JSON": "{",
"no format": `{"resource_changes":[]}`,
"no actions": `{"format_version":"1.2","resource_changes":[{"address":"a.b","type":"a","change":{"actions":[]}}]}`,
"a plan's text": "Plan: 1 to add, 0 to change, 0 to destroy.",
} {
if d, err := Decide([]byte(raw), nil); err == nil {
t.Errorf("%s: %+v", name, d)
}
}
}
38 changes: 38 additions & 0 deletions site/src/content/docs/planguard.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
---
title: planguard
description: Whether an OpenTofu plan may be applied without a person reading it - nothing, apply, or person - so an installation can apply on a schedule what only adds and updates, and leave the rest to a pull request.
---

An installation that follows a release channel, or its module's main, changes without anybody
writing a commit: a new release moves the images its launch templates name, a new module commit
moves whatever it moves. Applying each of those by hand is a plan read and a button pressed for a
change nobody chose. Applying all of them on a schedule is how a database gets replaced on a
Tuesday night. `planguard` draws the line between the two from the plan itself.

```sh
tofu plan -out=plan.bin
tofu show -json plan.bin > plan.json
go tool planguard [-replaceable aws_launch_template,...] plan.json
```

| the plan | verdict |
|---|---|
| no resource changes - nothing, or only data sources read | `nothing` |
| creates and in-place updates, and nothing else | `apply`: applied unread |
| any delete, replacement (delete and create, either order), forget, or an action it does not know | `person`: each such change is listed |

The plan cannot say which resources hold data, so every resource is treated as one that might:
a replaced bucket, database or KMS key is a person's whatever its type. A type made to be replaced -
`-replaceable aws_launch_template` - may be replaced unread, but never deleted alone.

The verdict is the first line on stdout and the changes held follow it; in GitHub Actions it is
also `verdict=<it>` in `$GITHUB_OUTPUT`, for a step's `if:`. Every verdict exits 0 - a plan that is
a person's is not a failed run - and what cannot be read exits 2, never `nothing`.

```yaml title=".github/workflows/auto.yml"
- run: go tool task plan:json # tofu plan -out, tofu show -json
- id: guard
run: go tool task guard # go tool planguard plan.json
- if: steps.guard.outputs.verdict == 'apply'
run: go tool task apply:saved # tofu apply plan.bin: what was judged is what is applied
```
1 change: 1 addition & 0 deletions site/src/lib/nav.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@ export const sidebar = [
{ label: 'sfw', slug: 'sfw' },
{ label: 'Provenance and SBOMs', slug: 'supply-chain' },
{ label: 'exposure', slug: 'exposure' },
{ label: 'planguard', slug: 'planguard' },
],
},
{ label: 'Doing less work', items: [{ label: 'gencache', slug: 'gencache' }] },
Expand Down