Update the Operator Guide

[dwelsch-esi]

Revise the Operator Guide to be user focused: it should provide explicit instructions to complete any task the user might commonly need to accomplish after the product is deployed.

This issue tracks recommended changes resulting from an analysis of the KEDA documentation commissioned by CNCF. The analysis and supporting documents are here: https://github.com/cncf/techdocs/tree/main/assessments/0011-keda/

Use-Case

KEDA has one user persona, a Kubernetes Operator whose goal is to:

1. Add KEDA to a Kubernetes cluster
2. Use KEDA to scale resource usage on the cluster

The Operator Guide gives the user detailed instructions on how to do the second part. It should be predominantly a set of step-by-step instructions for any task the Operator must accomplish to use and maintain KEDA in the cluster.

Some guidelines for improving the KEDA Operator Guide:

• Can be named "Using KEDA" or "Operator Guide".
• Base the guide on the existing "Operator" section.
• 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/#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 page could go on one page named "Using HTTP".

Specification

Here is a proposed outline. Links are to existing pages that can be used as-is or provide a starting point.

• Using KEDA or Operator Guide (rename current "Operate")
  • Setting up a scaler (write or adapt a more detailed procedure than the example used in Getting Started - see "Write 'Setting Up a Scaler'")
  • Usage Scenarios
  • Scaling with RabbitMQ and Go
  • Scaling with Azure Functions and Kafka on Openshift 4
  • ... and so on.
  • Admission Webhooks
  • Prevention Rules (https://keda.sh/docs/2.13/concepts/admission-webhooks/#prevention-rules)
  • Validation Enforcement
  • Cluster - (Relocate sections that are purely reference info)
  • Using HTTP Setting Timeouts Disabling Keep-alive Using HTTP Proxies [Configuring Minimum TLS Version]
  • Integrating with OpenTelemetry Collector (Experimental)
  • Integrating with Prometheus
  • Using the KEDA Metrics Server
  • Querying Metrics
  • Getting Metric Names
  • Security
  • Migrating to a new release (current "Migration Guide")
  • 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)
  • 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/)

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed in 7 days if no further activity occurs. Thank you for your contributions.

[nate-double-u]

I think it's best not to auto-delete this issue, I think it is still relevant.

[shubhusion]

@nate-double-u I would like to work on this issue if assigned.

[nate-double-u]

I'm not able to assign folks to issues in this repo. Though, I'm sure PRs are welcome! You can take a look at Keda's getting started info here: https://keda.sh/community/#get-involved

[shubhusion]

I will start working on this issue after my PR #1415 on Procedure to Setup a Scaler is merged.

[shubhusion]

I am working on this issue now

[shubhusion]

@JorTurFer @tomkerkhove I wanted to confirm if I can proceed with the outlined plan for updating the Operator Guide. Based on the current documentation, setting up a scaler and troubleshooting are already included in the Getting Started section.

Additionally, should I create separate pages for Usage Scenarios or just link to the existing GitHub repository?

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed in 7 days if no further activity occurs. Thank you for your contributions.