Helm plugin for managing chart repositories on Google Cloud Storage
- Overview
- Features
- Installation
- Quick Start
- Authentication
- Usage
- Advanced Features
- Troubleshooting
- Version Compatibility
- Contributing
- License
helm-gcs is a Helm plugin that enables you to manage private Helm chart repositories using Google Cloud Storage (GCS) buckets as the backend storage.
Store, version, and distribute your Helm charts on GCS with the same ease and security you expect from Google Cloud Platform.
- 🔐 Secure: Leverage GCP IAM for fine-grained access control
- 💰 Cost-effective: Pay only for storage used, no infrastructure to maintain
- 🚀 Fast: Benefit from Google's global CDN and low-latency storage
- 🔄 Concurrent-safe: Built-in optimistic locking prevents race conditions
- 📦 Simple: Works seamlessly with existing Helm workflows
- ☁️ Cloud-native: Native integration with Google Cloud Platform
- 📥 Push/Pull charts to/from GCS buckets
- 🔧 Initialize repositories anywhere in your GCS bucket
- 🗑️ Remove charts by version or entirely
- 🔐 Multiple authentication methods (ADC, Service Account, OAuth)
- 🔄 Concurrent update handling with automatic retry
- 🏷️ Custom metadata support for chart objects
- 📁 Bucket path organization for structured chart storage
- 🌍 Multi-platform support (Linux, macOS, Windows on amd64/arm64)
- ✅ Helm 4 compatible (also supports Helm 3)
helm plugin install https://github.com/hayorov/helm-gcs.githelm plugin install https://github.com/hayorov/helm-gcs.git --version 0.6.0helm plugin update gcshelm gcs versionGet started in under 2 minutes:
# 1. Initialize a new repository in your GCS bucket
helm gcs init gs://my-bucket/helm-charts
# 2. Add your repository to Helm
helm repo add my-repo gs://my-bucket/helm-charts
# 3. Package your chart
helm package ./my-chart
# 4. Push chart to your repository
helm gcs push my-chart-1.0.0.tgz my-repo
# 5. Update Helm cache
helm repo update
# 6. Search for your chart
helm search repo my-repo
# 7. Install your chart
helm install my-release my-repo/my-charthelm-gcs supports multiple authentication methods (in priority order):
export GOOGLE_OAUTH_ACCESS_TOKEN=$(gcloud auth print-access-token)
helm gcs push chart.tgz my-repo⏱️ Token expires in 1 hour. Best for temporary operations.
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json
helm gcs push chart.tgz my-repo🔑 Recommended for CI/CD environments.
gcloud auth application-default login
helm gcs push chart.tgz my-repo👤 Best for local development.
Your service account or user needs these permissions:
storage.objects.getstorage.objects.createstorage.objects.deletestorage.objects.list
Recommended IAM Role: Storage Object Admin or Storage Admin
Create a new Helm repository in your GCS bucket:
helm gcs init gs://your-bucket/path/to/chartsOptions:
- Repository can be created anywhere in your bucket
- Creates an empty
index.yamlif it doesn't exist - Safe to run multiple times (idempotent)
Example with nested path:
helm gcs init gs://company-charts/production/stablehelm repo add stable-charts gs://company-charts/production/stable
helm repo add dev-charts gs://company-charts/developmentVerify repositories:
helm repo list# Package your chart
helm package ./my-application
# Push to repository
helm gcs push my-application-1.0.0.tgz stable-chartshelm gcs push my-application-1.0.0.tgz stable-charts --retry🔄 Automatically retries if concurrent updates detected
Add custom metadata to your chart object:
helm gcs push my-app-1.0.0.tgz stable-charts \
--metadata env=production,team=platform,region=us-central1Organize charts within your bucket:
helm gcs push my-app-1.0.0.tgz stable-charts --bucketPath=applications/backendThis stores the chart at: gs://your-bucket/charts/applications/backend/my-app-1.0.0.tgz
Overwrite existing chart:
helm gcs push my-app-1.0.0.tgz stable-charts --force
⚠️ Use with caution - overwrites existing chart with same version
Make chart publicly accessible:
helm gcs push my-app-1.0.0.tgz stable-charts --publichelm gcs remove my-application stable-charts --version 1.0.0helm gcs remove my-application stable-charts💡 Don't forget to update your local cache:
helm repo update
helm-gcs uses optimistic locking to prevent index corruption during concurrent updates:
# If you see: "Error: index is out-of-date"
# Simply retry the command or use --retry flag
helm gcs push chart.tgz my-repo --retryThe plugin will automatically:
- Detect concurrent modification
- Fetch latest index
- Retry the operation
- Use exponential backoff
Enable detailed logging:
# Using environment variable
export HELM_GCS_DEBUG=true
helm gcs push chart.tgz my-repo
# Or use global flag
helm gcs push chart.tgz my-repo --debugUse custom domain or CDN:
helm gcs push chart.tgz my-repo \
--public \
--publicURL=https://charts.example.comError: failed to authenticate to GCS
Solution:
- Verify credentials:
gcloud auth list - Check
GOOGLE_APPLICATION_CREDENTIALSpath - Ensure service account has required permissions
- Try:
gcloud auth application-default login
Error: update index file: index is out-of-date
Solution: Use --retry flag for automatic retry:
helm gcs push chart.tgz my-repo --retryError: googleapi: Error 403: Forbidden
Solution:
- Verify IAM permissions (need
Storage Object Admin) - Check bucket name is correct
- Ensure bucket exists:
gsutil ls gs://your-bucket
Error: chart already indexed
Solution: Use --force to overwrite:
helm gcs push chart.tgz my-repo --forceexport HELM_GCS_DEBUG=true
helm gcs push chart.tgz my-repo --debughelm gcs --help
helm gcs push --help| helm-gcs Version | Helm Version | Go Version | Status |
|---|---|---|---|
| 0.6.x | Helm 4.x, 3.x | 1.25+ | ✅ Active |
| 0.5.x | Helm 3.x | 1.24+ | ✅ Supported |
| 0.4.x | Helm 3.x | 1.20+ | |
| 0.3.x | Helm 3.x | 1.16+ | |
| 0.2.x | Helm 2.x | 1.13+ | ❌ Unsupported |
For Helm 2 support, use version 0.2.2:
helm plugin install https://github.com/hayorov/helm-gcs.git --version 0.2.2
⚠️ Helm 2 reached end-of-life. Please upgrade to Helm 3 or 4.
Contributions are welcome! Please feel free to submit a Pull Request.
# Clone the repository
git clone https://github.com/hayorov/helm-gcs.git
cd helm-gcs
# Copy environment template
cp .env.example .env
# Edit .env with your GCS test bucket and credentials
# Run tests
go test -v ./...
# Run integration tests (requires GCS credentials)
go test -v -tags=integration ./pkg/repo
# Build
go build -o bin/helm-gcs ./cmd/helm-gcs# Unit tests
go test -v -race ./...
# Integration tests (requires GCS bucket)
export GCS_TEST_BUCKET=gs://your-test-bucket/helm-gcs-tests
go test -v -tags=integration ./pkg/repo
# With debug logging
export HELM_GCS_DEBUG=true
go test -v -tags=integration ./pkg/repo# Format code
gofmt -s -w .
# Run linter
golangci-lint run
# Check code complexity
gocyclo -over 19 cmd pkg
# Vet code
go vet ./...This project is licensed under the MIT License - see the LICENSE file for details.
- Helm - The package manager for Kubernetes
- Google Cloud Storage - Object storage service
- All our contributors
- 🐛 Bug Reports: GitHub Issues
- 💬 Questions: GitHub Discussions
- 📖 Documentation: Project Wiki
Made with ❤️ by the helm-gcs community
![@renovate[bot]](https://avatars.githubusercontent.com/in/2740?s=64&v=4){kind=small}
![@dependabot[bot]](https://avatars.githubusercontent.com/in/29110?s=64&v=4){kind=small}
