Admin overview doc

docs/versioned/.nav.yml

@@ -233,7 +233,7 @@ nav:
     # Administration
 ###############################################################################
     - Administration:
-      - Overview: administer/README.md
+      - Overview: admin/admin-overview.md
       - Installing Knative:
         - Overview: install/README.md
         # YAML Installation

docs/versioned/admin/admin-overview.md

@@ -0,0 +1,115 @@
+---
+audience: administrator
+components:
+  - serving
+  - eventing
+function: explanation
+---
+# Overview
+
+This page provides guidance for administrators on how to manage Knative on an existing Kubernetes cluster.
+
+As a cluster administrator, your responsibilities include managing the Kubernetes environment, installing cluster-wide components, and enabling developers to deploy applications on the cluster. Knative aims to simplify developer tasks, while aligning with existing management tools and processes.
+
+Knative includes a plugin system to interoperate with existing cluster infrastructure, enabling Knative resources, such as Routes and Brokers, to be implemented using multiple underlying suppliers. For example, Knative Eventing applications can deliver events to a broker and then trigger a function based on the received event. If the broker type is not explicitly specified, a testing cluster could use an in-memory option while a staging or production environment might use a cloud-provided Kafka service.
+
+Of particular interest to cluster administrators is that Knative supports customizable _default values_ on the parameters defined in resource YAML files. These configurations reduce the amount of environment configuration tasks developers needs to consider.
+
+## Knative installations
+
+See the [Installation roadmap](../install/README.md#installation-roadmap) for prerequisites and installation steps. Your first installation decision is whether to use a YAML-based installation or use the Knative Operator. If you just need to get acquainted with Knative at this time, you can install the quickstart.
+
+## Configuring Knative
+
+Knative uses Kubernetes-style YAML manifests to define and configure system components. These manifests include core resources, custom resource definitions (CRDs), and extensibility features. As with Kubernetes, these configuration resources are declarative and managed using the `kubectl` CLI tool.
+
+### Resource scoping and namespaces
+
+Knative resources are associated with namespaces. Knative adheres to the Kubernetes model of namespace-based isolation, enabling you to control the following:
+
+- Development teams and resources by assigning developers to teams defined by namespaces.
+- The capabilities applications have by referencing a namespace.
+- Exclude webhooks from using a namespace, useful for apps in development.
+
+Namespaces can also isolate boundaries for tooling such as logs, metrics, tracing, CI/CD integrations, and dashboards. The extent of this isolation depends on both the enforcement strategy and how consistently teams adhere to namespace boundaries.
+
+You can optimize and enforce isolation involving namespaces using standard Kubernetes mechanisms, including:
+
+- Role-Based Access Control (RBAC)
+- Resource quotas
+- Network and security policies
+
+### Configuring Knative components
+
+Knative configurations are performed by the following methods:
+
+- Editing YAML manifests
+
+    Modify resource definitions directly, including labels, annotations, and field values. You can use Kubernetes features such as [OPA](https://kubernetes.io/blog/2019/08/06/opa-gatekeeper-policy-and-governance-for-kubernetes/) and [Kyverno](https://kyverno.io) to enforce specific values for fields on a resource type, or use ConfigMaps in plugin installation to set values at the cluster level through Knative.
+
+- Using ConfigMaps
+
+    Store and manage configuration data as key-value pairs. ConfigMaps are frequently used to tune platform-wide behavior. Most of the Knative ConfigMaps are in the `knative-serving` or `knative-eventing` namespace, and apply their settings to all the relevant Knative components in all namespaces.
+
+- Applying resources with `kubectl`
+
+    Apply updated YAML manifests, as opposed to ConfigMaps, to the cluster using standard Kubernetes workflows.
+
+- Using the Knative Operator
+
+    Some platform-wide settings can be managed declaratively using the Knative Operator.
+
+### Configuration tasks
+
+Knative documentation provides the following configuration procedures. This list is subject subject to change.
+
+Configurations for default settings:
+
+- [Broker defaults](../eventing/configuration/broker-configuration.md)
+- [ConfigMap defaults](../serving/configuration/config-defaults.md)
+- [Event source defaults](../eventing/configuration/sources-configuration.md)
+- [Channel defaults](../eventing/configuration/channel-configuration.md)
+- [Kafka channel defaults](../eventing/configuration/kafka-channel-configuration.md)
+- [Domain names](../serving/using-a-custom-domain.md)
+- [Ingress gateway replacement](../serving/setting-up-custom-ingress-gateway.md)
+
+Configurations for new development:
+
+- [Deployment resources](../serving/configuration/deployment.md)
+- [Istio access to deployed services](../serving/istio-authorization.md)
+- [Namespace exclusion from webhooks](../serving/istio-authorization.md)
+
+Configurations for maintenance:
+
+- [Garbage collection](../serving/revisions/revision-admin-config-options.md)
+- [High availability](../serving/config-ha.md)
+- [Rollout duration for revisions](../serving/configuration/rolling-out-latest-revision-configmap.md)
+- [Autoscaling of Kafka features](../eventing/configuration/keda-configuration.md)
+
+Configurations for security encryptions:
+
+- [cert-manager](../serving/encryption/configure-certmanager-integration.md)
+- [External domains](../serving/encryption/external-domain-tls.md)
+- [Local domains](../serving/encryption/cluster-local-domain-tls.md)
+- [system-internal](../serving/encryption/system-internal-tls.md)
+
+Configurations for extensions:
+
+- [Kafka Broker features](../serving/encryption/system-internal-tls.md)
+- [Sugar Controller](../eventing/configuration/sugar-configuration.md)
+
+Configurations for flagging features:
+
+- [Serving features](../serving/configuration/feature-flags.md)
+- [Eventing features](../eventing/features/README.md)
+
+## Authorizations
+
+You can grant developers access to additional resources related to their namespace in other services, such as observability, logs, metrics, tracing, and dashboards.
+
+## Upgrades
+
+More often than not, you will be performing upgrades to your cluster's infrastructure and apps and services. Knative is designed and tested for continuous operation during upgrades and rollbacks, allowing you to:
+
+- Upgrade or revert a Knative cluster while it is serving traffic, rather than needing a maintenance window.
+- Downgrade. Downgrades work provided that no applications have used the new features since the upgrade.

docs/versioned/install/README.md

@@ -8,58 +8,130 @@ function: reference
 
 # Installing Knative
 
-There are three installation methods to install Knative:
+This page provides guidance for Kubernetes administrators on how to install Knative on an existing Kubernetes cluster. Knative has three components: Eventing, Serving, and Functions and the CLI client tools `kn` and `func`. Serving and Eventing are installed into clusters. Functions is not installed into clusters given that the client `func` CLI tool builds and deploys stateless functions as standard containers.
 
-- A quickstart experience on a local computer only by using a preconfigured extension.
-- A YAML installation suitable for production use.
-- A Knative Operator installation suitable for production use.
+A Knative installation assumes you are familiar with the following:
 
-A Knative installation is composed of the Serving and Eventing components. The quickstart implements both. The YAML and Knative Operator installations provide options to install either or both.
+- Kubernetes and Kubernetes administration.
+- The `kubectl` CLI tool. You can use existing Kubernetes management tools (policy, quota, etc) to manage Knative workloads.
+- Using `cluster-admin` permissions or equivalent 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 is recommended with Cloud Native Computing Foundation (CNCF) projects such as [Prometheus](https://kubernetes.io/docs/concepts/cluster-administration/system-metrics/), [Istio](https://istio.io), and [Strimzi](https://strimzi.io), many of which can be used alongside Knative.
 
-Supported platforms are Linux, MacOS, and Windows.
+You can install the Serving and Eventing components independently of one another. You can also add and remove plugins at any time, as well as optional integration tools that span observability, security, and testing. Recommended tools include open source Prometheus, and [Jaeger](https://www.cncf.io/projects/jaeger/) for observability, and cert-manager for access authentication. Backstage tools are available to help you monitor and manage resources, as well as tools for vendor management.
 
 ## Installation roadmap
 
-Use the following table to evaluate your installation method.
+Use the following table to determine your installation method. If you just want to get an understanding of Knative functionality at this time, install the quickstart.
 
-|  | Quickstart | YAML | Knative Operator |
+|  | Quickstart | YAML-based | Knative Operator |
 | --- | --- | --- | --- |
 | Purpose  | local   | production     | production  |
-| Kubernetes | local deployment of kind or Minikube | existing deployment | existing deployment  |
-| Hardware | 3 CPU, 3 GB RAM | One node: 6 CPUs, 6 GB memory, 30 GB disk storage.<br>Multiple nodes: 2 CPUs each, 4 GB memory, 20 GB disk storage.   | same as YAML |
+| Kubernetes deployment | local, either `kind` or `Minikube` | existing  | existing  |
+| Hardware | 3 CPU, 3 GB RAM | One node:<br>6 CPUs, 6 GB memory, 30 GB disk storage.<br>Multiple nodes:<br>2 CPUs each, 4 GB memory, 20 GB disk storage.   | same as YAML-based |
+
+Supported platforms are Linux, MacOS, and Windows.
 
-Use the following steps to install Knative depending on your installation method.
+For more information about YAML-based and installations with the Knative Operator, see [YAML and Knative Operator installations compared](#yaml-and-knative-operator-installations-compared).
+
+Use the following steps to install Knative depending on your installation method:
 
 **Quickstart**:
 
   1. Install the [CLI Tools](../client/install-kn.md).
   1. Install the [Knative Quickstart plugin](../getting-started/quickstart-install.md).
 
-**YAML**:
+**YAML-based**:
+
+Install using all YAML files. This option is the most useful if you're using GitOps tools such as [Flux](https://fluxcd.io) or [ArgoCD](https://argo-cd.readthedocs.io/en/stable/) 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.
 
   1. Install the [CLI Tools](../client/install-kn.md).
   1. Install either or both:
-       - Install [Knative Serving](yaml-install/serving/install-serving-with-yaml.md).
-       - Install [Knative Eventing](yaml-install/eventing/install-eventing-with-yaml.md).
+       - Install [Knative Serving](../install/yaml-install/serving/install-serving-with-yaml.md).
+       - Install [Knative Eventing](../install/yaml-install/eventing/install-eventing-with-yaml.md).
 
-**Operator**:
+**Knative Operator**:
+
+Install using the Knative Operator as installed with manifests or [Helm](https://helm.sh), or install using the Knative Operator as installed with the Knative Operator CLI plugin.
 
   1. Install the [CLI Tools](../client/install-kn.md) including the Knative Operator CLI plugin.
   1. Install using the Knative Operator, and with it the Serving and Eventing components, by either of the following:
-       - The [Knative Operator](./operator/knative-with-operators.md) using K8S Manifests or via Helm.
-       - The [Knative Operator CLI](./operator/knative-with-operator-cli.md).
+       - The [Knative Operator](../install/operator/knative-with-operators.md) using Kubernetes manifests or by using Helm.
+       - The [Knative Operator CLI](../install/operator/knative-with-operator-cli.md).
+
+All installations require a supported Kubernetes version. System requirements provided are recommendations only. The requirements for your installation may vary depending on whether you use optional components, such as a networking layer.
+
+For a list of commercial Knative products, see [Knative offerings](../install/knative-offerings.md).
+
+## YAML and Knative Operator installations compared
+
+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, patching, and customizing the content. 
+
+The Knative Operator alleviates installation complexities and is compatible with a GitOps approach. It also gives you a separation of the core Knative application definition and the ConfigMap and other changes you make. You install the Knative Operator either by using the Knative CLI Operator Plugin or by using Kubernetes Manifests or by Helm.
+
+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.| Manage custom resources using command-line tools or manifests. |
+
+## Extensibility plugins
+
+Knative utilizes the existing infrastructure installed on your cluster and provides a developer-facing interface between similar components. The Serving and Eventing components 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 such as Kafka and RabbitMQ.
+
+Knative supports installing additional plugins after the initial installation, 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.
+
+### Networking plugins
+
+If you don't have an ingress that meets the requirements, Knative provides Kourier from [Kore Technologies](https://github.com/knative-extensions/net-kourier), a default lightweight HTTP routing implementation. Plugins include:
+
+- Istio
+
+    Service mesh from [Istio](https://istio.io). See [Installing Istio for Knative](../install/installing-istio.md).
+
+- Contour
+
+    General-purpose ingress with a goal of enabling multi-team delegation. See [Contour](https://projectcontour.io/).
+
+- Gateway API
+
+    The Kubernetes [Gateway API](https://kubernetes.io/docs/concepts/services-networking/gateway/) (beta).
+
+### Messaging plugins
+
+Knative has default lightweight in-memory messaging implementation if you don't already have a solution.
+
+- Kafka
+
+    Distributed event streaming platform from [Apache Kafka](https://kafka.apache.org). In-order, high-thoughput but moderate complexity. See [Install Kafka for Knative](../install/eventing/kafka-install.md).
+
+- RabbitMQ
+
+    A messaging and streaming broker from [RabbitMQ](https://www.rabbitmq.com). In-order, moderate throughput and complexity. See [Install RabbitMQ for Knative](../install/eventing/rabbitmq-install.md)
+
+- NATS
+
+    An event streaming platform from [NATS](https://nats.io). Low complexity.
+
+## Integration plugins
+
+These plugins facilitate Knative operations.
+
+- cert-manager
 
-All installations require a supported Kubernetes version.
+    For requesting TLS certificates in secure HTTPS connections, see [Install cert-manager](../install/installing-cert-manager.md).
 
-System requirements provided are recommendations only. The requirements for your installation  may vary depending on whether you use optional components, such as a networking layer.
+- Backstage
 
-For a list of commercial Knative products, see [Knative offerings](knative-offerings.md).
+    Plugins for handling Knative backends. See [Installing backstage plugins](../install/installing-backstage-plugins.md).
 
 ## Installation resources
 
 Use the following links to maintain your installations.
 
-- [Upgrading Knative](upgrade/README.md)
-- [Uninstall Knative](uninstall.md)
-- [Check Knative version](upgrade/check-install-version.md)
-- [Troubleshoot Knative installations](troubleshooting.md)
+- [Upgrading Knative](../install/upgrade/README.md)
+- [Uninstall Knative](../install/uninstall.md)
+- [Check Knative version](../install/upgrade/check-install-version.md)
+- [Troubleshoot Knative installations](../install/troubleshooting.md)