|
1 | | -= AWS Operator |
| 1 | += AWS Service Operator |
2 | 2 |
|
3 | | -The AWS Operator allows you to create custom AWS specific resources using |
4 | | -Kubernetes CRDs or Custom Resource Definitions. These help with defining your |
5 | | -applications including all the necessary components such as Amazon RDS |
6 | | -databases, Amazon ElasticCache resources, Amazon SQS queues and many more. |
| 3 | +The AWS Service Operator allows you to manage AWS resources using |
| 4 | +Kubernetes Custom Resource Definitions. |
7 | 5 |
|
8 | | -Using the AWS Operator allows your to use processes like `gitops` to keep your |
9 | | -clusters in a specified state with the internal control loop managing the |
10 | | -lifecycle of those components. |
| 6 | +Using the AWS Service Operator enables a `gitops` workflow to drive your infrastructure to the desired state leveraging Kubernetes Custom Resource Definitions (CRD), the Kubernetes internal control loop, and AWS cloudformation orchestration. Read more about "operators" link:https://coreos.com/operators/[here]. |
11 | 7 |
|
12 | | -To make this all possible we merge together Kubernetes CRDs with an operator |
13 | | -which interacts with Amazon Cloudformation to keep the AWS resources in-sync |
14 | | -with the control loop. |
| 8 | +image::aws-service-operator-example.gif[] |
15 | 9 |
|
16 | | -// TODO: Add demo screen capture |
| 10 | +== Prerequisites |
| 11 | + |
| 12 | +To get started you will need |
| 13 | + |
| 14 | +- a Kubernetes cluster running in AWS. Check out link:https://docs.aws.amazon.com/eks/latest/userguide/what-is-eks.html[EKS] or link:https://github.com/kubernetes/kops[kops] to get started |
| 15 | +- link:https://kubernetes.io/docs/tasks/tools/install-kubectl/[kubectl] |
| 16 | +- link:https://docs.aws.amazon.com/cli/latest/userguide/installing.html[awscli] |
17 | 17 |
|
18 | 18 | == Getting Started |
19 | 19 |
|
20 | | -First thing that you will need to do is install an Pod to IAM management layer |
21 | | -such as `kube2iam`. This will allow you to create an AWS IAM role that gives |
22 | | -access to create resources. For an example policy check the |
23 | | -`examples/iam-policy.json`. |
| 20 | +Make sure your Kubernetes cluster is up and running and you've configured your awscli for the approriate account and region you'll be working in. |
| 21 | + |
| 22 | +=== IAM permissions management |
| 23 | + |
| 24 | +You will need to install an IAM management layer |
| 25 | +such as `kube2iam`. This will allow you to use an AWS IAM role to manage a pod's |
| 26 | +access to AWS resources. |
24 | 27 |
|
25 | | -To get started with `kube2iam` go [here](https://github.com/jtblin/kube2iam) |
| 28 | +To get started with `kube2iam` go link:https://github.com/jtblin/kube2iam[here] or check out the |
| 29 | +link:https://github.com/helm/charts/tree/master/stable/kube2iam[helm chart] |
26 | 30 |
|
27 | | -After you have installed `kube2iam` we need to do is deploy the `aws-operator` |
28 | | -this runs as a pod in your Kubernetes cluster and listen for new CRD's of the |
29 | | -`aws` type and creates the resource and allocates a kubernetes `Service` to |
30 | | -connect to it. |
| 31 | +The `aws-service-operator` runs as a pod in your Kubernetes cluster and listens for new `aws` type CRDs. |
| 32 | +When a new CRD is created the operator will create the resource in AWS via cloudformation and |
| 33 | +create a Kubernetes `Service` for access within the cluster. |
31 | 34 |
|
32 | | -You'll want to download the operator file like so |
| 35 | +=== Create an IAM role for the `aws-service-operator` |
| 36 | + |
| 37 | + The `K8S_WORKER_NODE_IAM_ROLE` is the IAM role assigned to your kubernetes worker instances. |
33 | 38 |
|
34 | 39 | [source,shell] |
35 | | ----- |
36 | | -wget https://raw.githubusercontent.com/christopherhein/aws-operator/master/configs/aws-operator.yaml |
37 | | ----- |
| 40 | +aws cloudformation create-stack \ |
| 41 | + --stack-name aws-service-operator-role \ |
| 42 | + --capabilities CAPABILITY_NAMED_IAM \ |
| 43 | + --template-body file://configs/aws-service-operator-role.yaml \ |
| 44 | + --parameters \ |
| 45 | + ParameterKey=WorkerArn,ParameterValue=<K8S_WORKER_NODE_IAM_ROLE> |
38 | 46 |
|
39 | | -Then edit the file and replace `{{POD-ARN}}` with the pod ARN you created for |
40 | | -`kube2iam` |
| 47 | +Your resulting IAM role arn should look something like `arn:aws:iam::<ACCOUNT_ID>:role/aws-service-operator` |
41 | 48 |
|
42 | | -Last install the manifest with the pod ARN specified. |
| 49 | +=== Deploy the aws-service-operator |
43 | 50 |
|
44 | | -[source,shell] |
45 | | ----- |
46 | | -# Install RBAC |
47 | | -kubectl apply -f aws-operator.yaml |
48 | | ----- |
| 51 | +Before applying these resources make sure to replace the following placeholders with the approriate information in `configs/aws-service-operator.yaml` |
49 | 52 |
|
50 | | -To test this create a file like this |
| 53 | +- `<ACCOUNT_ID>` - Your AWS Account ID |
| 54 | +- `<REGION>` - The AWS Region you're working in |
| 55 | +- `<CLUSTER_NAME>` - The name of your cluster |
| 56 | +- `<BUCKET_NAME>` - (optional) The operator stores certain things in s3 create a bucket or provide an existing bucket for the operator to use `i.e. aws s3 mb s3://foobar` |
51 | 57 |
|
52 | | -[source,yaml] |
53 | | ----- |
54 | | -# s3bucket.yml |
55 | | -apiVersion: operator.aws/v1alpha1 |
56 | | -kind: S3Bucket |
57 | | -metadata: |
58 | | - name: some-name-for-your-bucket |
59 | | -spec: |
60 | | - bucketName: some-name-for-your-bucket |
61 | | - versioning: false |
62 | | - logging: |
63 | | - enabled: true |
64 | | - prefix: "archive" |
65 | | - tags: |
66 | | - - key: service |
67 | | - value: kube |
68 | | ----- |
69 | | - |
70 | | -Then install like you would any other manifest file. |
71 | 58 |
|
| 59 | +.1. Create the operator |
| 60 | +[source,shell] |
| 61 | +kubectl apply -f configs/aws-service-operator.yaml |
| 62 | + |
| 63 | +.2. Create the cloudformation templates (cft) used by the operator |
72 | 64 | [source,shell] |
73 | | ----- |
74 | | -kubectl apply -f s3bucket.yml |
75 | | ----- |
| 65 | +kubectl apply -f examples/cloudformationtemplates |
76 | 66 |
|
77 | | -This will communicate directly with Cloudformation to create the S3 bucket using |
| 67 | +.3. (optional) Follow the operator logs |
| 68 | +[source,shell] |
| 69 | +kubectl logs -f -n aws-service-operator deploy/aws-service-operator |
| 70 | + |
| 71 | +.4. Create an ecr repository with the operator |
| 72 | +[source,yaml] |
| 73 | +kubectl apply -f examples/ecrrepository.yaml |
| 74 | + |
| 75 | +The operator will communicate directly with Cloudformation to create the ecr repository using |
78 | 76 | the parameters you have passed in. If you'd like to see the progress you can |
79 | 77 | view the status directly via `kubectl`. |
80 | 78 |
|
| 79 | +.5. Check the ecr resource in Kubernetes |
81 | 80 | [source,shell] |
82 | | ----- |
83 | | -kubectl get s3buckets <bucket-name> -w |
84 | | -// TODO: add output. |
85 | | ----- |
| 81 | +kubectl describe ecr example-repository-name |
86 | 82 |
|
87 | | -To learn more about the other resources please visit the documentation at |
88 | | -link:/docs/readme.adoc[Documentation] |
| 83 | +== Removing everything |
89 | 84 |
|
| 85 | +If you would like to tear everything down - run the following commands. |
| 86 | + |
| 87 | +*IMPORTANT* this will not remove anything you created with the AWS cli (ecr repo for the operator itself, IAM roles etc.) |
| 88 | + |
| 89 | +[source,shell] |
| 90 | +kubectl delete ecr example-repository-name |
| 91 | +kubectl get crd | grep ".operator.aws" | awk '{print $1}' | xargs kubectl delete crd |
| 92 | +kubectl delete -f configs/aws-service-operator.yaml |
0 commit comments