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.
Processed most reviewer edits
Added "YAML and CLI installations compared" section
Misc edits
Processed reviwer edits
|
With the other PR merged are any changes in this PR still necessary? |
knative-prow-robot
added
the
needs-rebase
Edits per repurposing
knative-prow
bot
added
size/M
knative-prow
bot
removed
the
do-not-merge/work-in-progress
knative-prow-robot
removed
the
needs-rebase
Set admin-overview.md as the top topic
Removed section that will be doc'd elsewhere
Single edit "messaging implementation"
| - In-memory (internal no-dependency option) | ||
| - Kafka (in-order, high-thoughput but moderate complexity) | ||
| - RabbitMQ (configurable order, moderate throughput and complexity) | ||
| - NATS (low complexity) |
There was a problem hiding this comment.
Below this, I think there's at least one section on the Knative model for a cluster, which generally matches the Kubernetes model:
- Each application or developer team is assigned a namespace. Developers generally have the ability to create / edit resources within that namespace.
- Namespaces should generally act as independent units. This can be enforced with tools like RBAC, quota, and policy.
- Without substantial Kubernetes planning, namespaces are a soft isolation boundary between teams. See the threat model for more details about security between users on the same cluster.
- Developers often need access to additional resources related to their namespace in other services, such as observability (logs, metrics, tracing) and dashboards (e.g. Grafana / Backstage). It's expected that the administrator will provision this access alongside creating the namespace and assigning permissions.
There was a problem hiding this comment.
I'm not sure if there's another section or not. I tend to like threes, but I'm not sure I have a third important part at the moment.
Moved install content from administer/admin-overiview.md into the install/README.md
knative-prow
bot
added
size/L
Installation content all in README.md - admin-overview.md emptied with placeholder
Reset overview to README.md
Fixed Nav error
Fixed broken links
There was a problem hiding this comment.
I actually liked the idea of having a of the larger context around how & why of running Knative separate from the "get it done" installation documentation.
Also, it looks like admin-overview.md is orphaned (not in the nav) in this PR. Does it make sense to keep it separate from administer/README.md, or do the two serve the same purpose?
docs/versioned/install/README.md
Outdated
|
|
||
| To simplify Knative installation and administration, you can use the Knative Operator with the Knative `kn` CLI tool, but they are not required. Essentially, Knative aims to extend Kubernetes, and build on existing capabilities where feasible. | ||
|
|
||
| Knative has three components: Eventing, Serving, and Functions. Serving and Eventing are installed into clusters. Functions is not installed into clusters because it is operated by the client `func` CLI tool. |
There was a problem hiding this comment.
This seems to duplicate line 11 with only slightly more clarity. Merge this with that paragraph?
docs/versioned/install/README.md
Outdated
| - Using cluster-admin permissions or equivalent to to install software and manage resources in all clusters in the namespace. For information about permissions, see [Using RBAC Authorization](https://kubernetes.io/docs/reference/access-authn-authz/rbac/AC). | ||
| - Familiarity with Cloud Native Computing Foundation (CNCF) projects such as Prometheus, Istio, and Strimzi, many of which can be used alongside Knative, is recommended. | ||
|
|
||
| To simplify Knative installation and administration, you can use the Knative Operator with the Knative `kn` CLI tool, but they are not required. Essentially, Knative aims to extend Kubernetes, and build on existing capabilities where feasible. |
There was a problem hiding this comment.
The second sentence doesn't really summarize the first, so "essentially" doesn't seem to fit here. I'm wondering if these two sentences are part of the same paragraph at this point.
There was a problem hiding this comment.
I removed the second sentence "Essentiall, ... " It's a good insight and will be used elsewhere.
docs/versioned/install/README.md
Outdated
| Serving and Eventing support multiple underlying transports plugins within the same cluster. Serving supports pods with pluggable network ingress routes, and Eventing supports pods with pluggable message transports (e.g. Kafka, RabbitMQ). | ||
|
|
||
| Knative has default lightweight messaging implementation if you don't already have a solution. Knative also has Kourier, a default lightweight HTTP routing implementation, if you don't already have an ingress that meets the requirements. |
There was a problem hiding this comment.
What's the purpose of this document? These paragraphs seem to be a discursion from the "how-to" style of much of the document.
There was a problem hiding this comment.
I see what you mean - good insight but better in another topic.
docs/versioned/install/README.md
Outdated
|
|
||
| - Use a [YAML-based installation](/install/yaml-install/README.md) with `kubectl`. | ||
|
|
||
| This option is the most useful if you're using delivery solutions such as Flux or ArgoCD to apply manifests checked into a Git repository. This is the lowest common denominator approach, giving you granular control of the process and resource definitions. |
There was a problem hiding this comment.
| This option is the most useful if you're using delivery solutions such as Flux or ArgoCD to apply manifests checked into a Git repository. This is the lowest common denominator approach, giving you granular control of the process and resource definitions. | |
| This option is the most useful if you use GitOps tools such as Flux or ArgoCD to apply manifests checked into a Git repository. This is the lowest common denominator approach, giving you granular control of the process and resource definitions. |
docs/versioned/install/README.md
Outdated
|
|
||
| - Install the [Knative Operator](/install/operator/knative-with-operators.md) using Manifests or Helm, and then use `kubectl` to install Knative components. | ||
|
|
||
| This option alleviates complexity by using the Knative Operator, while still enabling purpose-built manageability using popular tools. It also gives you a separation of the core Knative application definition and the ConfigMap and other changes you make. |
There was a problem hiding this comment.
I'm not sure what "purpose-built manageability using popular tools" means. If we mean "is compatible with a GitOps approach" or "deployment using Flux or ArgoCD", we should say that.
There was a problem hiding this comment.
chose GitHub approach
docs/versioned/install/README.md
Outdated
|
|
||
| For details, see [YAML and Knative Operator installations compared](#yaml-and-knative-operator-installations-compared). | ||
|
|
||
| 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. |
There was a problem hiding this comment.
| 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. | |
| Knative supports installing additional plugins 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. |
docs/versioned/install/README.md
Outdated
| | You can see exactly what you get. | You specify choices at a higher level. | | ||
| | You can adjust any parameters by editing them directly. | Not every setting is exposed. | | ||
| | If you make changes, you have to keep track of what you changed when you want to upgrade. | It's easy to separate your customizations from the base installation. | | ||
| | Version and audit control as YAML files are stored in a GitHub repository.| No version or audit control. | |
There was a problem hiding this comment.
As mentioned in a previous comment, it's still possible to perform version and audit control on the Knative Operator, but it also enables a simple command-driven approach.
| | Version and audit control as YAML files are stored in a GitHub repository.| No version or audit control. | | |
| | Manage Kubernetes manifests using your existing tools. | Manage custom resources using command-line tools or manifests. | |
docs/versioned/install/README.md
Outdated
| Networking plugins: | ||
|
|
||
| - Kourier | ||
| Data management from [Kore Technologies](https://koretech.com) with has a internal no-dependency option. |
There was a problem hiding this comment.
This link is wrong. Kourier is a lightweight ingress which leverages Envoy proxy.
docs/versioned/install/README.md
Outdated
| - Courier | ||
| General-purpose ingress. |
There was a problem hiding this comment.
I probably screwed up the name at some point, but this should be:
| - Courier | |
| General-purpose ingress. | |
| - [Contour](https://projectcontour.io/) | |
| General-purpose ingress with a goal of enabling multi-team delegation. |
docs/versioned/install/README.md
Outdated
| - NATS | ||
| An event streaming platform from [NATS](https://nats.io). Low complexity. | ||
|
|
||
| Knative has an in-memory and internal no-dependency messaging option. |
There was a problem hiding this comment.
| Knative has an in-memory and internal no-dependency messaging option. | |
| Knative Eventing also includes a no-dependency in-memory (non-durable) messaging implementation. |
Processed reviewer edits
More link fixes
5 participants
Write an Aministration Overview and finish up high-level remaining tasks for install docs.
Proposed Changes