Admin and Install docs #6412
Admin and Install docs #6412
Conversation
Craft an Amin Overview and finish up high-level remaining tasks for install docs.
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: iRaindrop The full list of commands accepted by this bot can be found here.
Needs approval from an approver in each of these files:
Approvers can indicate their approval by writing |
knative-prow
bot
added
the
size/S
knative-prow
bot
added
the
do-not-merge/work-in-progress
❌ Deploy Preview for knative failed.Built without sensitive environment variables
|
Spelling fix!
Wrote up admin tasks and interests by categories
knative-prow
bot
added
size/M
Changed H1 to include "Knative"
| ############################################################################### | ||
| - Administration: | ||
| # TODO: add a general overview of Knative for administrators | ||
| - Administration overview: admin/admin-overview.md |
There was a problem hiding this comment.
Since this is under "Administration", maybe just call it "Overview"?
| --- | ||
| # Knative administration overview | ||
|
|
||
| Knative has a comprehensive set of tools and capabilities to administer your Kubernetes clusters. This article provides a overview of Knative features, capabilities, and resources of interest to Kubernetes Administrators, and is organized by the following areas: |
There was a problem hiding this comment.
| Knative has a comprehensive set of tools and capabilities to administer your Kubernetes clusters. This article provides a overview of Knative features, capabilities, and resources of interest to Kubernetes Administrators, and is organized by the following areas: | |
| Knative has a comprehensive set of tools and capabilities to administer your Kubernetes clusters. This article provides a overview of Knative features, capabilities, and resources of interest to Kubernetes Administrators, and is organized by the following areas: |
The use of filler words like "comprehensive" is an LLM tell. Additionally, Knative only supplies some capabilities, but doesn't attempt to manage other cluster concerns like nodes, persistent storage, or databases.
|
|
||
| ## Installation | ||
|
|
||
| Use the Installation Roadmap for guidance on installing Knative using the resources and tool choices that best fit your needs. You can install using YAML resources, manifests, or CLI tools that include the Knative operator. |
| The Knative Operator is a custom controller that extends the Kubernetes API to install Knative components as well as configure your Kubernetes infrastructure accommodating tasks such as installing, deployment, scaling, updates, and recovery. | ||
|
|
||
| You can install Knative either by using YAML files or the Knative Operator. The Knative Operator is installed with the Knative Operator CLI plugin, or by using manifest resources. | ||
|
|
There was a problem hiding this comment.
These sentences read choppily. Maybe combine them into a single paragraph with compare / contrast or some linking sentences?
|
|
||
| You can install Knative either by using YAML files or the Knative Operator. The Knative Operator is installed with the Knative Operator CLI plugin, or by using manifest resources. | ||
|
|
||
| You can configure customized Knative Serving can customized Eventing resources. |
There was a problem hiding this comment.
I'm not sure what this sentence is trying to say.
|
|
||
| | Concepts and Procedures | Reference | | ||
| | --- | --- | | ||
| | Install Serving with YAML<br>Install Eventing with YAML<br>Install by using the Knative Operator<br>Install by using the Knative Operator CLI plugin<br>Configuring Knative using the Operator<br>Configuring Knative Serving CRDs<br>Configuring Knative Eventing CRDs<br>Install Knative Backstage plugin<br> | Knative Serving installation files<br>Knative Eventing installation files | |
There was a problem hiding this comment.
I don't really understand the presentation purpose of this table.
|
|
||
| ## Configurations | ||
|
|
||
| Knative provides comprehensive optimization capabilities for the Serving and Eventing components and settings for administering your clusters. |
There was a problem hiding this comment.
Again, I'd avoid terms like "comprehensive", which are a bit of an LLM tell. I'd instead focus on the mechanism, which is by named ConfigMaps in the controller namespace.
It's also worth explaining the ConfigMap editing process and the _example comment at the start of the ConfigMap, which should not be edited -- the system will warn if you edit the example rather than creating separate keys alongside _example.
|
|
||
| ## Monitoring and Observability | ||
|
|
||
| Both the Serving and Eventing components are well maintained with logging, tracing, and metric collections. |
There was a problem hiding this comment.
Again, I'd trim "well maintained" -- that should either be evident from usage, or no amount of claiming it will make it true.
There was a problem hiding this comment.
You might say "integrated with OpenTelemetry"
|
|
||
| ## Security | ||
|
|
||
| Knative provides robust security and access control measures with the certificate manager, networking TLS certificates, domain and cluster encryption, and application security. |
There was a problem hiding this comment.
Rather than saying "provides robust security ...", I'd probably emphasize "integrates with existing security and access control measures" and include links to e.g. Kubernetes access control and policy tools like Kyverno or Open Policy Agent.
|
|
||
| ## Updates and Maintenance | ||
|
|
||
| In addition to updates, Knative provides several configurations for maintaining your clusters in optimal condition including resources, volume, traffic, and load balancing. |
There was a problem hiding this comment.
Again, I'd emphasize integrating with existing components for things like resource limits and volumes (using the existing Kubernetes feature).
The "gradual rollout of traffic" and "developer configuration options" are probably more appropriate for the developer documentation (most of the site) than cluster administrators. There are settings administrators can use to adjust the default behavior for users that don't specify behaviors, so you might have a setting on "adjusting cluster defaults". That generally feels like it falls under "configuration", though.
Write an Aministration Overview and finish up high-level remaining tasks for install docs.
Proposed Changes