This repository contains a Terraform module that creates a Helm chart repository using an AWS S3 bucket. The S3 bucket is configured as a static website and contains an auto-generated index.html with instructions on using and managing the Helm chart repository.
A live example can be found at http://dumrauf-helm-chart-repo.s3-website-us-east-1.amazonaws.com.
For further information, see the corresponding article Build Your Own Helm Chart Repository in S3 — With Auto-Generated User Documentation! on How Hard Can It Be?!.
The master branch in this repository is compliant with Terraform v0.12; a legacy version that is compatible with Terraform v0.11 is available in branch terraform@0.11.
Before you can use the Terraform module in this repository out of the box, you need
- an AWS account
- a Terraform CLI
- a log bucket which can be used to store S3 access logs (use the Terraform module provided in https://github.com/dumrauf/aws_log_bucket to create a log bucket if needed)
Moreover, you probably also have a directory containing the packaged Helm charts along with an index.yaml file.
After running the Terraform module in this repository you get an S3 bucket that contains auto-generated documentation and can be used to host a Helm chart repository.
The input variables for the module are defined in settings/example.tfvars to be
region = "<your-region>"
shared_credentials_file = "/path/to/.aws/credentials"
profile = "<your-profile>"
bucket_name = "<your-bucket-name>"
repository_name = "<your-repository-name>"
log_bucket_id = "<your-log-bucket-id>"Here, you need to replace the example values with your settings.
Moreover, note that the S3 bucket will be named ${var.repository_name}-${var.bucket_name}.
Initialise Terraform by running
terraform init
As a best practice, create a new workspace by running
terraform workspace new example
The Helm chart repository can be planned by running
terraform plan -var-file=settings/example.tfvars
and created by running
terraform apply -var-file=settings/example.tfvars
The module has CLI outputs as well as template files it generates. Here, the template files contain the auto-generated documentation.
The module has two outputs, namely helm_chart_repository_bucket_domain_name and helm_chart_repository_website_endpoint which are the corresponding Terraform attributes of the newly created Helm chart repository bucket. Point your browser to the output of helm_chart_repository_website_endpoint in order to visit your new Helm chart repository as well as to review the auto-generated documentation.
The module also generates a Markdown as well as an HTML file. Both files are named ${var.repository_name}-${var.bucket_name}.index.{md,html}. Here, the HTML file is constructed from the rendered Markdown file and intended to be used as an index.html file for the new Helm chart repository. It contains tailored instructions on how to use the Helm chart repository, making it easier for your users to add, use, and remove the Helm chart repository via the helm CLI. Moreover, the index.html file also contains instructions on how to manage the Helm chart repository.
For example inputs
bucket_name = "helm-charts-repo"
repository_name = "dumrauf"files dumrauf-helm-charts-repo.index.md and dumrauf-helm-charts-repo.index.html are generated.
Here, the contents of file dumrauf-helm-charts-repo.index.html which is automatically uploaded to http://dumrauf-helm-chart-repo.s3-website-us-east-1.amazonaws.com as index.html are
Welcome to the Helm chart repository
dumrauf. See below for instructions on how to add or remove this chart repository usinghelm. If you're the owner of this Helm chart repository, then please refer to the "Managing the Repository" section below.This section describes the use of the repository
dumrauf. It describes how to add, search, and eventually remove the repository viahelm.This chart repository can be added to
helmviahelm repo add dumrauf 'https://dumrauf-helm-charts-repo.s3.amazonaws.com' helm repo updateHere, the latter command is required in order to get the (latest) information about charts from the repository
dumrauf.All charts in the repository can be listed via
helm search dumraufThis chart repository can be removed from
helmviahelm repo remove dumraufThis section outlines steps for managing Helm chart repository
dumrauf. It describes how to upload Helm charts and eventually delete them again.The Helm charts can be uploaded to S3 bucket
dumrauf-helm-charts-repoviaaws s3 sync <packaged-charts-directory> s3://dumrauf-helm-charts-repoAssuming the packaged Helm charts are located in
../packaged-helm-charts/, then they can be uploaded viaaws s3 sync ../packaged-helm-charts/ s3://dumrauf-helm-charts-repoThe Helm charts can be deleted from S3 bucket
dumrauf-helm-charts-repoviaaws s3 rm s3://dumrauf-helm-charts-repo --recursiveNote that due to versioning, additional steps may be necessary.
The Helm chart repository
dumraufand this documentation was created using https://github.com/dumrauf/s3-helm-chart-repo-with-docs. Create your own Helm chart repository with auto-generated documentation and start serving Helm charts in a matter of seconds.
The Helm chart repository can be deleted by running
terraform destroy -var-file=settings/example.tfvars
This respository uses the following projects for handling markdown:
- Showdown from https://github.com/showdownjs/showdown to render the generated markdown entirely in the visitor's browser
- The minified GitHub markdown CSS from https://www.npmjs.com/package/github-markdown-css to achieve a GitHub like look and feel of the resulting
index.htmlpage
The force_destroy option is deliberately set to false in variables.tf in order to avoid accidental deletion of the contents when running terraform destroy. It's essentially a safety net. Feel free to change and use it at your own risk.
For a detailed overview of Helm chart repositories, see the excellent official Helm documentation on https://docs.helm.sh/developing_charts/#the-chart-repository-guide.