Documentation
¶
Overview ¶
Package iampolicy renders AWS IAM policy documentation for commands that have multiple variants (e.g. create-asset target-infra, migration-infra). It is consumed by the AnnotationKey annotation on each command and injected into generated markdown by cmd/gen-docs.
Index ¶
- Constants
- func Difference(superset, subset []string) []string
- func Overlap(a, b []string) []string
- func Render(intro string, base []string, variants []Variant) string
- func RenderSingle(intro string, actions []string, resources ...string) string
- func RenderStatements(intro string, statements []Statement) string
- func Union(fragments ...[]string) []string
- type Statement
- type Variant
Constants ¶
const AnnotationKey = "aws_iam_permissions"
AnnotationKey is the Cobra Annotations map key under which commands publish their AWS IAM permissions markdown for cmd/gen-docs to pick up.
Variables ¶
This section is empty.
Functions ¶
func Difference ¶
Difference returns the sorted, deduped set of actions in `superset` that are not in `subset`. Helper for computing a variant's Additions from its full captured action set and the shared base.
func Overlap ¶
Overlap returns the intersection of two action sets, sorted. Used by tests to assert that a variant's Additions do not duplicate actions already in the base — those should be in the base, not the additions.
func Render ¶
Render assembles the body of a cobra aws_iam_permissions annotation as markdown. The output is the body only; cmd/gen-docs prepends the "### AWS IAM Permissions" heading when it injects the section into the generated command reference page.
Structure:
<intro>
#### Base — always required
```json
{ ...sorted, deduped base actions... }
```
#### Additional for `<FlagHint>`
<Summary>
```json
{ ...sorted, deduped additions... }
```
Variants with empty Additions render the summary followed by "_No additional permissions beyond the base._" instead of a JSON block.
func RenderSingle ¶
RenderSingle renders the body of a cobra aws_iam_permissions annotation for a command whose IAM footprint is a single Allow statement. Pass zero resources to produce `"Resource": "*"`, one resource for a bare string, or multiple for a JSON array. Actions are sorted alphabetically and deduped. The output is intro + fenced JSON block (no "Base/Additional" headings — those only make sense for variant-bearing commands).
func RenderStatements ¶
RenderStatements renders the body of a cobra aws_iam_permissions annotation as a fenced JSON block with one or more Allow statements. Use for commands whose documented policy spans multiple Sid-labeled statements (e.g. discover, bastion-host, scan-clusters). Actions inside each statement are sorted alphabetically and deduped; statement order is preserved from the input so operators see them in the order the author intended.
Types ¶
type Statement ¶
type Statement struct {
// Sid is an optional label shown in the rendered JSON to help docs
// readers map a statement to its purpose (e.g. "MSKClusterKafkaAccess").
// Omit to skip the Sid field entirely.
Sid string
// Actions is the set of IAM actions this statement grants. Sorted and
// deduped by the renderer.
Actions []string
// Resources scopes the statement. If empty or nil, renders as
// "Resource": "*". If a single element, renders as a bare string. If
// two or more, renders as a JSON array in the given order.
Resources []string
}
Statement describes one entry in an IAM policy's Statement array for commands that publish their permissions via RenderSingle / RenderStatements. Effect is always "Allow"; there is no legitimate reason to publish a Deny policy as a tooling requirement, so it's not exposed.
type Variant ¶
type Variant struct {
// FlagHint is the flag combination that selects this variant,
// e.g. "--cluster-type enterprise" or "--type 4 (dedicated target)".
// Rendered verbatim inside a ` code span ` in the subsection heading.
FlagHint string
// Summary is a one-line description of what this variant provisions,
// rendered under the heading before the JSON block.
Summary string
// Additions are IAM actions required by this variant on top of Base.
// May be empty — in that case the variant renders as a note rather
// than a JSON block.
Additions []string
}
Variant describes one permutation of a command's AWS IAM footprint.
Source Files