diff --git a/docs/install.md b/docs/install.md index 5cbe97c2..ce5e8a74 100644 --- a/docs/install.md +++ b/docs/install.md @@ -1,8 +1,68 @@ ## Install -*Minimum supported Kubernetes version: v1.11* +### Kubernetes Requirements -Although the controller can be used independently from the aws-app-mesh-inject webhook, it is recommended that they be used together. To Install the webhook, execute the following commands: +* *Minimum supported Kubernetes version: v1.11* +* IAM permissions for the controller. See the policy under "Using the install scripts" below, or create a cluster using eksctl with the following flags set: + +```bash +eksctl create cluster --appmesh-access +``` + +Alternatively, you can use set up a role for the controller using [IAM for Service Accounts](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html). This approach follows the principle of least privilege by keeping the permissions required by the controller off the worker node instance profile. + +### With Helm (Recommended) + +To start, add the eks-charts helm repository: + +```bash +helm repo add eks https://aws.github.io/eks-charts +``` + +Create the `appmesh-system` namespace: + +```bash +kubectl create ns appmesh-system +``` + +Apply the CRDs: + +```bash +kubectl apply -f https://raw.githubusercontent.com/aws/eks-charts/master/stable/appmesh-controller/crds/crds.yaml +``` + +Install the appmesh-controller: + +```bash +helm upgrade -i appmesh-controller eks/appmesh-controller --namespace appmesh-system +``` + +Install the mutating admission webhook (aws-app-mesh-inject): + +```bash +helm upgrade -i appmesh-inject eks/appmesh-inject \ +--namespace appmesh-system \ +--set mesh.create=true \ +--set mesh.name=global +``` + +If you've installed the App Mesh controllers with scripts, you can switch to Helm by removing the controllers with: + +```bash +# remove injector objects +kubectl delete ns appmesh-inject +kubectl delete ClusterRoleBinding aws-app-mesh-inject-binding +kubectl delete ClusterRole aws-app-mesh-inject-cr +kubectl delete MutatingWebhookConfiguration aws-app-mesh-inject + +# remove controller objects +kubectl delete ns appmesh-system +kubectl delete ClusterRoleBinding app-mesh-controller-binding +kubectl delete ClusterRole app-mesh-controller +Note that you shouldn't delete the App Mesh CRDs or the App Mesh custom resources (virtual nodes or services) in your cluster. Once you've removed the App Mesh controller and injector objects, you can proceed with the Helm installation as described above. +``` + +### Using the install scripts ```bash # use `export MESH_NAME=color-mesh` to work with the example in this repository. @@ -43,7 +103,17 @@ This will launch the webhook into the appmesh-inject namespace. Now add the corr "appmesh:DeleteVirtualNode", "appmesh:DeleteVirtualService", "appmesh:DeleteVirtualRouter", - "appmesh:DeleteRoute" + "appmesh:DeleteRoute", + "servicediscovery:CreateService", + "servicediscovery:GetService", + "servicediscovery:RegisterInstance", + "servicediscovery:DeregisterInstance", + "servicediscovery:ListInstances", + "route53:GetHealthCheck", + "route53:CreateHealthCheck", + "route53:UpdateHealthCheck", + "route53:ChangeResourceRecordSets", + "route53:DeleteHealthCheck" ], "Resource": "*" }