Admin overview doc #6412
Admin overview doc #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 ready!Built without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify project configuration. |
Spelling fix!
Wrote up admin tasks and interests by categories
knative-prow
bot
added
size/M
Changed H1 to include "Knative"
Link testing and de-emphasizing tables
Link fixes
indented bullets test
Settling on combo or paras with lins and minimal bulleted lists
Worked on Configurations section
Worked on the Monitoring and Observability section
knative-prow
bot
added
size/L
Finished initial write-up for each section
Added blog links (as a test)
There was a problem hiding this comment.
This reads more like a table of contents than an overview, at the moment.
Looking at I'm noticing that right now it's largely an exposition of the left-hand nav (or desired left-hand nav), which doesn't feel like the best use of reading time.
If you look at https://knative.dev/docs/, it starts out with "what this document is about".
In this case, I think the document is about something like:
Knative consists of several on-cluster components alongside client tools like
knandfunc. This page explains how to install and manage Knative on an existing Kubernetes cluster. It assumes that you are generally familiar with Kubernetes, Kubernetes administration, thekubectlcommand, and have at least some familiarity with the larger CNCF ecosystem. Additionally, it assumes that you have the ability to install software and manage resources in all clusters in the namespace (cluster-adminpermissions, or equivalent). When you've finished, you will understand the different Knative components, their roles, the Knative philosophy, and how to enable your cluster's users to develop using Knative.
| Knative has a 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: | ||
|
|
||
| - Installation | ||
| - Configuration | ||
| - Monitoring and Observability | ||
| - Security and Access Control | ||
| - Updates and Maintenance |
There was a problem hiding this comment.
We already have a right-side TOC, so I'd rather spend this space explaining the Knative philosophy for system administrators.
-
Knative aims to extend Kubernetes, and build on existing capabilities where feasible
-
You should be able to use existing Kubernetes management tools (policy, quota, etc) to manage Knative workloads
-
Serving and Eventing are server-side; Functions is generally client side and so shouldn't need to be managed by administrators
-
Underlying components for Knative are generally:
- Serving: pods and pluggable network ingress routes
- Eventing: pods and pluggable message transports (e.g. Kafka, RabbitMQ)
-
Knative supports plugging in multiple underlying transports / routes; you can use several even in the same cluster. Knative has default lightweight implementations if you don't already have a solution.
There was a problem hiding this comment.
Good point re RHS TOC. Also agree that it's appropriate to explain the Knative philosophy and purpose here, especially since this is the main section of conceptual information in the documentation. It seems to be developing into a lifecycle/process framework, which is fine, but use that as an opportunity to explain the product, not just a preview of the administrator's guide.
|
|
||
| ### Recommended plugins | ||
|
|
||
| You can also install these plugins service to extend Knative capabilities for service meshes and application security: |
There was a problem hiding this comment.
Will everyone know what these plugins are for? Maybe provide a short description of each saying what the benefits are? Consider using a definition list in that case.
| - [Knative Serving CRDs](/install/operator/configuring-serving-cr.md) | ||
| - [Knative Eventing CRDs](/install/operator/configuring-eventing-cr.md) |
There was a problem hiding this comment.
Provide descriptions in a definition list?
|
|
||
| TODO: Editing ConfigMaps guidance | ||
|
|
||
| ### Autoscaling, high-availability and load balancing |
There was a problem hiding this comment.
Review capitalization of in-line references in this section.
| - Event sources, see [Configure event source defaults](/eventing/configuration/sources-configuration.md) and also refer to [Knative reference mapping](/eventing/features/kreference-mapping.md). | ||
| - Brokers. See [Developer configuration options](/eventing/brokers/broker-developer-config-options.md) and [Configure Broker defaults](/eventing/configuration/broker-configuration.md) for an overview of broker configurations and an example. | ||
| - Kafka, a distributed event store and stream-processing platform. See [Configure Kafka features](/eventing/brokers/broker-types/kafka-broker/configuring-kafka-features.md) and [Configure Apache Kafka Channel defaults](/eventing/configuration/kafka-channel-configuration.md). See also [Configure KEDA Autoscaling of Knative Kafka Resources](/eventing/configuration/keda-configuration.md) | ||
| - Istio, a programmable, application-aware network. See [Eventing with Istio](/eventing/features/istio-integration.md). | ||
| - Channels. See [Configure Channel defaults](/eventing/configuration/channel-configuration.md). | ||
|
|
There was a problem hiding this comment.
This would be more readable in a definition list.
Processed most reviewer edits
Added "YAML and CLI installations compared" section
|
|
||
| Knative supports subsequent installs after the initial installation, you so your initial choices don't lock you in. For example, you can migrate from one message transport or network ingress to another without losing messages. | ||
|
|
||
| ### YAML and CLI installations compared |
There was a problem hiding this comment.
This section is inaccurate and the content will be repurposed.
Write an Aministration Overview and finish up high-level remaining tasks for install docs.
Proposed Changes