Skip to content
This repository was archived by the owner on Jan 9, 2023. It is now read-only.

Commit 39ac5fa

Browse files
simonswinesimonswine
authored
Merge pull request #295 from MattiasGees/kube2iam-docs
Kube2iam docs
2 parents fa7a7b9 + 70bc5b2 commit 39ac5fa

File tree

4 files changed

+261
-0
lines changed

4 files changed

+261
-0
lines changed

‎docs/examples.rst‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
Examples
2+
========
3+
4+
This section covers extra add-ons you can install on Tarmak kubernetes
5+
clusters.
6+
7+
.. toctree::
8+
:glob:
9+
:maxdepth: 1
10+
11+
examples/*

‎docs/examples/kube2iam.rst‎

Lines changed: 246 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,246 @@
1+
Kube2IAM
2+
--------
3+
4+
Kube2IAM is an extension to kubernetes that will allow you to give
5+
fine grained AWS access to pods without. More information about the
6+
project can be found on the `project page <https://github.com/jtblin/kube2iam>`_.
7+
8+
Prerequisite
9+
~~~~~~~~~~~~
10+
11+
Make sure `HELM <https://www.helm.sh/>`_ is `activated <https://docs.tarmak.io/user-guide.html#tiller>`_ on the Tarmak cluster.
12+
You also need to make sure you can connect to the cluster with your HELM install.
13+
14+
.. code-block:: bash
15+
16+
helm version
17+
Client: &version.Version{SemVer:"v2.9.1", GitCommit:"20adb27c7c5868466912eebdf6664e7390ebe710", GitTreeState:"clean"}
18+
Server: &version.Version{SemVer:"v2.9.1", GitCommit:"20adb27c7c5868466912eebdf6664e7390ebe710", GitTreeState:"clean"}
19+
20+
Setup
21+
~~~~~
22+
23+
Create instance IAM policy
24+
++++++++++++++++++++++++++
25+
26+
Every instance that will run the kube2iam pod needs to have an specific
27+
IAM policy attached to the IAM instance role of that instance.
28+
29+
The following Terraform project creates an IAM policy that will give
30+
instances the ability to assume roles. The assume role is restricted to
31+
only have access to roles deployed in a specific path. By doing this, we can
32+
limit the amount of roles an instance can assume to only the roles that it really
33+
needs to.
34+
The Terraform project has 2 inputs ``aws_region`` and ``cluster_name``.
35+
The projects also has 2 outputs defined the ``ARN`` and ``path`` of the IAM policy.
36+
The ARN is what you need to give to Tarmak and the path is needed to be
37+
able to deploy your roles for the pods in the correct path.
38+
39+
.. code-block:: none
40+
41+
terraform {}
42+
43+
provider "aws" {
44+
region = "${var.aws_region}"
45+
}
46+
47+
variable "aws_region" {
48+
description = "AWS Region you want to deploy it in"
49+
default = "eu-west-1"
50+
}
51+
52+
variable "cluster_name" {
53+
description = "Name of the cluster"
54+
}
55+
56+
data "aws_caller_identity" "current" {}
57+
58+
resource "aws_iam_policy" "kube2iam" {
59+
name = "kube2iam_assumeRole_policy_${var.cluster_name}"
60+
path = "/"
61+
description = "Kube2IAM role policy for ${var.cluster_name}"
62+
63+
policy = "${data.aws_iam_policy_document.kube2iam.json}"
64+
}
65+
66+
data "aws_iam_policy_document" "kube2iam" {
67+
statement {
68+
sid = "1"
69+
70+
actions = [
71+
"sts:AssumeRole",
72+
]
73+
74+
effect = "Allow"
75+
76+
resources = [
77+
"arn:aws:iam::${data.aws_caller_identity.current.account_id}:role/kube2iam_${var.cluster_name}/*",
78+
]
79+
}
80+
}
81+
82+
output "kube2iam_arn" {
83+
value = "${aws_iam_policy.kube2iam.arn}"
84+
}
85+
86+
output "kube2iam_path" {
87+
value = "/kube2iam_${var.cluster_name}/"
88+
}
89+
90+
91+
You can run the Terraform project the following way:
92+
93+
.. code-block:: bash
94+
95+
terraform init
96+
terraform apply -var cluster_name=example -var region=eu-west-1
97+
98+
Attach instance policy
99+
++++++++++++++++++++++
100+
101+
Add the created IAM policy ARN to your tarmak config. You can do this by
102+
adding `additional IAM policies <https://docs.tarmak.io/user-guide.html#additional-iam-policies>`_.
103+
104+
Deploy kube2iam
105+
+++++++++++++++
106+
107+
With `HELM <https://www.helm.sh/>`_ it is easy to deploy kube2iam with
108+
the correct settings.
109+
110+
You can deploy it with the following command:
111+
112+
.. code-block:: bash
113+
114+
helm upgrade kube2iam stable/kube2iam \
115+
--install \
116+
--version 0.9.0 \
117+
--namespace kube-system \
118+
--set=extraArgs.host-ip=127.0.0.1 \
119+
--set=extraArgs.log-format=json \
120+
--set=updateStrategy=RollingUpdate \
121+
--set=rbac.create=true \
122+
--set=host.iptables=false
123+
124+
125+
We set ``iptables`` to false and ``host-ip`` to 127.0.0.1 as Tarmak already creates
126+
the iptables rule and forward it to ``127.0.0.1:8181``.
127+
Specific kube2iam options can be found in the `documentation <https://github.com/jtblin/kube2iam>`_ of kube2iam.
128+
129+
Usage
130+
~~~~~
131+
132+
Now that kube2IAM is installed on your system, you can start creating roles
133+
and policies to give your pods access to AWS resources.
134+
135+
An example creation of an IAM policy and role:
136+
137+
.. code-block:: none
138+
139+
terraform {}
140+
141+
provider "aws" {
142+
region = "${var.aws_region}"
143+
}
144+
145+
variable "aws_region" {
146+
description = "AWS Region you want to deploy it in"
147+
default = "eu-west-1"
148+
}
149+
150+
variable "cluster_name" {
151+
description = "Name of the cluster"
152+
}
153+
154+
variable "instance_iam_role_arn" {
155+
description = "ARN of the instance IAM role"
156+
}
157+
158+
resource "aws_iam_role" "test_role" {
159+
name = "test_role"
160+
path = "/kube2iam_${var.cluster_name}/"
161+
162+
assume_role_policy = "${data.aws_iam_policy_document.test_role.json}"
163+
}
164+
165+
data "aws_iam_policy_document" "test_role" {
166+
statement {
167+
sid = "1"
168+
169+
actions = [
170+
"sts:AssumeRole",
171+
]
172+
173+
principals {
174+
type = "AWS"
175+
identifiers = ["${var.instance_iam_role_arn}"]
176+
}
177+
}
178+
}
179+
180+
resource "aws_iam_role_policy" "test_role_policy" {
181+
name = "test_policy"
182+
role = "${aws_iam_role.test_role.id}"
183+
184+
policy = "${data.aws_iam_policy_document.test_role_policy.json}"
185+
}
186+
187+
data "aws_iam_policy_document" "test_role_policy" {
188+
statement {
189+
sid = "1"
190+
191+
actions = [
192+
"s3:ListAllMyBuckets",
193+
]
194+
195+
resources = [
196+
"*",
197+
]
198+
}
199+
}
200+
201+
output "test_role" {
202+
value = "${aws_iam_role.test_role.arn}"
203+
}
204+
205+
Now you can run this Terraform project the following way:
206+
207+
.. code-block:: bash
208+
209+
terraform init
210+
terraform apply -var cluster_name=example -var region=eu-west-1 -var instance_iam_role_arn=arn:aws:iam::xxxxxxx:role/my-instance-role
211+
212+
213+
When you create a role, you need to make sure you deploy it in the correct
214+
``path`` and also add an assume role policy to it. That assume role policy
215+
needs to grant access to the role ARN that is attached to the instances.
216+
In our example Terraform project above we solved that by adding a variable for
217+
the ``instance_iam_role_arn`` and the ``cluster_name``.
218+
219+
.. warning::
220+
Make sure you use the IAM role ARN attached to your worker Kubernetes
221+
instances as input for ``instance_iam_role_arn``. You can retrieve the
222+
IAM role ARN through the AWS console.
223+
Don't confuse this with the earlier created IAM policy.
224+
225+
With the output ``test_role``, you can add that ARN as an annotation to
226+
your Pod/Deployment/ReplicaSet etc.
227+
In the following example we spin up a pod to list all buckets:
228+
229+
.. code-block:: yaml
230+
231+
apiVersion: v1
232+
kind: Pod
233+
metadata:
234+
name: aws-cli
235+
labels:
236+
name: aws-cli
237+
annotations:
238+
iam.amazonaws.com/role: role-arn
239+
spec:
240+
containers:
241+
- name: aws-cli
242+
image: fstab/aws-cli
243+
command:
244+
- "/home/aws/aws/env/bin/aws"
245+
- "s3"
246+
- "ls"

‎docs/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,7 @@ build and deploy Kubernetes in production at scale.
4848

4949
known-issues
5050
troubleshooting
51+
examples
5152
existing-vpc
5253
vault-setup-config
5354
vault-helper-guide

‎docs/spelling_wordlist.txt‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -65,6 +65,8 @@ Jenkins
6565
prepended
6666
username
6767
loopback
68+
iptables
69+
ons
6870
CIDR
6971
addons
7072
autoscaler
@@ -75,6 +77,7 @@ admin
7577
plugin
7678
checklist
7779
localhost
80+
ReplicaSet
7881
overprovisioning
7982
autoscaling
8083
preempted

0 commit comments

Comments
 (0)