Repo Browser: Kubergrunt You need to enable JavaScript to run this app.
Gruntwork Website
Kubergrunt A standalone go binary with a collection of commands to fill in the gaps between Terraform, Helm, and Kubectl.
kubergrunt
kubergrunt
is 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.
Some of the features of kubergrunt
include:
Configuring kubectl
to authenticate with a given EKS cluster. Learn more about authenticating kubectl
to EKS
in the our production deployment guide .
Managing Helm and associated TLS certificates on any Kubernetes cluster.
Setting up Helm client with TLS certificates on any Kubernetes cluster.
Generating TLS certificate key pairs and storing them as Kubernetes Secrets
on any Kubernetes cluster.
Installation
The binaries are all built as part of the CI pipeline on each release of the package, and is appended to the
corresponding release in the Releases Page . You can download the corresponding binary for your
platform from the releases page.
Alternatively, you can install kubergrunt
using the Gruntwork
Installer . For example, to install version v0.5.13
:
gruntwork-install --binary-name "kubergrunt" --repo "https://github.com/gruntwork-io/kubergrunt" --tag "v0.5.13"
3rd party package managers
Note that third-party Kubergrunt packages may not be updated with the latest version, but are often close. Please check your version against the latest available on the Releases Page .
Chocolatey (Windows):
choco install kubergrunt
AWS CLI authentication
You need to authenticate with the AWS CLI before you can run kubergrunt/eksctl commands, please see our authentication guide
Building from source
The main package is in cmd
. To build the binary, you can run:
go build -o bin/kubergrunt ./cmd
If you need to set a version on the binary (so that kubergrunt --version
works), you use ldflags
to set the version
string on the compiled binary:
go build -o kubergrunt -ldflags "-X main.VERSION=v0.7.6 -extldflags '-static'" ./cmd
Commands
The following commands are available as part of kubergrunt
:
eks
k8s
tls
Deprecated commands
eks
The eks
subcommand of kubergrunt
is used to setup the operator machine to interact with a Kubernetes cluster running
on EKS.
verify
This subcommand verifies that the specified EKS cluster is up and ready. An EKS cluster is considered ready when:
The cluster status reaches ACTIVE state.
The cluster Kubernetes API server endpoint responds to http requests.
When passing --wait
to the command, this command will wait until the EKS cluster reaches the ready state, or it
times out. The timeout parameters are configurable with the --max-retries
and --sleep-between-retries
options, where
--max-retries
specifies the number of times the command will try to verify a specific condition before giving up, and
--sleep-between-retries
specifies the duration of time (e.g 10m = 10 minutes) to wait between each trial. So for
example, if you ran the command:
--- - -- --- --- -
and the cluster was not active yet, this command will query the AWS API up to 10 times, waiting 15 seconds inbetween
each try for a total of 150 seconds (2.5 minutes) before timing out.
Run kubergrunt eks verify --help
to see all the available options.
Similar Commands:
AWS CLI (aws eks wait
): This command will wait until the EKS cluster reaches the ACTIVE state. Note that oftentimes
the Kubernetes API endpoint has a delay in accepting traffic even after reaching the ACTIVE state. We have observed it
take up to 1.5 minutes after the cluster becomes ACTIVE before we can have a valid TCP connection with the Kubernetes
API endpoint.
This subcommand will setup the installed kubectl
with config contexts that will allow it to authenticate to a
specified EKS cluster by leveraging the kubergrunt eks token
command. This binary is designed to be used as part of
one of the modules in the package, although this binary supports running as a standalone binary. For example, this
binary might be used to setup a new operator machine to be able to talk to an existing EKS cluster.
For example to setup a kubectl
install on an operator machine to authenticate with EKS:
kubergrunt eks configure --eks-cluster -arn $EKS_CLUSTER_ARN
Run kubergrunt eks configure --help
to see all the available options.
Similar Commands:
AWS CLI (aws eks update-kubeconfig
): This command will configure kubeconfig
in a similar manner. Instead of using
kubergrunt eks token
, this version will use the get-token
subcommand built into the AWS CLI.
token
This subcommand is used by kubectl
to retrieve an authentication token using the AWS API authenticated with IAM
credentials. This token is then used to authenticate to the Kubernetes cluster. This command embeds the
aws-iam-authenticator
tool into kubergrunt
so that operators don't have to install a separate tool to manage
authentication into Kubernetes.
The configure
subcommand of kubergrunt eks
assumes you will be using this method to authenticate with the Kubernetes
cluster provided by EKS. If you wish to use aws-iam-authenticator
instead, replace the auth info clause of the kubectl
config context.
This subcommand also supports outputting the token in a format that is consumable by terraform as an external data
source when you pass in the --as-tf-data
CLI arg.
You can then pass the token directly into the kubernetes
provider configuration. For example:
provider "kubernetes" {
load_config_file = false
host = "${data.template_file.kubernetes_cluster_endpoint.rendered} "
cluster_ca_certificate = "${base64decode(data.template_file.kubernetes_cluster_ca.rendered) } "
token = "${lookup(data.external.kubernetes_token.result, "token_data" ) } "
}
data "template_file" "kubernetes_cluster_endpoint" {
template = "${module.eks_cluster.eks_cluster_endpoint} "
}
data "template_file" "kubernetes_cluster_ca" {
template = "${module.eks_cluster.eks_cluster_certificate_authority} "
}
data "external" "kubernetes_token" {
program = ["kubergrunt" , "--loglevel" , "error" , "eks" , "token" , "--as-tf-data" , "--cluster-id" , "${module.eks_cluster.eks_cluster_name} " ]
}
This will configure the kubernetes
provider in Terraform without setting up kubeconfig, allowing you to do everything
in Terraform without side effects to your local machine.
Similar Commands:
AWS CLI (aws eks get-token
): This command will do the same thing, but does not provide any specific optimizations
for terraform.
Terraform aws_eks_cluster_auth
data source:
This data source can be used to retrieve a temporary auth token for EKS in Terraform. This can only be used in
Terraform.
aws-iam-authenticator
: This is a standalone binary that
can be used to fetch a temporary auth token.
oidc-thumbprint
This subcommand will take the EKS OIDC Issuer URL and retrieve the root CA thumbprint. This is used to set the trust
relation for any certificates signed by that CA for the issuer domain. This is necessary to setup the OIDC provider,
which is used for the IAM Roles for Service Accounts feature of EKS.
You can read more about the general procedure for retrieving the root CA thumbprint of an OIDC Provider in the official
documentation .
To retrieve the thumbprint, call the command with the issuer URL:
kubergrunt eks oidc-thumbprint --issuer-url $ISSUER_URL
This will output the thumbprint to stdout in JSON format, with the key thumbprint
.
Run kubergrunt eks oidc-thumbprint --help
to see all the available options.
Similar Commands:
You can use openssl
to retrieve the thumbprint as described by the official
documentation .
eksctl
provides routines for directly configuring the OIDC provider so you don't need to retrieve the thumbprint.
deploy
This subcommand will initiate a rolling deployment of the current AMI config to the EC2 instances in your EKS cluster.
This command will not deploy or update an application deployed on your Kubernetes cluster (e.g Deployment
resource,
Pod
resource, etc). We provide helm charts that you can use to deploy your applications on to a Kubernetes cluster.
See our helm-kubernetes-services
repo for more info.
Instead, this command is for managing and deploying an update to the EC2 instances underlying your EKS cluster.
Terraform and AWS do not provide a way to automatically roll out a change to the Instances in an EKS Cluster. Due to
Terraform limitations (see here for a
discussion ), there is currently no way to
implement this purely in Terraform code. Therefore, we've created this subcommand that can do a zero-downtime roll out
for you.
To deploy a change (such as rolling out a new AMI) to all EKS workers using this command:
Make sure the cluster_max_size
is at least twice the size of cluster_min_size
. The extra capacity will be used to
deploy the updated instances.
Update the Terraform code with your changes (e.g. update the cluster_instance_ami
variable to a new AMI).
Run terraform apply
.
Run the command:
kubergrunt eks deploy --region REGION --asg-name ASG_NAME
When you call the command, it will:
Double the desired capacity of the Auto Scaling Group that powers the EKS Cluster. This will launch new EKS workers
with the new launch configuration.
Wait for the new nodes to be ready for Pod scheduling in Kubernetes. This includes waiting for the new nodes to be
registered to any external load balancers managed by Kubernetes.
Cordon the old instances in the ASG so that they won't schedule new Pods.
Drain the pods scheduled on the old EKS workers (using the equivalent of kubectl drain
), so that they will be
rescheduled on the new EKS workers.
Wait for all the pods to migrate off of the old EKS workers.
Set the desired capacity down to the original value and remove the old EKS workers from the ASG.
Note that to minimize service disruption from this command, your services should setup a
PodDisruptionBudget , a readiness
probe
that fails on container shutdown events, and implement graceful handling of SIGTERM in the container. You can learn more
about these features in our blog post series covering
them .
Currently kubergrunt
does not implement any checks for these resources to be implemented. However in the future, we
plan to bake in checks into the deployment command to verify that all services have a disruption budget set, and warn
the user of any services that do not have a check.
eks deploy
recovery file
Due to the nature of rolling update, the deploy
subcommand performs multiple sequential actions that
depend on success of the previous operations. To mitigate intermittent failures, the deploy
subcommand creates a
recovery file in the working directory for storing current deploy state. The recovery file is updated after
each stage and if the deploy
subcommand fails for some reason, execution resumes from the last successful state.
The existing recovery file can also be ignored with the --ignore-recovery-file
flag. In this case the recovery
file will be re-initialized.
sync-core-components
This subcommand will sync the core components of an EKS cluster to match the deployed Kubernetes version by following
the steps listed in the official documentation .
The core components managed by this command are:
kube-proxy
Amazon VPC CNI plug-in
CoreDNS
By default, this command will rotate the images without waiting for the Pods to be redeployed. You can use the --wait
option to force the command to wait until all the Pods have been replaced.
Example:
kubergrunt eks sync-core-components
cleanup-security-group
This subcommand cleans up the leftover AWS-managed security groups that are associated with an EKS cluster you intend
to destroy. It accepts
--eks-cluster-arn
: the ARN of the EKS cluster
--security-group-id
: a known security group ID associated with the EKS cluster
--vpc-id
: the VPC ID where the cluster is located
It also looks for other security groups associated with the EKS cluster, such as the security group created by the AWS
Load Balancer Controller. To safely delete these resources, it detaches and deletes any associated AWS Elastic Network
Interfaces.
Example:
kubergrunt eks cleanup-security -group
schedule-coredns
This subcommand can be used to toggle the CoreDNS service between scheduling on Fargate and EC2 worker types. During
the creation of an EKS cluster that uses Fargate, schedule-coredns fargate
will annotate the deployment so that
CoreDNS can find and allow EKS to use Fargate nodes. To switch back to EC2, you can run schedule-coredns ec2
to
reset the annotations such that EC2 nodes can be found by CoreDNS.
This command is useful when creating Fargate only EKS clusters. By default, EKS will schedule the coredns
service
assuming EC2 workers. You can use this command to force the service to run on Fargate.
You can also use this command in local-exec
provisioners on an aws_eks_fargate_profile
resource so you can
schedule the CoreDNS service after creating the profile, and revert back when destroying the profile.
Currently fargate
and ec2
are the only subcommands that schedule-coredns
accepts.
Examples:
- --- - --- -
- --- - --- -
drain
This subcommand can be used to drain Pods from the instances in the provided Auto Scaling Groups. This can be used to
gracefully retire existing Auto Scaling Groups by ensuring the Pods are evicted in a manner that respects disruption
budgets.
You can read more about the drain operation in the official
documentation .
To drain the Auto Scaling Group my-asg
in the region us-east-2
:
--- - -- - -
You can drain multiple ASGs by providing the --name
option multiple times:
--- - - -- - - -- - - -- - -
k8s
The k8s
subcommand of kubergrunt
includes commands that directly interact with the Kubernetes resources.
wait-for-ingress
This subcommand waits for the Ingress endpoint to be provisioned. This will monitor the Ingress resource, continuously
checking until the endpoint is allocated to the Ingress resource or times out. By default, this will try for 5 minutes
(max retries 60 and time betweeen sleep of 5 seconds).
You can configure the timeout settings using the --max-retries and --sleep-between-retries CLI args. This will check for
--max-retries times, sleeping for --sleep-between-retries inbetween tries.
For example, if you ran the command:
kubergrunt k8s wait-for-ingress \
--ingress-name $INGRESS_NAME \
--namespace $NAMESPACE \
--max-retries 10 \
--sleep-between-retries 15 s
this command will query the Kubernetes API to check the Ingress
resource up to 10 times, waiting for 15 seconds
inbetween each try for a total of 150 seconds (2.5 minutes) before timing out.
Run kubergrunt k8s wait-for-ingress --help
to see all the available options.
kubectl
This subcommand will call out to kubectl with a temporary file that acts as the kubeconfig, set up with the parameters
--kubectl-server-endpoint
, --kubectl-certificate-authority
, --kubectl-token
. Unlike using kubectl directly, this
command allows you to pass in the base64 encoded certificate authority data directly as opposed to as a file.
To forward args to kubectl, pass all the args you wish to forward after a --
. For example, the following command runs
kubectl get pods -n kube-system
:
kubergrunt k8s kubectl \
--kubectl-server-endpoint $SERVER_ENDPOINT \
--kubectl-certificate-authority $SERVER_CA \
--kubectl-token $TOKEN \
-- get pods -n kube-system
Run kubergrunt k8s kubectl --help
to see all the available options.
tls
The tls
subcommand of kubergrunt
is used to manage TLS certificate key pairs as Kubernetes Secrets.
gen
This subcommand will generate new TLS certificate key pairs based on the provided configuration arguments. Once the
certificates are generated, they will be stored on your targeted Kubernetes cluster as
Secrets . This supports features such as:
Generating a new CA key pair and storing the generated key pair in your Kubernetes cluster.
Issuing a new signed TLS certificate key pair using an existing CA stored in your Kubernetes cluster.
Replacing the stored certificate key pair in your Kubernetes cluster with a newly generated one.
Controlling which Namespace the Secrets are stored in.
For example, to generate a new CA key pair, issue a TLS certificate key pair, storing each of those as the Secrets
ca-keypair
and tls-keypair
respectively:
kubergrunt tls gen \
--namespace kube-system \
--secret-name ca-keypair \
--ca \
--tls-common-name kiam-ca \
--tls-org Gruntwork \
--tls-org-unit IT \
--tls-city Phoenix \
--tls-state AZ \
--tls-country US \
--secret-annotation "gruntwork.io/version=v1"
kubergrunt tls gen \
--namespace kube-system \
--secret-name tls-keypair \
--ca-secret-name ca-keypair \
--tls-common-name kiam-server \
--tls-org Gruntwork \
--tls-org-unit IT \
--tls-city Phoenix \
--tls-state AZ \
--tls-country US \
--secret-annotation "gruntwork.io/version=v1"
The first command will generate a CA key pair and store it as the Secret ca-keypair
. The --ca
argument signals to
kubergrunt
that the TLS certificate is for a CA.
The second command uses the generated CA key pair to issue a new TLS key pair. The --ca-secret-name
signals
kubergrunt
to use the CA key pair stored in the Kubernetes Secret ca-keypair
.
This command should be run by a cluster administrator to ensure access to the Secrets are tightly controlled.
See the command help for all the available options: kubergrunt tls gen --help
.
Deprecated commands
helm
The helm
subcommand contained utilities for managing Helm v2, and is not necessary for Helm v3. This subcommand was
removed as of kubergrunt
version v0.6.0
with Helm v2 reaching end of life.
Who maintains this project?
kubergrunt
is maintained by Gruntwork . If you are looking for help or commercial support,
send an email to support@gruntwork.io .
Gruntwork can help with:
Setup, customization, and support for this project.
Modules and submodules for other types of infrastructure in major cloud providers, such as VPCs, Docker clusters,
databases, and continuous integration.
Modules and Submodules that meet compliance requirements, such as HIPAA.
Consulting & Training on AWS, GCP, Terraform, and DevOps.
How do I contribute?
Contributions are very welcome! Check out the Contribution Guidelines for instructions.
How is this project versioned?
This project follows the principles of Semantic Versioning . You can find each new release, along
with the changelog, in the Releases Page .
During initial development, the major version will be 0 (e.g., 0.x.y
), which indicates the code does not yet have a
stable API. Once we hit 1.0.0
, we will make every effort to maintain a backwards compatible API and use the MAJOR,
MINOR, and PATCH versions on each release to indicate any incompatibilities.
License
Please see LICENSE and NOTICE for how the code in this repo is licensed.
Copyright © 2020 Gruntwork, Inc.
Questions? Ask away. We're here to talk about our services, answer any questions, give advice, or just to chat.
Ready to hand off the Gruntwork? "https://cdn.gruntwork.io/gruntwork-website/"
{"index":{"js":"https://cdn.gruntwork.io/gruntwork-website/index.bundle.c7884255553b53fbca3a.js","map":"https://cdn.gruntwork.io/gruntwork-website/index.bundle.1b14c1b7d19f1f5eb35d6e118e838255.map"},"styles":{"css":"https://cdn.gruntwork.io/gruntwork-website/styles.bundle.f22938926651ddec7c49.css","js":"https://cdn.gruntwork.io/gruntwork-website/styles.bundle.e782420e74a20dcb8691.js","map":"https://cdn.gruntwork.io/gruntwork-website/styles.bundle.d5e2af49807c6ca33f8367d621ece507.map"},"vendors":{"css":"https://cdn.gruntwork.io/gruntwork-website/vendors.bundle.29f7d0366a0978763f96.css","js":"https://cdn.gruntwork.io/gruntwork-website/vendors.bundle.fa8174a130797d75d12c.js","map":"https://cdn.gruntwork.io/gruntwork-website/vendors.bundle.57243d94deeeb29d5061288a338b4eb6.map"}}
{"treedata":{"name":"root","toggled":true,"children":[{"name":".circleci","children":[{"name":"config.yml","path":".circleci/config.yml","sha":"5feb38e518efcd787d56df0adef71f05487e2a0f"}]},{"name":".github","children":[{"name":"FUNDING.yml","path":".github/FUNDING.yml","sha":"566a763464130563a50fc4215208b2c774379b02"},{"name":"ISSUE_TEMPLATE","children":[{"name":"bug_report.md","path":".github/ISSUE_TEMPLATE/bug_report.md","sha":"d2e87e27c601e423865ed660ec697082470ca60f"},{"name":"feature_request.md","path":".github/ISSUE_TEMPLATE/feature_request.md","sha":"023a33099be2336476930c96e17ff1ba5dc55348"}]},{"name":"pull_request_template.md","path":".github/pull_request_template.md","sha":"32715d22010f81b4805e180f6ce3a503570f42a4"}]},{"name":".gitignore","path":".gitignore","sha":"91612eda73b4a152b6df107e01987d66a0292405"},{"name":".gon_amd64.hcl","path":".gon_amd64.hcl","sha":"44b58e7e1fc3fae87fa285f1f52aa6ee6c50d853"},{"name":".gon_arm64.hcl","path":".gon_arm64.hcl","sha":"6b97f386073c1c3a359405ed46aec20488eed1e1"},{"name":"CODEOWNERS","path":"CODEOWNERS","sha":"8ba0a5b507c530688dfe1cb071d04738d5c89b00"},{"name":"CONTRIBUTING.md","path":"CONTRIBUTING.md","sha":"bdf61efcd779faccd6eb524ae5e9a3f9031490aa"},{"name":"LICENSE","path":"LICENSE","sha":"796e2195629294b73e19304788728030c8cba81d"},{"name":"NOTICE","path":"NOTICE","sha":"f19e55a1e66ab14492f91d7523bb4f9a693617e8"},{"name":"README.md","path":"README.md","sha":"25ae5a2cdf383c469ab61f7d8c979a88438e3fc3","toggled":true},{"name":"cmd","children":[{"name":".gitignore","path":"cmd/.gitignore","sha":"29ab11f52f98e413779a989bc072dc8f09047c02"},{"name":"common.go","path":"cmd/common.go","sha":"86eb415afeb0d6b49b3883cf946bd50cdee775e3"},{"name":"common_test.go","path":"cmd/common_test.go","sha":"3ac440c147f32c9826a56184e3695bbdf66a2139"},{"name":"eks.go","path":"cmd/eks.go","sha":"9a4dad6e4cfac9358a65e1dd8f892c6738259b24"},{"name":"eks","children":[{"name":"types.go","path":"cmd/eks/types.go","sha":"e2495aa25c65ebd45798932126cbeb7120da3dde"}]},{"name":"errors.go","path":"cmd/errors.go","sha":"70e0a9376c9a6e2736b72788850db4825b6af8f0"},{"name":"k8s.go","path":"cmd/k8s.go","sha":"49e1e8db0a0cdac5207f94265141210a025428bd"},{"name":"main.go","path":"cmd/main.go","sha":"d779eb1d2c036d30ccf5c81f4c50b41b69689aab"},{"name":"tls.go","path":"cmd/tls.go","sha":"21aef54ae21aef672269f2573ff43538f9567d6c"}]},{"name":"commonerrors","children":[{"name":"commonerrors.go","path":"commonerrors/commonerrors.go","sha":"f3e0d9e49eb44a4e68a1132073af84770a2c2178"}]},{"name":"eks","children":[{"name":"asg.go","path":"eks/asg.go","sha":"dbbb8d81a612ca75703f7b875695fc836e81ef8a"},{"name":"asg_test.go","path":"eks/asg_test.go","sha":"e85271972467e4a8a8e202fd587d8708939883fe"},{"name":"cleanup.go","path":"eks/cleanup.go","sha":"54a452daaf343b5faa7c01a69f62654432215921"},{"name":"cleanup_test.go","path":"eks/cleanup_test.go","sha":"09eb2d0e26907056fe80e44851adbc3031a9bc04"},{"name":"cluster.go","path":"eks/cluster.go","sha":"c8d5465c9c4a71a04f0289a7b8eb9fbdca84276a"},{"name":"coredns.go","path":"eks/coredns.go","sha":"07c57fd73161d24415c4f06c3f9f58120eca76b8"},{"name":"deploy.go","path":"eks/deploy.go","sha":"5a5ca4720b72695ebbb8162946bea79313f60053"},{"name":"deploy_state.go","path":"eks/deploy_state.go","sha":"f53617f11630ecddbd08f5dec78e5b75936a7a8b"},{"name":"deploy_state_test.go","path":"eks/deploy_state_test.go","sha":"2d4860f3d86a40908c4e7af07405a4f4bcb65429"},{"name":"drain.go","path":"eks/drain.go","sha":"413798a771c89da7508089f78414b7ae08cf018e"},{"name":"eks.go","path":"eks/eks.go","sha":"ddbdd69bfe360b2e25f0864c087c16280ea8bd19"},{"name":"elb.go","path":"eks/elb.go","sha":"29ad1e5d971b2da11a1ff05c36ca64e1c7f4c2c5"},{"name":"errors.go","path":"eks/errors.go","sha":"26125a9f71f5a8a011ea7ebb6f29f7905dec8f0a"},{"name":"fixture","children":[{"name":"aws-k8s-cni.yaml","path":"eks/fixture/aws-k8s-cni.yaml","sha":"8481ff0304e826d962732d8658d52a4a69e2226c"},{"name":"cleanup-test","children":[{"name":"attached-ni","children":[{"name":"main.tf","path":"eks/fixture/cleanup-test/attached-ni/main.tf","sha":"47317cb29be7b3c3052587a2eff66826d2987ff6"},{"name":"outputs.tf","path":"eks/fixture/cleanup-test/attached-ni/outputs.tf","sha":"f4d0d7bfb1e6c60647293ae9dfe4a45735a35bc2"},{"name":"variables.tf","path":"eks/fixture/cleanup-test/attached-ni/variables.tf","sha":"5a627a7a4eae6c7cec5654f5ebfacd64534a1239"}]},{"name":"unattached-ni","children":[{"name":"main.tf","path":"eks/fixture/cleanup-test/unattached-ni/main.tf","sha":"a25567204c1f883b38dc807f0eac819d43939bbd"},{"name":"outputs.tf","path":"eks/fixture/cleanup-test/unattached-ni/outputs.tf","sha":"7884d48b89317a082434fdd5e379135546fa2774"},{"name":"variables.tf","path":"eks/fixture/cleanup-test/unattached-ni/variables.tf","sha":"5a627a7a4eae6c7cec5654f5ebfacd64534a1239"}]}]}]},{"name":"instances.go","path":"eks/instances.go","sha":"cdbd2f28d7f24784dd0b39d1cecc349e0f8ff6fc"},{"name":"instances_test.go","path":"eks/instances_test.go","sha":"e376fd254922f766397380bd1eeb381ff9731426"},{"name":"kubectl_configure.go","path":"eks/kubectl_configure.go","sha":"448aae5621ccf92350ee66317c36d386fdef2208"},{"name":"kubectl_configure_test.go","path":"eks/kubectl_configure_test.go","sha":"5802ad06e614eeff5981ac08198d97f48d55b18e"},{"name":"oidc.go","path":"eks/oidc.go","sha":"7317c597a37a6f832dec35419fd358e7e9e513de"},{"name":"oidc_test.go","path":"eks/oidc_test.go","sha":"6b5ba03fdaaf2954f2b5efd8a5936ce28e37390e"},{"name":"sync.go","path":"eks/sync.go","sha":"968d7a4b4cf922afe6d73e47fa04440123d8ce5b"},{"name":"sync_test.go","path":"eks/sync_test.go","sha":"ee45348617aa318963427d33013e8092ca7bef4b"},{"name":"tls.go","path":"eks/tls.go","sha":"9c09306e9c5bff6d3fdf27a12f855093387f8c36"}]},{"name":"eksawshelper","children":[{"name":"arn.go","path":"eksawshelper/arn.go","sha":"0def4d85947963b79516fac8074fbd6ed1d54358"},{"name":"arn_test.go","path":"eksawshelper/arn_test.go","sha":"65921f3a8bc0f22f8fc4b926ab19f514cd0fa694"},{"name":"client.go","path":"eksawshelper/client.go","sha":"e2f86c1281ff172792511078667b1a3741dadeaa"},{"name":"cluster.go","path":"eksawshelper/cluster.go","sha":"304a8f1b2b1d267a6e614e6abdf2aa839d3718a3"},{"name":"ecr.go","path":"eksawshelper/ecr.go","sha":"8b85e21fd669c24ec04a155450e3ffda160d9d1d"},{"name":"ecr_test.go","path":"eksawshelper/ecr_test.go","sha":"fa1f4c969b62434b5c9f5b499092f3fd74a8875e"},{"name":"eksawshelper.go","path":"eksawshelper/eksawshelper.go","sha":"0f9a14eeadab257cc27f947191b388e6aba24375"},{"name":"errors.go","path":"eksawshelper/errors.go","sha":"76885a5739ab5be70df6cad419db182975cb5f82"}]},{"name":"go.mod","path":"go.mod","sha":"33bb3164b86bb732d1e46d365f861c7fb30dfc93"},{"name":"go.sum","path":"go.sum","sha":"317095bd72a90d73c52b47eae42e4da807d7cad2"},{"name":"jsonpatch","children":[{"name":"jsonpatch.go","path":"jsonpatch/jsonpatch.go","sha":"e3e922deda40f45b7e2124994d909b1f47076fec"}]},{"name":"kubectl","children":[{"name":"client.go","path":"kubectl/client.go","sha":"6d7359fa0838ee0101a52636e018434b8dfe90d2"},{"name":"command.go","path":"kubectl/command.go","sha":"04e020648c1d0f1151d07cefb5eee5f9b2afc722"},{"name":"config.go","path":"kubectl/config.go","sha":"f87860ffd081c70473cf22580b5fdb061717cb42"},{"name":"config_test.go","path":"kubectl/config_test.go","sha":"59d6b29e450b5827197864d710688764f9c80810"},{"name":"errors.go","path":"kubectl/errors.go","sha":"5ff25b9bf0548b6d40e4e3ffbb98f05eb9610886"},{"name":"helpers.go","path":"kubectl/helpers.go","sha":"6d1794daeaa29656eec6b9b1a59914a618201178"},{"name":"ingress.go","path":"kubectl/ingress.go","sha":"b4e3ab5fb0b923c22af3f505c9353fe33935c2b8"},{"name":"ingress_test.go","path":"kubectl/ingress_test.go","sha":"01b1916f891b59e27dba656e0f387cd2e00f19a2"},{"name":"kubectl.go","path":"kubectl/kubectl.go","sha":"d730eba845a51c993a688a5cfcbd583eda2d169a"},{"name":"node.go","path":"kubectl/node.go","sha":"3a0072ee93a7f24fc114d4795ad2047745acee01"},{"name":"node_test.go","path":"kubectl/node_test.go","sha":"748f33f08e0a8209cfcc71b8b918b38b4a71ed1e"},{"name":"options.go","path":"kubectl/options.go","sha":"f957d3af97794e1a94d2026b78c6cb2677e6b156"},{"name":"pod.go","path":"kubectl/pod.go","sha":"acf442f26ee13566913f9fd06319b7e65f9dd748"},{"name":"pod_test.go","path":"kubectl/pod_test.go","sha":"5144ff984fa14fbf4f29f557f11386316b03c595"},{"name":"role.go","path":"kubectl/role.go","sha":"84e42dfd290e77793a79e7921e6f4797eb34156e"},{"name":"role_test.go","path":"kubectl/role_test.go","sha":"29212e92c41f743296de4abb00d2a2539f9b49fa"},{"name":"rolebinding.go","path":"kubectl/rolebinding.go","sha":"7b8ff704952683517726a198217a1fcd75df036f"},{"name":"secret.go","path":"kubectl/secret.go","sha":"e46cb871eefa7b31d5c64f32f40b803ac90b83b1"},{"name":"secret_test.go","path":"kubectl/secret_test.go","sha":"34fc09f3dad8d871dc76de1c446fd0aa7c94d32a"},{"name":"service.go","path":"kubectl/service.go","sha":"bc1805a7764ba84ac5382fff0f0b7b553f331c15"},{"name":"service_test.go","path":"kubectl/service_test.go","sha":"7aa4e32886c67b5a14fc1f463e804c007ba30717"},{"name":"test_helpers.go","path":"kubectl/test_helpers.go","sha":"b33736b8a8c4d195f02bdd0fc050779e56a7889b"},{"name":"types.go","path":"kubectl/types.go","sha":"f45c42439dc87d502b51bf8285680cf0792830ad"},{"name":"validate.go","path":"kubectl/validate.go","sha":"069e7b6f769598234e807e9fda7b22078a089b85"}]},{"name":"logging","children":[{"name":"logging.go","path":"logging/logging.go","sha":"d69dea6863cae09fe36370a6473c61bb062b5b8b"}]},{"name":"tls","children":[{"name":"cert_common.go","path":"tls/cert_common.go","sha":"4e637e3773a83c420c0d28aa045e3f4f56d04156"},{"name":"cert_common_test.go","path":"tls/cert_common_test.go","sha":"b0b2beb6c95abdfeb0ba7c665bc6228250e55a0a"},{"name":"ecdsa_cert.go","path":"tls/ecdsa_cert.go","sha":"89deffaacadda9ee34e8c0e2d8f36fef61279b00"},{"name":"ecdsa_cert_test.go","path":"tls/ecdsa_cert_test.go","sha":"69ef2cd2c87e4d1b3f8b9395a75639b808d35e7a"},{"name":"ecdsa_keys.go","path":"tls/ecdsa_keys.go","sha":"1886828415cc28bf508f45c8d466dc654ba8532b"},{"name":"ecdsa_keys_test.go","path":"tls/ecdsa_keys_test.go","sha":"e3f1b860b318dac3d3d68f4d516989888d476be3"},{"name":"errors.go","path":"tls/errors.go","sha":"0ba6fad3115f66aa682c6eb222c8de6f54b8b5eb"},{"name":"gencmd.go","path":"tls/gencmd.go","sha":"828808c03568d1ea208367071650241f0edeba95"},{"name":"gencmd_test.go","path":"tls/gencmd_test.go","sha":"14dee7c2ec73b3db64f96bd18e6edc360601c8f8"},{"name":"options.go","path":"tls/options.go","sha":"2f1929fd8b4b8cb286f6ebc91a06629a78747211"},{"name":"options_test.go","path":"tls/options_test.go","sha":"58b01a9f5632e539d090ce3ee30160beb4e54d7a"},{"name":"pem.go","path":"tls/pem.go","sha":"35f65d549effd2b763aad430a2da36d89139d6a9"},{"name":"rsa_cert.go","path":"tls/rsa_cert.go","sha":"e10230d0a0e3fd50c31bf625a7034e20cbf230bb"},{"name":"rsa_cert_test.go","path":"tls/rsa_cert_test.go","sha":"9e27a262de8944eadd1dadcf86831c877e85bcce"},{"name":"rsa_keys.go","path":"tls/rsa_keys.go","sha":"47ebd40802381f86626a8a8866e5a8fd239ce44b"},{"name":"rsa_keys_test.go","path":"tls/rsa_keys_test.go","sha":"1e5ff9c4b1dad9f86592af176fa1ec2868376fc5"},{"name":"test_helpers.go","path":"tls/test_helpers.go","sha":"03b0898c000b35649f6dd05c77f7851e29ae69b0"},{"name":"testfixtures","children":[{"name":"ca.cert","path":"tls/testfixtures/ca.cert","sha":"8c1c6e1110b3f21b60b8fb46906deea36f878f37"},{"name":"ca.key.pem","path":"tls/testfixtures/ca.key.pem","sha":"ea1c25f73e666a0cee970887e7adea73c02138da"},{"name":"ca.pub","path":"tls/testfixtures/ca.pub","sha":"c814e7e09c09871a4408010a0c99fcf9c4f2aef5"},{"name":"tiller.cert","path":"tls/testfixtures/tiller.cert","sha":"de50042102286d9bd04e9c8c863a52e3ebb03681"},{"name":"tiller.key.pem","path":"tls/testfixtures/tiller.key.pem","sha":"dce47300da0d908c6ed0db0e802e22c5082822c4"},{"name":"tiller.pub","path":"tls/testfixtures/tiller.pub","sha":"3b5e902f177caa6720abc3ba26d19b39487bcc69"}]},{"name":"tls.go","path":"tls/tls.go","sha":"66d46f6cc5fde7ca3edbbfcd61c04a17114443a6"}]}]},"detailsContent":"<p><a href=\"https://gruntwork.io/?ref=repo_kubergrunt\" class=\"preview__body--description--blue\" target=\"_blank\"><img src=\"https://img.shields.io/badge/maintained%20by-gruntwork.io-%235849a6.svg\" alt=\"Maintained by Gruntwork.io\" class=\"preview__body--diagram\"></a>\n<a href=\"#open_modal\" class=\"preview__body--description--blue\"><img src=\"https://img.shields.io/github/tag/gruntwork-io/kubergrunt.svg?label=latest\" alt=\"GitHub tag (latest SemVer)\" class=\"preview__body--diagram\"></a></p>\n<h1 class=\"preview__body--title\" id=\"kubergrunt\">kubergrunt</h1><div class=\"preview__body--border\"></div><p><code>kubergrunt</code> is a standalone go binary with a collection of commands that attempts to fill in the gaps between Terraform,\nHelm, and Kubectl for managing a Kubernetes Cluster.</p>\n<p>Some of the features of <code>kubergrunt</code> include:</p>\n<ul>\n<li>Configuring <code>kubectl</code> to authenticate with a given EKS cluster. Learn more about authenticating <code>kubectl</code> to EKS\nin the <a href=\"https://gruntwork.io/guides/kubernetes/how-to-deploy-production-grade-kubernetes-cluster-aws/#authenticate\" class=\"preview__body--description--blue\" target=\"_blank\">our production deployment guide</a>.</li>\n<li>Managing Helm and associated TLS certificates on any Kubernetes cluster.</li>\n<li>Setting up Helm client with TLS certificates on any Kubernetes cluster.</li>\n<li>Generating TLS certificate key pairs and storing them as Kubernetes <code>Secrets</code> on any Kubernetes cluster.</li>\n</ul>\n<h2 class=\"preview__body--subtitle\" id=\"installation\">Installation</h2>\n<p>The binaries are all built as part of the CI pipeline on each release of the package, and is appended to the\ncorresponding release in the <a href=\"/repos/releases\" class=\"preview__body--description--blue\">Releases Page</a>. You can download the corresponding binary for your\nplatform from the releases page.</p>\n<p>Alternatively, you can install <code>kubergrunt</code> using the <a href=\"/repos/gruntwork-installer\" class=\"preview__body--description--blue\">Gruntwork\nInstaller</a>. For example, to install version <code>v0.5.13</code>:</p>\n<pre><span class=\"hljs-string\">gruntwork-install </span><span class=\"hljs-built_in\">--binary-name</span> <span class=\"hljs-string\">\"kubergrunt\"</span> <span class=\"hljs-built_in\">--repo</span> <span class=\"hljs-string\">\"https://github.com/gruntwork-io/kubergrunt\"</span> <span class=\"hljs-built_in\">--tag</span> <span class=\"hljs-string\">\"v0.5.13\"</span>\n</pre>\n<h3 class=\"preview__body--subtitle\" id=\"3rd-party-package-managers\">3rd party package managers</h3>\n<p>Note that third-party Kubergrunt packages may not be updated with the latest version, but are often close. Please check your version against the latest available on the <a href=\"/repos/releases\" class=\"preview__body--description--blue\">Releases Page</a>.</p>\n<p>Chocolatey (Windows):</p>\n<pre>choco <span class=\"hljs-keyword\">install</span> kubergrunt\n</pre>\n<h3 class=\"preview__body--subtitle\" id=\"aws-cli-authentication\">AWS CLI authentication</h3>\n<p>You need to authenticate with the AWS CLI before you can run kubergrunt/eksctl commands, please see our <a href=\"https://blog.gruntwork.io/a-comprehensive-guide-to-authenticating-to-aws-on-the-command-line-63656a686799\" class=\"preview__body--description--blue\" target=\"_blank\">authentication guide</a></p>\n<h2 class=\"preview__body--subtitle\" id=\"building-from-source\">Building from source</h2>\n<p>The main package is in <code>cmd</code>. To build the binary, you can run:</p>\n<pre><span class=\"hljs-symbol\">go</span> <span class=\"hljs-keyword\">build </span>-o <span class=\"hljs-keyword\">bin/kubergrunt </span>./cmd\n</pre>\n<p>If you need to set a version on the binary (so that <code>kubergrunt --version</code> works), you use <code>ldflags</code> to set the version\nstring on the compiled binary:</p>\n<pre>go build -o kubergrunt -ldflags <span class=\"hljs-string\">\"-X main.VERSION=v0.7.6 -extldflags '-static'\"</span> ./<span class=\"hljs-keyword\">cmd</span><span class=\"bash\">\n</span></pre>\n<h2 class=\"preview__body--subtitle\" id=\"commands\">Commands</h2>\n<p>The following commands are available as part of <code>kubergrunt</code>:</p>\n<ol>\n<li><a href=\"#eks\" class=\"preview__body--description--blue\">eks</a>\n<ul>\n<li><a href=\"#verify\" class=\"preview__body--description--blue\">verify</a></li>\n<li><a href=\"#configure\" class=\"preview__body--description--blue\">configure</a></li>\n<li><a href=\"#token\" class=\"preview__body--description--blue\">token</a></li>\n<li><a href=\"#oidc-thumbprint\" class=\"preview__body--description--blue\">oidc-thumbprint</a></li>\n<li><a href=\"#deploy\" class=\"preview__body--description--blue\">deploy</a></li>\n<li><a href=\"#sync-core-components\" class=\"preview__body--description--blue\">sync-core-components</a></li>\n<li><a href=\"#cleanup-security-group\" class=\"preview__body--description--blue\">cleanup-security-group</a></li>\n<li><a href=\"#schedule-coredns\" class=\"preview__body--description--blue\">schedule-coredns</a></li>\n<li><a href=\"#drain\" class=\"preview__body--description--blue\">drain</a></li>\n</ul>\n</li>\n<li><a href=\"#k8s\" class=\"preview__body--description--blue\">k8s</a>\n<ul>\n<li><a href=\"#wait-for-ingress\" class=\"preview__body--description--blue\">wait-for-ingress</a></li>\n<li><a href=\"#kubectl\" class=\"preview__body--description--blue\">kubectl</a></li>\n</ul>\n</li>\n<li><a href=\"#tls\" class=\"preview__body--description--blue\">tls</a>\n<ul>\n<li><a href=\"#gen\" class=\"preview__body--description--blue\">gen</a></li>\n</ul>\n</li>\n<li><a href=\"#deprecated-commands\" class=\"preview__body--description--blue\">Deprecated commands</a>\n<ul>\n<li><a href=\"#helm\" class=\"preview__body--description--blue\">helm</a></li>\n</ul>\n</li>\n</ol>\n<h3 class=\"preview__body--subtitle\" id=\"eks\">eks</h3>\n<p>The <code>eks</code> subcommand of <code>kubergrunt</code> is used to setup the operator machine to interact with a Kubernetes cluster running\non EKS.</p>\n<h4 id=\"verify\">verify</h4>\n<p>This subcommand verifies that the specified EKS cluster is up and ready. An EKS cluster is considered ready when:</p>\n<ul>\n<li>The cluster status reaches ACTIVE state.</li>\n<li>The cluster Kubernetes API server endpoint responds to http requests.</li>\n</ul>\n<p>When passing <code>--wait</code> to the command, this command will wait until the EKS cluster reaches the ready state, or it\ntimes out. The timeout parameters are configurable with the <code>--max-retries</code> and <code>--sleep-between-retries</code> options, where\n<code>--max-retries</code> specifies the number of times the command will try to verify a specific condition before giving up, and\n<code>--sleep-between-retries</code> specifies the duration of time (e.g 10m = 10 minutes) to wait between each trial. So for\nexample, if you ran the command:</p>\n<pre><span class=\"hljs-comment\">kubergrunt</span> <span class=\"hljs-comment\">eks</span> <span class=\"hljs-comment\">verify</span> --<span class=\"hljs-comment\">eks</span><span class=\"hljs-literal\">-</span><span class=\"hljs-comment\">cluster</span><span class=\"hljs-literal\">-</span><span class=\"hljs-comment\">arn</span> <span class=\"hljs-comment\">$EKS_CLUSTER_ARN</span> --<span class=\"hljs-comment\">wait</span> --<span class=\"hljs-comment\">max</span><span class=\"hljs-literal\">-</span><span class=\"hljs-comment\">retries</span> <span class=\"hljs-comment\">10</span> --<span class=\"hljs-comment\">sleep</span><span class=\"hljs-literal\">-</span><span class=\"hljs-comment\">between</span><span class=\"hljs-literal\">-</span><span class=\"hljs-comment\">retries</span> <span class=\"hljs-comment\">15s</span>\n</pre>\n<p>and the cluster was not active yet, this command will query the AWS API up to 10 times, waiting 15 seconds inbetween\neach try for a total of 150 seconds (2.5 minutes) before timing out.</p>\n<p>Run <code>kubergrunt eks verify --help</code> to see all the available options.</p>\n<p>Similar Commands:</p>\n<ul>\n<li>AWS CLI (<code>aws eks wait</code>): This command will wait until the EKS cluster reaches the ACTIVE state. Note that oftentimes\nthe Kubernetes API endpoint has a delay in accepting traffic even after reaching the ACTIVE state. We have observed it\ntake up to 1.5 minutes after the cluster becomes ACTIVE before we can have a valid TCP connection with the Kubernetes\nAPI endpoint.</li>\n</ul>\n<h4 id=\"configure\">configure</h4>\n<p>This subcommand will setup the installed <code>kubectl</code> with config contexts that will allow it to authenticate to a\nspecified EKS cluster by leveraging the <code>kubergrunt eks token</code> command. This binary is designed to be used as part of\none of the modules in the package, although this binary supports running as a standalone binary. For example, this\nbinary might be used to setup a new operator machine to be able to talk to an existing EKS cluster.</p>\n<p>For example to setup a <code>kubectl</code> install on an operator machine to authenticate with EKS:</p>\n<pre>kubergrunt eks configure --eks-<span class=\"hljs-keyword\">cluster</span>-arn $EKS_CLUSTER_ARN\n</pre>\n<p>Run <code>kubergrunt eks configure --help</code> to see all the available options.</p>\n<p>Similar Commands:</p>\n<ul>\n<li>AWS CLI (<code>aws eks update-kubeconfig</code>): This command will configure <code>kubeconfig</code> in a similar manner. Instead of using\n<code>kubergrunt eks token</code>, this version will use the <code>get-token</code> subcommand built into the AWS CLI.</li>\n</ul>\n<h4 id=\"token\">token</h4>\n<p>This subcommand is used by <code>kubectl</code> to retrieve an authentication token using the AWS API authenticated with IAM\ncredentials. This token is then used to authenticate to the Kubernetes cluster. This command embeds the\n<code>aws-iam-authenticator</code> tool into <code>kubergrunt</code> so that operators don't have to install a separate tool to manage\nauthentication into Kubernetes.</p>\n<p>The <code>configure</code> subcommand of <code>kubergrunt eks</code> assumes you will be using this method to authenticate with the Kubernetes\ncluster provided by EKS. If you wish to use <code>aws-iam-authenticator</code> instead, replace the auth info clause of the <code>kubectl</code>\nconfig context.</p>\n<p>This subcommand also supports outputting the token in a format that is consumable by terraform as an <a href=\"https://www.terraform.io/docs/providers/external/data_source.html\" class=\"preview__body--description--blue\" target=\"_blank\">external data\nsource</a> when you pass in the <code>--as-tf-data</code> CLI arg.\nYou can then pass the token directly into the <code>kubernetes</code> provider configuration. For example:</p>\n<pre><span class=\"hljs-comment\"># <span class=\"hljs-doctag\">NOTE:</span> Terraform does not allow you to interpolate resources in a provider config. We work around this by using the</span>\n<span class=\"hljs-comment\"># template_file data source as a means to compute the resource interpolations.</span>\n<span class=\"hljs-keyword\">provider</span> <span class=\"hljs-string\">\"kubernetes\"</span> {\n load_config_file = false\n host = <span class=\"hljs-string\">\"<span class=\"hljs-variable\">${data.template_file.kubernetes_cluster_endpoint.rendered}</span>\"</span>\n cluster_ca_certificate = <span class=\"hljs-string\">\"<span class=\"hljs-variable\">${<span class=\"hljs-meta\">base64decode(data.template_file.kubernetes_cluster_ca.rendered)</span>}</span>\"</span>\n token = <span class=\"hljs-string\">\"<span class=\"hljs-variable\">${<span class=\"hljs-meta\">lookup(data.external.kubernetes_token.result, <span class=\"hljs-string\">\"token_data\"</span>)</span>}</span>\"</span>\n}\n\n<span class=\"hljs-keyword\">data</span> <span class=\"hljs-string\">\"template_file\"</span> <span class=\"hljs-string\">\"kubernetes_cluster_endpoint\"</span> {\n template = <span class=\"hljs-string\">\"<span class=\"hljs-variable\">${module.eks_cluster.eks_cluster_endpoint}</span>\"</span>\n}\n\n<span class=\"hljs-keyword\">data</span> <span class=\"hljs-string\">\"template_file\"</span> <span class=\"hljs-string\">\"kubernetes_cluster_ca\"</span> {\n template = <span class=\"hljs-string\">\"<span class=\"hljs-variable\">${module.eks_cluster.eks_cluster_certificate_authority}</span>\"</span>\n}\n\n<span class=\"hljs-keyword\">data</span> <span class=\"hljs-string\">\"external\"</span> <span class=\"hljs-string\">\"kubernetes_token\"</span> {\n program = [<span class=\"hljs-string\">\"kubergrunt\"</span>, <span class=\"hljs-string\">\"--loglevel\"</span>, <span class=\"hljs-string\">\"error\"</span>, <span class=\"hljs-string\">\"eks\"</span>, <span class=\"hljs-string\">\"token\"</span>, <span class=\"hljs-string\">\"--as-tf-data\"</span>, <span class=\"hljs-string\">\"--cluster-id\"</span>, <span class=\"hljs-string\">\"<span class=\"hljs-variable\">${module.eks_cluster.eks_cluster_name}</span>\"</span>]\n}\n</pre>\n<p>This will configure the <code>kubernetes</code> provider in Terraform without setting up kubeconfig, allowing you to do everything\nin Terraform without side effects to your local machine.</p>\n<p>Similar Commands:</p>\n<ul>\n<li>AWS CLI (<code>aws eks get-token</code>): This command will do the same thing, but does not provide any specific optimizations\nfor terraform.</li>\n<li>Terraform <a href=\"https://www.terraform.io/docs/providers/aws/d/eks_cluster_auth.html\" class=\"preview__body--description--blue\" target=\"_blank\"><code>aws_eks_cluster_auth</code></a> data source:\nThis data source can be used to retrieve a temporary auth token for EKS in Terraform. This can only be used in\nTerraform.</li>\n<li><a href=\"https://github.com/kubernetes-sigs/aws-iam-authenticator\" class=\"preview__body--description--blue\" target=\"_blank\"><code>aws-iam-authenticator</code></a>: This is a standalone binary that\ncan be used to fetch a temporary auth token.</li>\n</ul>\n<h4 id=\"oidc-thumbprint\">oidc-thumbprint</h4>\n<p>This subcommand will take the EKS OIDC Issuer URL and retrieve the root CA thumbprint. This is used to set the trust\nrelation for any certificates signed by that CA for the issuer domain. This is necessary to setup the OIDC provider,\nwhich is used for the IAM Roles for Service Accounts feature of EKS.</p>\n<p>You can read more about the general procedure for retrieving the root CA thumbprint of an OIDC Provider in <a href=\"https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc_verify-thumbprint.html\" class=\"preview__body--description--blue\" target=\"_blank\">the official\ndocumentation</a>.</p>\n<p>To retrieve the thumbprint, call the command with the issuer URL:</p>\n<pre><span class=\"hljs-attribute\">kubergrunt</span> eks oidc-thumbprint --issuer-url <span class=\"hljs-variable\">$ISSUER_URL</span>\n</pre>\n<p>This will output the thumbprint to stdout in JSON format, with the key <code>thumbprint</code>.</p>\n<p>Run <code>kubergrunt eks oidc-thumbprint --help</code> to see all the available options.</p>\n<p>Similar Commands:</p>\n<ul>\n<li>You can use <code>openssl</code> to retrieve the thumbprint as described by <a href=\"https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc_verify-thumbprint.html\" class=\"preview__body--description--blue\" target=\"_blank\">the official\ndocumentation</a>.</li>\n<li><code>eksctl</code> provides routines for directly configuring the OIDC provider so you don't need to retrieve the thumbprint.</li>\n</ul>\n<h4 id=\"deploy\">deploy</h4>\n<p>This subcommand will initiate a rolling deployment of the current AMI config to the EC2 instances in your EKS cluster.\nThis command will not deploy or update an application deployed on your Kubernetes cluster (e.g <code>Deployment</code> resource,\n<code>Pod</code> resource, etc). We provide helm charts that you can use to deploy your applications on to a Kubernetes cluster.\nSee our <a href=\"/repos/helm-kubernetes-services\" class=\"preview__body--description--blue\"><code>helm-kubernetes-services</code> repo</a> for more info.\nInstead, this command is for managing and deploying an update to the EC2 instances underlying your EKS cluster.</p>\n<p>Terraform and AWS do not provide a way to automatically roll out a change to the Instances in an EKS Cluster. Due to\nTerraform limitations (see <a href=\"https://github.com/terraform-providers/terraform-provider-aws/issues/567\" class=\"preview__body--description--blue\" target=\"_blank\">here for a\ndiscussion</a>), there is currently no way to\nimplement this purely in Terraform code. Therefore, we've created this subcommand that can do a zero-downtime roll out\nfor you.</p>\n<p>To deploy a change (such as rolling out a new AMI) to all EKS workers using this command:</p>\n<ol>\n<li>Make sure the <code>cluster_max_size</code> is at least twice the size of <code>cluster_min_size</code>. The extra capacity will be used to\ndeploy the updated instances.</li>\n<li>Update the Terraform code with your changes (e.g. update the <code>cluster_instance_ami</code> variable to a new AMI).</li>\n<li>Run <code>terraform apply</code>.</li>\n<li>Run the command:</li>\n</ol>\n<pre>kubergrunt eks <span class=\"hljs-keyword\">deploy</span> <span class=\"hljs-params\">--region</span> REGION <span class=\"hljs-params\">--asg-name</span> ASG_NAME\n</pre>\n<p>When you call the command, it will:</p>\n<ol>\n<li>Double the desired capacity of the Auto Scaling Group that powers the EKS Cluster. This will launch new EKS workers\nwith the new launch configuration.</li>\n<li>Wait for the new nodes to be ready for Pod scheduling in Kubernetes. This includes waiting for the new nodes to be\nregistered to any external load balancers managed by Kubernetes.</li>\n<li>Cordon the old instances in the ASG so that they won't schedule new Pods.</li>\n<li>Drain the pods scheduled on the old EKS workers (using the equivalent of <code>kubectl drain</code>), so that they will be\nrescheduled on the new EKS workers.</li>\n<li>Wait for all the pods to migrate off of the old EKS workers.</li>\n<li>Set the desired capacity down to the original value and remove the old EKS workers from the ASG.</li>\n</ol>\n<p>Note that to minimize service disruption from this command, your services should setup <a href=\"https://kubernetes.io/docs/tasks/run-application/configure-pdb/\" class=\"preview__body--description--blue\" target=\"_blank\">a\nPodDisruptionBudget</a>, <a href=\"https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/#define-readiness-probes\" class=\"preview__body--description--blue\" target=\"_blank\">a readiness\nprobe</a>\nthat fails on container shutdown events, and implement graceful handling of SIGTERM in the container. You can learn more\nabout these features in <a href=\"https://blog.gruntwork.io/zero-downtime-server-updates-for-your-kubernetes-cluster-902009df5b33\" class=\"preview__body--description--blue\" target=\"_blank\">our blog post series covering\nthem</a>.</p>\n<p>Currently <code>kubergrunt</code> does not implement any checks for these resources to be implemented. However in the future, we\nplan to bake in checks into the deployment command to verify that all services have a disruption budget set, and warn\nthe user of any services that do not have a check.</p>\n<p><strong><code>eks deploy</code> recovery file</strong></p>\n<p>Due to the nature of rolling update, the <code>deploy</code> subcommand performs multiple sequential actions that\ndepend on success of the previous operations. To mitigate intermittent failures, the <code>deploy</code> subcommand creates a\nrecovery file in the working directory for storing current deploy state. The recovery file is updated after\neach stage and if the <code>deploy</code> subcommand fails for some reason, execution resumes from the last successful state.\nThe existing recovery file can also be ignored with the <code>--ignore-recovery-file</code> flag. In this case the recovery\nfile will be re-initialized.</p>\n<h4 id=\"sync-core-components\">sync-core-components</h4>\n<p>This subcommand will sync the core components of an EKS cluster to match the deployed Kubernetes version by following\nthe steps listed <a href=\"https://docs.aws.amazon.com/eks/latest/userguide/update-cluster.html\" class=\"preview__body--description--blue\" target=\"_blank\">in the official documentation</a>.</p>\n<p>The core components managed by this command are:</p>\n<ul>\n<li>kube-proxy</li>\n<li>Amazon VPC CNI plug-in</li>\n<li>CoreDNS</li>\n</ul>\n<p>By default, this command will rotate the images without waiting for the Pods to be redeployed. You can use the <code>--wait</code>\noption to force the command to wait until all the Pods have been replaced.</p>\n<p>Example:</p>\n<pre>kubergrunt eks sync-core-components <span class=\"hljs-comment\">--eks-cluster-arn EKS_CLUSTER_ARN</span>\n</pre>\n<h4 id=\"cleanup-security-group\">cleanup-security-group</h4>\n<p>This subcommand cleans up the leftover AWS-managed security groups that are associated with an EKS cluster you intend\nto destroy. It accepts</p>\n<ul>\n<li><code>--eks-cluster-arn</code>: the ARN of the EKS cluster</li>\n<li><code>--security-group-id</code>: a known security group ID associated with the EKS cluster</li>\n<li><code>--vpc-id</code>: the VPC ID where the cluster is located</li>\n</ul>\n<p>It also looks for other security groups associated with the EKS cluster, such as the security group created by the AWS\nLoad Balancer Controller. To safely delete these resources, it detaches and deletes any associated AWS Elastic Network\nInterfaces.</p>\n<p>Example:</p>\n<pre>kubergrunt eks cleanup-<span class=\"hljs-keyword\">security</span>-<span class=\"hljs-keyword\">group</span> <span class=\"hljs-comment\">--eks-cluster-arn EKS_CLUSTER_ARN --security-group-id SECURITY_GROUP_ID \\</span>\n<span class=\"hljs-comment\">--vpc-id VPC_ID</span>\n</pre>\n<h4 id=\"schedule-coredns\">schedule-coredns</h4>\n<p>This subcommand can be used to toggle the CoreDNS service between scheduling on Fargate and EC2 worker types. During\nthe creation of an EKS cluster that uses Fargate, <code>schedule-coredns fargate</code> will annotate the deployment so that\nCoreDNS can find and allow EKS to use Fargate nodes. To switch back to EC2, you can run <code>schedule-coredns ec2</code> to\nreset the annotations such that EC2 nodes can be found by CoreDNS.</p>\n<p>This command is useful when creating Fargate only EKS clusters. By default, EKS will schedule the <code>coredns</code> service\nassuming EC2 workers. You can use this command to force the service to run on Fargate.</p>\n<p>You can also use this command in <code>local-exec</code> provisioners on an <code>aws_eks_fargate_profile</code> resource so you can\nschedule the CoreDNS service after creating the profile, and revert back when destroying the profile.</p>\n<p>Currently <code>fargate</code> and <code>ec2</code> are the only subcommands that <code>schedule-coredns</code> accepts.</p>\n<p>Examples:</p>\n<pre><span class=\"hljs-comment\">kubergrunt</span> <span class=\"hljs-comment\">eks</span> <span class=\"hljs-comment\">schedule</span><span class=\"hljs-literal\">-</span><span class=\"hljs-comment\">coredns</span> <span class=\"hljs-comment\">fargate</span> --<span class=\"hljs-comment\">eks</span><span class=\"hljs-literal\">-</span><span class=\"hljs-comment\">cluster</span><span class=\"hljs-literal\">-</span><span class=\"hljs-comment\">name</span> <span class=\"hljs-comment\">EKS_CLUSTER_NAME</span> --<span class=\"hljs-comment\">fargate</span><span class=\"hljs-literal\">-</span><span class=\"hljs-comment\">profile</span><span class=\"hljs-literal\">-</span><span class=\"hljs-comment\">arn</span> <span class=\"hljs-comment\">FARGATE_PROFILE_ARN</span>\n</pre>\n<pre><span class=\"hljs-comment\">kubergrunt</span> <span class=\"hljs-comment\">eks</span> <span class=\"hljs-comment\">schedule</span><span class=\"hljs-literal\">-</span><span class=\"hljs-comment\">coredns</span> <span class=\"hljs-comment\">ec2</span> --<span class=\"hljs-comment\">eks</span><span class=\"hljs-literal\">-</span><span class=\"hljs-comment\">cluster</span><span class=\"hljs-literal\">-</span><span class=\"hljs-comment\">name</span> <span class=\"hljs-comment\">EKS_CLUSTER_NAME</span> --<span class=\"hljs-comment\">fargate</span><span class=\"hljs-literal\">-</span><span class=\"hljs-comment\">profile</span><span class=\"hljs-literal\">-</span><span class=\"hljs-comment\">arn</span> <span class=\"hljs-comment\">FARGATE_PROFILE_ARN</span>\n</pre>\n<h4 id=\"drain\">drain</h4>\n<p>This subcommand can be used to drain Pods from the instances in the provided Auto Scaling Groups. This can be used to\ngracefully retire existing Auto Scaling Groups by ensuring the Pods are evicted in a manner that respects disruption\nbudgets.</p>\n<p>You can read more about the drain operation in <a href=\"https://kubernetes.io/docs/tasks/administer-cluster/safely-drain-node/\" class=\"preview__body--description--blue\" target=\"_blank\">the official\ndocumentation</a>.</p>\n<p>To drain the Auto Scaling Group <code>my-asg</code> in the region <code>us-east-2</code>:</p>\n<pre><span class=\"hljs-comment\">kubergrunt</span> <span class=\"hljs-comment\">eks</span> <span class=\"hljs-comment\">drain</span> --<span class=\"hljs-comment\">asg</span><span class=\"hljs-literal\">-</span><span class=\"hljs-comment\">name</span> <span class=\"hljs-comment\">my</span><span class=\"hljs-literal\">-</span><span class=\"hljs-comment\">asg</span> --<span class=\"hljs-comment\">region</span> <span class=\"hljs-comment\">us</span><span class=\"hljs-literal\">-</span><span class=\"hljs-comment\">east</span><span class=\"hljs-literal\">-</span><span class=\"hljs-comment\">2</span>\n</pre>\n<p>You can drain multiple ASGs by providing the <code>--name</code> option multiple times:</p>\n<pre><span class=\"hljs-comment\">kubergrunt</span> <span class=\"hljs-comment\">eks</span> <span class=\"hljs-comment\">drain</span> --<span class=\"hljs-comment\">asg</span><span class=\"hljs-literal\">-</span><span class=\"hljs-comment\">name</span> <span class=\"hljs-comment\">my</span><span class=\"hljs-literal\">-</span><span class=\"hljs-comment\">asg</span><span class=\"hljs-literal\">-</span><span class=\"hljs-comment\">a</span> --<span class=\"hljs-comment\">name</span> <span class=\"hljs-comment\">my</span><span class=\"hljs-literal\">-</span><span class=\"hljs-comment\">asg</span><span class=\"hljs-literal\">-</span><span class=\"hljs-comment\">b</span> --<span class=\"hljs-comment\">name</span> <span class=\"hljs-comment\">my</span><span class=\"hljs-literal\">-</span><span class=\"hljs-comment\">asg</span><span class=\"hljs-literal\">-</span><span class=\"hljs-comment\">c</span> --<span class=\"hljs-comment\">region</span> <span class=\"hljs-comment\">us</span><span class=\"hljs-literal\">-</span><span class=\"hljs-comment\">east</span><span class=\"hljs-literal\">-</span><span class=\"hljs-comment\">2</span>\n</pre>\n<h3 class=\"preview__body--subtitle\" id=\"k-8-s\">k8s</h3>\n<p>The <code>k8s</code> subcommand of <code>kubergrunt</code> includes commands that directly interact with the Kubernetes resources.</p>\n<h4 id=\"wait-for-ingress\">wait-for-ingress</h4>\n<p>This subcommand waits for the Ingress endpoint to be provisioned. This will monitor the Ingress resource, continuously\nchecking until the endpoint is allocated to the Ingress resource or times out. By default, this will try for 5 minutes\n(max retries 60 and time betweeen sleep of 5 seconds).</p>\n<p>You can configure the timeout settings using the --max-retries and --sleep-between-retries CLI args. This will check for\n--max-retries times, sleeping for --sleep-between-retries inbetween tries.</p>\n<p>For example, if you ran the command:</p>\n<pre>kubergrunt k8s wait-for-ingress \\\n -<span class=\"ruby\">-ingress-name $INGRESS_NAME \\\n</span> -<span class=\"ruby\">-namespace $NAMESPACE \\\n</span> -<span class=\"ruby\">-max-retries <span class=\"hljs-number\">10</span> \\\n</span> -<span class=\"ruby\">-sleep-between-retries <span class=\"hljs-number\">15</span>s\n</span></pre>\n<p>this command will query the Kubernetes API to check the <code>Ingress</code> resource up to 10 times, waiting for 15 seconds\ninbetween each try for a total of 150 seconds (2.5 minutes) before timing out.</p>\n<p>Run <code>kubergrunt k8s wait-for-ingress --help</code> to see all the available options.</p>\n<h4 id=\"kubectl\">kubectl</h4>\n<p>This subcommand will call out to kubectl with a temporary file that acts as the kubeconfig, set up with the parameters\n<code>--kubectl-server-endpoint</code>, <code>--kubectl-certificate-authority</code>, <code>--kubectl-token</code>. Unlike using kubectl directly, this\ncommand allows you to pass in the base64 encoded certificate authority data directly as opposed to as a file.</p>\n<p>To forward args to kubectl, pass all the args you wish to forward after a <code>--</code>. For example, the following command runs\n<code>kubectl get pods -n kube-system</code>:</p>\n<pre>kubergrunt k8s kubectl \\\n -<span class=\"ruby\">-kubectl-server-endpoint $SERVER_ENDPOINT \\\n</span> -<span class=\"ruby\">-kubectl-certificate-authority $SERVER_CA \\\n</span> -<span class=\"ruby\">-kubectl-token $TOKEN \\\n</span> -<span class=\"ruby\">- get pods -n kube-system\n</span></pre>\n<p>Run <code>kubergrunt k8s kubectl --help</code> to see all the available options.</p>\n<h3 class=\"preview__body--subtitle\" id=\"tls\">tls</h3>\n<p>The <code>tls</code> subcommand of <code>kubergrunt</code> is used to manage TLS certificate key pairs as Kubernetes Secrets.</p>\n<h4 id=\"gen\">gen</h4>\n<p>This subcommand will generate new TLS certificate key pairs based on the provided configuration arguments. Once the\ncertificates are generated, they will be stored on your targeted Kubernetes cluster as\n<a href=\"https://kubernetes.io/docs/concepts/configuration/secret/\" class=\"preview__body--description--blue\" target=\"_blank\">Secrets</a>. This supports features such as:</p>\n<ul>\n<li>Generating a new CA key pair and storing the generated key pair in your Kubernetes cluster.</li>\n<li>Issuing a new signed TLS certificate key pair using an existing CA stored in your Kubernetes cluster.</li>\n<li>Replacing the stored certificate key pair in your Kubernetes cluster with a newly generated one.</li>\n<li>Controlling which Namespace the Secrets are stored in.</li>\n</ul>\n<p>For example, to generate a new CA key pair, issue a TLS certificate key pair, storing each of those as the Secrets\n<code>ca-keypair</code> and <code>tls-keypair</code> respectively:</p>\n<pre><span class=\"hljs-comment\"># Generate the CA key pair</span>\n<span class=\"hljs-string\">kubergrunt </span><span class=\"hljs-string\">tls </span><span class=\"hljs-string\">gen </span>\\\n <span class=\"hljs-built_in\">--namespace</span> <span class=\"hljs-string\">kube-system </span>\\\n <span class=\"hljs-built_in\">--secret-name</span> <span class=\"hljs-string\">ca-keypair </span>\\\n <span class=\"hljs-built_in\">--ca</span> \\\n <span class=\"hljs-built_in\">--tls-common-name</span> <span class=\"hljs-string\">kiam-ca </span>\\\n <span class=\"hljs-built_in\">--tls-org</span> <span class=\"hljs-string\">Gruntwork </span>\\\n <span class=\"hljs-built_in\">--tls-org-unit</span> <span class=\"hljs-string\">IT </span>\\\n <span class=\"hljs-built_in\">--tls-city</span> <span class=\"hljs-string\">Phoenix </span>\\\n <span class=\"hljs-built_in\">--tls-state</span> <span class=\"hljs-string\">AZ </span>\\\n <span class=\"hljs-built_in\">--tls-country</span> <span class=\"hljs-string\">US </span>\\\n <span class=\"hljs-built_in\">--secret-annotation</span> <span class=\"hljs-string\">\"gruntwork.io/version=v1\"</span>\n<span class=\"hljs-comment\"># Generate a signed TLS key pair using the previously created CA</span>\n<span class=\"hljs-string\">kubergrunt </span><span class=\"hljs-string\">tls </span><span class=\"hljs-string\">gen </span>\\\n <span class=\"hljs-built_in\">--namespace</span> <span class=\"hljs-string\">kube-system </span>\\\n <span class=\"hljs-built_in\">--secret-name</span> <span class=\"hljs-string\">tls-keypair </span>\\\n <span class=\"hljs-built_in\">--ca-secret-name</span> <span class=\"hljs-string\">ca-keypair </span>\\\n <span class=\"hljs-built_in\">--tls-common-name</span> <span class=\"hljs-string\">kiam-server </span>\\\n <span class=\"hljs-built_in\">--tls-org</span> <span class=\"hljs-string\">Gruntwork </span>\\\n <span class=\"hljs-built_in\">--tls-org-unit</span> <span class=\"hljs-string\">IT </span>\\\n <span class=\"hljs-built_in\">--tls-city</span> <span class=\"hljs-string\">Phoenix </span>\\\n <span class=\"hljs-built_in\">--tls-state</span> <span class=\"hljs-string\">AZ </span>\\\n <span class=\"hljs-built_in\">--tls-country</span> <span class=\"hljs-string\">US </span>\\\n <span class=\"hljs-built_in\">--secret-annotation</span> <span class=\"hljs-string\">\"gruntwork.io/version=v1\"</span>\n</pre>\n<p>The first command will generate a CA key pair and store it as the Secret <code>ca-keypair</code>. The <code>--ca</code> argument signals to\n<code>kubergrunt</code> that the TLS certificate is for a CA.</p>\n<p>The second command uses the generated CA key pair to issue a new TLS key pair. The <code>--ca-secret-name</code> signals\n<code>kubergrunt</code> to use the CA key pair stored in the Kubernetes Secret <code>ca-keypair</code>.</p>\n<p>This command should be run by a <strong>cluster administrator</strong> to ensure access to the Secrets are tightly controlled.</p>\n<p>See the command help for all the available options: <code>kubergrunt tls gen --help</code>.</p>\n<h3 class=\"preview__body--subtitle\" id=\"deprecated-commands\">Deprecated commands</h3>\n<h4 id=\"helm\">helm</h4>\n<p>The <code>helm</code> subcommand contained utilities for managing Helm v2, and is not necessary for Helm v3. This subcommand was\nremoved as of <code>kubergrunt</code> version <code>v0.6.0</code> with Helm v2 reaching end of life.</p>\n<h2 class=\"preview__body--subtitle\" id=\"who-maintains-this-project\">Who maintains this project?</h2>\n<p><code>kubergrunt</code> is maintained by <a href=\"http://www.gruntwork.io/\" class=\"preview__body--description--blue\" target=\"_blank\">Gruntwork</a>. If you are looking for help or commercial support,\nsend an email to <a href=\"mailto:support@gruntwork.io?Subject=kubergrunt\" class=\"preview__body--description--blue\" target=\"_blank\">support@gruntwork.io</a>.</p>\n<p>Gruntwork can help with:</p>\n<ul>\n<li>Setup, customization, and support for this project.</li>\n<li>Modules and submodules for other types of infrastructure in major cloud providers, such as VPCs, Docker clusters,\ndatabases, and continuous integration.</li>\n<li>Modules and Submodules that meet compliance requirements, such as HIPAA.</li>\n<li>Consulting & Training on AWS, GCP, Terraform, and DevOps.</li>\n</ul>\n<h2 class=\"preview__body--subtitle\" id=\"how-do-i-contribute\">How do I contribute?</h2>\n<p>Contributions are very welcome! Check out the <a href=\"/repos/v0.15.0/kubergrunt/CONTRIBUTING.md\" class=\"preview__body--description--blue\">Contribution Guidelines</a> for instructions.</p>\n<h2 class=\"preview__body--subtitle\" id=\"how-is-this-project-versioned\">How is this project versioned?</h2>\n<p>This project follows the principles of <a href=\"http://semver.org/\" class=\"preview__body--description--blue\" target=\"_blank\">Semantic Versioning</a>. You can find each new release, along\nwith the changelog, in the <a href=\"/repos/releases\" class=\"preview__body--description--blue\">Releases Page</a>.</p>\n<p>During initial development, the major version will be 0 (e.g., <code>0.x.y</code>), which indicates the code does not yet have a\nstable API. Once we hit <code>1.0.0</code>, we will make every effort to maintain a backwards compatible API and use the MAJOR,\nMINOR, and PATCH versions on each release to indicate any incompatibilities.</p>\n<h2 class=\"preview__body--subtitle\" id=\"license\">License</h2>\n<p>Please see <a href=\"/repos/v0.15.0/kubergrunt/LICENSE\" class=\"preview__body--description--blue\">LICENSE</a> and <a href=\"/repos/v0.15.0/kubergrunt/NOTICE\" class=\"preview__body--description--blue\">NOTICE</a> for how the code in this repo is licensed.</p>\n<p>Copyright © 2020 Gruntwork, Inc.</p>\n","repoName":"kubergrunt","repoRef":"v0.15.0","serviceDescriptor":{"serviceName":"Kubergrunt","serviceRepoName":"kubergrunt","serviceRepoOrg":"gruntwork-io","cloudProviders":["aws","gcp","azure"],"description":"A standalone go binary with a collection of commands to fill in the gaps between Terraform, Helm, and Kubectl.","imageUrl":"grunt.png","licenseType":"open-source","technologies":["Go"],"compliance":[],"tags":[""],"noDisplayInUI":true},"serviceCategoryName":"Reference Architecture","fileName":"README.md","filePath":"","title":"Repo Browser: Kubergrunt","description":"Browse the repos in the Gruntwork Infrastructure as Code Library."}