Merge branch 'feat/integrate-tag-release-automation-into-k8s' into 'main'

Integrate tag-release automation into k8s

Closes #154

See merge request postgres-ai/postgresai!132

Author: Sarumyan

.gitlab-ci.yml

@@ -22,9 +22,14 @@ stages:
   - security
   - build
   - test
+  - validate
   - publish
+  - release
   - preview
 
+variables:
+  HELM_VERSION: "3.13.0"
+
 # Build images from current code for e2e tests
 # Images are pushed to GitLab Container Registry and pulled by test jobs
 
@@ -299,6 +304,37 @@ cli:node:tests:
     - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
     - if: '$CI_COMMIT_BRANCH == "main"'
 
+# Validate helm chart on merge requests and main branch
+validate-helm-chart:
+  stage: validate
+  image: 
+    name: alpine/helm:${HELM_VERSION}
+    entrypoint: [""]
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+      changes:
+        - postgres_ai_helm/**/*
+        - .gitlab-ci.yml
+    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
+      changes:
+        - postgres_ai_helm/**/*
+        - .gitlab-ci.yml
+  script:
+    - echo "Starting helm chart validation"
+    - apk add --no-cache bash git
+    - bash postgres_ai_helm/test-release-logic.sh
+    - cd postgres_ai_helm
+    - echo "Validating helm chart"
+    - helm dependency update
+    - helm lint .
+    - helm template test-release .
+    - helm package .
+    - ls -lh postgres-ai-monitoring-*.tgz
+  artifacts:
+    paths:
+      - postgres_ai_helm/*.tgz
+    expire_in: 1 week
+
 cli:npm:publish:
   stage: publish
   interruptible: false  # Never cancel publish jobs
@@ -418,6 +454,8 @@ cli:npm:publish:
   after_script:
     - rm -f ~/.npmrc
   rules:
+    - if: '$CI_COMMIT_TAG =~ /^helm-v/'
+      when: never
     - if: '$CI_COMMIT_TAG'
 
 .docker-publish-base: &docker-publish-base
@@ -508,8 +546,103 @@ docker:publish:images:
       PLATFORMS="linux/amd64,linux/arm64"
     - *docker-build-script
   rules:
+    - if: '$CI_COMMIT_TAG =~ /^helm-v/'
+      when: never
     - if: '$CI_COMMIT_TAG'
 
+# Release helm chart when a tag is pushed.
+# NOTE: The 'helm-v' prefix is an explicit exception to the org 'vX.Y.Z' tag convention.
+# It is required to distinguish helm chart releases from npm/Docker image releases so that
+# the cli:npm:publish and docker:publish:images jobs are not triggered on helm chart tags.
+release-helm-chart:
+  stage: release
+  image:
+    name: alpine/helm:${HELM_VERSION}
+    entrypoint: [""]
+  rules:
+    - if: '$CI_COMMIT_TAG =~ /^helm-v[0-9]+\.[0-9]+\.[0-9]+$/'
+  script:
+    - apk add --no-cache bash
+    - |
+      bash -euo pipefail << 'BASH_SCRIPT'
+      set -euo pipefail
+      # Extract version from tag
+      VERSION="${CI_COMMIT_TAG#helm-}"
+      VERSION="${VERSION#v}"
+      echo "Version: ${VERSION}"
+
+      cd postgres_ai_helm
+
+      # Update Chart.yaml chart version only (appVersion tracks the deployed app, not the chart)
+      sed "s/^version: .*/version: \"${VERSION}\"/" Chart.yaml > Chart.yaml.tmp
+      mv Chart.yaml.tmp Chart.yaml
+
+      # Verify the substitution succeeded
+      if ! grep -q "^version: \"${VERSION}\"" Chart.yaml; then
+        echo "ERROR: Failed to update version in Chart.yaml (sed pattern may not match)" >&2
+        exit 1
+      fi
+
+      # Build and package
+      helm dependency update
+      helm lint .
+      helm package .
+      pkg=(postgres-ai-monitoring-*.tgz)
+      if [ ! -f "${pkg[0]}" ]; then
+        echo "Error: Package file not found after helm package" >&2
+        exit 1
+      fi
+      PACKAGE_FILE="${pkg[0]}"
+      echo "Packaged: ${PACKAGE_FILE} ($(du -h "${PACKAGE_FILE}" | cut -f1))"
+
+      # Copy artifact to fixed name so release: block can reference it with a known path
+      # (shell variables like ${PACKAGE_FILE} are not available in the release: YAML block)
+      cp "${PACKAGE_FILE}" "../postgres-ai-monitoring-chart.tgz"
+      BASH_SCRIPT
+  artifacts:
+    paths:
+      - postgres-ai-monitoring-chart.tgz
+    expire_in: 30 days
+  release:
+    tag_name: $CI_COMMIT_TAG
+    name: "Helm chart $CI_COMMIT_TAG"
+    description: |
+      ## PostgresAI monitoring helm chart $CI_COMMIT_TAG
+
+      ### Installation
+
+      Download `postgres-ai-monitoring-chart.tgz` from this release's assets and run:
+
+      ```bash
+      helm install postgres-ai-monitoring postgres-ai-monitoring-chart.tgz
+      ```
+
+      ### Upgrade
+
+      ```bash
+      helm upgrade postgres-ai-monitoring postgres-ai-monitoring-chart.tgz
+      ```
+
+      ### What's included
+
+      - PGWatch for Postgres metrics collection
+      - VictoriaMetrics for metrics storage
+      - Grafana for visualization
+      - Node exporter for system metrics
+      - cAdvisor for container metrics
+      - Automated reporting cronjobs
+
+      ### Documentation
+
+      - [Installation guide]($CI_PROJECT_URL/-/blob/main/postgres_ai_helm/INSTALLATION_GUIDE.md)
+      - [Helm chart README]($CI_PROJECT_URL/-/blob/main/postgres_ai_helm/README.md)
+      - [Release process]($CI_PROJECT_URL/-/blob/main/postgres_ai_helm/RELEASE.md)
+    assets:
+      links:
+        - name: "postgres-ai-monitoring-chart.tgz"
+          url: "$CI_PROJECT_URL/-/jobs/$CI_JOB_ID/artifacts/raw/postgres-ai-monitoring-chart.tgz"
+          link_type: package
+
 cli:node:e2e:dind:
   stage: test
   image: node:20-alpine
@@ -838,4 +971,4 @@ preview:destroy:
 # Results appear in the Security tab of merge requests and pipelines.
 # https://docs.gitlab.com/ee/user/application_security/sast/
 sast:
-  stage: test
+  stage: test

README.md

@@ -320,6 +320,56 @@ postgresai mon health
 
 Check Grafana dashboards at http://localhost:3000 to confirm metrics are being collected.
 
+## ☸️ Kubernetes deployment
+
+Deploy postgres_ai monitoring to Kubernetes using helm:
+
+```bash
+# Install from the helm chart directory
+helm install postgres-ai-monitoring ./postgres_ai_helm
+
+# Or install from a release (replace <VERSION> with the desired release, e.g. 0.14.0)
+curl -LO https://gitlab.com/postgres-ai/postgresai/-/releases/helm-v<VERSION>/downloads/postgres-ai-monitoring-chart.tgz
+helm install postgres-ai-monitoring postgres-ai-monitoring-chart.tgz
+
+# Customize installation
+helm install postgres-ai-monitoring ./postgres_ai_helm -f custom-values.yaml
+```
+
+### Helm chart features
+
+- Complete monitoring stack for Kubernetes
+- PGWatch, VictoriaMetrics, and Grafana
+- Automated report generation via CronJobs
+- Node exporter and cAdvisor for system metrics
+- Configurable resource limits and persistence
+
+### Helm chart documentation
+
+- [README](./postgres_ai_helm/README.md): Quick start and overview
+- [INSTALLATION_GUIDE](./postgres_ai_helm/INSTALLATION_GUIDE.md): Detailed installation instructions
+- [RELEASE](./postgres_ai_helm/RELEASE.md): Release process for maintainers
+
+### Creating helm releases
+
+For maintainers creating new helm chart releases:
+
+```bash
+cd postgres_ai_helm
+
+# Test the chart locally
+./test-release.sh
+
+# Create a new release (e.g. 0.14.0)
+./release.sh <VERSION>
+```
+
+This automatically:
+- Updates Chart.yaml with the new version
+- Creates a git tag
+- Triggers GitLab CI/CD to package and publish the chart
+- Creates a GitLab release with the packaged chart
+
 ## 📋 Checkup reports
 
 postgres_ai monitoring generates automated health check reports based on [postgres-checkup](https://gitlab.com/postgres-ai/postgres-checkup). Each report has a unique check ID and title:
@@ -461,7 +511,7 @@ View the coverage report by opening `htmlcov/index.html` in your browser.
 
 ## 🤝 Contributing
 
-We welcome contributions from Postgres experts! Please check our [GitLab repository](https://gitlab.com/postgres-ai/postgres_ai) for:
+We welcome contributions from Postgres experts! Please check our [GitLab repository](https://gitlab.com/postgres-ai/postgresai) for:
 - Code standards and review process
 - Dashboard design principles
 - Testing requirements for monitoring components
@@ -479,7 +529,7 @@ postgres_ai monitoring is developed by [PostgresAI](https://postgres.ai), bringi
 - 💬 [Get support](https://postgres.ai/contact)
 - 📺 [Postgres.TV (YouTube)](https://postgres.tv)
 - 🎙️ [Postgres FM Podcast](https://postgres.fm)
-- 🐛 [Report issues](https://gitlab.com/postgres-ai/postgres_ai/-/issues)
+- 🐛 [Report issues](https://gitlab.com/postgres-ai/postgresai/-/issues)
 - 📧 [Enterprise support](https://postgres.ai/consulting)
 
 </div>

postgres_ai_helm/Chart.yaml

@@ -1,10 +1,10 @@
 apiVersion: v2
-appVersion: 1.0.0
+appVersion: "1.0.0"
 dependencies:
 - condition: grafana.enabled
   name: grafana
   repository: https://grafana.github.io/helm-charts
-  version: 10.1.4
+  version: "10.1.4"
 description: PostgresAI monitoring stack with PGWatch, VictoriaMetrics, and Grafana
   for Kubernetes
 home: https://postgres.ai
@@ -22,4 +22,4 @@ name: postgres-ai-monitoring
 sources:
 - https://github.com/PostgresAI/double-pgwatch-poc
 type: application
-version: 0.12
+version: "0.12.0"