diff --git a/docs/versioned/.nav.yml b/docs/versioned/.nav.yml index 4088a923bc..75968b917d 100644 --- a/docs/versioned/.nav.yml +++ b/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 diff --git a/docs/versioned/admin/admin-overview.md b/docs/versioned/admin/admin-overview.md new file mode 100644 index 0000000000..16f9f94133 --- /dev/null +++ b/docs/versioned/admin/admin-overview.md @@ -0,0 +1,108 @@ +--- +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 integrate with existing infrastructure in the cluster, enabling Knative resources such as Routes and Brokers to be implemented using one of multiple underlying suppliers. For example, a Knative Eventing app can deliver events to a Broker that triggers a function based on the received event. In a testing cluster, the delivery might 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. The Knative Operator is a custom controller that extends the Kubernetes API to install Knative components. If you just need to get acquainted with Knative at this time, you can install the [quickstart](../getting-started/quickstart-install.md). + +## Configuring Knative + +Knative uses Kubernetes 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 can be managed using the `kubectl` CLI tool or with continuous delivery tools. + +### Resource scoping and namespaces + +Knative resources are namespaced. Knative adheres to the Kubernetes model of namespace-based isolation that lets you manage development teams and resources by assigning them to namespaces. + +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)](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) +- [Resource Quotas](https://kubernetes.io/docs/concepts/policy/resource-quotas/) +- [Network Policies](https://kubernetes.io/docs/concepts/services-networking/network-policies/) +- [Pod Security Standards](https://kubernetes.io/docs/concepts/security/pod-security-standards/) + +### 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 on a resource type, or use ConfigMaps in plugin installations to set values at the cluster level. + +- 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` and `knative-eventing` namespaces. Their settings apply to all the relevant Knative components in all namespaces. + +- 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 + +Administrators are generally responsible for performing upgrades cluster infrastructure and apps and services. Knative is designed and tested for continuous operation during upgrades and rollbacks, allowing you to: + +- Upgrade or revert the Knative components while it is serving traffic, rather than needing a maintenance window. +- Downgrade one Knative version. Downgrades work provided that no applications have used new features since the last upgrade. diff --git a/docs/versioned/administer/README.md b/docs/versioned/administer/README.md deleted file mode 100644 index 2fa2838d2b..0000000000 --- a/docs/versioned/administer/README.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -audience: administrator -components: - - eventing - - serving -function: concept ---- - -# Administration Overview - -The Knative [Serving](../serving/) and [Eventing](../ eventing/) components extend Kubernetes clusters to provide consistent serverless compute and event-delivery interfaces for developers. (Knative [Functions](../functions/) provides primarily client-side tools for more easily building containers.) This means that Serving and Eventing need to be installed on a Kubernetes cluster, and they extend the Kubernetes API using [Custom Resources Definitions](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/). - -Knative aims to integrate with Kubernetes, so existing tools for managing Kubernetes such as RBAC, quota, admission control, and monitoring should "just work". By using a plug-in model for underlying HTTP and event routing functionality, Knative aims to integrate with existing battle-tested software you may already have installed on your cluster, such as Istio, Contour, Kafka, NATS or RabbitMQ. Knative also provides lightweight implementations for these functions if you are looking to avoid pulling in large, complex systems. \ No newline at end of file diff --git a/docs/versioned/install/README.md b/docs/versioned/install/README.md index 16221dcf65..7653d940f5 100644 --- a/docs/versioned/install/README.md +++ b/docs/versioned/install/README.md @@ -8,58 +8,132 @@ 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. 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. Plugins are described in the [Extensibility](#extensibility) section. ## 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.
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:
6 CPUs, 6 GB memory, 30 GB disk storage.
Multiple nodes:
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. +The Knative Operator is a custom controller that extends the Kubernetes API to install Knative components. 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: + 1. Install either or both components: - Install [Knative Serving](yaml-install/serving/install-serving-with-yaml.md). - Install [Knative Eventing](yaml-install/eventing/install-eventing-with-yaml.md). -**Operator**: +**Knative Operator**: + +Install using the Knative Operator as using manifests or [Helm](https://helm.sh), or install using the Knative Operator that is 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). + 1. Install the Serving and Eventing components, by either of the following: + - 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 which plugin components you use. + +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 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 + +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. + +For LLM deployments, consider the [KServe](https://kserve.github.io) platform. KServe is a Kubernetes-native model serving platform built on Knative Serving designed for production LLM deployments. + +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 [net-kourier](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)