Skip to content

Commit 9e1831a

Browse files
MadVikingGodMadVikingGod
authored
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
1 parent dcef21a commit 9e1831a

9 files changed

+330
-8
lines changed

‎Makefile

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,11 @@ generate:
4545
docker-build: test
4646
docker build . -t ${IMG}
4747
@echo "updating kustomize image patch file for manager resource"
48-
sed -i '' -e 's@image: .*@image: '"${IMG}"'@' ./config/default/manager_image_patch.yaml
48+
ifeq ($(IAMROLEARN), )
49+
echo "IAMROLEARN must be set"
50+
exit 1
51+
endif
52+
sed -i '' -e 's@image: .*@image: '"${IMG}"'@' -e '[email protected]/role: .*@iam.amazonaws.com/role: '"${IAMROLEARN}"'@' ./config/default/manager_image_patch.yaml
4953

5054
# Push the docker image
5155
docker-push:

‎README.md

Lines changed: 97 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,105 @@
1-
![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)
1+
![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)
22

33
## AWS EKS Cluster Controller
44

5-
Manages EKS clusters in different AWS accounts. Provide CRUD like functionality and deployment of Kubernetes resources to EKS clusters.
5+
The aws-eks-cluster-controller manages cross account EKS clusters and [supported Kubernetes resources](docs/CurrentComponenets.md).
66

7+
This controller is built using the [kubebuilder](https://github.com/kubernetes-sigs/kubebuilder) framework. For more information [read their docs](https://book.kubebuilder.io/)
78

9+
### Concepts
10+
11+
- Parent EKS Cluster: The Kubernetes cluster where this controller runs.
12+
- Child EKS Clusters: These are the Kubernetes clusters managed by the controller running in parent EKS cluster.
13+
14+
### Turn Key Installation
15+
16+
#### Prerequisites
17+
18+
Make sure you have following tools installed on your workstation:
19+
20+
1. [aws-cli](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html)
21+
1. [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl)
22+
1. [eksctl](https://github.com/weaveworks/eksctl)
23+
1. [jq](https://stedolan.github.io/jq/download/)
24+
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)
25+
1. [kubebuilder](https://github.com/kubernetes-sigs/kubebuilder) - [install step](https://book.kubebuilder.io/getting_started/installation_and_setup.html)
26+
27+
-- or on MacOS via brew --
28+
29+
```sh
30+
brew install kustomize kubernetes-cli eksctl awscli weaveworks/tap/eksctl jq
31+
go get -u -v github.com/kubernetes-sigs/aws-iam-authenticator/cmd/aws-iam-authenticator
32+
```
33+
And [install kubebuilder](https://book.kubebuilder.io/getting_started/installation_and_setup.html)
34+
35+
36+
_IMPORTANT_ make sure your AWS user/role has sufficient permissions to use `eksctl`.
37+
38+
#### Setup Parent EKS cluster
39+
40+
1. Create the Parent EKS cluster
41+
42+
```sh
43+
eksctl create cluster
44+
```
45+
46+
1. Once `eksctl` has finished, verify you can access the cluster.
47+
48+
```sh
49+
kubectl get nodes
50+
```
51+
52+
1. For this installation process we use [kube2iam](https://github.com/jtblin/kube2iam) to manage IAM permissions for pods running on the parent cluster.
53+
54+
```sh
55+
kubectl apply -f deploy/kube2iam.yaml
56+
```
57+
58+
#### Build and deploy the Controller
59+
60+
1. Clone this project
61+
62+
```sh
63+
mkdir -p some/path
64+
cd some/path
65+
git clone [email protected]:awslabs/aws-eks-cluster-controller.git
66+
```
67+
68+
1. Create the IAM role that the controller will use
69+
70+
```sh
71+
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(",")'`; \
72+
73+
aws cloudformation create-stack \
74+
--stack-name aws-eks-controller-role \
75+
--capabilities CAPABILITY_IAM CAPABILITY_NAMED_IAM \
76+
--template-body file://config/setup/aws-eks-cluster-controller-role.yaml \
77+
--parameters \
78+
ParameterKey=WorkerArn,ParameterValue="'${NODE_INSTANCE_ROLE_ARNS}'"
79+
80+
export IAMROLEARN=`aws iam get-role --role-name aws-eks-cluster-controller | jq -r .Role.Arn`
81+
```
82+
83+
1. Create repository and build/push image
84+
85+
```sh
86+
# Create ECR Repository
87+
aws ecr create-repository --repository-name aws-eks-cluster-controller
88+
export REPOSITORY=`aws ecr describe-repositories --repository-name aws-eks-cluster-controller | jq -r '.repositories[0].repositoryUri'`
89+
90+
# Build/tag the docker image
91+
IMG=${REPOSITORY}:latest IAMROLEARN=${IAMROLEARN} make docker-build
92+
93+
# Push the docker image
94+
aws ecr get-login --no-include-email | bash -
95+
docker push ${REPOSITORY}:latest
96+
```
97+
98+
1. Install required Kubernetes CustomResourceDefinitions (CRDs) and deploy controller
99+
100+
```sh
101+
make deploy
102+
```
8103

9104
## License
10105

‎config/samples/cluster_v1alpha1_eks.yaml

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -5,11 +5,9 @@ metadata:
55
controller-tools.k8s.io: "1.0"
66
name: eks-sample
77
spec:
8-
# Add fields here
9-
foo: bar
10-
accountId: "12345678912"
11-
crossAccountRoleName: "foo"
12-
region: "us-test-1"
8+
accountId: "12345678912" # child AWS account
9+
crossAccountRoleName: "aws-eks-cluster-controller-management"
10+
region: "us-test-1" # region where child EKS cluster need to be created
1311
controlPlane:
1412
clusterName: "eks-1"
1513
nodeGroups:

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

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# this role need to be created in child aws account
2+
AWSTemplateFormatVersion: "2010-09-09"
3+
Description: "Role for the aws-eks-cluster-controller to assume"
4+
5+
Parameters:
6+
TrustedEntities:
7+
Type: CommaDelimitedList
8+
Description: AWS entities(IAM role ARNs, IAM user ARN, etc) allowed to assume this role in comma separated fashion
9+
10+
Resources:
11+
AWSServiceControllerRole:
12+
Type: AWS::IAM::Role
13+
Properties:
14+
RoleName: aws-eks-cluster-controller-management
15+
AssumeRolePolicyDocument:
16+
Version: "2012-10-17"
17+
Statement:
18+
-
19+
Effect: "Allow"
20+
Principal:
21+
AWS: !Ref TrustedEntities
22+
Action: "sts:AssumeRole"
23+
Policies:
24+
- PolicyName: aws-eks-cluster-controller-management
25+
PolicyDocument: |
26+
{
27+
"Version": "2012-10-17",
28+
"Statement": [
29+
{
30+
"Effect": "Allow",
31+
"Action": [
32+
"ec2:*",
33+
"autoscaling:*",
34+
"iam:*",
35+
"cloudformation:*",
36+
"eks:*",
37+
"sts:*"
38+
],
39+
"Resource": "*"
40+
}
41+
]
42+
}

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

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# this role need to be created in parent AWS account to be used with kube2iam
2+
AWSTemplateFormatVersion: "2010-09-09"
3+
Description: "Role for the eks-cluster-controller"
4+
5+
Parameters:
6+
WorkerArn:
7+
Type: String
8+
Description: The arn of the worker nodes used to assume this role
9+
10+
Resources:
11+
AWSServiceControllerRole:
12+
Type: AWS::IAM::Role
13+
Properties:
14+
RoleName: aws-eks-cluster-controller
15+
AssumeRolePolicyDocument: !Sub
16+
- |
17+
{
18+
"Version": "2012-10-17",
19+
"Statement": [
20+
{
21+
"Effect": "Allow",
22+
"Principal": {
23+
"Service": "ec2.amazonaws.com"
24+
},
25+
"Action": "sts:AssumeRole"
26+
},
27+
{
28+
"Effect": "Allow",
29+
"Principal": {
30+
"AWS": "${WorkerArn}"
31+
},
32+
"Action": "sts:AssumeRole"
33+
}
34+
]
35+
}
36+
- WorkerArn: !Ref WorkerArn
37+
Policies:
38+
- PolicyName: aws-eks-cluster-controller
39+
PolicyDocument: |
40+
{
41+
"Version": "2012-10-17",
42+
"Statement": [
43+
{
44+
"Effect": "Allow",
45+
"Action": [
46+
"sts:AssumeRole"
47+
],
48+
"Resource": "*"
49+
}
50+
]
51+
}

‎config/setup/kube2iam.yaml

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
---
2+
apiVersion: v1
3+
kind: ServiceAccount
4+
metadata:
5+
name: kube2iam
6+
namespace: default
7+
---
8+
apiVersion: rbac.authorization.k8s.io/v1
9+
kind: ClusterRole
10+
metadata:
11+
name: kube2iam
12+
rules:
13+
- apiGroups:
14+
- ""
15+
resources:
16+
- namespaces
17+
- pods
18+
verbs:
19+
- get
20+
- watch
21+
- list
22+
---
23+
apiVersion: rbac.authorization.k8s.io/v1
24+
kind: ClusterRoleBinding
25+
metadata:
26+
name: kube2iam
27+
roleRef:
28+
apiGroup: rbac.authorization.k8s.io
29+
kind: ClusterRole
30+
name: kube2iam
31+
subjects:
32+
- kind: ServiceAccount
33+
name: kube2iam
34+
namespace: default
35+
---
36+
apiVersion: extensions/v1beta1
37+
kind: DaemonSet
38+
metadata:
39+
generation: 1
40+
labels:
41+
app: kube2iam
42+
name: kube2iam
43+
namespace: default
44+
spec:
45+
revisionHistoryLimit: 10
46+
selector:
47+
matchLabels:
48+
name: kube2iam
49+
template:
50+
metadata:
51+
labels:
52+
name: kube2iam
53+
spec:
54+
containers:
55+
- args:
56+
- --auto-discover-base-arn
57+
- --host-interface=eni+
58+
- --host-ip=$(HOST_IP)
59+
- --iptables=true
60+
env:
61+
- name: HOST_IP
62+
valueFrom:
63+
fieldRef:
64+
apiVersion: v1
65+
fieldPath: status.podIP
66+
image: jtblin/kube2iam:0.10.4
67+
imagePullPolicy: IfNotPresent
68+
name: kube2iam
69+
ports:
70+
- containerPort: 8181
71+
hostPort: 8181
72+
name: http
73+
protocol: TCP
74+
securityContext:
75+
privileged: true
76+
dnsPolicy: ClusterFirst
77+
hostNetwork: true
78+
serviceAccountName: kube2iam
79+
updateStrategy:
80+
rollingUpdate:
81+
maxUnavailable: 1
82+
type: RollingUpdate

‎docs/CurrentComponenets.md

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
aws-eks-cluster-controller models following resources as Kubernetes [CustomResourceDefinitions(CRDs)](https://kubernetes.io/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definitions/):
2+
3+
### Current Resources
4+
1. EKS Clusters
5+
1. EKS Controlplane
6+
1. EKS Nodegroups
7+
1. Kubernetes [Deployments](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.13/#deployment-v1-apps)
8+
1. Kubernetes [Services](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.13/#service-v1-core)
9+
1. Kubernetes [ConfigMaps](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.13/#configmap-v1-core)
10+
1. Kubernetes [Ingress](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.13/#ingress-v1beta1-extensions)
11+
1. Kubernetes [Secrets](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.13/#secret-v1-core)
12+
13+
### Future Resources
14+
None current planned. Please include a link to the issue that describing the use case.

‎docs/Examples.md

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
### Create resources on child AWS account
2+
Make sure you can access parent EKS cluster using kubectl.
3+
4+
#### Create EKS cluster in child account
5+
* Check the `config/samples/cluster_v1alpha1_eks.yaml` and make necessary changes
6+
```
7+
kubectl apply -f config/samples/cluster_v1alpha1_eks.yaml
8+
```
9+
#### Create Deployment in child EKS cluster
10+
* Make changes to `config/samples/components_v1alpha1_deployment.yaml`, if required.
11+
```
12+
kubectl apply -f config/samples/components_v1alpha1_deployment.yaml
13+
```
14+
#### Create Service in child EKS cluster
15+
* Make changes to `config/samples/components_v1alpha1_service.yaml`, if required.
16+
```
17+
kubectl apply -f config/samples/components_v1alpha1_service.yaml
18+
```
19+
#### Other samples
20+
There are sample files in `config/samples` directory for other resources.

‎docs/LocalDevelopment.md

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Local Development
2+
This is the process where you can start building and testing locally.
3+
4+
### Prerequisites
5+
The same prerequisites from the [readme](../README.md#Prerequisites)
6+
7+
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)
8+
9+
Your local environment will need to be able to assume the role that manages the remote environment.
10+
11+
##### Run controller locally
12+
1. Run the controller
13+
```
14+
make run
15+
```
16+
Generally you will iterate on this step in development or testing out something quickly.

0 commit comments

Comments
 (0)