From d3e9f3e0e4a167e43812b2ba0a169d4df66bcc20 Mon Sep 17 00:00:00 2001
From: Eli Polonsky <epolon@amazon.com>
Date: Sun, 21 Mar 2021 15:10:30 +0200
Subject: [PATCH] chore(elasticsearch): Explain SLR requirement in README
 (#13546)

Explain when an SLR is needed, and how to create one. This can be a source of confusion because the ES console experience hides the SLR from users by automatically creating it if needed.

Related to https://github.com/aws/aws-cdk/issues/13367

----

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*
---
 packages/@aws-cdk/aws-elasticsearch/README.md | 24 +++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/packages/@aws-cdk/aws-elasticsearch/README.md b/packages/@aws-cdk/aws-elasticsearch/README.md
index 37d117c393616..359b28dda1b66 100644
--- a/packages/@aws-cdk/aws-elasticsearch/README.md
+++ b/packages/@aws-cdk/aws-elasticsearch/README.md
@@ -74,6 +74,30 @@ const prodDomain = new es.Domain(this, 'Domain', {
 This creates an Elasticsearch cluster and automatically sets up log groups for
 logging the domain logs and slow search logs.
 
+## A note about SLR
+
+Some cluster configurations (e.g VPC access) require the existence of the [`AWSServiceRoleForAmazonElasticsearchService`](https://docs.aws.amazon.com/elasticsearch-service/latest/developerguide/slr-es.html) Service-Linked Role.
+
+When performing such operations via the AWS Console, this SLR is created automatically when needed. However, this is not the behavior when using CloudFormation. If an SLR is needed, but doesn't exist, you will encounter a failure message simlar to:
+
+```console
+Before you can proceed, you must enable a service-linked role to give Amazon ES...
+```
+
+To resolve this, you need to [create](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html#create-service-linked-role) the SLR. We recommend using the AWS CLI:
+
+```console
+aws iam create-service-linked-role --aws-service-name es.amazonaws.com
+```
+
+You can also create it using the CDK, **but note that only the first application deploying this will succeed**:
+
+```ts
+const slr = new iam.CfnServiceLinkedRole(this, 'ElasticSLR', {
+  awsServiceName: 'es.amazonaws.com'
+});
+```
+
 ## Importing existing domains
 
 To import an existing domain into your CDK application, use the `Domain.fromDomainEndpoint` factory method.