Terraform AWS EKS

This Terraform module is designed to configure Amazon Elastic Kubernetes Service (EKS) to integrate with Expel Workbench. The module sets up a CloudWatch subscription filter to send data to a Kinesis data stream, which is then consumed by Expel Workbench.

:exclamation: Terraform state may contain sensitive information. Please follow best security practices when securing your state.

Table of Contents

• Features
• Usage
• Enabling k8s API Read-Only Access
  • Using eksctl
  • Using Terraform
• AWS Documentation
• Finishing Steps
• Permissions
• Example
• Limitations
• Requirements
• Providers
• Inputs
• Outputs
• Resources
• Contributing

Features

This Terraform module offers the following features:

• Amazon EKS Integration: Seamlessly integrates your Amazon EKS setup with Expel Workbench for enhanced security monitoring.
• CloudWatch Subscription Filter: Automatically configures a CloudWatch subscription filter to send data to a Kinesis data stream.
• Kinesis Data Stream: Sets up a Kinesis data stream that is consumed by Expel Workbench, providing real-time data for security monitoring.
• Kubernetes API Read-Only Access: Provides instructions for enabling read-only access to the Kubernetes API, either through eksctl or directly through Terraform.
• AWS Documentation: Links to the full AWS documentation for additional guidance and support.
• Security Device Setup: Guides you through the process of creating an AWS EKS security device on Expel Workbench to start monitoring your AWS environment.
• Permissions: Allocates permissions that allow Expel Workbench to perform investigations and gain a broad understanding of your AWS footprint.
• Limitations: Clearly outlines the limitations of the module, such as only supporting the onboarding of a single AWS account and always creating a new CloudWatch subscription filter and Kinesis data stream.

Usage

The use this module in a Terraform Script, users need to replace certain placeholders with their specific values, such as their organization's GUID from Expel Workbench, the AWS region where the Kinesis data stream will be created, and the log group name for EKS logs.

module "expel_aws_eks" {
  source  = "expel-io/k8s-control-plane/aws"
  version = "1.1.0"

  expel_customer_organization_guid = "Replace with your organization GUID from Expel Workbench"
  region = "AWS region in which Kinesis data stream will be created"
  eks_log_group_name = "The log group name for EKS logs to integration with Expel Workbench"
}

Enabling k8s API read only access

This module does not map the Expel ARN to the kubernetes expel-user (necessary for our Benchmark Report). This requires modifying the aws-auth config map either through eksctl or terraform.

1. Using eksctl

eksctl can update this map for you by running:

eksctl create iamidentitymapping \
    --cluster <your-cluster-name> \
    --region <your-region> \
    --arn <your-expel-role-arn> \
    --username expel-user

You can confirm the mapping is created by running:

eksctl get iamidentitymapping --cluster <your-cluster-name> --region <your-region>

2. Using terraform

If you are using the official EKS AWS module you can update this with your existing EKS module

module "eks" {
  [...]

  # aws-auth configmap
  manage_aws_auth_configmap = true

  aws_auth_users = [
    {
      userarn  = <your-expel-role-arn>
      username = "expel-user"
      groups   = []
    },
  ]

AWS Documentation

You can find the full AWS documentation here.

Validating mapping configuration

Once completed you can confirm the mapping is created by running:

eksctl get iamidentitymapping --cluster <your-cluster-name> --region <your-region>

Finishing steps

Once you have configured your AWS environment, go to https://workbench.expel.io/settings/security-devices?setupIntegration=kubernetes_eks and create an AWS EKS security device to enable Expel to begin monitoring your AWS environment.

Permissions

The permissions allocated by this module allow Expel Workbench to perform investigations and get a broad understanding of your AWS footprint.

Example

You can find an example of how to use this module in the examples directory.

Limitations

1. Only supports onboarding a single AWS account, not an entire AWS Organization.
2. Will always create a new CloudWatch subscription filter (AWS has a limit of 2 subscription filters per CloudWatch log group)
3. Will always create a new Kinesis data stream.

See Expel's Getting Started Guide for Amazon EKS for options if you have an AWS Organization or already have a Kinesis data stream you want to re-use.

Issues

Found a bug or have an idea for a new feature? Please create an issue. We'll respond as soon as possible!

Contributing

We welcome contributions! Here's how you can help:

1. Fork the Project.
2. Create your Feature Branch (git checkout -b feature/AmazingFeature).
3. Commit your Changes (git commit -m 'Add some AmazingFeature').
4. Push to the Branch (git push origin feature/AmazingFeature).
5. Open a Pull Request.

Please read our Contributing Code of Conduct to get started.

Requirements

Providers

Inputs

Outputs

Resources