Skip to content

AGENTS.md

Latest commit

 

History

History
244 lines (181 loc) · 6.47 KB

AGENTS.md

File metadata and controls

244 lines (181 loc) · 6.47 KB

AGENTS.md - Mattermost Helm Chart Development

This document provides guidelines for AI coding agents working on the Mattermost Helm chart repository.

Project Overview

This repository contains an Operator-based Helm chart for deploying Mattermost Enterprise Edition on Kubernetes. The chart uses the Mattermost Operator CRD (installation.mattermost.com/v1beta1) for deployment management.

Key Features

  • Operator-based deployment: Uses Mattermost CRD for lifecycle management
  • In-cluster Redis: Bitnami Redis subchart for cluster caching
  • VPN sidecar: OpenVPN client for internal network access (via resourcePatch)
  • TLS via cert-manager: Automatic certificate management
  • GitHub Actions CI/CD: Automated deployment with health checks and rollback

Build/Lint/Test Commands

Linting

# Lint the Helm chart
helm lint charts/mattermost

# Lint with additional values files
helm lint charts/mattermost -f values-test.yaml

# Run chart-testing lint
ct lint --charts charts/mattermost --config ct.yaml

Testing

# Run helm install in dry-run mode to validate templates
helm install mattermost ./charts/mattermost --dry-run --debug --namespace mattermost

# Test with specific values
helm install mattermost ./charts/mattermost --dry-run -f custom-values.yaml --namespace mattermost

# Run chart-testing install (requires cluster)
ct install --config ct.yaml

Template Rendering

# Update dependencies first
helm dependency update charts/mattermost

# Render templates without installing
helm template mattermost ./charts/mattermost --namespace mattermost

# Render to a file for review
helm template mattermost ./charts/mattermost --namespace mattermost > rendered.yaml

# Render with debug output
helm template mattermost ./charts/mattermost --debug --namespace mattermost

Deployment

# Update dependencies
helm dependency update charts/mattermost

# Deploy/upgrade
helm upgrade --install mattermost ./charts/mattermost \
  --namespace mattermost \
  --values charts/mattermost/values.yaml \
  --timeout 5m \
  --atomic

# Check deployment status
kubectl get mattermost -n mattermost
kubectl get pods -n mattermost -l "installation.mattermost.com/installation=mm-glia"

Directory Structure

.
├── .github/
│   └── workflows/
│       └── deploy.yaml          # CI/CD pipeline
├── charts/
│   └── mattermost/
│       ├── Chart.yaml           # Chart metadata, Redis dependency
│       ├── values.yaml          # Default configuration
│       ├── values.schema.json   # JSON schema for validation
│       └── templates/
│           ├── _helpers.tpl     # Template helpers
│           ├── mattermost-cr.yaml  # Mattermost CRD instance
│           ├── ingress-redirect.yaml # Redirect ingress
│           └── NOTES.txt        # Post-install notes
├── ct.yaml                      # Chart-testing configuration
└── AGENTS.md

Code Style Guidelines

YAML Formatting

  • Use 2 spaces for indentation
  • Add a newline at the end of files
  • Maximum line length: 120 characters
  • Use | for multi-line strings (block style)
  • Quote strings that contain special characters

Helm Template Conventions

Naming

  • Use lowercase with hyphens: mm-glia
  • CRD name configurable via crdName in values
  • Template names: {{ include "mattermost.fullname" . }}
  • Label names: app.kubernetes.io/name, helm.sh/chart

Standard Labels

metadata:
  labels:
    app.kubernetes.io/name: {{ include "mattermost.name" . }}
    app.kubernetes.io/instance: {{ .Release.Name }}
    app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
    app.kubernetes.io/component: server
    app.kubernetes.io/part-of: mattermost
    app.kubernetes.io/managed-by: {{ .Release.Service }}
    helm.sh/chart: {{ include "mattermost.chart" . }}

Conditional Logic

Use {{- if }} with proper whitespace handling:

{{- if .Values.redis.enabled }}
- name: MM_CLUSTERSETTINGS_USEREDIS
  value: "true"
{{- end }}

Error Handling

  • Use required for mandatory values
  • Use fail for validation errors

Mattermost-Specific Configuration

Pre-existing Secrets

The chart references these pre-existing secrets (not created by Helm):

Secret Keys Purpose
mysql-connection DB_CONNECTION_STRING PostgreSQL connection string
s3-access-key accesskey, secretkey S3/Spaces credentials
mattermost-license license Enterprise license
openvpn-config config.ovpn OpenVPN client config
openvpn-credentials username, password VPN auth

Redis Configuration

Redis is deployed as a subchart for cluster caching:

redis:
  enabled: true
  auth:
    enabled: true
  master:
    persistence:
      enabled: false  # Cache only

Redis connection is auto-configured via environment variables.

VPN Sidecar Configuration

OpenVPN sidecar uses resourcePatch to add a container to the operator-managed deployment:

vpn:
  enabled: true
  configSecret: openvpn-config
  credentialsSecret: openvpn-credentials
  routes:
    - 192.168.1.0/24  # Only route this network via VPN

Ingress Configuration

ingress:
  enabled: true
  host: group.glia.org
  tlsSecret: mm-glia
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
    kubernetes.io/ingress.class: nginx

GitHub Actions Workflow

Trigger

  • Push to main branch
  • Paths: charts/mattermost/**
  • Manual dispatch via workflow_dispatch

Workflow Steps

  1. Lint: Validate chart syntax and rendering
  2. Deploy: helm upgrade --install with atomic rollback
  3. Wait: Poll Mattermost CR status.state == stable
  4. Health Check: Verify all pods are ready
  5. Rollback: Automatic on failure

Required Secrets

Secret Description
KUBE_CONFIG Base64-encoded kubeconfig

Generate with:

kubectl config view --raw --minify | base64 -w 0

Commit Guidelines

  • Use conventional commits: feat:, fix:, docs:, chore:
  • Reference issues in commit messages
  • Keep commits atomic and focused

Pre-commit Checklist

  1. Run helm dependency update charts/mattermost
  2. Run helm lint charts/mattermost
  3. Run helm template mattermost ./charts/mattermost --namespace mattermost
  4. Verify YAML is valid
  5. Ensure all new values have defaults
  6. Test deployment on dev cluster if significant changes