Skip to content

Commit e6cc72e

Browse files
diamonwigginsdiamonwiggins
committed
readme updates
1 parent 72dc308 commit e6cc72e

File tree

3 files changed

+302
-1
lines changed

3 files changed

+302
-1
lines changed

‎.github/workflows/mlflow-ci.yml‎

Lines changed: 70 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -66,9 +66,78 @@ jobs:
6666
# Ensure Chart.yaml and HelmChart versions are in sync
6767
task check:versions
6868
69+
helm-docs:
70+
runs-on: ubuntu-22.04
71+
steps:
72+
- name: Checkout
73+
uses: actions/checkout@v4
74+
with:
75+
fetch-depth: 0
76+
77+
- name: Install Task
78+
uses: arduino/setup-task@v1
79+
with:
80+
version: 3.x
81+
repo-token: ${{ secrets.GITHUB_TOKEN }}
82+
83+
- name: Set up Helm
84+
uses: azure/[email protected]
85+
with:
86+
version: v3.13.3
87+
88+
- name: Install helm-docs
89+
run: |
90+
HELM_DOCS_VERSION=v1.12.0
91+
wget https://github.com/norwoodj/helm-docs/releases/download/${HELM_DOCS_VERSION}/helm-docs_${HELM_DOCS_VERSION#v}_Linux_x86_64.tar.gz -O - | tar -xz
92+
sudo mv helm-docs /usr/local/bin/helm-docs
93+
helm-docs --version
94+
95+
- name: Check Helm Documentation
96+
working-directory: applications/mlflow
97+
run: |
98+
# Use Taskfile to check if helm docs are up to date
99+
task add:repos:helm
100+
task update:deps:helm
101+
task docs:helm:check
102+
103+
- name: Generate Helm Documentation
104+
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
105+
working-directory: applications/mlflow
106+
run: |
107+
# Only generate documentation on main branch pushes
108+
task docs:helm:generate
109+
110+
- name: Generate KOTS Manifest Guide
111+
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
112+
working-directory: applications/mlflow
113+
run: |
114+
# Generate KOTS manifest guide
115+
task docs:kots:summary
116+
117+
- name: Create PR if docs changed
118+
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
119+
uses: peter-evans/create-pull-request@v5
120+
with:
121+
token: ${{ secrets.GITHUB_TOKEN }}
122+
commit-message: "docs: update documentation"
123+
title: "docs: update documentation"
124+
body: |
125+
This PR updates documentation:
126+
127+
- Updated Helm chart documentation based on the current templates
128+
- Generated KOTS manifest guide for platform engineers
129+
130+
Automatically generated by the MLflow CI workflow.
131+
branch: update-docs
132+
base: main
133+
labels: documentation
134+
paths: |
135+
applications/mlflow/charts/*/README.md
136+
applications/mlflow/docs/KOTS_MANIFEST_GUIDE.md
137+
69138
create-release:
70139
runs-on: ubuntu-22.04
71-
needs: [lint-and-template]
140+
needs: [lint-and-template, helm-docs]
72141
outputs:
73142
customer-id: ${{ steps.create-customer.outputs.customer-id }}
74143
channel-slug: ${{ steps.create-release.outputs.channel-slug }}

‎applications/mlflow/Taskfile.yml‎

Lines changed: 199 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -795,6 +795,205 @@ tasks:
795795
cmds:
796796
- echo "All tests completed successfully"
797797

798+
# Documentation generation tasks
799+
docs:helm:generate:
800+
desc: Generate Helm chart documentation from templates
801+
deps: [add:repos:helm, update:deps:helm]
802+
cmds:
803+
- echo "Generating Helm chart documentation..."
804+
- |
805+
# Make sure helm-docs is installed
806+
if ! command -v helm-docs &> /dev/null; then
807+
echo "❌ helm-docs is not installed. Please install it from https://github.com/norwoodj/helm-docs"
808+
exit 1
809+
fi
810+
811+
# Run helm-docs for each chart
812+
for chart in {{.CHARTS}}; do
813+
echo "Generating documentation for $chart chart..."
814+
cd {{.CHART_DIR}}/$chart && helm-docs -t README.md.gotmpl -t README_CHANGELOG.md.gotmpl -t README_CONFIG.md.gotmpl
815+
done
816+
817+
echo "✅ Helm chart documentation generated successfully."
818+
819+
docs:helm:check:
820+
desc: Check if Helm chart documentation is up to date
821+
deps: [add:repos:helm, update:deps:helm]
822+
cmds:
823+
- echo "Checking if Helm chart documentation is up to date..."
824+
- |
825+
# Make sure helm-docs is installed
826+
if ! command -v helm-docs &> /dev/null; then
827+
echo "❌ helm-docs is not installed. Please install it from https://github.com/norwoodj/helm-docs"
828+
exit 1
829+
fi
830+
831+
docs_outdated=false
832+
833+
# For each chart, generate docs to a temp dir and compare with current docs
834+
for chart in {{.CHARTS}}; do
835+
echo "Checking documentation for $chart chart..."
836+
837+
# Create temp directory
838+
tmp_dir=$(mktemp -d)
839+
trap 'rm -rf "$tmp_dir"' EXIT
840+
841+
# Copy current README.md to temp dir
842+
readme_path="{{.CHART_DIR}}/$chart/README.md"
843+
tmp_readme="$tmp_dir/README.md"
844+
845+
if [ -f "$readme_path" ]; then
846+
cp "$readme_path" "$tmp_readme"
847+
else
848+
echo "⚠️ README.md not found for $chart chart. This check will only be useful after docs are generated."
849+
touch "$tmp_readme" # Create empty file for comparison
850+
fi
851+
852+
# Generate fresh docs
853+
cd {{.CHART_DIR}}/$chart && helm-docs -t README.md.gotmpl -t README_CHANGELOG.md.gotmpl -t README_CONFIG.md.gotmpl -o "$tmp_dir"
854+
855+
# Compare with current docs
856+
if [ -f "$readme_path" ] && ! diff -q "$readme_path" "$tmp_readme" > /dev/null; then
857+
echo "❌ Documentation for $chart chart is outdated. Run 'task docs:helm:generate' to update."
858+
docs_outdated=true
859+
else
860+
echo "✅ Documentation for $chart chart is up to date."
861+
fi
862+
done
863+
864+
# Exit with error if any docs are outdated
865+
if [ "$docs_outdated" = true ]; then
866+
echo "❌ Some chart documentation files are outdated. Run 'task docs:helm:generate' to update them."
867+
exit 1
868+
else
869+
echo "✅ All chart documentation is up to date."
870+
fi
871+
872+
docs:kots:summary:
873+
desc: Generate a summary of KOTS manifest files for platform engineers
874+
cmds:
875+
- echo "Generating KOTS manifest summary in docs/KOTS_MANIFEST_GUIDE.md..."
876+
- |
877+
# Create docs directory if it doesn't exist
878+
mkdir -p docs
879+
880+
# Generate the summary document
881+
cat > docs/KOTS_MANIFEST_GUIDE.md << 'EOF'
882+
# MLflow KOTS Manifest Guide
883+
884+
This document provides a technical overview of the Replicated KOTS manifests used to package and deliver the MLflow application.
885+
886+
## Overview
887+
888+
The manifests in the `applications/mlflow/kots` directory define how MLflow is packaged, configured, and deployed using the Replicated platform.
889+
890+
## Key Files and Their Purpose
891+
892+
### kots-app.yaml
893+
894+
Defines the core application properties:
895+
- Application metadata (name, icon, description)
896+
- Status informers for monitoring deployment health
897+
- Port definitions for services
898+
- Release notes handling
899+
900+
### kots-config.yaml
901+
902+
Contains all user-configurable settings presented during installation:
903+
- Database configuration (embedded PostgreSQL or external)
904+
- S3 storage settings (embedded MinIO or external S3)
905+
- Networking and ingress configuration
906+
- Resource allocation settings
907+
908+
Each configuration option includes:
909+
- Type (string, boolean, password, etc.)
910+
- Default values
911+
- Validation rules
912+
- Help text for users
913+
- Dependencies/when conditions
914+
915+
### mlflow-chart.yaml
916+
917+
A HelmChart custom resource that:
918+
- References the MLflow Helm chart
919+
- Maps configuration values from user inputs to Helm values
920+
- Defines conditional logic for different deployment scenarios
921+
- Uses templating functions to insert configuration values
922+
923+
### infra-chart.yaml
924+
925+
Similar to mlflow-chart.yaml but for infrastructure components:
926+
- Configures supporting services (databases, object storage)
927+
- Typically deployed before the main application
928+
929+
### kots-preflight.yaml
930+
931+
Defines preflight checks to validate the environment before installation:
932+
- Kubernetes version compatibility
933+
- Resource availability (CPU, memory)
934+
- Namespace access permissions
935+
- Storage class availability
936+
937+
### k8s-app.yaml
938+
939+
Kubernetes Application custom resource for discovery and management.
940+
941+
### ec.yaml
942+
943+
EntitlementSpec that controls:
944+
- License entitlements and limits
945+
- Feature flags based on license tier
946+
- Usage restrictions
947+
948+
## Best Practices for Modifications
949+
950+
When making changes to these files:
951+
952+
1. **Version Consistency**: Update both Helm chart versions and kots-chart references
953+
2. **Testing**: Test with both new installations and upgrades
954+
3. **Config Options**: When adding new config options:
955+
- Provide meaningful default values
956+
- Include clear help text
957+
- Consider when dependencies for conditional display
958+
4. **Templates**: Use consistent templating patterns
959+
5. **Preflight Checks**: Update preflight checks when requirements change
960+
961+
## Common Tasks
962+
963+
### Adding a New Configuration Option
964+
965+
1. Add the option to `kots-config.yaml` with appropriate metadata
966+
2. Reference the value in `mlflow-chart.yaml` using template functions
967+
3. Update preflight checks if the option affects requirements
968+
969+
### Updating Helm Chart Versions
970+
971+
1. Update the chartVersion in both infra-chart.yaml and mlflow-chart.yaml
972+
2. Run `task update:versions:chart` to ensure consistency
973+
3. Test both installation and upgrade scenarios
974+
975+
### Adding Support for a New Feature
976+
977+
1. First, implement the feature in the Helm chart
978+
2. Add any new configuration options to kots-config.yaml
979+
3. Connect the configuration to the Helm values in the chart files
980+
4. Optionally add preflight checks for any new requirements
981+
5. Test with both embedded and external dependencies
982+
983+
## Troubleshooting
984+
985+
Common issues when working with these files:
986+
987+
- **Template Rendering Errors**: Check template syntax in .yaml files
988+
- **Preflight Check Failures**: Ensure requirements are correctly specified
989+
- **Configuration Mismatches**: Verify config option names match between files
990+
- **Upgrade Issues**: Test upgrades from earlier versions
991+
992+
For more detailed information, refer to the [Replicated KOTS documentation](https://docs.replicated.com/vendor/packaging-kots-apps).
993+
EOF
994+
995+
echo "✅ KOTS manifest summary generated in docs/KOTS_MANIFEST_GUIDE.md"
996+
798997
# Version extraction
799998
extract:version:chart:
800999
desc: Extract and print the MLflow chart version

‎applications/mlflow/charts/mlflow/README_CONFIG.md.gotmpl‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -705,12 +705,43 @@ jobs:
705705
```
706706
{{- end -}}
707707

708+
{{- define "custom.understanding.platform" -}}
709+
### Understanding Platform Integration Files
710+
711+
This section describes the KOTS manifest files used for platform integration in the `applications/mlflow/kots` directory. These files enable MLflow to be deployed through the Replicated platform.
712+
713+
#### KOTS Manifest Files
714+
715+
| File | Description |
716+
| ---- | ----------- |
717+
| `kots-app.yaml` | Defines the application metadata for KOTS, including title, icon, status informers, and ports. |
718+
| `kots-config.yaml` | Contains all configurable options presented to the user during installation, organized in groups like database settings, S3 storage, and networking configuration. |
719+
| `mlflow-chart.yaml` | A HelmChart custom resource that integrates the MLflow Helm chart with KOTS, connecting user configuration options to Helm values. |
720+
| `infra-chart.yaml` | A HelmChart custom resource for infrastructure components that MLflow depends on. |
721+
| `kots-preflight.yaml` | Defines preflight checks that run before installation to validate the environment meets requirements. |
722+
| `kots-support-bundle.yaml` | Configures support bundle collection for troubleshooting. |
723+
| `k8s-app.yaml` | Kubernetes Application custom resource definition. |
724+
| `ec.yaml` | EntitlementSpec that defines license entitlements and limits. |
725+
726+
#### Integration Pattern
727+
728+
These files work together to create an integrated experience:
729+
730+
1. The user configures settings through the options defined in `kots-config.yaml`
731+
2. The values are injected into the Helm charts via template functions in `mlflow-chart.yaml` and `infra-chart.yaml`
732+
3. Preflight checks in `kots-preflight.yaml` ensure the environment is properly set up
733+
4. Deployment status is tracked via the informers defined in `kots-app.yaml`
734+
735+
When making changes to the MLflow Helm chart, corresponding updates may be needed in the KOTS manifests to ensure proper integration.
736+
{{- end -}}
737+
708738
{{- define "custom.config.all" -}}
709739
{{- template "custom.config.resources" . -}}
710740
{{- template "custom.config.persistence" . -}}
711741
{{- template "custom.config.security" . -}}
712742
{{- template "custom.config.monitoring" . -}}
713743
{{- template "custom.config.ha" . -}}
744+
{{- template "custom.understanding.platform" . -}}
714745
{{- template "chart.valuesTable" . -}}
715746
{{- end -}}
716747

@@ -734,6 +765,8 @@ jobs:
734765

735766
{{ template "custom.config.ha" . }}
736767

768+
{{ template "custom.understanding.platform" . }}
769+
737770
{{ template "chart.valuesTable" . }}
738771

739772
{{ template "chart.maintainersSection" . }}

0 commit comments

Comments
 (0)