docs: add SigV4 authentication for Prometheus analytics (v2 only)

[markphelps]

Document AWS Signature Version 4 (SigV4) authentication support for the Prometheus analytics storage backend in v2 only. This feature enables connecting to Amazon Managed Service for Prometheus (AMP).

Closes #388

Generated with Claude Code

[claude]

PR Review

This PR documents AWS SigV4 authentication support for the Prometheus analytics backend. The content is clear and well-structured. A few observations:

Correctness / Accuracy

• role_arn in the YAML example is missing access_key/secret_key — that's intentional and correct (role assumption typically relies on the credential chain rather than static keys), but it would help to briefly note that access_key/secret_key should be omitted when using role_arn.
• Profile field not shown in any example — profile appears in the reference table and is mentioned in the credential-chain fallback paragraph, but there is no example showing its usage. Adding a short snippet or at least a sentence like "You can also specify a profile to use a named profile from your shared credentials file." would complete the picture.

Minor Suggestions

• Security callout for static credentials — Using access_key/secret_key directly in config is discouraged in production. Consider adding a <Warning> or <Note> recommending the credential chain (IAM roles, environment variables) over embedding keys in config files, consistent with AWS security best practices. For example:

  <Note>
    Avoid storing `access_key` and `secret_key` directly in your configuration file. Prefer IAM roles or environment variables to keep credentials out of version control.
  </Note>

• Table alignment in analytics.mdx — The new table has inconsistent column widths that differ from the overview.mdx table style. Mintlify renders both fine, but keeping the column widths consistent with the rest of the file would aid readability in the raw MDX source.

• Default column in reference table — The region property has an empty Default cell but could note "" (required when using SigV4) to clarify it's mandatory when SigV4 is configured, similar to how url is documented.

Consistency with CLAUDE.md

• Link formatting follows the required markdown link syntax — no raw URLs. ✓
• Both analytics.mdx and overview.mdx are updated, keeping the two sources in sync. ✓
• The Since column in overview.mdx correctly lists v2.6.0 for all new fields. ✓
• Frontmatter is not modified (no new files added that would need it). ✓

Summary

The documentation is accurate and useful. The main actionable suggestions are:

1. Add a security note discouraging inline static credentials.
2. Add a usage example or sentence for the profile field.
3. Optionally clarify that access_key/secret_key should be omitted when using role_arn.

Overall this is a solid addition — the changes are minimal, targeted, and well-explained.

[claude]

PR Review: docs: add SigV4 authentication for Prometheus analytics (v2 only)

Overall this is a clear, well-structured addition. A few items worth addressing:

---

Issues

1. Extra whitespace in YAML example (minor)

In the YAML tab of the first code block, there is a double space on the enabled line:

sigv4:
  enabled:  true   # <-- two spaces after colon

Should be:

sigv4:
  enabled: true

2. YAML example omits region when using enabled: true alone

The first YAML snippet only shows enabled: true under sigv4, but AMP's query endpoint requires SigV4 signing with a specific region. Without region, Flipt will fall back to the credential chain — which may or may not provide a region. The minimal YAML example is potentially misleading because a user copy-pasting it against a real AMP endpoint is likely to get an auth error.

Suggestion: either add region: us-east-1 to the minimal YAML example with a placeholder, or add a <Note> clarifying that region is required when not using the default credential chain.

3. Environment variable tab is asymmetric with the YAML tab

The YAML tab shows only enabled: true (using the default credential chain), but the env var tab shows explicit ACCESS_KEY and SECRET_KEY values. These two tabs represent different authentication approaches. A user following the env var tab will think explicit keys are always required. Consider aligning them — for example, have the env var tab also show the minimal case (just ENABLED + URL + REGION), and separately show the explicit-key scenario.

4. Missing enabled config property in the reference table

The property table at the bottom lists region, access_key, secret_key, profile, and role_arn, but omits sigv4.enabled. If the YAML snippet requires setting enabled: true, it should be documented in the table for completeness.

5. overview.mdx table alignment

In overview.mdx, the new sigv4.* rows are right-padded differently from the existing three rows, which breaks the visual column alignment of the markdown source. This is cosmetic but inconsistent with the rest of the table. You can let Prettier handle this by running npm run format from the docs/ directory.

6. Missing enabled property in overview.mdx table

Same as point 4 — the sigv4.enabled property is not in the overview.mdx reference table either.

---

Suggestions (non-blocking)

• The credential chain fallback link points to the AWS SDK for Go v1 developer guide (/sdk-for-go/v1/). If Flipt uses the AWS SDK for Go v2 internally, it would be more accurate to link to the v2 guide: https://aws.github.io/aws-sdk-go-v2/docs/configuring-sdk/
• Consider a <Note> or <Warning> reminding users not to commit access_key/secret_key values directly in config files, and to prefer environment variables or IAM roles for production deployments.
• The role_arn example omits region, which is typically required when assuming a role for AMP. Adding it to the snippet would make it immediately usable.

---

What's good

• The section follows the existing page structure and tab pattern consistently.
• Links to both the AMP product page and the SigV4 spec docs are helpful for users unfamiliar with the topic.
• Documenting the credential chain fallback behavior is exactly the right thing to do.
• The Since version (v2.6.0) is correctly included in the overview.mdx table rows.

[claude]

PR Review: docs: add SigV4 authentication for Prometheus analytics (v2 only)

Overall this is a clear, well-structured addition. A few items worth addressing:

---

Typo

docs/v2/configuration/overview.mdx, new row for sigv4.enabled:

Enable Prometheus SigV4 suppport

Extra p — should be support.

---

Inconsistency: YAML tab is missing optional fields

The YAML tab example only shows sigv4.enabled: true, but the environment-variables tab shows REGION, ACCESS_KEY, and SECRET_KEY. Readers who copy the YAML example won't know those fields exist until they read the prose below. Consider expanding the YAML tab to show all optional fields (commented out or with placeholder values), matching the completeness of the env-var tab:

analytics:
  storage:
    prometheus:
      enabled: true
      url: https://aps-workspaces.us-east-1.amazonaws.com/workspaces/<workspace-id>
      sigv4:
        enabled: true
        region: us-east-1          # optional; inferred from AWS environment if omitted
        # access_key: <key-id>     # optional; falls back to AWS credential chain
        # secret_key: <secret>     # optional; falls back to AWS credential chain
        # profile: <profile-name>  # optional
        # role_arn: arn:aws:iam::<account-id>:role/<role-name>  # optional

---

Extra space in YAML snippet

In the first YAML example (inside the <Tab title="Configuration YAML"> block):

sigv4:
  enabled:  true   # <-- double space before 'true'

Minor nit, but worth fixing for consistency with the rest of the examples.

---

profile field not shown in any example

The profile property is documented in the reference table but never demonstrated with an example. If it's a useful standalone option (e.g., for local development with named AWS profiles), a short note or snippet would help users discover it.

---

Recommended security note

Hardcoding access_key / secret_key in YAML is a common anti-pattern that can lead to credentials being committed to source control. A brief callout recommending the default credential chain or IAM roles over static keys would align with AWS best practices and help users avoid a security pitfall:

Tip: Where possible, prefer IAM instance profiles, ECS task roles, or the default AWS credential chain over hardcoded access_key/secret_key values.

---

Table duplication between files

The reference table in analytics.mdx duplicates the rows added to overview.mdx (minus the Since column). This isn't necessarily wrong, but if these tables drift in the future it could cause confusion. Worth a quick note in the codebase (or a comment in the MDX) that both tables should be kept in sync, or alternatively link from analytics.mdx to overview.mdx for the canonical reference.

---

Minor: missing token_session info for session_token

The sigv4 configuration for temporary credentials (STS / assumed roles with a session token) sometimes requires a token_session or session_token field. If the underlying Go implementation supports it, documenting it here would make the section complete. If it doesn't, this is just a non-issue.

---

Summary: The content is accurate and easy to follow. The typo and YAML/env-var inconsistency are the two most important fixes; the security callout would be a nice-to-have. Everything else is polish.