helm-oss

English | 中文

helm-oss is a Helm plugin that provides Alibaba Cloud OSS protocol support.

Based on helm-s3 - This project is a fork of helm-s3, modified to support Alibaba Cloud OSS instead of AWS S3.

This allows you to have private or public Helm chart repositories hosted on Alibaba Cloud OSS.

The plugin supports Helm v3.

Buy Me a Coffee

If you find this project useful, you can buy me a coffee!

WeChat Pay	Alipay	PayPal

Please add a remark helm-oss when transferring, thank you for your support!

Table of Contents

• helm-oss
  • Table of Contents
  • Install
    • Docker Images
  • Configuration
    • OSS Access
  • Usage
    • Init
    • Push
    • Delete
    • Download
    • Reindex
  • Uninstall
  • Advanced Features
    • Relative chart URLs
    • Serving charts via HTTP
  • Documentation
  • Acknowledgments
  • Contributing
  • License

Install

Install the latest version:

helm plugin install https://github.com/Timozer/helm-oss.git

Install a specific release version:

helm plugin install https://github.com/Timozer/helm-oss.git --version 0.1.0

To use the plugin, you do not need any special dependencies. The installer will download versioned release with prebuilt binary from GitHub releases.

Docker Images

The plugin is also distributed as Docker images. You can pull the image from Docker Hub:

docker pull zhenyuwang94/helm-oss:latest

Or you can build the image yourself:

docker build -t helm-oss:latest .

Configuration

OSS Access

To publish charts to buckets and to fetch from private buckets, you need to provide valid Alibaba Cloud OSS credentials.

You can configure credentials using environment variables:

export HELM_OSS_ACCESS_KEY_ID="your-access-key-id"
export HELM_OSS_ACCESS_KEY_SECRET="your-access-key-secret"
export HELM_OSS_REGION="oss-cn-hangzhou"
export HELM_OSS_ENDPOINT="https://oss-cn-hangzhou.aliyuncs.com"

Optionally, you can also set:

export HELM_OSS_SESSION_TOKEN="your-session-token"  # For STS

To minimize security issues, remember to configure your RAM user policies properly. As an example, a setup can provide only read access for users, and write access for a CI that builds and pushes charts to your repository.

Configuration File

You can also configure the plugin using a YAML file located at ~/.config/helm_plugin_oss.yaml.

Example ~/.config/helm_plugin_oss.yaml:

endpoint: "https://oss-cn-hangzhou.aliyuncs.com"
region: "oss-cn-hangzhou"
accessKeyID: "your-access-key-id"
accessKeySecret: "your-access-key-secret"
# sessionToken: "your-session-token" # Optional, for STS

Note: Environment variables take precedence over the configuration file.

Usage

Init

Initialize a new chart repository:

helm oss init oss://my-bucket/charts

This command generates an empty index.yaml and uploads it to the OSS bucket under /charts key.

Push

To push a chart to the repository:

helm oss push ./mychart-0.1.0.tgz oss://my-bucket/charts

If you want to replace an existing chart, use the --force flag:

helm oss push --force ./mychart-0.1.0.tgz oss://my-bucket/charts

Delete

To delete a specific chart version from the repository:

helm oss delete mychart --version 0.1.0 oss://my-bucket/charts

Download

To download a chart from the repository:

helm pull oss://my-bucket/charts/mychart-0.1.0.tgz

Reindex

If your repository somehow became inconsistent or broken, you can use reindex to rebuild the index:

helm oss reindex oss://my-bucket/charts

This command will rebuild the index file from scratch.

Uninstall

helm plugin uninstall oss

Advanced Features

Relative chart URLs

The plugin uses relative URLs to support both direct OSS access and HTTP-based access (e.g., via CDN):

entries:
  mychart:
  - urls:
    - mychart-0.1.0.tgz

This allows you to:

1. Access charts directly via OSS plugin: helm pull oss://my-bucket/charts/mychart
2. Access charts via HTTP/CDN: helm pull https://my-cdn.com/charts/mychart

Serving charts via HTTP

You can enable public read access to your OSS bucket and serve charts via HTTP or CDN:

1. Set bucket ACL to public-read
2. Configure CDN (optional)
3. Add the HTTP repository to Helm:

helm repo add my-charts https://my-bucket.oss-cn-hangzhou.aliyuncs.com/charts
# or with CDN
helm repo add my-charts https://my-cdn.com/charts

4. Use charts as usual:

helm search repo my-charts
helm install myrelease my-charts/mychart

Documentation

• English: docs/en/
  • Development Guide
• 中文: docs/zh/
  • 开发指南

Acknowledgments

This project is based on helm-s3 by Igor Zibarev. We are deeply grateful for their excellent work that made this project possible.

Key differences from helm-s3:

• Uses Alibaba Cloud OSS SDK v2 instead of AWS S3 SDK
• Supports OSS-specific features and authentication
• Optimized for Alibaba Cloud infrastructure

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE file for details.

This project includes code from helm-s3, which is also licensed under the MIT License.

---

Original work: Copyright (c) 2017 Igor Zibarev (helm-s3)
Modified work: Copyright (c) 2026 Timozer (helm-oss)