The Helm plugin that provides s3 protocol support.
This allows you to have private Helm chart repositories hosted on Amazon S3. Refer to this article written by @andrewlock to get a detailed use case overview.
The installation itself is simple as:
$ helm plugin install https://github.com/hypnoglow/helm-s3.git
You can install a specific release version:
$ helm plugin install https://github.com/hypnoglow/helm-s3.git --version 0.7.0
To use the plugin, you do not need any special dependencies. The installer will download versioned release with prebuilt binary from github releases. However, if you want to build the plugin from source, or you want to contribute to the plugin, please see these instructions.
Because this plugin assumes private access to S3, you need to provide valid AWS credentials.
You can do this in the same manner as for AWS CLI tool.
So, if you want to use the plugin and you are already using AWS CLI - you are
good to go, no additional configuration required. Otherwise, follow the official guide
to set up credentials.
To minimize security issues, remember to configure your IAM 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.
Example Read Only IAM policy
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:ListBucket",
"s3:GetObject"
],
"Resource": [
"arn:aws:s3:::bucket-name",
"arn:aws:s3:::bucket-name/*"
]
}
]
}Example Read and Write IAM policy
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:ListBucket",
"s3:GetObject",
"s3:PutObject",
"s3:DeleteObject"
],
"Resource": [
"arn:aws:s3:::bucket-name",
"arn:aws:s3:::bucket-name/*"
]
}
]
}For now let's omit the process of uploading repository index and charts to s3 and assume
you already have your repository index.yaml file on s3 under path s3://bucket-name/charts/index.yaml
and a chart archive epicservice-0.5.1.tgz under path s3://bucket-name/charts/epicservice-0.5.1.tgz.
Add your repository:
$ helm repo add coolcharts s3://bucket-name/charts
Now you can use it as any other Helm chart repository. Try:
$ helm search coolcharts
NAME VERSION DESCRIPTION
coolcharts/epicservice 0.5.1 A Helm chart.
$ helm install coolchart/epicservice --version "0.5.1"
Fetching also works:
$ helm fetch s3://bucket-name/charts/epicservice-0.5.1.tgz
To create a new repository, use init:
$ helm s3 init s3://bucket-name/charts
This command generates an empty index.yaml and uploads it to the S3 bucket
under /charts key.
To work with this repo by it's name, first you need to add it using native helm command:
$ helm repo add mynewrepo s3://bucket-name/charts
To store the repository in S3, but to publish it at a different URI you can specify the URI when initializing. This will rewrite the URIs in the repository index so that they are downloadable via the published URI. This is useful in case you want to keep the S3 bucket private and expose the repository over HTTP(S) via CloudFront or a web server. The delete and push commands will automatically take into account this publish URI when updating the index.
$ helm s3 init s3://bucket-name/charts --publish https://charts.my-company.tld
The repository owner can continue to use the S3 URIs while the repository user can consume the repository via its published URI:
$ helm repo add publishedrepo https://charts.my-company.tld
Now you can push your chart to this repo:
$ helm s3 push ./epicservice-0.7.2.tgz mynewrepo
On push, both remote and local repo indexes are automatically updated (that means
you don't need to run helm repo update).
Your pushed chart is available:
$ helm search mynewrepo
NAME VERSION DESCRIPTION
mynewrepo/epicservice 0.7.2 A Helm chart.
Note that the plugin denies push when the chart with the same version already exists in the repository. This behavior is intentional. It is useful, for example, in CI automated pushing: if someone forgets to bump chart version - the chart would not be overwritten.
However, in some cases you want to replace existing chart version. To do so,
add --force flag to a push command:
$ helm s3 push --force ./epicservice-0.7.2.tgz mynewrepo
To see other available options, use --help flag:
$ helm s3 push --help
To delete specific chart version from the repository:
$ helm s3 delete epicservice --version 0.7.2 mynewrepo
As always, both remote and local repo indexes updated automatically.
The chart is deleted from the repo:
$ helm search mynewrepo/epicservice
No results found
If your repository somehow became inconsistent or broken, you can use reindex to recreate the index in accordance with the charts in the repository.
$ helm s3 reindex mynewrepo
Alternatively, you can specify --publish uri to reindex an existing repository with a
different published URI. If you don't specify a publish URI, it will reset the repository
back to using S3 URIs.
$ helm plugin remove s3
In use cases where you share a repo across multiple AWS accounts,
you may want the ability to define object ACLS to allow charts to persist there
permissions across accounts.
To do so, add the flag --acl="ACL_POLICY". The list of ACLs can be found here:
$ helm s3 push --acl="bucket-owner-full-control" ./epicservice-0.7.2.tgz mynewrepo
You can also set the default ACL be setting the S3_ACL environment variable.
The plugin assumes Amazon S3 by default. However, it can work with any S3-compatible
object storage, like minio, DreamObjects
and others. To configure the plugin to work alternative S3 backend, just define
AWS_ENDPOINT (and optionally AWS_DISABLE_SSL):
$ export AWS_ENDPOINT=localhost:9000
$ export AWS_DISABLE_SSL=true
See these integration tests that use local minio docker container for a complete example.
To enable S3 SSE export environment variable AWS_S3_SSE and set it to desired type for example AES256.
Additional documentation is available in the docs directory. This currently includes:
- estimated usage cost calculation
- best practices for organizing your repositories.
Contributions are welcome. Please see these instructions that will help you to develop the plugin.