{"id":14155475,"url":"https://github.com/hypnoglow/helm-s3","last_synced_at":"2025-05-14T01:04:22.682Z","repository":{"id":37549531,"uuid":"105292823","full_name":"hypnoglow/helm-s3","owner":"hypnoglow","description":"⎈ Helm plugin that adds support for AWS S3 as a chart repository.","archived":false,"fork":false,"pushed_at":"2025-03-24T08:02:50.000Z","size":9097,"stargazers_count":581,"open_issues_count":27,"forks_count":167,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-03-27T14:01:44.573Z","etag":null,"topics":["aws-s3","hacktoberfest","helm","helm-plugin","helm-plugins","helm-registry","kubernetes","minio","s3"],"latest_commit_sha":null,"homepage":"https://helm-s3.hypnoglow.io","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hypnoglow.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-09-29T16:15:09.000Z","updated_at":"2025-03-25T16:26:38.000Z","dependencies_parsed_at":"2023-02-09T09:47:22.420Z","dependency_job_id":"2cf7f4a7-53ad-41ce-8f3c-9c1ec58a8447","html_url":"https://github.com/hypnoglow/helm-s3","commit_stats":{"total_commits":308,"total_committers":24,"mean_commits":"12.833333333333334","dds":"0.47077922077922074","last_synced_commit":"0a7a6c94d80fb691fd6d3c618ee412f9deb32091"},"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hypnoglow%2Fhelm-s3","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hypnoglow%2Fhelm-s3/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hypnoglow%2Fhelm-s3/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hypnoglow%2Fhelm-s3/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hypnoglow","download_url":"https://codeload.github.com/hypnoglow/helm-s3/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247014520,"owners_count":20869376,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws-s3","hacktoberfest","helm","helm-plugin","helm-plugins","helm-registry","kubernetes","minio","s3"],"created_at":"2024-08-17T08:03:25.860Z","updated_at":"2025-04-03T15:02:14.653Z","avatar_url":"https://github.com/hypnoglow.png","language":"Go","funding_links":[],"categories":["kubernetes"],"sub_categories":[],"readme":"\u003cp align=\"left\"\u003e\u003cimg src=\".github/assets/icon_with_name.png\" width=\"500\" alt=\"helm-s3 Logo\"\u003e\u003c/p\u003e\n\n[![main](https://github.com/hypnoglow/helm-s3/actions/workflows/main.yml/badge.svg)](https://github.com/hypnoglow/helm-s3/actions/workflows/main.yml)\n[![release](https://github.com/hypnoglow/helm-s3/actions/workflows/release.yml/badge.svg)](https://github.com/hypnoglow/helm-s3/actions/workflows/release.yml)\n[![codecov](https://codecov.io/gh/hypnoglow/helm-s3/branch/master/graph/badge.svg?token=lJqiDsDfPu)](https://codecov.io/gh/hypnoglow/helm-s3)\n[![License MIT](https://img.shields.io/badge/license-MIT-blue.svg?style=flat)](LICENSE)\n[![GitHub release](https://img.shields.io/github/release/hypnoglow/helm-s3.svg)](https://github.com/hypnoglow/helm-s3/releases)\n[![Artifact Hub](https://img.shields.io/endpoint?url=https://artifacthub.io/badge/repository/s3)](https://artifacthub.io/packages/search?repo=s3)\n\n**helm-s3** is a Helm plugin that provides Amazon S3 protocol support.\n\nThis allows you to have private or public Helm chart repositories hosted on\nAmazon S3. See [this guide](https://docs.aws.amazon.com/prescriptive-guidance/latest/patterns/set-up-a-helm-v3-chart-repository-in-amazon-s3.html) to get a detailed example use case overview.\n\nThe plugin supports both Helm v2 and v3.\n\n\u003e [!NOTE]\n\u003e The documentation is available on [website](https://helm-s3.hypnoglow.io/).\n\n## Table of contents\n\n   * [Install](#install)\n      * [Docker Images](#docker-images)\n   * [Configuration](#configuration)\n      * [AWS Access](#aws-access)\n      * [Helm version mode](#helm-version-mode)\n   * [Usage](#usage)\n      * [Init](#init)\n      * [Push](#push)\n      * [Delete](#delete)\n      * [Reindex](#reindex)\n   * [Uninstall](#uninstall)\n   * [Advanced Features](#advanced-features)\n      * [Relative chart URLs](#relative-chart-urls)\n      * [Serving charts via HTTP](#serving-charts-via-http)\n      * [ACLs](#acl)\n      * [Timeout](#timeout)\n      * [Using alternative S3-compatible vendors](#using-alternative-s3-compatible-vendors)\n      * [Using S3 bucket ServerSide Encryption](#using-s3-bucket-serverside-encryption)\n      * [S3 bucket location](#s3-bucket-location)\n      * [AWS SSO](#aws-sso)\n      * [Signed charts](#signed-charts)\n   * [Additional Documentation](#additional-documentation)\n   * [Community and Related Projects](#community-and-related-projects)\n   * [Contributing](#contributing)\n   * [License](#license)\n\n## Install\n\nThe installation itself is simple as:\n\n    $ helm plugin install https://github.com/hypnoglow/helm-s3.git\n\nYou can install a specific release version:\n\n    $ helm plugin install https://github.com/hypnoglow/helm-s3.git --version 0.16.3\n\nTo use the plugin, you do not need any special dependencies. The installer will\ndownload versioned release with prebuilt binary from [github releases](https://github.com/hypnoglow/helm-s3/releases).\nHowever, if you want to build the plugin from source, or you want to contribute\nto the plugin, please see [these instructions](.github/CONTRIBUTING.md).\n\n### Docker Images\n\n[![Docker Pulls](https://img.shields.io/docker/pulls/hypnoglow/helm-s3)](https://hub.docker.com/r/hypnoglow/helm-s3)\n\nThe plugin is also distributed as Docker images. Images are pushed to Docker Hub\ntagged with plugin release version and suffixed with Helm version. The image\nbuilt from master branch is also available, note that it should be only used for\nplaying and testing, it is **strongly discouraged** to use that image for\nproduction use cases. Refer to https://hub.docker.com/r/hypnoglow/helm-s3 for\ndetails and all available tags.\n\n## Configuration\n\n### AWS Access\n\nTo publish charts to buckets and to fetch from private buckets, you need to\nprovide valid AWS credentials.\nYou can do this in [the same manner](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html) as for `AWS CLI` tool.\n\nSo, if you want to use the plugin and you are already using `AWS CLI` - you are\ngood to go, no additional configuration required. Otherwise, follow [the official guide](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html)\nto set up credentials.\n\nTo minimize security issues, remember to configure your IAM user policies\nproperly. As an example, a setup can provide only read access for users, and\nwrite access for a CI that builds and pushes charts to your repository.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eExample Read Only IAM policy\u003c/b\u003e\u003c/summary\u003e\n\n```json\n{\n    \"Version\": \"2012-10-17\",\n    \"Statement\": [\n        {\n            \"Effect\": \"Allow\",\n            \"Action\": [\n                \"s3:ListBucket\",\n                \"s3:GetObject\"\n            ],\n            \"Resource\": [\n                \"arn:aws:s3:::bucket-name\",\n                \"arn:aws:s3:::bucket-name/*\"\n            ]\n        }\n    ]\n}\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eExample Read and Write IAM policy\u003c/b\u003e\u003c/summary\u003e\n\n```json\n{\n    \"Version\": \"2012-10-17\",\n    \"Statement\": [\n        {\n            \"Sid\": \"files\",\n            \"Effect\": \"Allow\",\n            \"Action\": [\n                \"s3:PutObjectAcl\",\n                \"s3:PutObject\",\n                \"s3:GetObjectAcl\",\n                \"s3:GetObject\",\n                \"s3:DeleteObject\"\n            ],\n            \"Resource\": [\n                \"arn:aws:s3:::bucket-name/repository-name/*\",\n                \"arn:aws:s3:::bucket-name/repository-name\"\n            ]\n        },\n        {\n            \"Sid\": \"bucket\",\n            \"Effect\": \"Allow\",\n            \"Action\": \"s3:ListBucket\",\n            \"Resource\": \"arn:aws:s3:::bucket-name\"\n        }\n    ]\n}\n```\n\u003c/details\u003e\n\n### Helm version mode\n\nThe plugin is able to detect if you are using Helm v2 or v3 automatically. If,\nfor some reason, the plugin does not detect Helm version properly, you can set\n`HELM_S3_MODE` environment variable to value `2` or `3` to force the mode.\n\n\u003cdetails\u003e\n\u003csummary\u003eDemonstration\u003c/summary\u003e\n\n```bash\n# We have Helm version 3:\n$ helm version --short\nv3.0.2+g19e47ee\n\n# For some reason, the plugin detects Helm version badly:\n$ helm s3 version --mode\nhelm-s3 plugin version: 0.9.2\nHelm version mode: v2\n\n# Force the plugin to operate in v3 mode:\n$ HELM_S3_MODE=3 helm s3 version --mode\nhelm-s3 plugin version: 0.9.2\nHelm version mode: v3\n```\n\u003c/details\u003e\n\n## Usage\n\n*Note: example commands below are provided for Helm v3. If you still use Helm\nv2, see alternatives marked with a tip 💡.*\n\nFor now let's omit the process of uploading repository index and charts to s3\nand assume you already have your repository `index.yaml` file on s3 under path\n`s3://bucket-name/charts/index.yaml` and a chart archive `epicservice-0.5.1.tgz`\nunder path `s3://bucket-name/charts/epicservice-0.5.1.tgz`.\n\nAdd your repository:\n\n```bash\n$ helm repo add coolcharts s3://bucket-name/charts\n```\n\nNow you can use it as any other Helm chart repository.\nTry:\n\n```bash\n$ helm search coolcharts\nNAME                       \tVERSION\t  DESCRIPTION\ncoolcharts/epicservice\t    0.5.1     A Helm chart.\n```\n\n💡 *For Helm v2, use `helm search coolcharts`*.\n\nTo install the chart:\n\n```bash\n$ helm install coolchart/epicservice --version \"0.5.1\"\n```\n\nFetching also works:\n\n```bash\n$ helm pull coolchart/epicservice --version \"0.5.1\"\n```\n\n💡 *For Helm v2, use `helm fetch`*.\n    \nAlternatively:\n\n```bash\n$ helm pull s3://bucket-name/charts/epicservice-0.5.1.tgz\n```\n    \n### Init\n\nTo create a new repository, use `init`:\n\n```bash\n$ helm s3 init s3://bucket-name/charts\n```\n\nThis command generates an empty **index.yaml** and uploads it to the S3 bucket\nunder `/charts` key.\n\nTo work with this repo by its name, first you need to add it using native helm\ncommand:\n\n```bash\n$ helm repo add mynewrepo s3://bucket-name/charts\n```\n\n### Push\n\nNow you can push your chart to this repo:\n\n```bash\n$ helm s3 push ./epicservice-0.7.2.tgz mynewrepo\n```\n\nYou may want to push the chart with relative URL, see\n[Relative chart URLs](#relative-chart-urls).\n\nOn push, both remote and local repo indexes are automatically updated (that\nmeans you don't need to run `helm repo update`).\n\nYour pushed chart is available:\n\n```bash\n$ helm search repo mynewrepo\nNAME                    VERSION\t DESCRIPTION\nmynewrepo/epicservice   0.7.2    A Helm chart.\n```\n\n💡 *For Helm v2, use `helm search mynewrepo`*.\n\nNote that the plugin denies push when the chart with the same version already\nexists in the repository. This behavior is intentional. It is useful, for\nexample, in CI automated pushing: if someone forgets to bump chart version - the\nchart would not be overwritten. However, in some cases you want to replace\nexisting chart version. To do so, add `--force` flag to a push command:\n\n```bash\n$ helm s3 push --force ./epicservice-0.7.2.tgz mynewrepo\n```\n\nTo see other available options, use `--help` flag:\n\n```bash\n$ helm s3 push --help\n```\n\n### Delete\n\nTo delete specific chart version from the repository:\n\n```bash\n$ helm s3 delete epicservice --version 0.7.2 mynewrepo\n```\n\nAs always, both remote and local repo indexes updated automatically.\n\nThe chart is deleted from the repo:\n\n```bash\n$ helm search repo mynewrepo/epicservice\nNo results found\n```\n\n💡 *For Helm v2, use `helm search mynewrepo/epicservice`*\n\n### Reindex\n\nIf your repository somehow became inconsistent or broken, you can use reindex to\nrecreate the index in accordance with the charts in the repository.\n\n```bash\n$ helm s3 reindex mynewrepo\n```\n\nYou may want to reindex the repo with relative chart URLs, see\n[Relative chart URLs](#relative-chart-urls).\n\n## Uninstall\n\n```bash\n$ helm plugin remove s3\n```\n\nThank you for using the plugin! 👋\n\n## Advanced Features\n\n### Relative chart URLs\n\nCharts can be `push`-ed with `--relative` flag so their URLs in the index file\nwill be relative to your repository root. This can be useful in various\nscenarios, e.g. serving charts via HTTP, serving charts from replicated buckets,\netc.\n\nAlso, you can run `reindex` command with `--relative` flag to make all chart\nURLs relative in an existing repository.\n\n### Serving charts via HTTP\n\nYou can enable HTTP access to your S3 bucket and serve charts via HTTP URLs, so\nyour repository users won't have to install this plugin.\n\nTo do this, you need your charts to have relative URLs in the index. See\n[Relative chart URLs](#relative-chart-urls).\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eExample of setting up a public repo using \u003ca href=\"https://docs.aws.amazon.com/AmazonS3/latest/userguide/VirtualHosting.html\"\u003eVirtual hosting of buckets\u003c/a\u003e\u003c/b\u003e\u003c/summary\u003e\n\n1. Create S3 bucket named `example-bucket` in EU (Frankfurt) `eu-central-1` region.\n\n2. Go to \"Permissions\", edit Bucket Policy:\n\n    ```\n    {\n      \"Version\": \"2012-10-17\",\n      \"Statement\": [\n        {\n          \"Effect\": \"Allow\",\n          \"Principal\": \"*\",\n          \"Action\": [\n            \"s3:ListBucket\",\n            \"s3:GetObject\"\n           ],\n          \"Resource\": [\n            \"arn:aws:s3:::example-bucket\",\n            \"arn:aws:s3:::example-bucket/*\"\n          ]\n        }\n      ]\n    }\n    ```\n\n3. Initialize repository:\n\n    ```\n    $ helm s3 init s3://example-bucket\n    Initialized empty repository at s3://example-bucket\n    ```\n\n4. Add repository:\n\n    ```\n    $ helm repo add example-bucket s3://example-bucket\n    \"example-bucket\" has been added to your repositories\n    ```\n\n5. Create demo chart:\n\n    ```\n    $ helm create petstore\n    Creating petstore\n\n    $ helm package petstore --version 1.0.0\n    Successfully packaged chart and saved it to: petstore-1.0.0.tgz\n    ```\n\n6. Push chart:\n\n    ```\n    $ helm s3 push ./petstore-1.0.0.tgz --relative\n    Successfully uploaded the chart to the repository.\n    ```\n\n7. The bucket is public and chart repo is set up. Now users can use the repo\n   without the need to install helm-s3 plugin. \n\n    Add HTTP repo:\n\n    ```\n    $ helm repo add example-bucket-http https://example-bucket.s3.eu-central-1.amazonaws.com/\n    \"example-bucket-http\" has been added to your repositories\n    ```\n\n    Search and download charts:\n\n    ```\n    $ helm search repo example-bucket-http\n    NAME                            CHART VERSION\tAPP VERSION\tDESCRIPTION\n    example-bucket-http/petstore\t1.0.0       \t1.16.0     \tA Helm chart for Kubernetes\n\n    $ helm pull example-bucket-http/petstore --version 1.0.0\n    ```\n\u003c/details\u003e\n\n### ACL\n\nIn use cases where you share a repo across multiple AWS accounts, you may want\nthe ability to define object ACLs to allow charts to persist their permissions\nacross accounts. To do so, add the flag `--acl=\"ACL_POLICY\"`. The list of ACLs\ncan be [found here](https://docs.aws.amazon.com/AmazonS3/latest/dev/acl-overview.html#canned-acl):\n\n```bash\n$ helm s3 push --acl=\"bucket-owner-full-control\" ./epicservice-0.7.2.tgz mynewrepo\n```\n\nNote that if you do use ACL, you need to add `--acl` flag for all commands, even\nfor 'delete', because the index file is still updated when you remove a chart.\n\nYou can also set the default ACL be setting the `S3_ACL` environment variable.\n\n### Timeout\n\nThe default timeout for all commands is 5 minutes. This is an opinionated\ndefault to be suitable for MFA use, among other things.\n\nIf you don't use MFA, it may be reasonable to lower the timeout for most \ncommands, e.g. to 10 seconds. In contrast, in cases where you want to reindex a\nbig repository with thousands of charts, you definitely want to increase the \ntimeout.\n\nExample:\n\n```bash\n$ helm s3 push --timeout=10s ./epicservice-0.7.2.tgz mynewrepo\n```\n\n### Using alternative S3-compatible vendors\n\nThe plugin assumes Amazon S3 by default. However, it can work with any\nS3-compatible object storage, like [minio](https://www.minio.io/),\n[DreamObjects](https://www.dreamhost.com/cloud/storage/) and others. To\nconfigure the plugin to work alternative S3 backend, just define `AWS_ENDPOINT`\n(and optionally `AWS_DISABLE_SSL` if you play with Minio locally):\n\n```bash\n$ export AWS_ENDPOINT=localhost:9000\n$ export AWS_DISABLE_SSL=true\n```\n\nSee [these integration tests](https://github.com/hypnoglow/helm-s3/blob/master/hack/test-e2e-local.sh)\nthat use local minio docker container for a complete example.\n\n### Using S3 bucket ServerSide Encryption\n\nTo enable S3 SSE, export environment variable `AWS_S3_SSE` and set it to desired\ntype, e.g. `AES256`.\n\n### S3 bucket location\n\nThe plugin will look for the bucket in the region inferred by the environment.\nThis can be controlled by exporting one of `HELM_S3_REGION`, `AWS_REGION` or \n`AWS_DEFAULT_REGION`, in order of precedence.\n\nSince [v0.11.0](https://github.com/hypnoglow/helm-s3/blob/master/CHANGELOG.md#0110---2022-05-24)\nthe plugin supports dynamic S3 bucket region retrieval, so in most cases you\ndon't need to provide the region. The plugin will detect it automatically and\nwork without issues.\n\n### AWS SSO\n\nThe plugin supports AWS IAM Identity Center (aka AWS SSO) authentication.\n\nTo use AWS SSO, make sure you [configured it via AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/sso-configure-profile-token.html#sso-configure-profile-token-auto-sso):\n\n```bash\n$ aws configure sso\nSSO session name (Recommended): my-sso\nSSO start URL [None]: https://my-sso-portal.awsapps.com/start\nSSO region [None]: us-east-1\nSSO registration scopes [None]: sso:account:access\n\n...\n\nCLI default client Region [None]: us-east-1\nCLI default output format [None]:\nCLI profile name [...]: YOUR-PROFILE-NAME\n```\n\nThen, set `AWS_PROFILE` environment variable to the profile name you used in\nthe previous step:\n\n```bash\n$ export AWS_PROFILE=YOUR-PROFILE-NAME\n```\n\nNow you can use the plugin as usual.\n\n### Signed Charts\n\nThe plugin supports signed charts. See [Helm documentation](https://helm.sh/docs/topics/provenance/)\nfor more information how it works.\n\nThe plugin ensures that the `.prov` file is pushed to the S3 bucket along with\nthe chart. Then, when Helm is invoked with `--verify` flag, the `.prov` file\nwill be automatically downloaded with the chart and used for verification.\n\n## Additional Documentation\n\nAdditional documentation is available in the [docs](docs) directory. This\ncurrently includes:\n- Estimated [usage cost calculation](docs/usage-cost.md)\n- [Best Practices](docs/best-practice.md) for organizing your repositories.\n\n## Community and Related Projects\n\n- [Helm | Related Projects and Documentation](https://helm.sh/docs/community/related/)\n- [Set up a Helm v3 chart repository in Amazon S3 - AWS Prescriptive Guidance](https://docs.aws.amazon.com/prescriptive-guidance/latest/patterns/set-up-a-helm-v3-chart-repository-in-amazon-s3.html)\n- [Deploy Kubernetes resources and packages using Amazon EKS and a Helm chart repository in Amazon S3 - AWS Prescriptive Guidance](https://docs.aws.amazon.com/prescriptive-guidance/latest/patterns/deploy-kubernetes-resources-and-packages-using-amazon-eks-and-a-helm-chart-repository-in-amazon-s3.html)\n- [Chart sources - Flux Helm Operator](https://docs.fluxcd.io/projects/helm-operator/en/stable/helmrelease-guide/chart-sources/#extending-the-supported-helm-repository-protocols)\n- [How to create a Helm chart repository using Amazon S3](https://andrewlock.net/how-to-create-a-helm-chart-repository-using-amazon-s3/)\n\n## Contributing\n\nContributions are welcome. Please see [these instructions](.github/CONTRIBUTING.md)\nthat will help you to develop the plugin.\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhypnoglow%2Fhelm-s3","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhypnoglow%2Fhelm-s3","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhypnoglow%2Fhelm-s3/lists"}