From 8d759294c1f86d578df66c01bfb7718675f206d3 Mon Sep 17 00:00:00 2001 From: SuJinpei <873118042@qq.com> Date: Wed, 29 Jul 2026 03:08:32 +0000 Subject: [PATCH] docs(konveyor): add the Alauda support for Konveyor installation guide The certified "Alauda support for Konveyor" package is going GA, and its marketplace Overview links to solutions/ecosystem/konveyor/Konveyor_Installation_Guide.html, which did not exist. This adds it, following the Knative/Nacos/OpenSearch guide convention. The guide leads with storage planning, because that is what actually blocks installs: the platform asks for two ReadWriteOnce volumes, and hand-written YAML that omits the size fields inherits an upstream default of 100Gi for the file store, which many clusters cannot bind. The console form is prefilled with smaller tested values (5Gi / 10Gi) and the guide says so explicitly. Known limitations are stated rather than left to be discovered: authentication and the AI-assisted migration feature cannot be enabled in this release (their images are published for amd64 only and are not shipped), ui_ingress_class_name defaults to a class many clusters do not run, and there is no upgrade path from the older community konveyor-operator catalog entry. The existing How_to_Use_Konveyor.md described that older entry and actively contradicted the certified package -- it recommends feature_auth_required: true, rwx_supported: true and a 100Gi bucket. Rather than rewrite content that is still correct for its own audience, it now states which package it applies to, and carries warnings at the two places that would break someone following it on the certified package (the Tackle example and the KAI section), each pointing at the new guide. en only: the zh mirrors are produced by the translation pipeline from the en sources (tracked via sourceSHA) and should not be committed by hand. No id: in the new file's frontmatter either -- add_id.sh allocates it from the CRM by title on merge to main, and skips files that already have one. --- docs/en/solutions/How_to_Use_Konveyor.md | 26 ++ .../konveyor/Konveyor_Installation_Guide.md | 256 ++++++++++++++++++ 2 files changed, 282 insertions(+) create mode 100644 docs/en/solutions/ecosystem/konveyor/Konveyor_Installation_Guide.md diff --git a/docs/en/solutions/How_to_Use_Konveyor.md b/docs/en/solutions/How_to_Use_Konveyor.md index a542d2548..04e8fa92d 100644 --- a/docs/en/solutions/How_to_Use_Konveyor.md +++ b/docs/en/solutions/How_to_Use_Konveyor.md @@ -10,6 +10,19 @@ id: KB260100023 # How to Deploy and Use Konveyor +> [!IMPORTANT] +> **Which package does this page apply to?** +> +> This page describes a self-managed Konveyor deployment based on the older community +> `konveyor-operator` catalog entry. It is **not** the installation guide for the certified +> **Alauda support for Konveyor** package. +> +> If you installed **Alauda support for Konveyor** from the Marketplace, follow +> [Alauda support for Konveyor — Installation Guide](./ecosystem/konveyor/Konveyor_Installation_Guide.md) +> instead. Several settings on this page do not apply to that package — in particular +> `feature_auth_required`, the Keycloak admin steps, and the KAI configuration, whose container +> images are not shipped with it. + ## Overview Konveyor is a CNCF (Cloud Native Computing Foundation) project that provides a modular platform for application modernization. It supports the entire lifecycle of modernization: discovery, assessment, analysis, and execution. This guide covers deploying the Konveyor Hub (Tackle) platform and its core components. @@ -31,6 +44,14 @@ Download the Konveyor Operator plugin from [Alauda Cloud Console](https://cloud. Deploy the Tackle platform by creating a Tackle CR. The Tackle instance must be deployed in the same namespace as the konveyor-operator. +> [!WARNING] +> The example below is written for the community `konveyor-operator` entry and assumes a +> ReadWriteMany StorageClass plus ~200Gi of capacity. **Do not copy it as-is onto +> Alauda support for Konveyor** — on that package `feature_auth_required` must stay `false`, and +> `rwx_supported: true` with a 100Gi bucket is more than most clusters can bind. Use the +> [Installation Guide](./ecosystem/konveyor/Konveyor_Installation_Guide.md) for a working starting +> point. + ```yaml cat << EOF | kubectl create -f - apiVersion: tackle.konveyor.io/v1alpha1 @@ -195,6 +216,11 @@ Access Tackle at `https://tackle.example.com`. KAI uses AI services to provide AI-powered code migration assistance. It supports multiple providers and models. +> [!NOTE] +> KAI is **not available** in the certified **Alauda support for Konveyor** package — the images it +> needs are published for amd64 only and are not shipped with it. This section applies to the +> community `konveyor-operator` entry. + ### Supported Providers and Models | Provider (`kai_llm_provider`) | Model (`kai_llm_model`) | diff --git a/docs/en/solutions/ecosystem/konveyor/Konveyor_Installation_Guide.md b/docs/en/solutions/ecosystem/konveyor/Konveyor_Installation_Guide.md new file mode 100644 index 000000000..60f2a4c99 --- /dev/null +++ b/docs/en/solutions/ecosystem/konveyor/Konveyor_Installation_Guide.md @@ -0,0 +1,256 @@ +--- +products: + - Alauda Application Services +kind: + - Solution +ProductsVersion: + - '4.1,4.2,4.3' +--- + + + +# Alauda support for Konveyor — Installation Guide + +## Overview + +**Alauda support for Konveyor** is the Alauda Application Services (S2, certified) packaging of the +upstream [Konveyor](https://www.konveyor.io/) application modernization platform, listed on the +Alauda Cloud marketplace and installable from the ACP OperatorHub. + +Konveyor is a CNCF project that helps teams move existing applications to Kubernetes. It lets you: + +- **Inventory and assess** applications — record their business services, owners and dependencies, + then answer assessment questionnaires to surface risk. +- **Analyze source code** for Java, Python, Node.js and C# to find migration blockers, with an effort + estimate per finding. +- **Discover technologies** an application actually uses. +- **Plan migration waves** and export reports. + +On Alauda Container Platform (ACP) the platform is delivered as an Operator that you install from the +Marketplace. Creating a single `Tackle` resource then brings up the whole platform — a REST API +(hub), a web console (ui), and the analysis add-ons — and keeps it reconciled thereafter. + +### Supported Versions + + +| Item | Version | +|------|---------| +| ACP | 4.1, 4.2, 4.3 | +| Architectures | amd64 (x86_64), arm64 | +| Network | IPv4, IPv6 | +| Alauda support for Konveyor (bundle) | v0.9.2 | +| Konveyor platform | v0.9.2 | +| License | Apache-2.0 | + + +## Prerequisites + +- An ACP cluster at one of the supported versions above, and `cluster-admin` access to the target + workload cluster. +- The **Alauda support for Konveyor** plugin available in your cluster's OperatorHub. If it has not + been uploaded yet, an administrator can push it with the `violet` CLI: + ```bash + violet push alauda-support-for-konveyor..tgz \ + --platform-address="https://" \ + --platform-username="" --platform-password="" \ + --clusters="" + ``` +- `kubectl` configured against the target cluster. +- **A StorageClass that supports ReadWriteOnce volumes.** The platform requests two volumes and will + not start without one. If your cluster does not mark a StorageClass as default, you must name it + explicitly in the `Tackle` resource — see [Plan storage first](#plan-storage-first). + +## Plan storage first + +This is the single most common reason an installation appears to hang, so decide it before you +install. + +The `Tackle` resource requests two ReadWriteOnce volumes: + +| Volume | Claim name | What it holds | Upstream default | Prefilled in the console form | +|---|---|---|---|---| +| Application database | `tackle-hub-database-volume-claim` | applications, assessments, questionnaires | 10Gi | 5Gi | +| File store | `tackle-hub-bucket-volume-claim` | analysis reports, uploaded archives | **100Gi** | 10Gi | + +Two rules follow: + +1. **If you create the `Tackle` resource from the console form**, it is prefilled with the smaller + sizes above, which most clusters can satisfy. +2. **If you write the YAML by hand and omit the size fields**, you get the upstream defaults — + including a **100Gi** file store that many clusters cannot bind. Always set + `hub_database_volume_size` and `hub_bucket_volume_size` explicitly. + +Set `rwo_storage_class` and `hub_bucket_storage_class` to a real StorageClass name unless your +cluster has a default one. Check with: + +```bash +kubectl get storageclass +``` + +## Install the Operator + +1. In the ACP Console, go to **Administrator > Marketplace > OperatorHub**, select the target + cluster, find **Alauda support for Konveyor**, and click **Install**. +2. Keep the default channel (`alpha`). For **Installation Location**, keep the suggested namespace + **`konveyor-tackle`** — the platform is designed to run in the same namespace as the Operator. +3. Confirm the installation. + +### Verify the Operator + +```bash +kubectl -n konveyor-tackle get csv | grep konveyor +kubectl -n konveyor-tackle get deploy +``` + +Expected: the entry `alauda-support-for-konveyor.v` reaches phase `Succeeded`, and the +Operator's own Deployment shows `1/1` ready. + +## Quick start: bring up the platform + +### 1. Create the Tackle resource + +From the console, open the installed Operator and create a **Tackle** instance — the form is +prefilled with working values. To do it from the command line instead: + +```yaml +apiVersion: tackle.konveyor.io/v1alpha1 +kind: Tackle +metadata: + name: tackle + namespace: konveyor-tackle +spec: + # ── Storage ─────────────────────────────────────────────────────────── + rwo_storage_class: "" # database volume; leave empty only if the cluster has a default + hub_bucket_storage_class: "" # file store; leave empty only if the cluster has a default + hub_database_volume_size: "5Gi" + hub_bucket_volume_size: "10Gi" # upstream default is 100Gi — set this explicitly + rwx_supported: false # set true only if you have a ReadWriteMany StorageClass + + # ── Access ──────────────────────────────────────────────────────────── + ui_ingress_class_name: "none" # "none" = no Ingress, reach the console through its Service; + # otherwise use the cluster's real class, e.g. "alb" + + # ── Authentication ──────────────────────────────────────────────────── + feature_auth_required: "false" # must stay false in this release — see Known Limitations +``` + +```bash +kubectl apply -f tackle.yaml +``` + +> `Tackle` accepts any of the platform's configuration keys directly under `spec`. If you use +> `kubectl apply` with keys the CRD does not enumerate, add `--validate=false`. + +### 2. Wait for the platform to come up + +```bash +kubectl -n konveyor-tackle get deploy tackle-hub tackle-ui +kubectl -n konveyor-tackle get pvc +``` + +Expected: both Deployments reach `1/1`, and both volume claims are `Bound`. + +> **First start takes a few minutes.** The hub has no readiness probe, so it reports Available before +> it has finished preparing its database. Wait until the API answers (next step) rather than trusting +> the Deployment status alone. + +### 3. Verify the API and the add-ons + +```bash +kubectl -n konveyor-tackle exec deploy/tackle-hub -- \ + curl -s -o /dev/null -w '%{http_code}\n' http://tackle-hub.konveyor-tackle.svc.cluster.local:8080/applications +# -> 200 + +kubectl -n konveyor-tackle get addons.tackle.konveyor.io +kubectl -n konveyor-tackle get extensions.tackle.konveyor.io +``` + +Expected: the API returns `200`, and the analyzer / discovery / platform add-ons and the language +provider extensions are registered. + +### 4. Open the web console + +If you set `ui_ingress_class_name` to a real class, the console is reachable through the Ingress the +platform created: + +```bash +kubectl -n konveyor-tackle get ingress +``` + +Otherwise, forward the console's Service: + +```bash +kubectl -n konveyor-tackle port-forward svc/tackle-ui 8080:8080 +# then open http://localhost:8080 +``` + +From there you can register your first application, run an analysis, and organize migration waves. +See the [upstream Konveyor documentation](https://konveyor.io/docs/) for how to use each feature. + +## Known Limitations + + +- **Authentication cannot be enabled in this release.** Leave `feature_auth_required: "false"`. + Turning it on starts a Keycloak server and its database, whose container images are published for + amd64 only and are not included in this package — they would fail to start on arm64 clusters and + would not be available at all on clusters without internet access. The console is reachable without + a login; restrict access at the network layer (Ingress rules, NetworkPolicy) if you need to. +- **The experimental AI-assisted migration feature is not available.** Leave + `experimental_deploy_kai` unset for the same reason. +- **`ui_ingress_class_name` defaults to `nginx`.** If your cluster does not run an ingress controller + with that class, the platform still installs but the Ingress it creates never routes. Set the + cluster's real class, or `none` to skip creating one and reach the console through its Service. +- **Running an end-to-end source analysis is not part of the validated install path.** This release + validates that the platform installs, serves its API and console, registers its add-ons, and + survives a restart with its data intact. Analyzing a real application additionally needs a + reachable source repository and enough spare capacity for the analysis pods. +- **There is no upgrade path from the older community `konveyor-operator` catalog entry + (0.6.0-beta.1).** This is a separate, newly published package. Install it fresh; do not expect the + older entry to upgrade into it. + + +## Uninstall + +```bash +kubectl -n konveyor-tackle delete tackle tackle +kubectl -n konveyor-tackle get pvc # both claims are removed with the resource +``` + +Deleting the `Tackle` resource removes the hub, the console and **both volumes**, so back up anything +you need first. Then uninstall the Operator from **Administrator > Marketplace > OperatorHub**, or: + +```bash +kubectl -n konveyor-tackle delete subscription alauda-support-for-konveyor +kubectl -n konveyor-tackle delete csv -l operators.coreos.com/alauda-support-for-konveyor.konveyor-tackle +``` + +## FAQ + +**Q: The volume claims stay `Pending` and nothing starts.** +Either the cluster has no default StorageClass, or the requested size cannot be satisfied. Run +`kubectl -n konveyor-tackle describe pvc` to see which. Set `rwo_storage_class` and +`hub_bucket_storage_class` to a real class name, and check `hub_bucket_volume_size` — hand-written +YAML that omits it asks for 100Gi. + +**Q: `tackle-hub` shows as available but the console reports errors.** +The hub has no readiness probe, so it is marked available before it has finished preparing its +database on first start. Wait until `GET /applications` returns `200` (step 3 above). + +**Q: The console cannot be reached, but the pods are all running.** +Check `kubectl -n konveyor-tackle get ingress`. If it is empty, `ui_ingress_class_name` is `none` — +use `port-forward`. If an Ingress exists but does not route, its class does not match any ingress +controller in the cluster; set the cluster's real class. + +**Q: Can I move the platform to a different namespace?** +No. The Operator is installed with own-namespace scope and the platform is designed to run alongside +it, in `konveyor-tackle`. + +**Q: How do I upgrade?** +Upgrade the Operator from the Marketplace. It rolls the platform components to the matching version +and keeps the existing volumes.