add dev setup guide

.github/workflows/tests.yml

@@ -35,4 +35,3 @@ jobs:
 
     - name: make test
       run: make test
-      working-directory: ./src

.gitignore

@@ -1,22 +1,24 @@
-### Go ###
 # Binaries for programs and plugins
 *.exe
 *.exe~
 *.dll
 *.so
 *.dylib
 
-# Test binary, built with `go test -c`
-*.test
+# Tools directory.
+bin/
+
+# Generated symlinks.
+cmd/**/kodata/
 
 # Output of the go coverage tool, specifically when used with LiteIDE
 *.out
-.idea/
 
-# Output of the go build for the cmd binary
-/node-termination-handler
+# Kubernetes Generated files - skip generated files, except for vendored files
+!vendor/**/zz_generated.*
 
-### Go Patch ###
-/vendor/
-/Godeps/
-/build/
+# Editor and IDE paraphernalia
+.idea
+*.swp
+*.swo
+*~

DEVELOPMENT.md

@@ -0,0 +1,160 @@
+# Setup Development Environment
+
+## 1. Clone the repo
+
+```sh
+git clone --branch v2 https://github.com/aws/aws-node-termination-handler.git nthv2
+cd nthv2
+```
+
+## 2. Specify an EKS Cluster
+
+*Tip:* Several steps in this guide, and utility scripts, use environment variables. Saving these environment variables in a file, or using a shell extension that manages sets of environment variables, will make it easier to restore your development environment in a new shell.
+
+```sh
+export CLUSTER_NAME=<name>
+export AWS_REGION=<region>
+```
+
+### 2.1. (Optional) Create the EKS Cluster
+
+Skip this set if you already have an EKS cluster.
+
+```sh
+envsubst <resources/eks-cluster.yaml.tmpl | eksctl create cluster --kubeconfig "${PWD}/kubeconfig" -f -
+
+export KUBECONFIG="$PWD/kubeconfig"
+```
+
+If you do not want to use `envsubst` you can copy the template file and substitute the referenced values.
+
+## 3. Create Infrastructure
+
+```sh
+export INFRASTRUCTURE_STACK_NAME="nth-${CLUSTER_NAME}"
+
+aws cloudformation deploy \
+    --template-file resources/infrastructure.yaml \
+    --stack-name "${INFRASTRUCTURE_STACK_NAME}" \
+    --capabilities CAPABILITY_NAMED_IAM \
+    --parameter-overrides ClusterName="${CLUSTER_NAME}"
+```
+
+Resources created:
+
+* `ServiceAccountPolicy` - IAM Managed Policy that allows access to Auto Scaling Groups, EC2, and SQS.
+
+```sh
+export DEV_INFRASTRUCTURE_STACK_NAME="${INFRASTRUCTURE_STACK_NAME}-dev"
+
+aws cloudformation deploy \
+    --template-file resources/dev-infrastructure.yaml \
+    --stack-name "${DEV_INFRASTRUCTURE_STACK_NAME}" \
+    --parameter-overrides ClusterName="${CLUSTER_NAME}"
+```
+
+Resources created:
+
+* `ControllerRespository` - ECR Respository for images of the Kubernetes controller.
+* `WebhookRespository` - ECR Repository for images of the Kubernetes admission webhook.
+
+```sh
+export QUEUE_NAME=<name>
+export QUEUE_STACK_NAME="${INFRASTRUCTURE_STACK_NAME}-queue-${QUEUE_NAME}"
+
+aws cloudformation deploy \
+    --template-file resources/queue-infrastructure.yaml \
+    --stack-name "${QUEUE_STACK_NAME}" \
+    --parameter-overrides \
+        ClusterName="${CLUSTER_NAME}" \
+        QueueName="${QUEUE_NAME}"
+```
+
+Resources created:
+
+* `Queue` - SQS Queue that will receive messages from EventBridge
+* `AutoScalingTerminationRule` - EventBridge Rule to route instance-terminate lifecycle action messages from Auto Scaling Groups to `Queue`
+* `RebalanceRecommendationRule` - EventBridge Rule to route rebalance recommendation messages from EC2 to `Queue`
+* `ScheduledChangeRule` - EventBridge Rule to route scheduled change messages from AWS Health to `Queue`
+* `SpotInterruptionRule` - EventBridge Rule to route EC2 Spot interruption notice messages from EC2 to `Queue`
+* `StateChangeRule` - EventBridgeRule to route state change messages from EC2 to `Queue`
+
+## 4. Connect Infrastructure to EKS Cluster
+
+```sh
+export CLUSTER_NAMESPACE=<namespace>
+export SERVICE_ACCOUNT_NAME="nth-${CLUSTER_NAME}-serviceaccount"
+
+eksctl create iamserviceaccount \
+    --cluster "${CLUSTER_NAME}" \
+    --namespace "${CLUSTER_NAMESPACE}" \
+    --name "${SERVICE_ACCOUNT_NAME}" \
+    --role-name "${SERVICE_ACCOUNT_NAME}" \
+    --attach-policy-arn $(./scripts/get-cfn-stack-output.sh "${INFRASTRUCTURE_STACK_NAME}" ServiceAccountPolicyARN) \
+    --role-only \
+    --approve
+
+export SERVICE_ACCOUNT_ROLE_ARN=$(eksctl get iamserviceaccount \
+    --cluster "${CLUSTER_NAME}" \
+    --namespace "${CLUSTER_NAMESPACE}" \
+    --name "${SERVICE_ACCOUNT_NAME}" \
+    --output json | \
+    jq -r '.[0].status.roleARN')
+```
+
+## 5. Configure and Login to Image Repository
+
+```sh
+export KO_DOCKER_REPO=$(./scripts/get-cfn-stack-output.sh "${DEV_INFRASTRUCTURE_STACK_NAME}" RepositoryBaseURI)
+
+./scripts/docker-login-ecr.sh
+```
+
+## 6. Build and deploy controller to EKS cluster
+
+```sh
+make apply
+```
+
+### 6.1. (Optional) Providing additional Helm values
+
+The `apply` target sets some Helm chart values for you based on environment variables. To set additional Helm values use the `HELM_OPTS` make argument. For example:
+
+```sh
+make HELM_OPTS='--set logging.level=debug' apply
+```
+
+## 7. Define and deploy a Terminator to EKS cluster
+
+```sh
+export TERMINATOR_NAME=<name>
+export QUEUE_URL=$(./scripts/get-cfn-stack-output.sh "${QUEUE_STACK_NAME}" QueueURL)
+
+envsubst <resources/terminator.yaml.tmpl >terminator-${TERMINATOR_NAME}.yaml
+
+kubectl apply -f terminator-${TERMINATOR_NAME}.yaml
+```
+
+If you do not want to use `envsubst` you can copy the template file and substitute the referenced values.
+
+## 8. Remove deployed controller from EKS cluster
+
+```sh
+make delete
+```
+
+# Tear down Development Environment
+
+```sh
+make delete
+
+eksctl delete cluster --name "${CLUSTER_NAME}"
+
+aws cloudformation delete-stack --stack-name "${QUEUE_STACK_NAME}"
+
+./scripts/clear-image-repo.sh "$(./scripts/get-cfn-stack-output.sh ${DEV_INFRASTRUCTURE_STACK_NAME} ControllerRepositoryName)"
+./scripts/clear-image-repo.sh "$(./scripts/get-cfn-stack-output.sh ${DEV_INFRASTRUCTURE_STACK_NAME} WebhookRepositoryName)"
+aws cloudformation delete-stack --stack-name "${DEV_INFRASTRUCTURE_STACK_NAME}"
+
+aws cloudformation delete-stack --stack-name "${INFRASTRUCTURE_STACK_NAME}"
+```

src/Makefile → Makefile

@@ -5,7 +5,7 @@ CONTROLLER_GEN = $(BIN_DIR)controller-gen
 KO = $(BIN_DIR)/ko
 SETUP_ENVTEST = $(BIN_DIR)/setup-envtest
 GINKGO = $(BIN_DIR)/ginkgo
-HELM_BASE_OPTS ?= --set serviceAccount.annotations.eks\\.amazonaws\\.com/role-arn=${NTHV2_IAM_ROLE_ARN}
+HELM_BASE_OPTS ?= --set aws.region=${AWS_REGION},serviceAccount.name=${SERVICE_ACCOUNT_NAME},serviceAccount.annotations.eks\\.amazonaws\\.com/role-arn=${SERVICE_ACCOUNT_ROLE_ARN}
 GINKGO_BASE_OPTS ?= --coverpkg $(shell head -n 1 $(PROJECT_DIR)/go.mod | cut -s -d ' ' -f 2)/pkg/...
 KODATA = \
 	cmd/controller/kodata/HEAD \

README.md

@@ -2,12 +2,6 @@
 
 <h4>Gracefully handle EC2 instance shutdown within Kubernetes</h4>
 
-### Community Meeting
-NTH community meeting is hosted on a monthly cadence. Everyone is welcome to participate!
-* **When:** first Tuesday of every month from 9:00-9:30AM PST | [Calendar Event (ics)](https://raw.githubusercontent.com/aws/aws-node-termination-handler/main/assets/nth-community-meeting.ics)
-* **Where:** [Chime meeting bridge](https://chime.aws/6502066216)
-
-
 ## Project Summary
 
 This project ensures that the Kubernetes control plane responds appropriately to events that can cause your EC2 instance to become unavailable, such as [EC2 maintenance events](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/monitoring-instances-status-check_sched.html), [EC2 Spot interruptions](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/spot-interruptions.html), [ASG Scale-In](https://docs.aws.amazon.com/autoscaling/ec2/userguide/AutoScalingGroupLifecycle.html#as-lifecycle-scale-in), [ASG AZ Rebalance](https://docs.aws.amazon.com/autoscaling/ec2/userguide/auto-scaling-benefits.html#AutoScalingBehavior.InstanceUsage), and EC2 Instance Termination via the API or Console.  If not handled, your application code may not stop gracefully, take longer to recover full availability, or accidentally schedule work to nodes that are going down.
@@ -23,20 +17,15 @@ This project ensures that the Kubernetes control plane responds appropriately to
 - Webhook feature to send shutdown or restart notification messages
 - Unit & Integration Tests
 
-## Installation and Configuration
-
-TBD
-
-### Installation and Configuration
-
-TBD
+## Getting Started
 
 ### Infrastructure Setup
 
 TBD
 
-## Building
-For build instructions please consult [BUILD.md](./BUILD.md).
+### Installation and Configuration
+
+For a full list of inputs see the Helm chart [README.md](./charts/aws-node-termination-handler-2/README.md).
 
 ## Metrics
 
@@ -50,6 +39,7 @@ TBD
 ##  Contributing
 Contributions are welcome! Please read our [guidelines](https://github.com/aws/aws-node-termination-handler/blob/main/CONTRIBUTING.md) and our [Code of Conduct](https://github.com/aws/aws-node-termination-handler/blob/main/CODE_OF_CONDUCT.md)
 
+To setup a development environment see the instructions in [DEVELOPMENT.md](./DEVELOPMENT.md).
+
 ## License
 This project is licensed under the Apache-2.0 License.
-