Create admin guide

docs/admin/_index.md

@@ -0,0 +1,14 @@
+---
+title: "Administration guide"
+weight: 10
+type: "docs"
+showlandingtoc: "true"
+---
+
+There are two core Knative components that can be installed and used together or independently to provide different functions:
+
+* [Knative Serving](../serving/): Easily manage stateless services on Kubernetes by reducing the developer effort required for autoscaling, networking, and rollouts.
+
+* [Knative Eventing](../eventing/): Easily route events between on-cluster and off-cluster components by exposing event routing as configuration rather than embedded in code.
+
+These components are delivered as Kubernetes custom resource definitions (CRDs), which can be configured by a cluster administrator to provide default settings for developer-created applications and event workflow components.

docs/serving/config-ha.md → docs/admin/config-ha.md

@@ -1,7 +1,9 @@
 ---
-title: "Configuring high-availability components"
+title: "High-availability"
 weight: 50
 type: "docs"
+aliases:
+  - /docs/serving/config-ha
 ---
 
 Active/passive high availability (HA) is a standard feature of Kubernetes APIs that helps to ensure that APIs stay operational if a disruption occurs. In an HA deployment, if an active controller crashes or is deleted, another controller is available to take over processing of the APIs that were being serviced by the controller that is now unavailable.
@@ -19,8 +21,8 @@ For components leveraging leader election to achieve HA, this capability can be
 
 With the exception of the `activator` component you can scale up any deployment running in `knative-serving` (or `kourier-system`) with a command like:
 
-```
-$ kubectl -n knative-serving scale deployment <deployment-name> --replicas=2
+```shell
+kubectl -n knative-serving scale deployment <deployment-name> --replicas=2
 ```
 
 - Setting `--replicas` to a value of `2` enables HA.
@@ -33,13 +35,13 @@ $ kubectl -n knative-serving scale deployment <deployment-name> --replicas=2
 
 The scale of the `activator` component is governed by the Kubernetes HPA component. You can see the current HPA scale limits and the current scale by running:
 
-```
-$ kubectl get hpa activator -n knative-serving
+```shell
+kubectl get hpa activator -n knative-serving
 ```
 
 The possible output will be something like:
 
-```
+```shell
 NAME        REFERENCE              TARGETS   MINPODS   MAXPODS   REPLICAS   AGE
 activator   Deployment/activator   2%/100%   5         15        11         346d
 ```

docs/install/_index.md → docs/admin/install/_index.md

@@ -18,6 +18,7 @@ aliases:
   - /docs/install/knative-with-minishift
   - /docs/install/knative-with-pks
   - /docs/install/any-kubernetes-cluster
+  - /docs/install/
 showlandingtoc: "false"
 ---
 

docs/install/check-install-version.md → docs/admin/install/check-install-version.md

@@ -3,6 +3,8 @@ title: "Checking the version of your Knative components"
 linkTitle: "Checking your install version"
 weight: 20
 type: "docs"
+aliases:
+  - /docs/install/check-install-version
 ---
 
 To obtain the version of the Knative component that you have running on your cluster, you query for the

docs/install/install-eventing-with-yaml.md → docs/admin/install/install-eventing-with-yaml.md

@@ -4,6 +4,8 @@ linkTitle: "Install Eventing using YAML"
 weight: 03
 type: "docs"
 showlandingtoc: "false"
+aliases:
+  - /docs/install/install-eventing-with-yaml
 ---
 
 This topic describes how to install Knative Eventing by applying YAML files using the `kubectl` CLI.

docs/install/install-extensions.md → docs/admin/install/install-extensions.md

@@ -1,9 +1,10 @@
 ---
 title: "Installing optional extensions"
-linkTitle: "Install optional extensions"
 weight: 04
 type: "docs"
 showlandingtoc: "false"
+aliases:
+  - /docs/install/install-extensions
 ---
 
 To add extra features to your Knative Serving or Eventing installation, you can install extensions

docs/install/install-serving-with-yaml.md → docs/admin/install/install-serving-with-yaml.md

@@ -4,6 +4,8 @@ linkTitle: "Install Serving using YAML"
 weight: 02
 type: "docs"
 showlandingtoc: "false"
+aliases:
+  - /docs/install/install-serving-with-yaml
 ---
 
 This topic describes how to install Knative Serving by applying YAML files using the `kubectl` CLI.

docs/install/installation-files.md → docs/admin/install/installation-files.md

@@ -2,6 +2,8 @@
 title: "Installation files"
 weight: 20
 type: "docs"
+aliases:
+  - /docs/install/installation-files
 ---
 
 This guide provides reference information about the YAML files in the Knative

docs/install/installing-istio.md → docs/admin/install/installing-istio.md

@@ -2,8 +2,11 @@
 title: "Installing Istio for Knative"
 weight: 15
 type: "docs"
+aliases:
+  - /docs/install/installing-istio
 ---
 
+<!-- TODO: add documentation on how to reuse an existing Istio installation. See comment https://github.com/knative/docs/pull/3526/files#r626716547 -->
 This guide walks you through manually installing and customizing Istio for use
 with Knative.
 

docs/install/knative-with-operators.md → docs/admin/install/knative-with-operators.md

@@ -3,6 +3,8 @@ title: "Knative Operator installation"
 weight: 05
 type: "docs"
 showlandingtoc: "false"
+aliases:
+  - /docs/install/knative-with-operators
 ---
 
 Knative provides a [Kubernetes Operator](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/) to install, configure and manage Knative.

docs/install/operator/configuring-eventing-cr.md → docs/admin/install/operator/configuring-eventing-cr.md

@@ -3,7 +3,8 @@ title: "Configuring the Eventing Operator custom resource"
 weight: 60
 type: "docs"
 aliases:
-- /docs/operator/configuring-eventing-cr/
+  - /docs/operator/configuring-eventing-cr/
+  - /docs/install/configuring-eventing-cr/
 ---
 
 You can configure the Knative Eventing operator by modifying settings in the KnativeEventing custom resource (CR).
@@ -48,7 +49,7 @@ The `spec.config` in the KnativeEventing CR has one `<name>` entry for each Conf
 
 ### Setting a default channel
 
-If you are using different channel implementations, like the KafkaChannel, or you want a specific configuration of the InMemoryChannel to be the default configuration, you can change the default behavior by updating the `default-ch-webhook` ConfigMap. 
+If you are using different channel implementations, like the KafkaChannel, or you want a specific configuration of the InMemoryChannel to be the default configuration, you can change the default behavior by updating the `default-ch-webhook` ConfigMap.
 
 You can do this by modifying the KnativeEventing CR:
 
@@ -83,7 +84,7 @@ spec:
 
 ### Setting the default channel for the broker
 
-If you are using a channel-based broker, you can change the default channel type for the broker from InMemoryChannel to KafkaChannel, by updating the `config-br-default-channel` ConfigMap. 
+If you are using a channel-based broker, you can change the default channel type for the broker from InMemoryChannel to KafkaChannel, by updating the `config-br-default-channel` ConfigMap.
 
 You can do this by modifying the KnativeEventing CR:
 

docs/install/operator/configuring-serving-cr.md → docs/admin/install/operator/configuring-serving-cr.md

@@ -3,7 +3,8 @@ title: "Configuring the Serving Operator Custom Resource"
 weight: 20
 type: "docs"
 aliases:
-- /docs/operator/configuring-serving-cr/
+  - /docs/operator/configuring-serving-cr/
+  - /docs/install/configuring-serving-cr/
 ---
 
 The Knative Serving operator can be configured with these options:

docs/install/prerequisites.md → docs/admin/install/prerequisites.md

@@ -3,6 +3,8 @@ title: "Prerequisites"
 weight: 01
 type: "docs"
 showlandingtoc: "false"
+aliases:
+  - /docs/install/prerequisites
 ---
 
 Before installing Knative, you must meet the following prerequisites:

docs/admin/logs/_index.md

@@ -0,0 +1,176 @@
+---
+title: "Logging"
+weight: 50
+type: "docs"
+aliases:
+  - /docs/install/collecting-logs
+showlandingtoc: "false"
+---
+
+You can use [Fluent Bit](https://docs.fluentbit.io/), a log processor and forwarder, to collect your kubernetes logs in a central directory.
+
+This is not required to run Knative, but can be helpful with [Knative Serving](../serving), which will automatically delete pods and associated logs when they are no longer needed.
+
+Fluent Bit supports exporting to a number of other log providers. If you already have an existing log provider, for example, Splunk, Datadog, ElasticSearch, or Stackdriver, you can follow the [FluentBit documentation](https://docs.fluentbit.io/manual/pipeline/outputs) to configure log forwarders.
+
+Setting up log collection requires two steps:
+
+1. Running a log forwarding DaemonSet on each node.
+2. Running a collector somewhere in the cluster.
+
+In the following example, a StatefulSet is used, which stores logs on a Kubernetes PersistentVolumeClaim, but you can also use a HostPath.
+
+## Setting up the collector
+
+Set up the collector before the forwarders. You will need the address of the collector when configuring the forwarders, and the forwarders may queue logs until the collector is ready.
+
+![System diagram: forwarders and co-located collector and nginx](system.svg)
+
+<!-- yuml.me UML rendering of:
+[Forwarder1]logs->[Collector]
+[Forwarder2]logs->[Collector]
+
+// Add notes
+[Collector]->[shared volume]
+[nginx]-[shared volume]
+-->
+
+The [`fluent-bit-collector.yaml`](./fluent-bit-collector.yaml) defines a
+StatefulSet, as well as a Kubernetes Service which allows accessing and reading
+the logs from within the cluster. The supplied configuration will create the
+monitoring configuration in a namespace called `logging`.
+
+You can apply the configuration by entering the command:
+
+```shell
+kubectl apply --filename https://github.com/knative/docs/raw/main/docs/install/collecting-logs/fluent-bit-collector.yaml
+```
+
+The default configuration will classify logs into:
+
+- Knative apps, or pods with an `app=Knative` label
+- Non-Knative apps
+
+The logs default to logging with the pod name; this can be changed by updating the `log-collector-config` ConfigMap before or after installation. Once the ConfigMap is updated, you must restart Fluent Bit. You can do this by deleting the pod and letting the StatefulSet recreate it.
+
+To access the logs through your web browser, enter the command:
+
+```shell
+kubectl port-forward --namespace logging service/log-collector 8080:80
+```
+
+And then visit http://localhost:8080/.
+
+You can also open a shell in the `nginx` pod and search the logs using unix
+tools, by entering the command:
+
+```shell
+kubectl exec --namespace logging --stdin --tty --container nginx log-collector-0
+```
+
+## Setting up the forwarders
+
+Follow the [Fluent Bit directions for installing on Kubernetes](https://docs.fluentbit.io/manual/installation/kubernetes) documentation to set up a Fluent Bit DaemonSet which forwards logs to ElasticSearch by default.
+
+When the directions call for creating the ConfigMap, you need to replace the ElasticSearch configuration with the [`fluent-bit-configmap.yaml`](./fluent-bit-configmap.yaml), or add the following block to the ConfigMap, and update the
+`@INCLUDE output-elasticsearch.conf` to be `@INCLUDE output-forward.conf`.
+
+```yaml
+output-forward.conf: |
+  [OUTPUT]
+      Name            forward
+      Host            log-collector.logging
+      Port            24224
+      Require_ack_response  True
+```
+
+## Local collector
+
+**NOTE:** This describes a development environment setup, and is not appropriate
+for production.
+
+If you are using a local Kubernetes cluster for development, you can create a `hostPath` PersistentVolume to store the logs on your desktop operating system. This allows you to use your usual desktop tools on the files without needing Kubernetes-specific tools.
+
+The PersistentVolumeClaim will look something like this, but the `hostPath` will
+vary based on your Kubernetes software and host operating system. Some example
+values are documented below.
+
+```yaml
+apiVersion: v1
+kind: PersistentVolume
+metadata:
+  name: shared-logs
+  labels:
+    app: logs-collector
+spec:
+  accessModes:
+    - "ReadWriteOnce"
+  storageClassName: manual
+  claimRef:
+    apiVersion: v1
+    kind: PersistentVolumeClaim
+    name: logs-log-collector-0
+    namespace: logging
+  capacity:
+    storage: 5Gi
+  hostPath:
+    path: <see below>
+```
+
+You must update the StatefulSet `volumeClaimTemplates` to reference the `shared-logs` volume, as shown in the following example:
+
+```yaml
+volumeClaimTemplates:
+  metadata:
+    name: logs
+  spec:
+    accessModes: ["ReadWriteOnce"]
+    volumeName: shared-logs
+```
+
+### Kind
+
+When creating your cluster, you must use a `kind-config.yaml` and specify
+`extraMounts` for each node, as shown in the following example:
+
+```yaml
+apiversion: kind.x-k8s.io/v1alpha4
+kind: Cluster
+nodes:
+  - role: control-plane
+    extraMounts:
+      - hostPath: ./logs
+        containerPath: /shared/logs
+  - role: worker
+    extraMounts:
+      - hostPath: ./logs
+        containerPath: /shared/logs
+```
+
+You can then use `/shared/logs` as the `spec.hostPath.path` in your
+PersistentVolume. Note that the directory path `./logs` is relative to the
+directory that the Kind cluster was created in.
+
+### Docker Desktop
+
+Docker desktop automatically creates some shared mounts between the host and the
+guest operating systems, so you only need to know the path to your home
+directory. The following are some examples for different operating systems:
+
+| Host OS | `hostPath`                               |
+| ------- | ---------------------------------------- |
+| Mac OS  | `/Users/${USER}`                         |
+| Windows | `/run/desktop/mnt/host/c/Users/${USER}/` |
+| Linux   | `/home/${USER}`                          |
+
+### Minikube
+
+Minikube requires an explicit command to [mount a directory](https://minikube.sigs.k8s.io/docs/handbook/mount/) into the virtual machine (VM) running Kubernetes.
+
+The following command mounts the `logs` directory inside the current directory onto `/mnt/logs` in the VM:
+
+```shell
+minikube mount ./logs:/mnt/logs
+```
+
+You must also reference `/mnt/logs` as the `hostPath.path` in the PersistentVolume.

docs/install/collecting-metrics/_index.md → docs/admin/metrics/_index.md

@@ -1,8 +1,10 @@
 ---
-title: "Collecting Metrics with OpenTelemetry"
-linkTitle: "Collecting metrics"
-weight: 50
+title: "Metrics"
+weight: 10
 type: "docs"
+aliases:
+  - /docs/install/collecting-metrics
+showlandingtoc: "false"
 ---
 
 This document describes how to set up the