kubergrunt, a Go binary for the gaps between Terraform, Helm and Kubectl

One binary for the operator chores that nobody wants to script

kubergrunt is described as a standalone Go binary with a collection of commands that attempts to fill in the gaps between Terraform, Helm and Kubectl for managing a Kubernetes cluster. The phrasing is careful, attempts to fill in the gaps, and it is the right framing, because the tool does not replace any of the three.

The feature list names four areas. Configuring kubectl to authenticate with a given EKS cluster, with a pointer to the Gruntwork production deployment guide for the details. Managing Helm and associated TLS certificates on any Kubernetes cluster, and setting up the Helm client with TLS certificates on any cluster. And generating TLS certificate key pairs and storing them as Kubernetes Secrets on any cluster.

The split between EKS and generic Kubernetes is the design. The Helm and TLS commands work anywhere, while the eks command group assumes Amazon, and the README says the eks subcommand is used to set up the operator machine to interact with a Kubernetes cluster running on EKS.

The repository structure backs this up. There are top level packages named eks/, kubectl/, tls/, eksawshelper/, jsonpatch/, commonerrors/ and logging/, alongside cmd/ which holds the main package. The go.mod names the module github.com/gruntwork-io/kubergrunt and pins Go 1.25.8.

The eks group, and why waiting for ACTIVE is not enough

The eks subcommand group is the largest part of the tool, with nine commands: verify, configure, token, oidc-thumbprint, deploy, sync-core-components, cleanup-security-group, schedule-coredns and drain.

The verify command is the clearest illustration of why this tool exists. It checks that the specified EKS cluster is up and ready, where ready means the cluster status reaches ACTIVE and the cluster Kubernetes API server endpoint responds to HTTP requests. With --wait it blocks until the cluster is ready or times out, and the timeout is configurable with --max-retries and --sleep-between-retries, the first being the number of attempts and the second the delay between them:

kubergrunt eks verify --eks-cluster-arn $EKS_CLUSTER_ARN --wait --max-retries 10 --sleep-between-retries 15s

The README then explains the arithmetic, ten queries fifteen seconds apart for a total of 150 seconds, and gives the reason the AWS CLI equivalent is not enough. The AWS CLI waits for the ACTIVE state, but the Kubernetes API endpoint often has a delay in accepting traffic even after ACTIVE, and the authors have observed it taking up to 1.5 minutes before a valid TCP connection is possible. That is exactly the kind of detail that turns a flaky deploy script into a reliable one.

Embedding the authenticator so operators do not install a second tool

The token command is the part of kubergrunt that removes a dependency rather than adding one.

It retrieves an authentication token using the AWS API with IAM credentials, and that token is what kubectl uses to authenticate to the cluster. The README explains the design decision: the command embeds the aws-iam-authenticator tool into kubergrunt so that operators do not have to install a separate tool to manage authentication into Kubernetes. The go.mod confirms this with a dependency on sigs.k8s.io/aws-iam-authenticator.

The configure command builds on it. It sets up the installed kubectl with config contexts that authenticate to a specified EKS cluster by leveraging the token command, and the binary is designed to be used as part of one of the modules in the package, although it also runs standalone. A typical use is setting up a new operator machine so it can talk to an existing EKS cluster:

kubergrunt eks configure --eks-cluster-arn $EKS_CLUSTER_ARN

If you would rather use aws-iam-authenticator directly, the README says to replace the auth info clause of the kubectl config context. The configure command also supports a --as-tf-data flag that outputs the token in a format consumable by Terraform as an external data source, so the token can be passed straight into the kubernetes provider configuration. The reason for that indirection is given in the example: Terraform does not allow you to interpolate resources in a provider config, so the template_file data source is used to compute the interpolations.

Helm, TLS and the commands that are on their way out

The k8s command group has two entries, wait-for-ingress and kubectl, and the tls group has one, gen. The deprecated commands section lists helm, which tells you something about how the tool is evolving.

The TLS capability is the one that has the clearest reason to exist in a separate tool. Generating TLS certificate key pairs and storing them as Kubernetes Secrets means the private key ends up as a Secret object rather than a file on someone's laptop, and the Helm client setup with TLS certificates is what allows a chart repository served over HTTPS to be trusted without each operator disabling verification.

The presence of a deprecated helm command is worth a moment's attention. It suggests the Helm-related functionality is being reorganised or replaced, and the README groups it separately from the current commands rather than hiding it. If you are picking this tool up now, read that section first, because the command you are used to may not be the one you should use.

The k8s group covers the two things an operator does repeatedly and badly: waiting for an ingress to be ready rather than assuming it is, and invoking kubectl with the right context so the command lands on the cluster you meant.

Installing the binary, and the AWS CLI prerequisite

The binaries are built as part of the CI pipeline on each release and attached to the corresponding release on the Releases Page, so you download the binary for your platform from there. Alternatively the Gruntwork Installer can fetch a specific version:

gruntwork-install --binary-name "kubergrunt" --repo "https://github.com/gruntwork-io/kubergrunt" --tag "v0.5.13"

There is also a Chocolatey package for Windows:

choco install kubergrunt

The README warns that third-party packages may not be updated with the latest version but are often close, and asks you to check your version against the releases page. The version pinning in the installer example is a deliberate hint in that direction, since a tool that changes how it authenticates to your cluster is not something to take on a floating tag.

One prerequisite is easy to miss. You need to authenticate with the AWS CLI before you can run kubergrunt or eksctl commands, and the README links a guide to authenticating to AWS on the command line. That is a hard dependency for the eks group, since the token command is calling the AWS API with your IAM credentials.

Building from source needs Go, and the main package is in cmd:

go build -o bin/kubergrunt ./cmd

If you need the version string to work with kubergrunt --version, the README shows the ldflags invocation that sets it.

Editorial conclusion

Adopt kubergrunt if you run Kubernetes clusters and want a single tool for the operator chores that sit between Terraform, Helm and Kubectl, especially EKS authentication and Helm TLS management. Do not adopt it if you are on a non-AWS platform and only need the Helm and TLS parts, because a large share of the command surface is EKS specific, and expect a moving target since several commands are already marked deprecated. Before you commit, read the deprecated commands section, confirm your AWS CLI is authenticated because the EKS commands need it, and note the release picture, with v0.19.0 published on 2026-01-14 and the last push on 2026-10-19.

Frequently asked questions

Official sources

1. gruntwork-io/kubergrunt on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases