search

awslabs / eksdemo

The easy button for learning, testing and demoing Amazon EKS
MIT No Attribution
212 stars 42 forks source link

readme

eksdemo - kubectl-like CLI for Amazon EKS

Go Report Card

The easy button for learning, testing, and demoing Amazon EKS:

Note: eksdemo is in beta and is intended for demo and test environments only.

Table of Contents

Why eksdemo?

While creating an EKS cluster is fairly easy thanks to eksctl, manually installing and configuring applications on EKS is complex, time consuming and error-prone. One of the most powerful feature of eksdemo is its extensive application catalog. An application can be installed (including dependencies) with a single command.

For example, the command: eksdemo install karpenter -c <cluster-name> will:

  1. Create the EC2 Spot Service Linked Role (if it doesn't already exist)
  2. Create the Karpenter Controller IAM Role (IRSA)
  3. Create the Karpenter Node IAM Role
  4. Create an SQS Queue and EventBridge rules for native Spot Termination Handling
  5. Add an entry to the aws-auth ConfigMap for the Karpenter Node IAM Role
  6. Install the Karpenter Helm Chart
  7. Create default Karpenter NodePool and EC2NodeClass Custom Resources

No Magic

Application installs are:

eksdemo vs EKS Blueprints

Both eksdemo and EKS Blueprints automate the creation of EKS clusters and install commonly used applications. Why would you use eksdemo for learning, testing, and demoing EKS?

eksdemo EKS Blueprints
Use cases: learning, testing, and demoing EKS Use cases: customers deploying to prod and non-prod environments
Kubectl-like CLI installs apps with single command Infrastructure as Code (IaC) built on Terraform or CDK
Imperative tooling is great for iterative testing Declarative IaC tooling is not designed for iterative testing
Used to get up and running quickly Used to drive standards and communicate vetted architecture patterns for utilizing EKS within customer organizations

Install eksdemo

eksdemo is a Golang binary and releases include support for Mac, Linux and Windows running on x86 or arm64. There are a number of ways you can install:

Prerequisites

  1. AWS Account with Administrator access
  2. Route53 Public Hosted Zone (Optional but strongly recommended)
    1. You can update the domain registration of your existing domain (using any domain registrar) to change the name servers for the domain to use the four Route 53 name servers.
    2. You can still use eksdemo if you don’t have a Route53 Hosted Zone. Most applications that explose an Ingress resource default to deploying a Service of type LoadBalancer if you don't use the --ingress-host flag and your connection to the application will be unencrypted.

Install using Homebrew

Homebrew installation method is supported for Mac and Linux. Using the Terminal, enter the following commands:

brew tap aws/tap
brew install eksdemo

Troubleshoot Homebrew Install

Note: Depending on how you originally installed eksctl, you may receive the error: eksctl is already installed from homebrew/core! This is because eksdemo uses the official Weaveworks tap weaveworks/tap as a dependency.

If you receive the error above, run the following commands:

brew uninstall eksctl
brew install eksdemo

Install on AWS CloudShell

AWS CloudShell environments are mostly ephemeral and software you install is lost the next time you reconnect. There is persistent storage available in the home directory that is retained for 120 days after the end of your last session. Use the following commands to install eksdemo on AWS CloudShell:

curl -s -L "https://github.com/weaveworks/eksctl/releases/latest/download/eksctl_Linux_amd64.tar.gz" | tar xz -C /tmp
curl -s -L "https://github.com/awslabs/eksdemo/releases/latest/download/eksdemo_Linux_x86_64.tar.gz" | tar xz -C /tmp
mkdir -p ~/.local/bin && mv /tmp/eksctl ~/.local/bin && mv /tmp/eksdemo ~/.local/bin

To configure Bash completion, first install the bash-completion package:

sudo dnf install bash-completion -y

Once that completes, run the following commands that will configure bash completion to work across CloudShell sessions by installing everything needed in the home directory:

mkdir -p ~/.bashrc.d
cp /usr/share/bash-completion/bash_completion ~/.bashrc.d/
echo '. <(eksdemo completion bash)' >> ~/.bashrc
source ~/.bashrc

Install on AWS Cloud9

To install on Cloud9, you will need to install Homebrew first. In the Cloud9 terminal, run the following commands:

CI=1 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
(echo; echo 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"') >> ~/.bashrc
eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"
brew install aws/tap/eksdemo

To configure Bash completion, run the following commands and then start a new terminal:

cat >> ~/.bashrc << \EOF
if type brew &>/dev/null
then
  for COMPLETION in "$(brew --prefix)/etc/bash_completion.d/"*
  do
    [[ -r "${COMPLETION}" ]] && source "${COMPLETION}"
  done
fi
EOF

Install Manually

Navigate to Releases, look under Assets and locate the binary that matches your operation system and platform. Download the file, uncompress and copy to a location of your choice that is in your path. A common location on Mac and Linux is /usr/local/bin. Note that eksctl is required and must be installed as well.

Set the AWS Region

Most eksdemo commands require that you have configured a default AWS region or use the --region flag. There are 2 ways to configure a default region, either:

Validate Install

To validate installation you can run the eksdemo version command and confirm you are running the latest version. The output will be similar to below:

» eksdemo version
eksdemo: version.Info{Version:"0.16.0", Date:"2024-08-19T17:41:55Z", Commit:"74fc767"}

To validate the AWS region is set, you can run eksdemo get cluster which will list running EKS clusters in the default region. If you don’t have any EKS clusters in the region, you will get the response: No resources found.

» eksdemo get cluster
+------------+--------+---------+---------+----------+----------+
|    Age     | Status | Cluster | Version | Platform | Endpoint |
+------------+--------+---------+---------+----------+----------+
| 3 weeks    | ACTIVE | green   |    1.27 | eks.23   | Public   |
| 20 minutes | ACTIVE | *blue   |    1.31 | eks.2    | Public   |
+------------+--------+---------+---------+----------+----------+
* Indicates current context in local kubeconfig

Application Catalog

eksdemo comes with an extensive application catalog. Each application can be installed with a single command: eksdemo install <application> -c <cluster-name> [flags]

To install applications under a group, you can use either a space or a hyphen. For example, each of the following are valid: eksdemo install ingress nginx or eksdemo install ingress-nginx

The application catalog includes:

Kubectl-like get commands

eksdemo makes it easy to view AWS resources from the command line with commands that are very similar to how kubectl get works. Output defaults to a table, but raw AWS API output can be viewed with -o yaml and -o json flag options.

Almost all of the command have shorthand alaises to make it easier to type. For example, get ec2 is an alias for get ec2-instance. You can find the aliases using the help command, eksdemo get ec2-instance -h.

Tutorials

The Basics tutorials provide detailed knowledge on how eksdemo works. It's recommended you review the Basics tutorials before proceeding to Advanced tutorial as they assume this knowlege.

Basics

Advanced

Support & Feedback

This project is maintained by AWS Solution Architects. It is not part of an AWS service and support is provided best-effort by the maintainers. To post feedback, submit feature ideas, or report bugs, please use the Issues section of this repo. If you are interested in contributing, please see the Contribution guide.

Security

See CONTRIBUTING for more information.

License

This library is licensed under the MIT-0 License. See the LICENSE file.