This is a rework of the readme PR. (#46)

* Updating Readme file

* Files needed for setup are now in config/setup

* Simplified the readme to get a better getting started flow.

* Added links to references, and updated prereqs

Makefile

@@ -45,7 +45,11 @@ generate:
 docker-build: test
 	docker build . -t ${IMG}
 	@echo "updating kustomize image patch file for manager resource"
-	sed -i '' -e 's@image: .*@image: '"${IMG}"'@' ./config/default/manager_image_patch.yaml
+ifeq ($(IAMROLEARN), )
+	echo "IAMROLEARN must be set"
+	exit 1
+endif
+	sed -i '' -e 's@image: .*@image: '"${IMG}"'@' -e 's@iam.amazonaws.com/role: .*@iam.amazonaws.com/role: '"${IAMROLEARN}"'@' ./config/default/manager_image_patch.yaml
 
 # Push the docker image
 docker-push:

README.md

@@ -1,10 +1,105 @@
-![CircleCI](https://circleci.com/gh/awslabs/aws-eks-cluster-controller.svg?style=svg&circle-token=5f800668d4109bde7cae271f9faa2500e7e33461)](https://circleci.com/gh/awslabs/aws-eks-cluster-controller)
+![CircleCI](https://circleci.com/gh/awslabs/aws-eks-cluster-controller.svg?style=svg&circle-token=5f800668d4109bde7cae271f9faa2500e7e33461)(https://circleci.com/gh/awslabs/aws-eks-cluster-controller)
 
 ## AWS EKS Cluster Controller
 
-Manages EKS clusters in different AWS accounts. Provide CRUD like functionality and deployment of Kubernetes resources to EKS clusters.
+The aws-eks-cluster-controller manages cross account EKS clusters and [supported Kubernetes resources](docs/CurrentComponenets.md).
 
+This controller is built using the [kubebuilder](https://github.com/kubernetes-sigs/kubebuilder) framework. For more information [read their docs](https://book.kubebuilder.io/)
 
+### Concepts
+
+- Parent EKS Cluster: The Kubernetes cluster where this controller runs.
+- Child EKS Clusters: These are the Kubernetes clusters managed by the controller running in parent EKS cluster.
+
+### Turn Key Installation
+
+#### Prerequisites
+
+Make sure you have following tools installed on your workstation:
+
+1. [aws-cli](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html)
+1. [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl)
+1. [eksctl](https://github.com/weaveworks/eksctl)
+1. [jq](https://stedolan.github.io/jq/download/)
+1. [aws-iam-authenticator](https://github.com/kubernetes-sigs/aws-iam-authenticator#4-set-up-kubectl-to-use-authentication-tokens-provided-by-aws-iam-authenticator-for-kubernetes)
+1. [kubebuilder](https://github.com/kubernetes-sigs/kubebuilder) - [install step](https://book.kubebuilder.io/getting_started/installation_and_setup.html)
+
+-- or on MacOS via brew --
+
+```sh
+brew install kustomize kubernetes-cli eksctl awscli weaveworks/tap/eksctl jq
+go get -u -v github.com/kubernetes-sigs/aws-iam-authenticator/cmd/aws-iam-authenticator
+```
+And [install kubebuilder](https://book.kubebuilder.io/getting_started/installation_and_setup.html)
+
+
+_IMPORTANT_ make sure your AWS user/role has sufficient permissions to use `eksctl`.
+
+#### Setup Parent EKS cluster
+
+1. Create the Parent EKS cluster
+
+   ```sh
+   eksctl create cluster
+   ```
+
+1. Once `eksctl` has finished, verify you can access the cluster.
+
+   ```sh
+   kubectl get nodes
+   ```
+
+1. For this installation process we use [kube2iam](https://github.com/jtblin/kube2iam) to manage IAM permissions for pods running on the parent cluster.
+
+   ```sh
+   kubectl apply -f deploy/kube2iam.yaml
+   ```
+
+#### Build and deploy the Controller
+
+1. Clone this project
+
+   ```sh
+   mkdir -p some/path
+   cd some/path
+   git clone git@github.com:awslabs/aws-eks-cluster-controller.git
+   ```
+
+1. Create the IAM role that the controller will use
+
+   ```sh
+   export NODE_INSTANCE_ROLE_ARNS=`aws iam list-roles | jq -r --arg reg_exp "^eksctl-.*-NodeInstanceRole-.*$" '.Roles | map(select(.RoleName|test($reg_exp))) | map(.Arn) | join(",")'`; \
+
+   aws cloudformation create-stack \
+    --stack-name aws-eks-controller-role \
+    --capabilities CAPABILITY_IAM CAPABILITY_NAMED_IAM \
+    --template-body file://config/setup/aws-eks-cluster-controller-role.yaml \
+    --parameters \
+      ParameterKey=WorkerArn,ParameterValue="'${NODE_INSTANCE_ROLE_ARNS}'"
+
+   export IAMROLEARN=`aws iam get-role --role-name aws-eks-cluster-controller | jq -r .Role.Arn`
+   ```
+
+1. Create repository and build/push image
+
+   ```sh
+   # Create ECR Repository
+   aws ecr create-repository --repository-name aws-eks-cluster-controller
+   export REPOSITORY=`aws ecr describe-repositories --repository-name aws-eks-cluster-controller | jq -r '.repositories[0].repositoryUri'`
+
+   # Build/tag the docker image
+   IMG=${REPOSITORY}:latest IAMROLEARN=${IAMROLEARN} make docker-build
+   
+   # Push the docker image
+   aws ecr get-login --no-include-email | bash -
+   docker push ${REPOSITORY}:latest
+   ```
+
+1. Install required Kubernetes CustomResourceDefinitions (CRDs) and deploy controller
+
+   ```sh
+   make deploy
+   ```
 
 ## License
 

config/samples/cluster_v1alpha1_eks.yaml

@@ -5,11 +5,9 @@ metadata:
     controller-tools.k8s.io: "1.0"
   name: eks-sample
 spec:
-  # Add fields here
-  foo: bar
-  accountId: "12345678912"
-  crossAccountRoleName: "foo"
-  region: "us-test-1"
+  accountId: "12345678912"    # child AWS account
+  crossAccountRoleName: "aws-eks-cluster-controller-management"
+  region: "us-test-1"         # region where child EKS cluster need to be created
   controlPlane:
     clusterName: "eks-1"
   nodeGroups:

config/setup/aws-eks-cluster-controller-management-role.yaml

@@ -0,0 +1,42 @@
+# this role need to be created in child aws account
+AWSTemplateFormatVersion: "2010-09-09"
+Description: "Role for the aws-eks-cluster-controller to assume"
+
+Parameters:
+  TrustedEntities:
+    Type: CommaDelimitedList
+    Description: AWS entities(IAM role ARNs, IAM user ARN, etc) allowed to assume this role in comma separated fashion
+
+Resources:
+  AWSServiceControllerRole:
+    Type: AWS::IAM::Role
+    Properties:
+      RoleName: aws-eks-cluster-controller-management
+      AssumeRolePolicyDocument:
+        Version: "2012-10-17"
+        Statement:
+          -
+            Effect: "Allow"
+            Principal:
+              AWS: !Ref TrustedEntities
+            Action: "sts:AssumeRole"
+      Policies:
+        - PolicyName: aws-eks-cluster-controller-management
+          PolicyDocument: |
+            {
+              "Version": "2012-10-17",
+              "Statement": [
+                {
+                  "Effect": "Allow",
+                  "Action": [
+                    "ec2:*",
+                    "autoscaling:*",
+                    "iam:*",
+                    "cloudformation:*",
+                    "eks:*",
+                    "sts:*"
+                  ],
+                  "Resource": "*"
+                }
+              ]
+            }

config/setup/aws-eks-cluster-controller-role.yaml

@@ -0,0 +1,51 @@
+# this role need to be created in parent AWS account to be used with kube2iam
+AWSTemplateFormatVersion: "2010-09-09"
+Description: "Role for the eks-cluster-controller"
+
+Parameters:
+  WorkerArn:
+    Type: String
+    Description: The arn of the worker nodes used to assume this role
+
+Resources:
+  AWSServiceControllerRole:
+    Type: AWS::IAM::Role
+    Properties:
+      RoleName: aws-eks-cluster-controller
+      AssumeRolePolicyDocument: !Sub
+        - |
+          {
+            "Version": "2012-10-17",
+            "Statement": [
+              {
+                "Effect": "Allow",
+                "Principal": {
+                  "Service": "ec2.amazonaws.com"
+                },
+                "Action": "sts:AssumeRole"
+              },
+              {
+                "Effect": "Allow",
+                "Principal": {
+                  "AWS": "${WorkerArn}"
+                },
+                "Action": "sts:AssumeRole"
+              }
+            ]
+          }
+        - WorkerArn: !Ref WorkerArn
+      Policies:
+        - PolicyName: aws-eks-cluster-controller
+          PolicyDocument: |
+            {
+              "Version": "2012-10-17",
+              "Statement": [
+                {
+                  "Effect": "Allow",
+                  "Action": [
+                    "sts:AssumeRole"
+                  ],
+                  "Resource": "*"
+                }
+              ]
+            }

config/setup/kube2iam.yaml

@@ -0,0 +1,82 @@
+---
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: kube2iam
+  namespace: default
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  name: kube2iam
+rules:
+- apiGroups:
+  - ""
+  resources:
+  - namespaces
+  - pods
+  verbs:
+  - get
+  - watch
+  - list
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+  name: kube2iam
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: ClusterRole
+  name: kube2iam
+subjects:
+- kind: ServiceAccount
+  name: kube2iam
+  namespace: default
+---
+apiVersion: extensions/v1beta1
+kind: DaemonSet
+metadata:
+  generation: 1
+  labels:
+    app: kube2iam
+  name: kube2iam
+  namespace: default
+spec:
+  revisionHistoryLimit: 10
+  selector:
+    matchLabels:
+      name: kube2iam
+  template:
+    metadata:
+      labels:
+        name: kube2iam
+    spec:
+      containers:
+      - args:
+        - --auto-discover-base-arn
+        - --host-interface=eni+
+        - --host-ip=$(HOST_IP)
+        - --iptables=true
+        env:
+        - name: HOST_IP
+          valueFrom:
+            fieldRef:
+              apiVersion: v1
+              fieldPath: status.podIP
+        image: jtblin/kube2iam:0.10.4
+        imagePullPolicy: IfNotPresent
+        name: kube2iam
+        ports:
+        - containerPort: 8181
+          hostPort: 8181
+          name: http
+          protocol: TCP
+        securityContext:
+          privileged: true
+      dnsPolicy: ClusterFirst
+      hostNetwork: true
+      serviceAccountName: kube2iam
+  updateStrategy:
+    rollingUpdate:
+      maxUnavailable: 1
+    type: RollingUpdate

docs/CurrentComponenets.md

@@ -0,0 +1,14 @@
+aws-eks-cluster-controller models following resources as Kubernetes [CustomResourceDefinitions(CRDs)](https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/):
+
+### Current Resources
+1. EKS Clusters
+   1. EKS Controlplane
+   1. EKS Nodegroups
+1. Kubernetes [Deployments](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.13/#deployment-v1-apps)
+1. Kubernetes [Services](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.13/#service-v1-core)
+1. Kubernetes [ConfigMaps](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.13/#configmap-v1-core)
+1. Kubernetes [Ingress](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.13/#ingress-v1beta1-extensions)
+1. Kubernetes [Secrets](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.13/#secret-v1-core)
+
+### Future Resources
+None current planned.  Please include a link to the issue that describing the use case.

docs/Examples.md

@@ -0,0 +1,20 @@
+### Create resources on child AWS account
+Make sure you can access parent EKS cluster using kubectl.
+
+#### Create EKS cluster in child account
+* Check the `config/samples/cluster_v1alpha1_eks.yaml` and make necessary changes
+    ```
+    kubectl apply -f config/samples/cluster_v1alpha1_eks.yaml
+    ```
+#### Create Deployment in child EKS cluster
+* Make changes to `config/samples/components_v1alpha1_deployment.yaml`, if required.
+    ```
+    kubectl apply -f config/samples/components_v1alpha1_deployment.yaml
+    ```
+#### Create Service in child EKS cluster
+* Make changes to `config/samples/components_v1alpha1_service.yaml`, if required.
+    ```
+    kubectl apply -f config/samples/components_v1alpha1_service.yaml
+    ```
+#### Other samples
+There are sample files in `config/samples` directory for other resources.

docs/LocalDevelopment.md

@@ -0,0 +1,16 @@
+# Local Development
+This is the process where you can start building and testing locally. 
+
+### Prerequisites
+The same prerequisites from the [readme](../README.md#Prerequisites)
+
+You will also need a kubernetes cluster running, docker comes with one, or follow the steps from the readme [Setup Parent EKS cluster](../README.md#Setup-Parent-EKS-cluster)
+
+Your local environment will need to be able to assume the role that manages the remote environment.
+
+##### Run controller locally
+1. Run the controller
+    ```
+    make run
+    ```
+    Generally you will iterate on this step in development or testing out something quickly.