Admin overview doc

[iRaindrop]

Write an Aministration Overview and finish up high-level remaining tasks for install docs.

Proposed Changes

• Add Administration Overview to the doc set. Summarize task areas for a Knative admin with links.

[knative-prow]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: iRaindrop
Once this PR has been reviewed and has the lgtm label, please assign creydr for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[netlify]

✅ Deploy Preview for knative ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	f5471d8
🔍 Latest deploy log	https://app.netlify.com/projects/knative/deploys/68e8a426cd6803000899dc58
😎 Deploy Preview	https://deploy-preview-6412--knative.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[evankanderson]

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 kn and func. 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, the kubectl command, 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-admin permissions, 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.

[dwelsch-esi]

@iRaindrop, @evankanderson

Comments and suggestions added. Happy to answer questions or explain my reasoning if you have questions. Please respond in the PR.

If I contradict the style guide, go with the style guide.

[dwelsch-esi]

Admin table is a good organizational aid.

Page headings don't match the left-sidebar TOC entries:
Administration -> Installing Knative
Administration overview -> Overview
Install Knative with YAML -> About YAML-based installation
etc.

[evankanderson]

Thanks, this is starting to look better, sorry about the big pile of comments, but it seemed useful at this point to get closer to the details.

[dprotaso]

With the other PR merged are any changes in this PR still necessary?

[evankanderson]

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.

[evankanderson]

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.