cncf
/
techdocs
mirror of https://github.com/cncf/techdocs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

[chore] Check Keda analysis pages 

Signed-off-by: Patrice Chalin <pchalin@gmail.com>
This commit is contained in:
Patrice Chalin 2025-02-26 15:21:18 -05:00
parent 64b6ce9e10
commit bb1228f19f
4 changed files with 55 additions and 51 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
analyses/0011-keda/keda-analysis.md
View File

@ -6,6 +6,8 @@ author: Dave Welsch (@dwelsch-esi)
cSpell:ignore: Welsch dwelsch pastable servicedesk
---
<!-- markdownlint-disable line-length no-duplicate-heading single-title no-emphasis-as-heading -->
# Introduction
This document analyzes the effectiveness and completeness of the
@ -46,15 +48,15 @@ Netlify platform. The site's code is stored on the KEDA GitHub repo.
**In scope:**
- Website: https://keda.sh
- Documentation: https://keda.sh/docs
- Website repo: https://github.com/kedacore/keda-docs
- Governance repo: https://github.com/kedacore/governance
- Main project contributor info: https://github.com/kedacore/keda
- Website: <https://keda.sh>
- Documentation: <https://keda.sh/docs>
- Website repo: <https://github.com/kedacore/keda-docs>
- Governance repo: <https://github.com/kedacore/governance>
- Main project contributor info: <https://github.com/kedacore/keda>
**Out of scope:**
- Other KEDA repos: https://github.com/kedacore/*
- Other KEDA repos under <https://github.com/kedacore/>
## How this document is organized
@ -233,12 +235,12 @@ The documentation includes some examples of
[**non-inclusive language**](https://inclusivenaming.org/). For example:
- "easily", "simple", "simply", etc.
- https://keda.sh/docs/2.13/deploy/
- https://keda.sh/docs/2.13/deploy/#uninstall-3
- https://keda.sh/docs/2.13/concepts/scaling-deployments/#triggers
- <https://keda.sh/docs/2.13/deploy/>
- <https://keda.sh/docs/2.13/deploy/#uninstall-3>
- <https://keda.sh/docs/2.13/concepts/scaling-deployments/#triggers>
- "master" node
- https://keda.sh/docs/2.13/troubleshooting/#google-kubernetes-engine-gke
- https://keda.sh/docs/2.13/scalers/redis-sentinel-lists/#authentication-parameters
- <https://keda.sh/docs/2.13/troubleshooting/#google-kubernetes-engine-gke>
- <https://keda.sh/docs/2.13/scalers/redis-sentinel-lists/#authentication-parameters>
## Recommendations

31
analyses/0011-keda/keda-implementation.md
View File

@ -1,8 +1,9 @@
---
title: Implementing KEDA Doc Improvements
tags: keda
---
<!-- markdownlint-disable line-length no-duplicate-heading single-title no-emphasis-as-heading -->
# Introduction
This document provides actionable suggestions for improving the KEDA technical
@ -76,7 +77,7 @@ Here is a proposed outline for the tech doc Table of Contents:
- [Getting Started (New users start here!)](https://keda.sh/docs/2.13/) (rename
current "KEDA Documentation" heading)
- [Deploying KEDA](https://keda.sh/docs/2.13/deploy/)
- Prerequisites (https://keda.sh/docs/2.13/operate/cluster/#requirements)
- Prerequisites (<https://keda.sh/docs/2.13/operate/cluster/#requirements>)
- [Deploying with Helm](?no-link-check#helm)
- [Installing](?no-link-check#install)
- [Uninstalling](?no-link-check#uninstall)
@ -91,7 +92,7 @@ Here is a proposed outline for the tech doc Table of Contents:
- [Uninstalling](?no-link-check#uninstall-3)
- Hello, KEDA (write a procedure for a simplest-possible use case for users to
get started on - something like
https://github.com/kedacore/sample-hello-world-azure-functions)
<https://github.com/kedacore/sample-hello-world-azure-functions>)
- [Using KEDA or Operator Guide](https://keda.sh/docs/2.13/operate/) (rename
current "Operate")
- How to set up a scaler (a more detailed procedure than the example used in
@ -102,13 +103,13 @@ Here is a proposed outline for the tech doc Table of Contents:
- ... and so on.
- [Admission Webhooks](https://keda.sh/docs/2.13/operate/admission-webhooks/)
- Prevention Rules
(https://keda.sh/docs/2.13/concepts/admission-webhooks/#prevention-rules)
(<https://keda.sh/docs/2.13/concepts/admission-webhooks/#prevention-rules>)
- Validation Enforcement
- [Cluster](https://keda.sh/docs/2.13/operate/cluster/) - Except sections that
are purely reference info, for example:
- https://keda.sh/docs/2.13/operate/cluster/#kubernetes-compatibility
- https://keda.sh/docs/2.13/operate/cluster/#cluster-capacity
- https://keda.sh/docs/2.13/operate/cluster/#firewall
- <https://keda.sh/docs/2.13/operate/cluster/#kubernetes-compatibility>
- <https://keda.sh/docs/2.13/operate/cluster/#cluster-capacity>
- <https://keda.sh/docs/2.13/operate/cluster/#firewall>
- [Integrating with OpenTelemetry Collector (Experimental)](https://keda.sh/docs/2.13/integrations/opentelemetry/)
- [Integrating with Prometheus](https://keda.sh/docs/2.13/integrations/prometheus/)
- [Using the KEDA Metrics Server](https://keda.sh/docs/2.13/operate/metrics-server/)
@ -118,22 +119,22 @@ Here is a proposed outline for the tech doc Table of Contents:
- [Migrating to a new release](https://keda.sh/docs/2.13/migration/) (current
"Migration Guide")
- Caching Metrics
(https://keda.sh/docs/2.13/concepts/scaling-deployments/#caching-metrics)
(<https://keda.sh/docs/2.13/concepts/scaling-deployments/#caching-metrics>)
- Pausing Autoscaling of deployments
(https://keda.sh/docs/2.13/concepts/scaling-deployments/#pause-autoscaling)
(<https://keda.sh/docs/2.13/concepts/scaling-deployments/#pause-autoscaling>)
- Pausing Autoscaling of jobs
(https://keda.sh/docs/2.13/concepts/scaling-jobs/#pause-autoscaling)
- [Troubleshooting](https://keda.sh/docs/2.13/concepts/troubleshooting/,
/docs/2.13/troubleshooting/)
(<https://keda.sh/docs/2.13/concepts/scaling-jobs/#pause-autoscaling>)
- [Troubleshooting](https://keda.sh/docs/2.13/concepts/troubleshooting/),
`/docs/2.13/troubleshooting/`
- Reference
- [Authentication Providers](https://keda.sh/docs/2.13/authentication-providers/)
- [AWS (IRSA) Pod Identity Webhook](https://keda.sh/docs/2.13/authentication-providers/aws/)
- ...
- [Secret](https://keda.sh/docs/2.13/authentication-providers/secret/)
- Scaled Object specification (from "Concepts";
https://keda.sh/docs/2.13/concepts/scaling-deployments/#scaledobject-spec)
<https://keda.sh/docs/2.13/concepts/scaling-deployments/#scaledobject-spec>)
- ScaledJob specification
(https://keda.sh/docs/2.13/concepts/scaling-jobs/#scaledjob-spec)
(<https://keda.sh/docs/2.13/concepts/scaling-jobs/#scaledjob-spec>)
- [Events](https://keda.sh/docs/2.13/operate/events/)
- [Firewall requirements](https://keda.sh/docs/2.13/operate/cluster/#firewall)
- ...
@ -210,7 +211,7 @@ annotated to illustrate this point:
- [Uninstalling](?no-link-check#uninstall-3)
- Hello, KEDA (write a procedure for a simplest-possible use case for users to
get started on - something like
https://github.com/kedacore/sample-hello-world-azure-functions) _analogous
<https://github.com/kedacore/sample-hello-world-azure-functions>) _analogous
to a "Hello World" exercise in programming language or API guides_
# Update the doc content creation instructions

47
analyses/0011-keda/keda-issues.md
View File

@ -1,9 +1,10 @@
---
title: KEDA Umbrella Issue
tags: keda
cSpell:ignore: externalscaler findability
---
<!-- markdownlint-disable line-length no-duplicate-heading single-title no-emphasis-as-heading -->
# Overview
This document outlines the recommended changes to the KEDA documentation. The
@ -98,7 +99,7 @@ into multiple pages, one for each procedure.
- [Uninstalling](?no-link-check#uninstall-3)
- Hello, KEDA (write a procedure for a simplest-possible use case for users to
get started on - something like
https://github.com/kedacore/sample-hello-world-azure-functions) _analogous
<https://github.com/kedacore/sample-hello-world-azure-functions>) _analogous
to a "Hello World" exercise in programming language or API guides_
## Issue: Update the Operator Guide
@ -110,9 +111,9 @@ Some guidelines:
- Move "Troubleshooting" to the end of the Operator Guide.
- Relocate sections that are purely reference information, including these
sections in [Cluster](https://keda.sh/docs/2.13/operate/cluster/):
- https://keda.sh/docs/2.13/operate/cluster/#kubernetes-compatibility
- https://keda.sh/docs/2.13/operate/cluster/#cluster-capacity
- https://keda.sh/docs/2.13/operate/cluster/#firewall
- <https://keda.sh/docs/2.13/operate/cluster/#kubernetes-compatibility>
- <https://keda.sh/docs/2.13/operate/cluster/#cluster-capacity>
- <https://keda.sh/docs/2.13/operate/cluster/#firewall>
- Break up long pages containing several topics. Aim for one major topic per
page. For example, all HTTP-related headings on the
[Cluster](https://keda.sh/docs/2.13/operate/cluster/) page could go on one
@ -132,7 +133,7 @@ or provide a starting point.
- ... and so on.
- [Admission Webhooks](https://keda.sh/docs/2.13/operate/admission-webhooks/)
- Prevention Rules
(https://keda.sh/docs/2.13/concepts/admission-webhooks/#prevention-rules)
(<https://keda.sh/docs/2.13/concepts/admission-webhooks/#prevention-rules>)
- Validation Enforcement
- [Cluster](https://keda.sh/docs/2.13/operate/cluster/) - (Relocate sections
that are purely reference info)
@ -150,13 +151,13 @@ or provide a starting point.
- [Migrating to a new release](https://keda.sh/docs/2.13/migration/) (current
"Migration Guide")
- Caching Metrics
(https://keda.sh/docs/2.13/concepts/scaling-deployments/#caching-metrics)
(<https://keda.sh/docs/2.13/concepts/scaling-deployments/#caching-metrics>)
- Pausing Autoscaling of deployments
(https://keda.sh/docs/2.13/concepts/scaling-deployments/#pause-autoscaling)
(<https://keda.sh/docs/2.13/concepts/scaling-deployments/#pause-autoscaling>)
- Pausing Autoscaling of jobs
(https://keda.sh/docs/2.13/concepts/scaling-jobs/#pause-autoscaling)
- [Troubleshooting](https://keda.sh/docs/2.13/concepts/troubleshooting/,
/docs/2.13/troubleshooting/)
(<https://keda.sh/docs/2.13/concepts/scaling-jobs/#pause-autoscaling>)
- [Troubleshooting](https://keda.sh/docs/2.13/concepts/troubleshooting/)
`/docs/2.13/troubleshooting/`
## Issue: Create a "Reference" topic
@ -174,9 +175,9 @@ or provide a starting point.
- ...
- [Secret](https://keda.sh/docs/2.13/authentication-providers/secret/)
- Scaled Object specification (from "Concepts";
https://keda.sh/docs/2.13/concepts/scaling-deployments/#scaledobject-spec)
<https://keda.sh/docs/2.13/concepts/scaling-deployments/#scaledobject-spec>)
- ScaledJob specification
(https://keda.sh/docs/2.13/concepts/scaling-jobs/#scaledjob-spec)
(<https://keda.sh/docs/2.13/concepts/scaling-jobs/#scaledjob-spec>)
- [Events](https://keda.sh/docs/2.13/operate/events/)
- [Firewall requirements](https://keda.sh/docs/2.13/operate/cluster/#firewall)
- ...
@ -202,16 +203,16 @@ they be revised or relocated. If this creates contradictory recommendations,
some judgement might be required to rearrange things.
| Page Title | URL | Notes |
| ------------------------------------------------------ | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Deploying KEDA | https://keda.sh/docs/2.13/deploy/ | Page is all install and uninstall tasks, but put each install procedure on its own page. Make this page an intro and index. |
| Scaling Deployments, StatefulSets and Custom Resources | https://keda.sh/docs/2.13/concepts/scaling-deployments/ | The "ScaledObject spec" is reference information. "Transfer ownership of an existing HPA" is a task. |
| Scaling Jobs | https://keda.sh/docs/2.13/concepts/scaling-jobs/ | "ScaledJob spec" is reference information. |
| Authentication | https://keda.sh/docs/2.13/concepts/authentication/ | Deliberately discuss the three patterns listed at the top of the page. This entire page might be better written as a task-based how-to guide. |
| External Scalers | https://keda.sh/docs/2.13/concepts/external-scalers/ | "Implementing KEDA external scaler GRPC interface" is a series of tasks. The steps after the first 2 are choices -- Describe the task of downloading `externalscaler.proto` and preparing the project, then offer steps 3 - 6 as sub-tasks that can be performed independently. |
| Troubleshooting | https://keda.sh/docs/2.13/concepts/troubleshooting/ | Remove this troubleshooting information and combine it with the troubleshooting section under "The KEDA Documentation". |
| Cluster | https://keda.sh/docs/2.13/operate/cluster/ | See the "Update the Operator Guide" issue |
| Events | https://keda.sh/docs/2.13/operate/events/ | This is reference information. |
| Integrate with Prometheus | https://keda.sh/docs/2.13/integrations/prometheus/ | Split this into a task ("Integrating with Prometheus" and a reference "Metrics Exported to Prometheus". |
| ------------------------------------------------------ | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Deploying KEDA | <https://keda.sh/docs/2.13/deploy/> | Page is all install and uninstall tasks, but put each install procedure on its own page. Make this page an intro and index. |
| Scaling Deployments, StatefulSets and Custom Resources | <https://keda.sh/docs/2.13/concepts/scaling-deployments/> | The "ScaledObject spec" is reference information. "Transfer ownership of an existing HPA" is a task. |
| Scaling Jobs | <https://keda.sh/docs/2.13/concepts/scaling-jobs/> | "ScaledJob spec" is reference information. |
| Authentication | <https://keda.sh/docs/2.13/concepts/authentication/> | Deliberately discuss the three patterns listed at the top of the page. This entire page might be better written as a task-based how-to guide. |
| External Scalers | <https://keda.sh/docs/2.13/concepts/external-scalers/> | "Implementing KEDA external scaler GRPC interface" is a series of tasks. The steps after the first 2 are choices -- Describe the task of downloading `externalscaler.proto` and preparing the project, then offer steps 3 - 6 as sub-tasks that can be performed independently. |
| Troubleshooting | <https://keda.sh/docs/2.13/concepts/troubleshooting/> | Remove this troubleshooting information and combine it with the troubleshooting section under "The KEDA Documentation". |
| Cluster | <https://keda.sh/docs/2.13/operate/cluster/> | See the "Update the Operator Guide" issue |
| Events | <https://keda.sh/docs/2.13/operate/events/> | This is reference information. |
| Integrate with Prometheus | <https://keda.sh/docs/2.13/integrations/prometheus/> | Split this into a task ("Integrating with Prometheus" and a reference "Metrics Exported to Prometheus". |
# Write a Glossary

2
package.json
View File

@ -12,7 +12,7 @@
"_check:markdown:1": "npx -p markdownlint-cli markdownlint -c .markdownlint.yaml",
"_list:git:delta": "git diff --name-only --diff-filter=ACMR | grep -E '\\.(js|md|scss|yml|yaml)$'",
"_list:check:md:no-analysis": "find . -name '*.md' -not -path '*/node_modules/*' -a -not -path '*/.?*' -a -not -path '*/00*'",
"_list:check:md": "find . -name '*.md' -not -path '*/node_modules/*' -a -not -path '*/.?*' | grep -Eve '/000|/0010|/0011'",
"_list:check:md": "find . -name '*.md' -not -path '*/node_modules/*' -a -not -path '*/.?*' | grep -Eve '/000|/0010'",
"_list:check:*": "npm run --loglevel=warn | grep -Ee '^\\s*check:[^:]+$'",
"_list:fix:*": "npm run --loglevel=warn | grep -Ee '^\\s*fix:[^:]+$' | grep -v 'fix:all'",
"check:format": "npm run _check:format || (echo '[help] Run: npm run fix:format'; exit 1)",