DOCSEARCHbyAlgolia
Submit Docs

eksdemo

repository·main·Indexed 42 days ago

https://github.com/awslabs/eksdemo

A kubectl-like CLI tool for learning, testing, and demoing Amazon EKS. It features an application catalog of over 70 options (including CNCF and open-source projects), automated dependency management for IAM roles and Helm charts, and over 60 'get' commands to query AWS resources.

Tokens
33.6K
Snippets
131
Records
154
Agent score
53%

What's inside eksdemo

  1. Overview of eksdemo

    main

    What is eksdemo?

    eksdemo is a kubectl-like CLI designed for learning, testing, and demoing Amazon EKS. It simplifies the process of installing complex applications and their dependencies on EKS clusters with single commands.

    Key Features

    • Application Catalog: Over 70 options including CNCF and open-source projects.
    • Automated Dependencies: Installs required IAM roles, SQS queues, and Helm charts automatically.
    • Customizable Installs: Use command-line flags or the --set flag to override Helm chart values.
    • Resource Querying: Over 60 kubectl-like get commands to search AWS resources.
    • Transparency: Use the --dry-run flag to see all steps before execution.

    Note: eksdemo is in beta and is intended for demo and test environments only. It is an imperative tool for iterative testing, whereas EKS Blueprints is a declarative IaC tool for production environments.

  2. Vault Installation Dependencies

    main
    The Vault installation via Helm includes a PersistentVolume. For the vault.vault-0 pod to schedule and launch successfully, your EKS cluster must have a functional storage layer and working CSI (Container Storage Interface) management. The success of the Vault deployment is directly dependent on the successful creation of this PersistentVolume.

  3. Available Kube Prometheus Stack installation options

    main

    When installing the Kube Prometheus Stack via eksdemo, you can choose between different deployment modes:

    • kube-prometheus-stack: Standard Kube Prometheus Stack installation.
    • kube-prometheus-stack-amp: Kube Prometheus Stack configured to use Amazon Managed Prometheus (AMP) for metric storage.
    • kube-prometheus-karpenter-dashboards: Includes Karpenter Dashboards and ServiceMonitor support.

  4. View detailed IAM policy documents

    main

    To view the full details of an IAM policy, including the JSON/YAML policy document, use the --output or -o flag with eksdemo get iam-policy. This returns the raw AWS API response.

    eksdemo get iam-policy --role eksdemo.<cluster-name>.kubecost.kubecost-cost-analyzer -o yaml

  5. Install Amazon VPC Lattice (Gateway API) Controller

    main

    The Amazon VPC Lattice Controller (also known as the AWS Gateway API Controller) implements the Kubernetes Gateway API to orchestrate Amazon VPC Lattice resources using Kubernetes Custom Resources like Gateway and HTTPRoute.

    You can automate the installation using eksdemo, which performs the following steps:

    1. Creates the VPC Lattice Controller IAM Role (IRSA).
    2. Adds a Security Group Rule to the EKS Cluster Security Group to allow inbound traffic from VPC Lattice.
    3. Installs the VPC Lattice Controller Helm Chart.
    4. Creates the VPC Lattice Controller GatewayClass Custom Resource.

  6. Create an Amazon EKS Cluster with eksdemo create cluster

    main

    Use the eksdemo create cluster command to provision an Amazon EKS cluster. While eksdemo can manage applications in existing clusters, using it for creation provides several defaults: cluster logging enabled, OIDC/IRSA enabled, Managed Node Group ASG max set to 10 for Cluster Autoscaler, private networking for nodes, and VPC CNI configured as a Managed Add-on with network policy.

    To customize the cluster, you can specify the operating system (e.g., bottlerocket or amazonlinux2023), instance types, node counts, and Kubernetes versions. If you need advanced customization, use the --dry-run flag to generate the eksctl YAML configuration, which you can then modify and apply manually via eksctl.

    # Example: Create a cluster named 'blue' using Bottlerocket nodes, 
# t3.xlarge instances, and 3 desired nodes.
eksdemo create cluster blue --os bottlerocket -i t3.xlarge -N 3

  7. Dry run a Karpenter installation

    main

    To inspect all the actions, CloudFormation stacks, Helm values, and Kubernetes resources that eksdemo will create without actually performing the installation, use the --dry-run flag. This is useful for verifying IAM roles, SQS queues, and the default NodePool/EC2NodeClass configurations before deployment.

    eksdemo install karpenter -c <cluster-name> --dry-run

  8. Install the VPC Lattice (Gateway API) Controller

    main

    Use the eksdemo install vpc-lattice-controller command to deploy the Amazon VPC Lattice Controller to your EKS cluster. This installation automates several steps: creating the IAM Role for Service Accounts (IRSA), adding security group rules to allow Lattice traffic, installing the Helm chart, and creating the GatewayClass resource.

    To simplify setup, use the --default-service-network flag to automatically create and associate a VPC Lattice service network with your cluster's VPC.

    eksdemo install vpc-lattice-controller -c <cluster-name> --default-service-network <service-network-name>

  9. Install eksdemo on AWS Cloud9

    main

    To install eksdemo on Cloud9, you must first install Homebrew, then install eksdemo via the aws/tap. The following steps also configure Bash completion.

    # Install Homebrew
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)"

# Install eksdemo
brew install aws/tap/eksdemo

# Configure Bash completion (requires a new terminal session to take effect)
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

  10. Validate eksdemo installation

    main

    After installation, verify that eksdemo is working and that your AWS region is correctly configured.

    • Use eksdemo version to check the installed version.
    • Use eksdemo get cluster to list EKS clusters in your configured region. If no clusters exist, it will return No resources found.
    # Check version
eksdemo version

# Check AWS region/clusters
eksdemo get cluster

  11. Test automatic node provisioning with example-inflate

    main

    To test if Karpenter is correctly provisioning nodes, you can install the example-inflate application using eksdemo. This application uses a Deployment that triggers autoscaling based on the number of replicas requested.

    Installation Flags for example-inflate

    • --on-demand: Requests On-Demand nodes by adding a Node Selector for the karpenter.sh/capacity-type: on-demand label.
    • --replicas <int>: Sets the number of replicas at install time (default is 0).
    • --spread: Uses topology spread constraints to spread replicas across availability zones using topologyKey: topology.kubernetes.io/zone.
    • --dry-run: Prints the installation steps (manifests) without actually installing them.

    Workflow

    1. Dry Run: Review the manifest to ensure the topology constraints and replica counts are correct.
    2. Install: Run the install command without --dry-run to trigger the scaling event.
    3. Verify: Use eksdemo get ec2-instance to see the new nodes being provisioned by Karpenter.
    # 1. Review the manifest
eksdemo install example-inflate -c <cluster-name> --replicas 10 --spread --dry-run

# 2. Install the app to trigger autoscaling
eksdemo install example-inflate -c <cluster-name> --replicas 10 --spread

# 3. Verify new instances
eksdemo get ec2-instance -c <cluster-name>

  12. Create a VPC Lattice Service using HTTPRoute

    main

    To create a VPC Lattice Service that performs path-based routing, deploy example applications and an HTTPRoute custom resource. This process uses the AWS Application Networking for Kubernetes controller to map Kubernetes services to VPC Lattice services.

    1. Deploy example applications: Apply the parking and review application manifests.
    2. Deploy the HTTPRoute: Apply the rate-route-path.yaml manifest. This configuration routes traffic based on the path:
      • /parking $\rightarrow$ parking service
      • /review $\rightarrow$ review service
    3. Verify: It takes approximately 20-30 seconds for the service to become ACTIVE. Use eksdemo get lattice-service to check the status.

    Note: This step follows the official AWS Application Networking Getting Started guide.

    # Deploy example applications
kubectl apply -f https://raw.githubusercontent.com/aws/aws-application-networking-k8s/main/files/examples/parking.yaml
kubectl apply -f https://raw.githubusercontent.com/aws/aws-application-networking-k8s/main/files/examples/review.yaml

# Deploy the HTTPRoute for path-based routing
kubectl apply -f https://raw.githubusercontent.com/aws/aws-application-networking-k8s/main/files/examples/rate-route-path.yaml

# Verify the service status
eksdemo get lattice-service