Tyk Governance - new content for v0.2 #6759

caroltyk · 2025-07-17T15:11:38Z

User description

Contributor checklist

Reviewed PR Code suggestions and updated accordingly
Tyklings: Labled the PR with the relevant releases
Tyklings: Added Jira DX PR ticket to the subject

New Contributors

Start the PR branch from our latest master
I have read the repository contribution guidelines
I have read the repository technical guidelines

PR Type

Documentation

Description

Adds comprehensive documentation for Agent Management, API Evaluation, and Governance Rulesets
Updates installation guide with UI and scheduled sync instructions for agents
Enhances overview with shift-left governance and scheduled sync details
Updates navigation menu to include new governance documentation pages

Changes diagram

flowchart LR
  A["Add Agent Management Doc"] -- "New page" --> B["Agent Management"]
  A2["Add API Evaluation Doc"] -- "New page" --> B2["API Evaluation"]
  A3["Add Governance Rulesets Doc"] -- "New page" --> B3["Governance Rulesets"]
  C["Update Installation Doc"] -- "Add UI & sync info" --> D["Installation"]
  E["Update Overview Doc"] -- "Add shift-left & sync" --> F["Overview"]
  G["Update Menu"] -- "Add new pages to nav" --> H["Navigation"]

Changes walkthrough 📝

Relevant files

Documentation

agent-management.md `Add comprehensive Agent Management documentation for v0.2` tyk-docs/content/tyk-governance/agent-management.md Adds a new, detailed documentation page for Agent Management Covers setup, configuration, deployment, use cases, best practices, FAQs, and troubleshooting Includes diagrams and YAML examples for clarity Documents new v0.2 features like scheduled sync and high availability	+572/-0
api-evaluation.md `Add API Evaluation documentation and usage examples` tyk-docs/content/tyk-governance/api-evaluation.md Introduces a new documentation page for API Evaluation Explains shift-left governance, API validation workflows, and integration with CI/CD Provides endpoint details, usage examples, and troubleshooting Documents new v0.2 API evaluation feature	+398/-0
governance-rulesets.md `Add Governance Rulesets documentation and examples` tyk-docs/content/tyk-governance/governance-rulesets.md Adds a new documentation page for Governance Rulesets Details ruleset creation, management, structure, and use cases Provides YAML examples and best practices for ruleset evolution Includes troubleshooting and FAQ sections	+335/-0
installation.md `Update installation guide for agent UI and scheduled sync` tyk-docs/content/tyk-governance/installation.md Updates agent installation instructions to include UI-based token generation Adds documentation for scheduled synchronization (v0.2) Updates Kubernetes deployment example for leader election Improves clarity and step-by-step guidance	+24/-2
overview.md `Update overview with shift-left and scheduled sync` tyk-docs/content/tyk-governance/overview.md Updates overview to emphasize shift-left governance Adds mention of scheduled synchronization and governance templates Clarifies benefits for architects and platform engineers	+3/-2
menu.yaml `Update navigation menu for new governance docs` tyk-docs/data/menu.yaml Adds navigation entries for Governance Rulesets, API Evaluation, and Agent Management Ensures new documentation pages are accessible from the sidebar	+12/-0

Need help?
Type /help how to ... in the comments thread for any questions about PR-Agent usage.
Check out the documentation for more information.

github-actions · 2025-07-17T15:12:04Z

⚠️ Deploy preview for PR #6759 did not become live after 3 attempts.
Please check Netlify or try manually: Preview URL

github-actions · 2025-07-17T15:13:11Z

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 2 🔵🔵⚪⚪⚪
🧪 No relevant tests
🔒 No security concerns identified
⚡ Recommended focus areas for review Sensitive Information Example The documentation includes example configuration files and shell commands with placeholder secrets (e.g., `your-aws-access-key-secret`, `your-tyk-dashboard-api-key`). While these are clearly marked as examples, reviewers should ensure that no real credentials are present and that users are reminded not to use example secrets in production. Create a file named `agent-config.yaml` with the following content: ```yaml # Tyk Governance Agent Configuration governanceDashboard: server: # The gRPC endpoint URL of the Tyk Governance service url: "your-governance-instance.tyk.io:50051" auth: # Authentication token for this agent token: "your-agent-token" # API Provider Configurations instances: # Example Tyk Provider Configuration - name: "tyk-provider" type: "tyk" config: host: "http://your-tyk-dashboard:3000" auth: "your-tyk-dashboard-api-key" # Example AWS API Gateway Configuration - name: "aws-provider" type: "aws" config: accessKeyId: "your-aws-access-key-id" accessKeySecret: "your-aws-access-key-secret" region: "us-east-1" # Sync schedule (added in v0.2) syncSchedule: # Enable scheduled synchronization enabled: true # Interval in minutes between syncs (minimum 5) intervalMinutes: 60 # Agent Settings logLevel: info ``` API Usage Clarity The documentation provides shell and CI/CD examples for using the API evaluation endpoint. Reviewers should verify that the endpoint URLs, authentication headers, and payload formats are accurate and up to date with the actual API implementation to avoid user confusion. ```sh curl -X POST https://your-governance-instance.tyk.io/api/rulesets/evaluate-spec \ -H "Content-Type: application/json" \ -H "X-API-Key: YOUR_API_KEY" \ -d '{ "rulesetId": "your-ruleset-id", "apiSpec": { "name": "My Test API", "content": { "openapi": "3.0.0", "info": { "title": "Test API", "version": "1.0.0" }, "paths": { "/example": { "get": { "responses": { "200": { "description": "OK" } } } } } } } }' ``` 4. Review the Results The response will include any violations found, with details about each issue: ```json { "status": "success", "message": "Rule violations found", "errors": [ { "code": "info-contact", "path": ["info"], "message": "API must have contact information", "severity": "error", "range": { "start": { "line": 3, "character": 2 }, "end": { "line": 6, "character": 3 } }, "howToFix": "Add contact information to the info section" } ] } ``` ### Validation - A successful request with no violations will return an empty errors array - If violations are found, each will include: - The rule code that was violated - The path in the API specification where the violation occurred - A message explaining the issue - The severity level (error, warning, info, hint) - The exact location in the file (line and character) - Guidance on how to fix the issue ## How It Works API Evaluation works by sending your API specification to the Tyk Governance Hub, where it's validated against a specified ruleset without being stored in your API repository. The system applies each rule in the ruleset to your specification and returns detailed results. ### Integration to Development Workflow #### Integrating with CI/CD Pipelines API Evaluation can be integrated into your CI/CD pipeline to automatically validate API specifications before they're deployed. This ensures that only compliant APIs make it to production. ```yaml # Example GitHub Actions workflow name: API Governance Check on: pull_request: paths: - 'api-specs/*' jobs: validate-api: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - name: Validate API Specification run: \| SPEC_CONTENT=$(cat api-specs/my-api.json \| jq -c .) curl -X POST https://your-governance-instance.tyk.io/api/rulesets/evaluate-spec \ -H "Content-Type: application/json" \ -H "X-API-Key: ${{ secrets.GOVERNANCE_API_KEY }}" \ -d "{ \"rulesetId\": \"your-ruleset-id\", \"apiSpec\": { \"name\": \"My API\", \"content\": ${SPEC_CONTENT} } }" > validation-results.json # Fail if any errors are found ERROR_COUNT=$(jq '.errors \| length' validation-results.json) if [ $ERROR_COUNT -gt 0 ]; then echo "API validation failed with $ERROR_COUNT issues:" jq '.errors' validation-results.json exit 1 fi Pre-commit Validation Developers can validate their API specifications before committing changes, ensuring they meet governance standards from the start. #!/bin/bash # pre-commit hook for API validation # Get the API specification file SPEC_FILE=$(git diff --cached --name-only \| grep -E '\.json$\|\.yaml$\|\.yml$' \| head -1) if [ -n "$SPEC_FILE" ]; then echo "Validating API specification: $SPEC_FILE" # Convert the file content to JSON if [[ $SPEC_FILE == .yaml \|\| $SPEC_FILE == .yml ]]; then SPEC_CONTENT=$(yq eval -j $SPEC_FILE) else SPEC_CONTENT=$(cat $SPEC_FILE) fi # Validate the specification RESPONSE=$(curl -s -X POST https://your-governance-instance.tyk.io/api/rulesets/evaluate-spec \ -H "Content-Type: application/json" \ -H "X-API-Key: YOUR_API_KEY" \ -d "{ \"rulesetId\": \"your-ruleset-id\", \"apiSpec\": { \"name\": \"$(basename $SPEC_FILE)\", \"content\": $SPEC_CONTENT } }") # Check for errors ERROR_COUNT=$(echo $RESPONSE \| jq '.errors \| length') if [ $ERROR_COUNT -gt 0 ]; then echo "API validation failed with $ERROR_COUNT issues:" echo $RESPONSE \| jq '.errors' exit 1 fi echo "API specification is valid!" fi exit 0 </details> <details><summary><a href='https://github.com/TykTechnologies/tyk-docs/pull/6759/files#diff-a69e947116bca402e5654d95765013c9b3234a58afdf19299c103d2a68c2cad4R99-R125'><strong>Ruleset Example Accuracy</strong></a> The ruleset examples use Spectral-compatible YAML. Reviewers should check that the syntax and field names (such as `given`, `then`, `function`, `functionOptions`) match what is supported by the product, and that example regular expressions and JSONPath selectors are correct. </summary> ```markdown ```yaml security-auth-required: description: APIs must require authentication severity: error given: $.paths..* then: field: security function: truthy howToFix: "Add a security requirement to this operation" API Design Standards Ruleset Define rules that enforce naming conventions, URL patterns, and response structures to maintain consistency across your API portfolio. path-case-convention: description: Path segments must use kebab-case severity: warning given: $.paths then: field: "@key" function: pattern functionOptions: match: "^\/([a-z0-9-]+\|{[a-zA-Z0-9_]+})(\/{[a-zA-Z0-9_]+}\|\/[a-z0-9-]+)*$" howToFix: "Rename path segments to use kebab-case (lowercase with hyphens)" `</details> </td></tr> </table>`

github-actions · 2025-07-17T15:13:18Z

PR Code Suggestions ✨

No code suggestions found for the PR.

netlify · 2025-07-17T15:14:33Z

✅ PS. Add to the end of url /docs/nightly

Name	Link
🔨 Latest commit	`fdceb75`
🔍 Latest deploy log	https://app.netlify.com/projects/tyk-docs/deploys/687912ad3a64e8000887d0b6
😎 Deploy Preview	https://deploy-preview-6759--tyk-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

netlify · 2025-07-17T15:14:33Z

✅ PS. Add to the end of url /docs/nightly

Name	Link
🔨 Latest commit	`e55c6ff`
🔍 Latest deploy log	https://app.netlify.com/projects/tyk-docs/deploys/6881b29e5488180008dc4ce3
😎 Deploy Preview	https://deploy-preview-6759--tyk-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

github-actions · 2025-07-18T07:00:52Z

Code Review: New Content for Tyk Governance v0.2

Summary

This PR adds comprehensive documentation for Tyk Governance v0.2, focusing on three new features: Agent Management, API Evaluation, and Governance Rulesets. It also updates the installation guide with UI and scheduled sync instructions, enhances the overview with shift-left governance details, and updates the navigation menu to include the new documentation pages.

Overall Assessment

The documentation is well-structured, comprehensive, and provides clear guidance for users. The content follows a consistent format across all pages with appropriate sections for overview, quick start, configuration options, use cases, best practices, FAQs, and troubleshooting. The documentation effectively communicates both conceptual information and practical implementation details.

Detailed Review

New Content

1. Agent Management (`agent-management.md`)

Strengths:

Comprehensive coverage of agent setup, configuration, and management
Clear explanation of the agent architecture with helpful mermaid diagrams
Detailed step-by-step instructions for deployment in different environments
Good coverage of advanced topics like high availability and scheduled synchronization
Well-structured FAQs and troubleshooting sections

Considerations:

The configuration examples include placeholder secrets (e.g., "your-aws-access-key-secret"). While these are clearly marked as examples, it might be worth adding a note reminding users not to use example credentials in production.
Some YAML indentation in code examples is inconsistent, particularly in the agent configuration example.

2. API Evaluation (`api-evaluation.md`)

Strengths:

Clear explanation of the "shift-left" governance concept
Detailed API usage examples with request/response formats
Practical integration examples for CI/CD pipelines and pre-commit hooks
Comprehensive troubleshooting and FAQ sections

Considerations:

The CI/CD examples use shell commands with string concatenation which could be error-prone. Consider using heredoc syntax or properly escaped JSON for better readability.
Ensure all code examples are complete and don't cut off mid-sentence.

3. Governance Rulesets (`governance-rulesets.md`)

Strengths:

Clear explanation of ruleset concepts and structure
Good examples of different types of rulesets (security, design, documentation)
Practical guidance on ruleset organization and evolution
Well-structured use cases showing how to apply rulesets in different scenarios

Considerations:

The ruleset examples use Spectral-compatible YAML. The documentation does mention this compatibility, which is helpful for users familiar with that tool.

Updated Content

1. Installation Guide (`installation.md`)

Strengths:

Added UI-based token generation instructions
Included documentation for scheduled synchronization (new in v0.2)
Updated Kubernetes deployment example for leader election
Improved clarity with detailed configuration examples

Considerations:

The installation guide has become quite lengthy. Consider adding a table of contents or quick navigation links at the top.

2. Overview (`overview.md`)

Strengths:

Updated to emphasize shift-left governance
Added mention of scheduled synchronization
Clarified benefits for different user roles (architects, platform engineers, developers)

Considerations:

The mermaid diagram in the overview is helpful but could benefit from a brief textual explanation.

3. Navigation Menu (`menu.yaml`)

Strengths:

Logically organized with new pages in appropriate sequence
Consistent naming convention with other menu items
Proper integration with existing menu structure

Security Considerations

The documentation includes example configuration files with placeholder secrets. While these are clearly marked as examples, it's important to ensure no real credentials were accidentally included.
The authentication and security aspects of the agent setup are well-documented, emphasizing the use of tokens and secure connections.

Recommendations

Consistency Check: Ensure consistent formatting across all code examples, particularly YAML indentation.
Security Reminder: Add a note about securely managing credentials in the agent configuration section.
Navigation Enhancement: Consider adding a table of contents to the longer pages like installation.md.
Cross-References: Add more cross-references between related sections to help users navigate the documentation.

Conclusion

This PR provides valuable, comprehensive documentation for the new features in Tyk Governance v0.2. The content is well-structured, detailed, and user-focused. With minor formatting improvements, this documentation will serve as an excellent resource for users implementing and working with Tyk Governance.

The PR is ready to be merged with the suggested minor improvements.

Tip: Mention me again using /probe <request>.
Powered by Probe AI

tyk-docs/content/tyk-governance/api-evaluation.md

Co-authored-by: bsten-tyk <[email protected]>

tyk-docs/content/tyk-governance/agent-management.md

bsten-tyk · 2025-07-21T15:14:22Z

tyk-docs/content/tyk-governance/agent-management.md

+1. **Agent Configuration File (Agent-side scheduling)**
+
+   Configure the `syncSchedule` section in the agent's configuration file:
+
+   ```yaml
+   # Agent configuration with scheduled sync
+   syncSchedule:
+     enabled: true
+     intervalMinutes: 60  # Sync every hour
+   ```
+
+   With this configuration:
+   - The agent will independently initiate synchronization every `intervalMinutes`
+   - This happens regardless of any schedules configured on the Governance Hub
+   - It's a "pull" model where the agent decides when to sync
+   - Minimum interval is 5 minutes


@sredxny correct me if I am wrong, but sync schedule is set on governance dashboard side; not agent side. So, there is no syncSchedule configurations on Agent side

bsten-tyk · 2025-07-21T15:15:51Z

tyk-docs/content/tyk-governance/agent-management.md

+### Scheduled Synchronization Variables (New in v0.2)
+
+| Environment Variable | Description | Default Value |
+|---------------------|-------------|---------------|
+| `TYK_AGENT_SYNCSCHEDULE_ENABLED` | Enable scheduled synchronization | `false` |
+| `TYK_AGENT_SYNCSCHEDULE_INTERVALMINUTES` | Interval in minutes between syncs (minimum 5) | `60` |


@sredxny do we have this option? I guess there are no such configurations

Co-authored-by: bsten-tyk <[email protected]>

new content for v0.2

fdceb75

caroltyk changed the title ~~new content for v0.2~~ New content for Governance v0.2 Jul 17, 2025

caroltyk added the Governance v0.2 label Jul 17, 2025

github-actions bot changed the title ~~New content for Governance v0.2~~ new content for v0.2 Jul 17, 2025

github-actions bot added the Review effort 2/5 label Jul 17, 2025

TykTechnologies deleted a comment from github-actions bot Jul 18, 2025

caroltyk and others added 8 commits July 18, 2025 22:09

docs update

92ee5fb

update

26caa91

standardization, front matters

94dda9c

update

53ece05

Update api-evaluation.md

4d822e4

Update governance-rulesets.md

e64866e

Merge master into tyk-governance-v0.2

2edc188

Merge master into tyk-governance-v0.2

3262c4c

caroltyk changed the title ~~new content for v0.2~~ Tyk Governance - new content for v0.2 Jul 21, 2025

caroltyk requested review from sredxny, tbuchaillot, buraksekili and kolavcic July 21, 2025 10:54

bsten-tyk reviewed Jul 21, 2025

View reviewed changes

tyk-docs/content/tyk-governance/api-evaluation.md Outdated Show resolved Hide resolved

bsten-tyk reviewed Jul 21, 2025

View reviewed changes

tyk-docs/content/tyk-governance/api-evaluation.md Outdated Show resolved Hide resolved

bsten-tyk reviewed Jul 21, 2025

View reviewed changes

tyk-docs/content/tyk-governance/api-evaluation.md Outdated Show resolved Hide resolved

bsten-tyk reviewed Jul 21, 2025

View reviewed changes

tyk-docs/content/tyk-governance/api-evaluation.md Outdated Show resolved Hide resolved

caroltyk and others added 4 commits July 21, 2025 16:04

Update tyk-docs/content/tyk-governance/api-evaluation.md

a135da5

Co-authored-by: bsten-tyk <[email protected]>

Update tyk-docs/content/tyk-governance/api-evaluation.md

5fd5f06

Co-authored-by: bsten-tyk <[email protected]>

Update tyk-docs/content/tyk-governance/api-evaluation.md

9b6b779

Co-authored-by: bsten-tyk <[email protected]>

Update api-evaluation.md

8369d56

bsten-tyk reviewed Jul 21, 2025

View reviewed changes

caroltyk and others added 4 commits July 22, 2025 17:27

Update tyk-docs/content/tyk-governance/agent-management.md

4f83324

Co-authored-by: bsten-tyk <[email protected]>

Update tyk-docs/content/tyk-governance/agent-management.md

eef12d1

Co-authored-by: bsten-tyk <[email protected]>

Merge master into tyk-governance-v0.2

021f913

Merge master into tyk-governance-v0.2

e55c6ff

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Tyk Governance - new content for v0.2 #6759

Tyk Governance - new content for v0.2 #6759

caroltyk commented Jul 17, 2025 •

edited by github-actions bot

Loading

Uh oh!

github-actions bot commented Jul 17, 2025

Uh oh!

github-actions bot commented Jul 17, 2025

Pre-commit Validation

API Design Standards Ruleset

Uh oh!

github-actions bot commented Jul 17, 2025

Uh oh!

netlify bot commented Jul 17, 2025

Uh oh!

netlify bot commented Jul 17, 2025 •

edited

Loading

Uh oh!

github-actions bot commented Jul 18, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bsten-tyk Jul 21, 2025

Uh oh!

bsten-tyk Jul 21, 2025

Uh oh!

Uh oh!

Tyk Governance - new content for v0.2 #6759

Are you sure you want to change the base?

Tyk Governance - new content for v0.2 #6759

Conversation

caroltyk commented Jul 17, 2025 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

User description

Contributor checklist

New Contributors

PR Type

Description

Changes diagram

Changes walkthrough 📝

Uh oh!

github-actions bot commented Jul 17, 2025

Uh oh!

github-actions bot commented Jul 17, 2025

PR Reviewer Guide 🔍

Pre-commit Validation

API Design Standards Ruleset

Uh oh!

github-actions bot commented Jul 17, 2025

PR Code Suggestions ✨

Uh oh!

netlify bot commented Jul 17, 2025

✅ PS. Add to the end of url /docs/nightly

Uh oh!

netlify bot commented Jul 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ PS. Add to the end of url /docs/nightly

Uh oh!

github-actions bot commented Jul 18, 2025

Code Review: New Content for Tyk Governance v0.2

Summary

Overall Assessment

Detailed Review

New Content

1. Agent Management (agent-management.md)

2. API Evaluation (api-evaluation.md)

3. Governance Rulesets (governance-rulesets.md)

Updated Content

1. Installation Guide (installation.md)

2. Overview (overview.md)

3. Navigation Menu (menu.yaml)

Security Considerations

Recommendations

Conclusion

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bsten-tyk Jul 21, 2025

Choose a reason for hiding this comment

Uh oh!

bsten-tyk Jul 21, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

caroltyk commented Jul 17, 2025 •

edited by github-actions bot

Loading

netlify bot commented Jul 17, 2025 •

edited

Loading

1. Agent Management (`agent-management.md`)

2. API Evaluation (`api-evaluation.md`)

3. Governance Rulesets (`governance-rulesets.md`)

1. Installation Guide (`installation.md`)

2. Overview (`overview.md`)

3. Navigation Menu (`menu.yaml`)