Admin overview doc

docs/versioned/.nav.yml

@@ -286,7 +286,7 @@ nav:
     # Administration
 ###############################################################################
     - Administration:
-      # TODO: add a general overview of Knative for administrators
+      - Administration overview: admin/admin-overview.md
       - Installing Knative: install/README.md
       # YAML Installation
       - Install Knative with YAML:

docs/versioned/admin/admin-overview.md

@@ -0,0 +1,84 @@
+---
+audience: administrator
+components:
+  - serving
+  - eventing
+function: reference
+---
+# Overview
+
+This page provides guidance for administrators on how to install and manage Knative on an existing Kubernetes cluster. It assumes you are familiar with the following:
+
+- Kubernetes and Kubernetes administration.
+- The `kubectl` CLI tool. You can use existing Kubernetes management tools (policy, quota, etc) to manage Knative workloads.
+- Cloud Native Computing Foundation (CNCF) projects such as Prometheus, Istio, and Strimzi, many of which can be used alongside Knative.
+- You should have 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)
+
+To simplify Knative installation and administration, you can use the Knative operator and the Knative 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. Severing and Eventing are installed into clusters, but not Functions. Functions does not require installation.
+
+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 implementations if you don't already have a solution.
+
+## Installing Knative
+
+You install Knative using YAML files and other resources either aided or not by the Knative Operator. The Knative Operator is a custom controller that extends the Kubernetes API to install Knative components. It allows you to automate applying the content, along with patching the contents to customize them. You install the Knative Operator either by using the Knative CLI Operator Plugin or by using KS8 Manifests or by Yelm.
+
+For hardware prerequisites and information about installing the quickstart, see the [Installation Roadmap](/install/README.md).
+
+Here are the considerations for installing using YAML or the Knative Operator:
+
+| YAML-based install | Knative Operator install|
+| --- | --- |
+| 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. |
+
+You can install Knative in the following ways:
+
+- 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.
+
+- Install the [Knative Operator](/install/operator/knative-with-operators.md) using Manifests or Yelm, 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.
+
+- Install the [Knative Operator CLI plugin](/install/operator/knative-with-operator-cli.md) and install the Knative Operator and the Knative CLI `kn` to  Knative components.
+
+    This is the easiest install option and suitable for using if customization is not a concern.
+
+The following table summarizes the options.
+
+| Install option | Resources | kubectl CLI | kn CLI |
+| --- | --- | --- | --- |
+| YAML-based | All YAML prepared | Install components | not used |
+| Knative Operator | Install Knative Operator using Manifests or Yelm |Install components | not used |
+| Knative Operator | Install Knative Operator CLI plugin | not used | Install components |
+
+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.
+
+## Defining and modifying custom resources
+
+Either before or after the installing Knative Eventing and Serving components, you can create and modify custom resources and reinstall components as needed. You do so by creating or modifying a ConfigMap using a custom resource definition (CRD). For more information, see [Knative Serving CRDs](/install/operator/configuring-serving-cr.md) and [Knative Eventing CRDs](/install/operator/configuring-eventing-cr.md).
+
+## Plugins
+
+A Knative installation includes the following plugins:
+
+Networking plugins
+
+- Kourier (internal no-dependency option)
+- Istio (service mesh)
+- Courier (general-purpose ingress)
+- Gateway API (beta)
+
+Messaging plugins
+
+- In-memory (internal no-dependency option)
+- Kafka (in-order, high-thoughput but moderate complexity)
+- RabbitMQ (configurable order, moderate throughput and complexity)
+- NATS (low complexity)