diff --git a/docs/en/solutions/ecosystem/knative/Knative_Installation_Guide.md b/docs/en/solutions/ecosystem/knative/Knative_Installation_Guide.md new file mode 100644 index 000000000..aaa21963a --- /dev/null +++ b/docs/en/solutions/ecosystem/knative/Knative_Installation_Guide.md @@ -0,0 +1,230 @@ +--- +products: + - Alauda Application Services +kind: + - Solution +ProductsVersion: + - '4.1,4.2,4.3' +id: TBD +--- + + + +# Alauda support for Knative — Installation Guide + +## Overview + +**Alauda support for Knative** is the Alauda Application Services (S2, certified) packaging of the +upstream CNCF Knative Operator, listed on the Alauda Cloud marketplace and installable from the ACP +OperatorHub. + +Knative is a CNCF project that adds serverless building blocks to Kubernetes. It has two components: + +- **Serving** — runs stateless, request-driven workloads with scale-to-zero, revision-based traffic + splitting, and a pluggable ingress layer (Kourier / Istio / Contour). +- **Eventing** — delivers CloudEvents through Brokers, Triggers, Channels, and Sources. + +On Alauda Container Platform (ACP), Knative is delivered as an OLM Operator that you install from the +Marketplace. The Operator manages the lifecycle of `KnativeServing` and `KnativeEventing` custom +resources. This guide describes how to install **Alauda support for Knative** from the ACP Marketplace, bring +up Knative Serving with the Kourier ingress, and validate a serverless `Service` end to end. + +### Supported Versions + + +| Item | Version | +|------|---------| +| ACP | 4.1, 4.2, 4.3 | +| Architectures | amd64 (x86_64), arm64 | +| Alauda support for Knative (bundle) | v1.22.1 | +| Knative Serving / Eventing operands | v1.22.0 | +| Upstream bundle | `quay.io/operatorhubio/knative-operator:v1.22.1` | + + +> **Networking requirement:** this release supports IPv4 and IPv4-primary dual-stack clusters only. +> See [Known Limitations](#known-limitations) for single-stack IPv6. + +## Prerequisites + +- An ACP cluster at one of the supported versions above, and `cluster-admin` access to the target + workload cluster. +- The **Alauda support for Knative** plugin available in your cluster's OperatorHub. If it is not yet uploaded, + an administrator can push it with the `violet` CLI: + ```bash + violet push alauda-support-for-knative..tgz \ + --platform-address="https://" \ + --platform-username="" --platform-password="" \ + --clusters="" + ``` +- `kubectl` configured against the target cluster. +- Cluster networking is IPv4 or IPv4-primary dual-stack (see [Known Limitations](#known-limitations)). + +## Install Alauda support for Knative + +1. In the ACP Console, go to **Administrator > Marketplace > OperatorHub**, select the target cluster, + find **Alauda support for Knative**, and click **Install**. +2. Keep the default channel (`alpha`) and namespace, and confirm the installation. + +### Verify the Operator + +```bash +kubectl -n operators get csv | grep alauda-support-for-knative +kubectl -n operators get deploy knative-operator +``` + +Expected: the CSV `alauda-support-for-knative.v` reaches phase `Succeeded`, and the +`knative-operator` Deployment (the operator's own deployment name, unchanged from upstream) +shows `1/1` ready. + +## Quick Start: Deploy a Serverless Service with Knative Serving + +### 1. Create the KnativeServing instance + +Knative Serving is a cluster singleton. Two ACP-specific rules apply: + +- **It must be created in the `knative-serving` namespace** when using Kourier — the Operator's + kourier-bootstrap ConfigMap hardcodes the xDS address `net-kourier-controller.knative-serving`. +- **You must set `spec.registry.override`** to rewrite the data-plane images to *tag* form. The + Operator's embedded manifest references operands by digest, and the platform image allowlist cannot + rewrite digest references — so on air-gapped clusters the pods would fail to pull. The + `queue-proxy` sidecar comes from `config-deployment` and is set separately. + +```yaml +apiVersion: operator.knative.dev/v1beta1 +kind: KnativeServing +metadata: + name: knative-serving + namespace: knative-serving +spec: + registry: + override: + # factory:auto:install-images BEGIN (operand tag == operator's embedded serving version) + activator: gcr.io/knative-releases/knative.dev/serving/cmd/activator:v1.22.0 + autoscaler: gcr.io/knative-releases/knative.dev/serving/cmd/autoscaler:v1.22.0 + autoscaler-hpa: gcr.io/knative-releases/knative.dev/serving/cmd/autoscaler-hpa:v1.22.0 + controller: gcr.io/knative-releases/knative.dev/serving/cmd/controller:v1.22.0 + webhook: gcr.io/knative-releases/knative.dev/serving/cmd/webhook:v1.22.0 + queue-proxy: gcr.io/knative-releases/knative.dev/serving/cmd/queue:v1.22.0 + net-kourier-controller/controller: gcr.io/knative-releases/knative.dev/net-kourier/cmd/kourier:v1.22.0 + # factory:auto:install-images END + ingress: + kourier: + enabled: true + config: + network: + ingress-class: "kourier.ingress.networking.knative.dev" + deployment: + # queue-proxy sidecar image comes from config-deployment; registry.override does not cover it + queue-sidecar-image: gcr.io/knative-releases/knative.dev/serving/cmd/queue:v1.22.0 +``` + +```bash +kubectl create namespace knative-serving --dry-run=client -o yaml | kubectl apply -f - +kubectl apply -f knative-serving.yaml +``` + +### 2. Wait for KnativeServing to become Ready + +```bash +kubectl get knativeserving knative-serving -n knative-serving \ + -o jsonpath='{.status.conditions[?(@.type=="Ready")].status}' +kubectl get pods -n knative-serving +``` + +Expected: `Ready` is `True`, and the core Deployments (`activator`, `autoscaler`, `controller`, +`webhook`, `net-kourier-controller`, `3scale-kourier-gateway`) are all Running. + +### 3. Deploy a sample Knative Service + +```yaml +apiVersion: serving.knative.dev/v1 +kind: Service +metadata: + name: hello + namespace: default +spec: + template: + spec: + containers: + - image: gcr.io/knative-samples/helloworld-go + ports: + - containerPort: 8080 + env: + - name: TARGET + value: "Knative on ACP" +``` + +```bash +kubectl apply -f hello.yaml +``` + +### 4. Verify the Service is serving + +```bash +kubectl get ksvc hello -n default +# READY should be True and URL populated, e.g. http://hello.default. +URL=$(kubectl get ksvc hello -n default -o jsonpath='{.status.url}') +curl -s "$URL" +# -> Hello Knative on ACP! +``` + +## Enabling Eventing (optional) + +Create a `KnativeEventing` instance in the `knative-eventing` namespace, applying the same +`spec.registry.override` pattern to the eventing images (controller, webhook, broker filter/ingress, +in-memory channel, mtping, jobsink) pinned to the operand version. See the +[upstream Eventing docs](https://knative.dev/docs/eventing/) for Broker/Trigger configuration. + +## Known Limitations + + +- **Single-stack IPv6 / IPv6-primary dual-stack clusters are not supported in this release.** The + Serving `autoscaler` enters `CrashLoopBackOff`: upstream's stat-forwarder hardcodes the bucket-lease + `EndpointSlice` `AddressType` to IPv4 (`pkg/autoscaler/statforwarder/leases.go`), so on an IPv6 pod + IP the API server rejects it (`endpoints[0].addresses ... must be an IPv4 address`) and + `KnativeServing` never becomes `Ready`. Fixed upstream on `main` + ([knative/serving#16591](https://github.com/knative/serving/pull/16591)) but not yet included in a + released 1.22.x. This plugin follows the community release stream, so the limitation clears once a + Knative release containing the fix is published. Until then, use IPv4 or IPv4-primary dual-stack + clusters. +- The install path validated for this release covers **Serving with Kourier**; Eventing and non-Kourier + ingress (Istio / Contour) are installed by the user per the upstream documentation. + + +## Cleanup + +```bash +kubectl delete ksvc hello -n default +kubectl delete knativeserving knative-serving -n knative-serving +kubectl delete namespace knative-serving +# Uninstall the Operator from Administrator > Marketplace > OperatorHub (or delete its Subscription/CSV) +kubectl -n operators delete subscription alauda-support-for-knative +kubectl -n operators delete csv -l operators.coreos.com/alauda-support-for-knative.operators +``` + +## FAQ + +**Q: The `autoscaler` pod is in `CrashLoopBackOff` and `KnativeServing` never becomes Ready.** +Check the cluster's IP family: `kubectl get pod -n knative-serving -o jsonpath='{.status.podIPs}'`. +If the pod IP is IPv6, you are hitting the single-stack-IPv6 limitation above — use an IPv4 or +IPv4-primary dual-stack cluster until a Knative release containing the upstream fix is available. + +**Q: Serving pods are stuck in `ImagePullBackOff`.** +Ensure `spec.registry.override` is present on the `KnativeServing` CR (and `queue-sidecar-image` under +`config.deployment`). Without it the Operator deploys operands by digest, which the platform image +allowlist cannot rewrite, so air-gapped clusters cannot pull them. + +**Q: The Kourier gateway never becomes Ready.** +`KnativeServing` must be created in the `knative-serving` namespace — the kourier-bootstrap ConfigMap +hardcodes `net-kourier-controller.knative-serving`. Other namespaces will not converge. + +**Q: How do I upgrade Knative?** +Upgrade the Operator to the new version from the Marketplace; it reconciles `KnativeServing` / +`KnativeEventing` to the matching operand version. Update the image tags in `spec.registry.override` +to the new operand version to keep them pinned.