pw

Reviewed-on: #13
Reviewed-by: gitea_admin <admin@forteapps.net>
Co-authored-by: Danijel Simeunovic <danijel.simeunovic@fortedigital.com>
Co-committed-by: Danijel Simeunovic <danijel.simeunovic@fortedigital.com>

.gitea/workflows/ai-review.yaml

@@ -34,6 +34,7 @@ jobs:
       with:
         submodules: true
         fetch-depth: 0
+        token: ${{ secrets.AI_REVIEW_TOKEN }}
 
     - name: Run inline review
       uses: docker://nikitafilonov/ai-review:v0.64.0

apps/base/ts-mcp.yaml

@@ -1,3 +1,13 @@
+---
+# Namespace must be created first (sync-wave: -1)
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: ts-mcp
+  annotations:
+    argocd.argoproj.io/sync-wave: "-1"
+---
+# ArgoCD Application syncs last (sync-wave: 11)
 apiVersion: argoproj.io/v1alpha1
 kind: Application
 metadata:

cluster-resources/backstage-keycloak-client-config.yaml

@@ -0,0 +1,43 @@
+# Self-service Keycloak client config for Backstage.
+# Kyverno clones this to the keycloak namespace, where the
+# keycloak-client-registrar CronJob processes it and creates
+# the backstage-oidc-credentials Secret in the backstage namespace.
+apiVersion: v1
+kind: Secret
+metadata:
+  name: keycloak-client-backstage
+  namespace: backstage
+  labels:
+    keycloak.forteapps.net/client-config: "true"
+stringData:
+  client.json: |
+    {
+      "clientId": "backstage",
+      "name": "Backstage Developer Portal",
+      "redirectUris": ["https://backstage.forteapps.net/api/auth/oidc/handler/frame"],
+      "webOrigins": ["https://backstage.forteapps.net"],
+      "defaultClientScopes": ["openid", "email", "profile"],
+      "protocolMappers": [
+        {
+          "name": "email_verified",
+          "protocol": "openid-connect",
+          "protocolMapper": "oidc-hardcoded-claim-mapper",
+          "config": {
+            "claim.name": "email_verified",
+            "claim.value": "true",
+            "jsonType.label": "boolean",
+            "id.token.claim": "true",
+            "access.token.claim": "true",
+            "userinfo.token.claim": "true"
+          }
+        }
+      ],
+      "secret": {
+        "namespace": "backstage",
+        "name": "backstage-oidc-credentials",
+        "keys": {
+          "clientId": "AUTH_OIDC_CLIENT_ID",
+          "clientSecret": "AUTH_OIDC_CLIENT_SECRET"
+        }
+      }
+    }

cluster-resources/policies/label-checker.yaml

@@ -1,41 +0,0 @@
-apiVersion: kyverno.io/v1
-kind: ClusterPolicy
-metadata:
-  name: require-labels
-  annotations:
-    policies.kyverno.io/title: Require Labels
-    policies.kyverno.io/category: Best Practices
-    policies.kyverno.io/minversion: 1.6.0
-    policies.kyverno.io/severity: medium
-    policies.kyverno.io/subject: Pod, Label
-    policies.kyverno.io/description: Define and use labels that identify semantic attributes of your application or Deployment. A common set of labels allows tools to work collaboratively, describing objects in a common manner that all tools can understand. The recommended labels describe applications in a way that can be queried. This policy validates that the label `app.kubernetes.io/name` is specified with some value.
-spec:
-  validationFailureAction: Audit
-  background: true
-  rules:
-  - name: check-for-labels
-    skipBackgroundRequests: true
-    exclude:
-      any:
-      - resources:
-          namespaces:
-          - kube-system
-          - istio-system
-          - argocd
-          - cert-manager
-          - monitoring
-          - secrets
-          - kyverno
-          - trivy-system
-    match:
-      any:
-      - resources:
-          kinds:
-          - Pod
-    validate:
-      message: The label `app.kubernetes.io/name` is required.
-      allowExistingViolations: true
-      pattern:
-        metadata:
-          labels:
-            app.kubernetes.io/name: "?*"

docs/REFERENCE.md

@@ -965,6 +965,83 @@ ignore:
 - Check Gitea Actions tab for workflow run status and logs
 - Monitor Anthropic usage dashboard for token consumption
 
+### Backstage / RHDH (Developer Portal)
+
+**Chart**: `backstage` (RHDH — Red Hat Developer Hub)
+**Version**: `5.8.0`
+**Namespace**: `backstage`
+**Helm Repo**: `https://redhat-developer.github.io/rhdh-chart`
+**Image**: `quay.io/rhdh-community/rhdh:next`
+
+**Purpose**: Internal developer portal where teams register and broadcast themselves, their applications, APIs, and systems. Provides a unified catalog, templates, and documentation hub.
+
+**Why RHDH over vanilla Backstage**: Ships 27+ plugins pre-bundled (ArgoCD, Kubernetes, Keycloak, GitHub, GitLab, Jira, SonarQube, Tekton, Jenkins, Quay, and more). Supports dynamic plugin installation at runtime — no image rebuilds needed.
+
+**Configuration** (`infra/values/base/backstage-values.yaml`):
+- OpenShift Route disabled (`route.enabled: false`) — uses Traefik ingress instead
+- PostgreSQL subchart enabled for persistence (2Gi)
+- SecurityContext configured for vanilla Kubernetes (non-OpenShift)
+- Traefik ingress with `websecure` entrypoint
+- App title: "Forte Developer Portal"
+- Dynamic plugins: loads `dynamic-plugins.default.yaml` (all 27+ bundled plugins)
+- Catalog rules: Component, System, API, Resource, Location, Template, Group, User, Domain
+
+**Authentication** (Keycloak OIDC):
+- Uses the self-service registrar pattern (see [Keycloak Client Registrar](#keycloak-client-registrar))
+- Config Secret: `cluster-resources/backstage-keycloak-client-config.yaml`
+- Kyverno clones it → registrar creates `backstage-oidc-credentials` Secret in `backstage` namespace
+- Credential keys: `AUTH_OIDC_CLIENT_ID`, `AUTH_OIDC_CLIENT_SECRET` (loaded via `extraEnvVarsSecrets`)
+- Redirect URI: `https://backstage.forteapps.net/api/auth/oidc/handler/frame`
+- Sign-in resolver: `emailMatchingUserEntityProfileEmail`
+
+**Catalog Discovery** (Gitea):
+- Auto-discovers `catalog-info.yaml` from all repos in the `Forte` organization
+- Scans every 30 minutes via the Gitea catalog provider plugin
+- Gitea SCM integration configured for URL resolution (`git.forteapps.net`)
+
+**Catalog Registration**:
+Teams register services by adding a `catalog-info.yaml` to their repo root:
+```yaml
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: my-service
+  description: My service description
+  annotations:
+    backstage.io/source-location: url:https://git.forteapps.net/Forte/my-service
+spec:
+  type: service
+  lifecycle: production
+  owner: team-name
+```
+
+Repos with this file are auto-discovered — no manual registration needed.
+
+**Dynamic Plugins**:
+Add plugins at runtime via `global.dynamic.plugins` in values — no image rebuild:
+```yaml
+global:
+  dynamic:
+    plugins:
+    - package: "@scope/my-plugin@1.0.0"
+      integrity: "sha512-..."
+```
+
+**Per-cluster Configuration** (`infra/values/upc-dev/backstage-values.yaml`):
+```yaml
+global:
+  host: backstage.forteapps.net
+upstream:
+  backstage:
+    appConfig:
+      app:
+        baseUrl: https://backstage.forteapps.net
+      backend:
+        baseUrl: https://backstage.forteapps.net
+  ingress:
+    host: backstage.forteapps.net
+```
+
 ### Keycloak Client Registrar
 
 **Type**: CronJob (deployed via Keycloak Helm chart `extraDeploy`)
@@ -1078,33 +1155,6 @@ kubectl get secret keycloak-client-<app> -n keycloak -o jsonpath='{.metadata.ann
 
 **See**: [Developer Guide - Adding a New Keycloak Client](DEVELOPER-GUIDE.md#adding-a-new-keycloak-client)
 
-### Karpor
-
-**Chart**: `karpor` from `https://kusionstack.github.io/charts`
-**Version**: 0.7.6 (app v0.6.4)
-**Namespace**: `karpor`
-**Sync Wave**: 1
-
-**Purpose**: Kubernetes visualization and intelligence tool. Provides cross-cluster resource search, compliance checking, and topology visualization. Gives platform engineers a unified view of all cluster resources and their relationships.
-
-**Architecture** (4 components):
-- **Server** — main Karpor API/UI (port 7443)
-- **Syncer** — syncs cluster state into the search index
-- **ElasticSearch** — search backend for resource indexing
-- **etcd** — persistent key-value store (10Gi PVC)
-
-**Configuration** (`infra/values/base/karpor-values.yaml`):
-- `namespaceEnabled: false` — ArgoCD manages namespace creation
-- Default resource limits tuned for small clusters
-- ElasticSearch: 2 CPU / 4Gi memory (the heaviest component)
-- AI features available but not enabled (requires `server.ai.authToken` + backend config)
-
-**Access**: Port-forward to reach the UI:
-```bash
-kubectl port-forward svc/karpor-release-server -n karpor 7443:7443
-# Open https://localhost:7443
-```
-
 ### Renovate
 
 **Chart**: `renovate` (OCI: `ghcr.io/renovatebot/charts`)

infra/base/backstage.yaml

@@ -1,12 +1,12 @@
 apiVersion: argoproj.io/v1alpha1
 kind: Application
 metadata:
-  name: karpor
+  name: backstage
   namespace: argocd
   annotations:
     argocd.argoproj.io/sync-wave: "1"
   labels:
-    app.kubernetes.io/name: karpor
+    app.kubernetes.io/name: backstage
     app.kubernetes.io/part-of: developer-portal
     app.kubernetes.io/managed-by: argocd
   finalizers:
@@ -15,13 +15,14 @@ spec:
   project: default
 
   sources:
-  - repoURL: https://kusionstack.github.io/charts
-    chart: karpor
-    targetRevision: "0.7.6"
+  - repoURL: https://redhat-developer.github.io/rhdh-chart
+    chart: backstage
+    targetRevision: "5.8.0"
     helm:
-      releaseName: karpor
+      releaseName: backstage
       valueFiles:
-      - $values/infra/values/base/karpor-values.yaml
+      - $values/infra/values/base/backstage-values.yaml
+      - $values/infra/values/upc-dev/backstage-values.yaml
 
   - repoURL: ssh://git@git.forteapps.net:2222/Forte/launchpad.git
     targetRevision: HEAD
@@ -29,7 +30,7 @@ spec:
 
   destination:
     server: https://kubernetes.default.svc
-    namespace: karpor
+    namespace: backstage
 
   syncPolicy:
     automated:

infra/base/kustomization.yaml

@@ -22,4 +22,4 @@ resources:
 - tempo.yaml
 - grafana-dashboards.yaml
 - network-policies-application.yaml
-- karpor.yaml
+- backstage.yaml

infra/values/base/backstage-values.yaml

@@ -0,0 +1,150 @@
+# Red Hat Developer Hub (RHDH) - Internal Developer Portal
+# Helm chart: https://github.com/redhat-developer/rhdh-chart
+# Includes 27+ plugins out of the box: ArgoCD, Kubernetes, Keycloak,
+# GitHub, GitLab, Jira, SonarQube, Tekton, Jenkins, and more.
+
+global:
+  auth:
+    backend:
+      enabled: true
+  dynamic:
+    includes:
+    - dynamic-plugins.default.yaml
+    plugins: []
+
+# Disable OpenShift Route (not on OpenShift)
+route:
+  enabled: false
+
+upstream:
+  backstage:
+    image:
+      registry: quay.io
+      repository: rhdh-community/rhdh
+      tag: next
+
+    podSecurityContext:
+      runAsUser: 1001
+      runAsGroup: 1001
+      fsGroup: 1001
+
+    resources:
+      requests:
+        cpu: 250m
+        memory: 512Mi
+      limits:
+        cpu: 1000m
+        memory: 1Gi
+
+    extraEnvVarsSecrets:
+    - backstage-oidc-credentials
+    - backstage-session-secret
+
+    appConfig:
+      app:
+        title: "Forte Backstage"
+        baseUrl: http://localhost:7007
+
+      backend:
+        baseUrl: http://localhost:7007
+
+      # -- Keycloak OIDC authentication
+      signInPage: oidc
+      auth:
+        session:
+          secret: ${AUTH_SESSION_SECRET}
+        environment: production
+        providers:
+          oidc:
+            production:
+              metadataUrl: https://id.forteapps.net/realms/forte/.well-known/openid-configuration
+              clientId: ${AUTH_OIDC_CLIENT_ID}
+              clientSecret: ${AUTH_OIDC_CLIENT_SECRET}
+              prompt: auto
+              # Allow login before User entities exist in the catalog.
+              # Remove once org data is populated.
+              dangerouslyAllowSignInWithoutUserInCatalog: true
+              signIn:
+                resolvers:
+                - resolver: emailMatchingUserEntityProfileEmail
+
+      # -- Gitea SCM integration (for catalog URL resolution)
+      integrations:
+        gitea:
+        - host: git.forteapps.net
+
+      # -- Software catalog
+      catalog:
+        rules:
+        - allow:
+          - Component
+          - System
+          - API
+          - Resource
+          - Location
+          - Template
+          - Group
+          - User
+          - Domain
+        providers:
+          # Auto-import users and groups from Keycloak
+          keycloakOrg:
+            default:
+              baseUrl: https://id.forteapps.net
+              realm: forte
+              clientId: ${AUTH_OIDC_CLIENT_ID}
+              clientSecret: ${AUTH_OIDC_CLIENT_SECRET}
+              schedule:
+                frequency: { minutes: 30 }
+                timeout: { minutes: 3 }
+                initialDelay: { seconds: 15 }
+          # Auto-discover catalog-info.yaml from all Forte org repos
+          gitea:
+            forte:
+              organization: Forte
+              host: git.forteapps.net
+              catalogPath: catalog-info.yaml
+              schedule:
+                frequency: { minutes: 30 }
+                timeout: { minutes: 3 }
+        locations:
+          # Backstage's own org data (bootstrap teams, systems, domains)
+          # - type: url
+          #   target: https://git.forteapps.net/Forte/backstage-catalog/raw/branch/main/org.yaml
+          #   rules:
+          #   - allow: [Group, User, System, Domain]
+
+  ingress:
+    enabled: true
+    className: traefik
+    annotations:
+      traefik.ingress.kubernetes.io/router.entrypoints: websecure
+      cert-manager.io/cluster-issuer: letsencrypt-prod
+    tls:
+      enabled: true
+      secretName: backstage-tls
+
+  postgresql:
+    enabled: true
+    auth:
+      # Fixed passwords prevent Helm from regenerating the Secret on
+      # each sync, which would mismatch with the PVC-persisted data.
+      password: backstage-db-pw
+      postgresPassword: backstage-admin-pw
+    primary:
+      persistence:
+        enabled: true
+        size: 2Gi
+      podSecurityContext:
+        enabled: true
+        fsGroup: 26
+        runAsUser: 26
+      resources:
+        requests:
+          cpu: 50m
+          memory: 128Mi
+        limits:
+          cpu: 250m
+          memory: 512Mi
+    volumePermissions:
+      enabled: false

infra/values/base/karpor-values.yaml

@@ -1,44 +0,0 @@
-# Karpor - Kubernetes Visualization & Intelligence Tool
-# Helm chart: https://github.com/KusionStack/charts/tree/master/charts/karpor
-
-# Let the ArgoCD Application manage the namespace
-namespaceEnabled: false
-
-server:
-  replicas: 1
-  port: 7443
-  resources:
-    requests:
-      cpu: 250m
-      memory: 256Mi
-    limits:
-      cpu: 500m
-      memory: 1Gi
-
-syncer:
-  replicas: 1
-  port: 7443
-  resources:
-    requests:
-      cpu: 250m
-      memory: 256Mi
-    limits:
-      cpu: 500m
-      memory: 1Gi
-
-elasticsearch:
-  replicas: 1
-  port: 9200
-  resources:
-    requests:
-      cpu: 500m
-      memory: 2Gi
-    limits:
-      cpu: "2"
-      memory: 4Gi
-
-etcd:
-  replicas: 1
-  port: 2379
-  persistence:
-    size: 5Gi

infra/values/base/keycloak-values.yaml

@@ -116,12 +116,12 @@ extraDeploy:
   metadata:
     name: keycloak-client-registrar
   rules:
-  - apiGroups: [""]
-    resources: ["secrets"]
-    verbs: ["get", "list", "create", "update", "patch"]
-  - apiGroups: [""]
-    resources: ["namespaces"]
-    verbs: ["get", "list"]
+  - apiGroups: [ "" ]
+    resources: [ "secrets" ]
+    verbs: [ "get", "list", "create", "update", "patch" ]
+  - apiGroups: [ "" ]
+    resources: [ "namespaces" ]
+    verbs: [ "get", "list" ]
 
 # -- ClusterRoleBinding for the registrar ServiceAccount
 - apiVersion: rbac.authorization.k8s.io/v1
@@ -158,7 +158,7 @@ extraDeploy:
             containers:
             - name: registrar
               image: alpine:3.20
-              command: ["/bin/sh", "-c"]
+              command: [ "/bin/sh", "-c" ]
               args:
               - |
                 set -e

infra/values/upc-dev/backstage-values.yaml

@@ -0,0 +1,12 @@
+global:
+  host: backstage.forteapps.net
+
+upstream:
+  backstage:
+    appConfig:
+      app:
+        baseUrl: https://backstage.forteapps.net
+      backend:
+        baseUrl: https://backstage.forteapps.net
+  ingress:
+    host: backstage.forteapps.net