Admin overview doc #6412
Admin overview doc #6412
Conversation
Craft an Amin Overview and finish up high-level remaining tasks for install docs.
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: iRaindrop The full list of commands accepted by this bot can be found here.
Needs approval from an approver in each of these files:
Approvers can indicate their approval by writing |
knative-prow
bot
added
the
size/S
knative-prow
bot
added
the
do-not-merge/work-in-progress
✅ Deploy Preview for knative ready!Built without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify project configuration. |
Spelling fix!
Wrote up admin tasks and interests by categories
knative-prow
bot
added
size/M
Changed H1 to include "Knative"
Link testing and de-emphasizing tables
Link fixes
indented bullets test
Settling on combo or paras with lins and minimal bulleted lists
Worked on Configurations section
Worked on the Monitoring and Observability section
knative-prow
bot
added
size/L
Finished initial write-up for each section
Added blog links (as a test)
There was a problem hiding this comment.
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
knandfunc. 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, thekubectlcommand, 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-adminpermissions, 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.
Processed most reviewer edits
Added "YAML and CLI installations compared" section
Updated Installation section
Installation, CRD, and ConfigMap guidance
Updates and restructuring sections into Administrative tasks table.
link fixes
Table fix
Table tweaks
Minor edits to rebuild
Minor edit
Misc edits
| --- | ||
| # Overview | ||
|
|
||
| This page provides guidance for administrators on how to install and manage Knative on an existing Kubernetes cluster, and assumes you have familiarity the following: |
There was a problem hiding this comment.
| This page provides guidance for administrators on how to install and manage Knative on an existing Kubernetes cluster, and assumes you have familiarity the following: | |
| 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: |
| This page provides guidance for administrators on how to install and manage Knative on an existing Kubernetes cluster, and assumes you have familiarity the following: | ||
|
|
||
| - Kubernetes and Kubernetes administration. | ||
| - The `kubectl`CLI tool. You can use existing Kubernetes management tools (policy, quota, etc) to manage Knative workloads. |
There was a problem hiding this comment.
| - The `kubectl`CLI tool. You can use existing Kubernetes management tools (policy, quota, etc) to manage Knative workloads. | |
| - The `kubectl` CLI tool. You can use existing Kubernetes management tools (policy, quota, etc) to manage Knative workloads. |
|
|
||
| - Kubernetes and Kubernetes administration. | ||
| - The `kubectl`CLI tool. You can use existing Kubernetes management tools (policy, quota, etc) to manage Knative workloads. | ||
| - The Cloud Native Computing Foundation (CNCF) for which Knative is one of its projects, along with Kubernetes, Prometheus, and Istio. |
There was a problem hiding this comment.
| - The Cloud Native Computing Foundation (CNCF) for which Knative is one of its projects, along with Kubernetes, Prometheus, and Istio. | |
| - The Cloud Native Computing Foundation (CNCF) an advocacy and support organization for open-source cloud software projects including Knative, Kubernetes, Prometheus, and Istio. |
Why does the user need to be familiar with CNCF? Does that affect the administration tasks in any way? If not, I'd remove this requirement. CNCF ownership of Knative should be discussed elsewhere, for example in governance, support, and communications.
If this does need to be included here, add a link to the CNCF website and/or to the CNCF project pages for these projects.
| - The `kubectl`CLI tool. You can use existing Kubernetes management tools (policy, quota, etc) to manage Knative workloads. | ||
| - The Cloud Native Computing Foundation (CNCF) for which Knative is one of its projects, along with Kubernetes, Prometheus, and Istio. | ||
|
|
||
| Additionally, you should have cluster-admin permissions or equivalent to to install software and manage resources in all clusters in the namespace. |
There was a problem hiding this comment.
Why "additionally"? Just list this as one of the requirement bullet items.
| - Serving: Pods and pluggable network ingress routes. | ||
| - Eventing: Pods and pluggable message transports (e.g. Kafka, RabbitMQ) |
|
|
||
| ## Administration tasks | ||
|
|
||
| The following table lists configurations, extensibility, conversions, and other actions for Knative Administrators organized by technical area. Tasks are linked to procedures and other guidance. |
There was a problem hiding this comment.
| The following table lists configurations, extensibility, conversions, and other actions for Knative Administrators organized by technical area. Tasks are linked to procedures and other guidance. | |
| The following table lists configurations, extensibility, conversions, and other actions for Knative Administrators organized by functional area. Tasks are linked to procedures. |
|
|
||
| Several of the tasks use the ConfigMaps object to store new data or update existing resources. ConfigMaps are namespace-scoped, meaning they are available to all Pods within the same namespace. To create a ConfigMap, use the `kubectl create configmap` command. To modify a ConfigMap use the `kubectl apply` command with the supplied YAML manifest. | ||
|
|
||
| Do not remove or modify the `_example` data entries in ConfigMaps. Doing so will cause a system warning. |
There was a problem hiding this comment.
| Do not remove or modify the `_example` data entries in ConfigMaps. Doing so will cause a system warning. | |
| Do not remove or modify the `_example` data entries in ConfigMaps. Doing so causes a system warning. |
|
|
||
| Do not remove or modify the `_example` data entries in ConfigMaps. Doing so will cause a system warning. | ||
|
|
||
| | Area | Task | Description | |
There was a problem hiding this comment.
| | Area | Task | Description | | |
| | Function | Task | Description | |
|
|
||
| | Area | Task | Description | | ||
| | --- | --- | --- | | ||
| | Access control | [cert-manager integration](/serving/encryption/configure-certmanager-integration.md) | Enable cert-manager for automated certificate provisioning. | |
There was a problem hiding this comment.
Spanning rows so that the function column entries each encompass all of their tasks would make the table look nicer. If it's not possible or worth the trouble in Markdown, this is acceptable.
| | | [Ingress gateway](/serving/setting-up-custom-ingress-gateway.md) | Shows how to replace the default gateway for incoming traffic. | | ||
| | | [Webhook bypass on system namespaces](/serving/webhook-customizations.md) | Disable the Knative webhook on system namespaces to avoid issues during upgrades. | | ||
| | Observability | [Metrics](/eventing/observability/metrics/eventing-metrics.md) | Monitor metrics exposed by each Eventing component. | | ||
| | Observability | [Metrics](/serving/observability/metrics/serving-metrics.md) | Monitor metrics exposed by each Serving component. | |
There was a problem hiding this comment.
| | Observability | [Metrics](/serving/observability/metrics/serving-metrics.md) | Monitor metrics exposed by each Serving component. | | |
| | | [Metrics](/serving/observability/metrics/serving-metrics.md) | Monitor metrics exposed by each Serving component. | |
| --- | ||
| # Overview | ||
|
|
||
| This page provides guidance for administrators on how to install and manage Knative on an existing Kubernetes cluster, and assumes you have familiarity the following: |
There was a problem hiding this comment.
| This page provides guidance for administrators on how to install and manage Knative on an existing Kubernetes cluster, and assumes you have familiarity the following: | |
| This page provides guidance for administrators on how to install and manage Knative on an existing Kubernetes cluster, and assumes you have familiarity with the following: |
|
|
||
| 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. It has two main underlying components that support plugging in multiple underlying transports within the same cluster: |
There was a problem hiding this comment.
I would move the "Knative aims to extend Kubernetes... where feasible" sentence up into the first paragraph.
|
|
||
| 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. It has two main underlying components that support plugging in multiple underlying transports within the same cluster: |
There was a problem hiding this comment.
Knative has three main components (as we say in the developer-facing overview). Only two require installation on the cluster, though. I'd mention functions as a third component, and then detail that it does not need cluster installation. That way, people reading both docs won't be confused about the state of functions.
| - The `kubectl`CLI tool. You can use existing Kubernetes management tools (policy, quota, etc) to manage Knative workloads. | ||
| - The Cloud Native Computing Foundation (CNCF) for which Knative is one of its projects, along with Kubernetes, Prometheus, and Istio. | ||
|
|
||
| Additionally, you should have cluster-admin permissions or equivalent to to install software and manage resources in all clusters in the namespace. |
There was a problem hiding this comment.
| Additionally, you should have cluster-admin permissions or equivalent to to install software and manage resources in all clusters in the namespace. | |
| Additionally, you should have cluster-admin permissions or equivalent to to install software and manage resources in all clusters in the namespace. |
(Link cluster-admin to kubernetes documentation, along with the other items like the Kubectl tool.)
|
|
||
| - Kubernetes and Kubernetes administration. | ||
| - The `kubectl`CLI tool. You can use existing Kubernetes management tools (policy, quota, etc) to manage Knative workloads. | ||
| - The Cloud Native Computing Foundation (CNCF) for which Knative is one of its projects, along with Kubernetes, Prometheus, and Istio. |
There was a problem hiding this comment.
| - The Cloud Native Computing Foundation (CNCF) for which Knative is one of its projects, along with Kubernetes, Prometheus, and Istio. | |
| - Cloud Native Computing Foundation (CNCF) projects (for example: Prometheus, Istio and Strimzi), many of which can be used alongside Knative. |
You already mention Kubernetes above, so it's odd to include it here again. We might (or might not) want to link to the CNCF landscape -- it can be somewhat overwhelming to pick through for a newcomer.
|
|
||
| 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). | ||
|
|
||
| You customize resources using `kubectl` using the Knative Operator using `kn`. See [Knative Serving CRDs](/install/operator/configuring-serving-cr.md) and [Knative Eventing CRDs](/install/operator/configuring-eventing-cr.md). |
There was a problem hiding this comment.
This sentence is weird, because it talks about both kubectl and kn, but it's not clear which tool is doing what.
| The following table lists the names of CRDs (metadata name) for the Serving and Eventing components. They are defined by `eventing-crds.yaml` and `serving-crds.yaml` in the [Knative Eventing installation files](/install/yaml-install/eventing/eventing-installation-files.md) and [Knative Serving installation Files](/install/yaml-install/serving/serving-installation-files.md), respectively. | ||
|
|
||
| | Eventing CRDs | Serving CRDs | | ||
| | --- | --- | | ||
| | brokers.eventing.knative.dev<br>channels.messaging.knative.dev<br>eventpolicies.eventing.knative.dev<br>eventtransforms.eventing.knative.dev<br>eventtypes.eventing.knative.dev<br>integrationsinks.sinks.knative.dev<br>jobsinks.sinks.knative.dev<br>parallels.flows.knative.dev<br>requestreplies.eventing.knative.dev<br>sequences.flows.knative.dev<br>subscriptions.messaging.knative.dev<br>triggers.eventing.knative.dev | certificates.networking.internal.knative.dev<br>configurations.serving.knative.dev<br>clusterdomainclaims.networking.internal.knative.dev<br>domainmappings.serving.knative.dev<br>ingresses.networking.internal.knative.dev<br>metrics.autoscaling.internal.knative.dev<br>podautoscalers.autoscaling.internal.knative.dev<br>revisions.serving.knative.dev<br>routes.serving.knative.dev<br>serverlessservices.networking.internal.knative.dev<br>services.serving.knative.dev<br>images.caching.internal.knative.dev | |
There was a problem hiding this comment.
Folks can get these from a live cluster using kubectl api-resources, which is probably a better way to do so if needed. I'm not sure this table adds much, so I'd probably remove it, again.
|
|
||
| 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 |
There was a problem hiding this comment.
It's not clear to me if this is supposed to be "Configuring Knative" or something else. If it is "Configuring Knative", I'd suggest an intro like the following (this one is kinda bad, and needs a rewrite, but getting notes out quickly):
A Knative installation consists of several custom resources in the
knative.devAPI namespace, and controllers running on the cluster which manage those custom resources. During installation and while operating the cluster, you may need to customize the behavior of the controller. Knative controllers read their configuration from ConfigMaps in the cluster, and can generally respond to changes in the ConfigMaps live, without needing a reload. In some cases, it may be necessary to restart the controller after updating a ConfigMap; this should be well-documented by the documentation in the ConfigMap.Knative installs ConfigMaps for each tracked configuration file, along with validation of the values in the configuration. The ConfigMaps installed by Knative leave all the controller settings at their default values, but include an
_examplekey which documents all the known keys and their operation as an entry within the ConfigMap. Note that if you perform an upgrade of a YAML installation, this will include new ConfigMaps which may overwrite your existing settings unless you preserve them.Knative uses this configuration pattern (existing ConfigMaps with empty defaults and an
_examplekey) to balance several different needs:
- Deploying all the ConfigMaps to the cluster during the installation makes it easy for new administrators to find the relevant ConfigMaps
- Not setting configuration keys in the ConfigMaps by default makes it easy for clusters to pick up new behavior and features during upgrade unless the feature is specifically intended to be held back.
- The
_examplekey allows the documentation of the configuration keys to be persisted on the Kubernetes apiserver, rather being lost (as YAML comments are) when applying the configuration to the server.- There is a webhook which will error if the
_examplekey content is changed -- we have found that people often edit the example text, rather than setting a configuration key.
It may be worth providing an right/wrong example here:
kind: ConfigMap
apiGroup: v1
metadata:
name: config-example
data:
_example: |
# sample-key can be "enabled" or "disabled"
sample-key: enabledRight:
kind: ConfigMap
apiGroup: v1
metadata:
name: config-example
data:
_example: |
# sample-key can be "enabled" or "disabled"
sample-key: enabled
sample-key: disabledwrong:
kind: ConfigMap
apiGroup: v1
metadata:
name: config-example
data:
_example: |
# sample-key can be "enabled" or "disabled"
sample-key: disabledYou'll get a warning when trying to save the second one. I don't know where you want to put that, but it's probably worth documenting somewhere on this page.
| You can also install these plugins service to extend Knative capabilities for service meshes: | ||
|
|
||
| - [Istio for Knative](/install/installing-istio.md) - Extends Kubernetes with a programmable, application-aware network. | ||
| - [Knative Backstage plugin](/install/installing-backstage-plugins.md) - An Event Mesh that allows you to view and manage Knative Eventing resources. | ||
| - [cert-manager](/install/installing-cert-manager.md) - Provision and manage TLS certificates in Kubernetes. |
There was a problem hiding this comment.
It's weird to highlight these particular plugins. It feels like it would be worth a diagram here explaining the pluggable components (the duck analogy I gave earlier, for example), and then giving some examples of the different ways things can plug in. These three have three different plugin modes, so it's not totally obvious which are special cases:
Networking plugins
Used by Serving to route incoming traffic. Main 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)
Optional plugins (can add or not, but they aren't fungible with each other)
- Cert-manager provides TLS certificate provisioning. This is needed (and not swappable) if you want to secure ingress traffic.
- Backstage provides a UI for developers
- Prometheus provides metrics observability
- Jaeger provides tracing observability
|
|
||
| ## Administration tasks | ||
|
|
||
| The following table lists configurations, extensibility, conversions, and other actions for Knative Administrators organized by technical area. Tasks are linked to procedures and other guidance. |
There was a problem hiding this comment.
We should just move these pages into the nav for administration, rather than building a big map in the file. (This also makes the navigation easier, rather than needing to go back and forward, and may help with reorganizing things to be more logically grouped to administrators.)
Processed reviwer edits
Write an Aministration Overview and finish up high-level remaining tasks for install docs.
Proposed Changes