[geekhubuser]

Description

The 3.16 upgrade guide was written before the release and covered one change, the read-only Tekton definitions for developers. This PR completes it from the diffs of the components that edp-install 3.16.0 pins, and fixes the pages that 3.16 makes wrong, the Quick Start first.

Ranges read commit by commit at the release tags (161 commits, 47 Jira tickets):

Component	3.15.0	3.16.0
edp-install	3.15.0	3.16.0
codebase-operator	2.35.0	2.36.0
edp-tekton	0.27.0	0.28.0
cd-pipeline-operator	2.32.0	2.33.1
gitfusion	0.6.1	0.7.0
krci-portal	0.8.0	0.9.0
gerrit-operator	2.25.0	2.25.0

Quick Start. edp-install 3.16.0 keeps the krci-portal chart default and no longer enables the Portal Ingress, so the values of the page render no Ingress and step 7 opens a host that does not exist. The page now enables the Ingress explicitly and drops krci-portal.ingress.dnsWildcard and extraEnvFrom, which 3.16.0 takes from global.dnsWildCard and from its own default.

Upgrade guide. The steps added to the guide, in the order an operator meets them:

Step	What it covers
1. (Required) Verify Prerequisites	the installed version from krci-config; Kubernetes 1.30 or later with the default values, because cd-pipeline-operator installs a ValidatingAdmissionPolicy (admissionregistration.k8s.io/v1)
3. (Required) Label Environment Namespaces Created Outside the Platform	the cd-pipeline-operator tenant-scope policy: an Environment in a namespace without app.edp.epam.com/tenant fails and its deletion does not finish; commands that list such namespaces (the platform namespace left out) and, after a review, label them; the operator then retries on its own
4. (Required if applicable) Portal Ingress and Portal Secret	the Ingress no longer enabled by edp-install, the wildcard fallback and edp-tekton.portalHost, the portal-secret default
5. (Required if applicable) GitFusion Probe Overrides	a tcpSocket, exec, or grpc override plus the new httpGet default is rejected by the API server; the override's handler goes, the chart's HTTP probe replaces it
6. (Required if applicable) External Secrets for Environments	edp-system reads only regcred; v1/v1beta1 detection; RoleBindings left by earlier deletions
7. (Required if applicable) pnpm, Python, and .NET Build Settings	pnpm installs through the npm ConfigMap registry; an overridden Python ConfigMap must exist and hold all four keys; .NET default versioning needs <Version> in the .csproj
8-9. (Required if applicable)	GitFusion API errors and parameter checks for custom clients; codebase deletion waits for deployments being deleted
10. (Recommended) Remove RBAC Objects That the Charts No Longer Render	four RBAC objects: helm upgrade deletes them, Argo CD only in a sync with Prune
11-14	least-privilege RBAC (with what manageNamespace: false now grants), new Tekton task parameters, pipeline behavior, portal capabilities
15-17	breaking changes, the upgrade (Argo CD sync with Prune, a --reuse-values warning, the CRD sentence corrected), post-upgrade checks with the expected image tags

Step 2 (written for EPMDEDP-17405) is shortened and keeps its facts, with these corrections: Stop needs patch on PipelineRuns (the 3.15 portal checked update), and Run with params now needs PipelineRun create. The extraObjects subject follows global.developerGroupName through the chart's tpl, and edits to chart-managed Pipelines and Tasks "can be overwritten" instead of being reverted. The matching post-upgrade item gets the extraObjects exception.

Other pages that 3.16 makes wrong or incomplete:

• Environment Creation Issues: a section for the tenant label error.
• Kubernetes Namespace Management: on Kubernetes with tenancyEngine: none, the administrator RoleBinding step is no longer needed, and the operator retries the Environment on its own instead of a restart; a note says that the scheme predates 3.16, and the values.yaml link moves to v2.33.1.
• Add Deployment and Platform Authorization Model: the label on namespaces that exist before their Environment.
• Annotations and Labels: no report comment for cancelled runs, and rows for app.edp.epam.com/pipeline-reported and app.edp.epam.com/tenant.
• Package Registry: the Python ConfigMap keys the task reads and the ci-nexus credentials it uses; the npm and Python examples are renamed so they do not collide with the ConfigMaps the chart owns.
• krci CLI: krci project build also starts pipelines (KubeRocketCI 3.16, krci 0.15.0 or later).
• Git Server Overview: read the Secret from spec.nameSshKeySecret.
• Platform Cleanup Guide: a deployment being deleted also blocks codebase deletion.
• Codebase API: the GitServer gitProvider description of codebase-operator 2.36.0.

Applied to docs/ and to versioned_docs/version-3.16/.

Jira: EPMDEDP-17413

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Improvement

How Has This Been Tested?

All runs on a kind cluster (Kubernetes v1.36.4) with the published epamedp/edp-install charts. Logs and scripts are kept with the ticket.

Quick Start, the commands taken from the edited page in page order (Helm 4.1.1):

Check	Result
every command of the page	passes
Ingress/krci-portal	krci-portal-krci.127.0.0.1.nip.io, class nginx
https://krci-portal-krci.127.0.0.1.nip.io:8443 through the ingress controller	HTTP 200
sign-in with the service account token	session cookie set, auth.me returns the service account
the same values without enabled: true (helm template, 3.15.0 vs 3.16.0)	3.15.0 renders the Ingress, 3.16.0 renders none
the values block of the final page on a fresh cluster	STATUS: deployed, Ingress krci-portal-krci.127.0.0.1.nip.io

Upgrade rehearsal: 3.15.0 installed by the 3.15 Quick Start, then upgraded with the code blocks of the guide:

Guide claim	Observed
Step 1: the version check and the API check (final text, on 3.16.0)	print 3.16.0 and served; edp_version comes from the same {{.Chart.Version}} line in 3.15.0 and 3.16.0
Step 2: developer permissions before and after	kubectl auth can-i --list rows match the table on both versions
Step 2: the extraObjects snippet	subject renders as krci-oidc-developers; developers can update Pipelines; removing the snippet takes it back
Step 3: an Environment in an unlabelled namespace fails	failed to create regcred secret: secrets "regcred" is forbidden: ValidatingAdmissionPolicy 'edp-cd-pipeline-operator-krci-tenant-scope' ... denied request: edp-cd-pipeline-operator may act only on its own namespace and namespaces it provisioned (label app.edp.epam.com/tenant)., also with regcred already present
Step 3: a new Environment in such a namespace fails the same way	denied at the tenant-admin RoleBinding
Step 3: its deletion does not finish	the Stage keeps finalizer envLabelDeletion, the namespace stays Active
Step 3: the two blocks fix it, without an operator restart (final text, on 3.16.0)	after 4 minutes of failed retries, the list block prints the namespace (the platform namespace is filtered out) and the label block labels it; available: true, status: created 92 s later, with the same operator pod and Deployment generation; deleting the Environment removes the namespace; an operator-created namespace is unaffected
Step 3: the label value (server-side dry-run of a new Environment)	namespace labelled with its own name: admission webhook "stage.epam.com" denied the request: namespace rh7-own is already used in the cluster; labelled with the platform namespace: accepted
Step 4: the upgrade without enabled: true	Ingress deleted, HTTP 404; the render check prints could not find template ... ingress.yaml; with the snippet the Ingress returns on the same host, HTTP 200
Step 4: the portal-secret check	SERVER_SECRET present
Step 5: a tcpSocket probe override	server-side dry-run: may not specify more than 1 handler type; the jq check prints both probes
Step 10: the four RBAC objects	present on 3.15.0, NotFound after helm upgrade
Step 11: EventListener ServiceAccount	can-i list secrets --all-namespaces: yes on 3.15.0, no on 3.16.0
Step 16: --reuse-values	Helm 4.1.1 and 3.22.0 both keep the Portal Ingress and give the GitFusion probes httpGet and tcpSocket, which the API server rejects
Step 17: the commands	all pods Running on the image tags of the table; no Stage stuck in deletion
downgrade 3.16.0 to 3.15.0 with helm upgrade	the admin ClusterRoleBinding returns, the admission policy is removed

Not run on a cluster: Step 6 (no External Secrets Operator on the test cluster), the builds of Step 7, OpenShift and Capsule tenancy, Argo CD pruning (taken from the Application template of edp-cluster-add-ons), and the manageNamespace: false flow of Namespace Management (its missing-namespace error takes the same retry path as Step 3, read in the operator code).

Site: on the final tree, cspell 10.4.0 with the repository config finds 0 issues in the changed pages, every relative link and #step-… anchor resolves, and docs/ matches versioned_docs/version-3.16/. On an earlier tree of this PR, npm run build (no broken links or anchors), npm run typecheck and npm run validate-redirects passed in node:22 with npm ci, as in CI; the checks of this PR run the full build on the final commit.

Checklist

• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• Pull Request contain one commit. I squash my commits.

[github-actions]

Azure Static Web Apps: Your stage site is ready! Visit it here: https://gentle-pebble-0839af61e-437.westus2.4.azurestaticapps.net

[github-actions]

Azure Static Web Apps: Your stage site is ready! Visit it here: https://gentle-pebble-0839af61e-437.westus2.4.azurestaticapps.net