zhenyuwang94/helm-oss repository overview

⁠helm-oss

English | 中文⁠

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

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

⁠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

1. 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)