Add EKS Pod Identity authentication instructions for the S3 repository

[somaz94]

Summary

Documents how to use EKS Pod Identity credentials with the S3 snapshot repository, as a companion to elastic/elasticsearch#151614. Adds an "Using EKS Pod Identity for authentication" subsection alongside the existing IRSA instructions: symlink the injected token into ${ES_PATH_CONF}/repository-s3/eks-pod-identity-token and repoint AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE (or the aws.containerAuthorizationTokenFile system property) at the symlink so the S3 repository can read it.

Validated locally with Vale (Elastic style v1.6.0): 0 errors, no findings on the added lines.

Related: elastic/elasticsearch#151614

---

Was generative AI tooling used to co-author this PR?

• Yes — Anthropic Claude (Opus 4.8)

[github-actions]

Elastic Docs AI PR menu

Check the box to run an AI review for this pull request.

• Review docs changes (docs-review). Status: not started.

Powered by GitHub Agentic Workflows and docs-actions. For more information, reach out to the docs team.

[eedugon]

Thanks a lot for proposing this new section @somaz94 ! I think it's great to support this new authentication method.

@DaveCTurner : I'm a bit concerned about possible confusion added by the new content in the s3 repository doc. Let me share my concerns and check the best way to go through them if needed (if you want I could also apply changes to the PR so we can review together)

• The introduction of the section should explain and describe better to what type of environment this applies. If I'm not mistaken this applies only to self-managed Elasticsearch nodes running as Kubernetes pods in EKS, so they can use the "EKS Pod identity authentication service", right? Even if that could feel obvious I guess we should address it in the intro, otherwise a reader of the S3 repository doc will suddenly encounter sentences talking about pods and tokens injection, and that could feel unexpected if they are not experts on EKS and AWS auth services.

• When it comes to running Elasticsearch pods on Kubernetes, I've always heard that the only officially supported way to run Elasticsearch on Kubernetes is through ECK (we don't have any docs or helm charts anymore to run Elasticsearch pods directly on Kubernetes). I know this section can help other users that might have their own managed pods running on EKS to use this service, but it feels a bit out of place at first sight, more over if this doesn't help explicitly ECK users. Anyway maybe a better intro helps here also, at least to ensure our readers know what this is about (but we should avoid users asking then how to run an Elasticsearch pod on EKS (without ECK) due to this).

• Would these instructions be useful for ECK users in any way?

  • If so we could add something at https://www.elastic.co/docs/deploy-manage/tools/snapshot-and-restore/cloud-on-k8s saying that this new authentication could be also used by ECK users.
  • If these instructions don't help ECK users at all we could create a new issue for ECK devs to consider this new addition and find a way to integrate it on ECK.

I'm not against documenting something EKS generic for self-managed pods (which aren't officially supported more than as a best effort basis), but I'd like to highlight it before adding it to the docs.

Please let me know your thoughts, thanks! And sorry if some of my assumptions are incorrect! ;)

[DaveCTurner]

Yes this should only apply to self-managed installations. I'm unclear whether it's applicable to ECK, or whether the ECK team would want to make use of this in future, so I'd be inclined not to mention ECK here. Is there a way to refine the applies_to thing to clarify this?

I'm not sure it's as confusing as you claim. There's a bunch of other things on this page that only apply to quite specific environments, e.g. the stuff about VPC bandwidth settings and the stuff about IAM roles for k8s service accounts. And here we start with "If you want to use EKS Pod Identity", linking to the AWS docs on EKS Pod Identity, so I wouldn't expect users to think they might be using this feature unwittingly.

[somaz94]

Thanks both! @DaveCTurner — yes, refined the applies_to to scope the section to self-managed only:

deployment:
  self: ga 9.6

This matches the page's own frontmatter (deployment: self:) and renders a self-managed badge on the section, so it's clear the instructions target self-managed {{es}} nodes rather than ECK or Cloud. I've left ECK unmentioned as you suggested. Pushed in b750c15.

@eedugon — hopefully the self-managed applies_to badge + the "If you want to use EKS Pod Identity" opening address the scoping concern. Happy to add an explicit intro sentence if you still feel it reads unexpectedly.

[DaveCTurner]

Thanks for working out the self: thing @somaz94. Apparently this repo doesn't work properly with PRs opened from forks so I've reopened this at #7316 to get the preview working.

[DaveCTurner]

Unsure if preview is available to external contributors but here's a screenshot.

[eedugon]

so I'd be inclined not to mention ECK here

Fair point, and mentioning ECK could mess things up. The current applies_to looks good also.

I'm not sure it's as confusing as you claim.

Yeah, I may have overstated it a bit.

There's a bunch of other things on this page that only apply to quite specific environments, e.g. the stuff about VPC bandwidth settings and the stuff about IAM roles for k8s service accounts.

The intro about the VPC bandwidth and NAT gateway considerations looks good to me.

It's true that the k8s service accounts related info could be a bit better scoped / introduced, more over if it relates to EKS only (which I'm not sure), but anyway that's a different story :)

Thanks a lot for your comments!

[DaveCTurner]

Sounds good thanks Edu -- I don't think there's any outstanding comments but this needs your approval before I can merge it.

[eedugon]

Approving to unlock in case you feel the proposed solution is enough!

One small concern I have on the technical solution is that we explain perfectly fine the objective (create a symlink and update the env var) and when (before node starts), but we don't really care or suggest anything to the user about the how to do it.

@somaz94 : how would you expect a user to apply this on their pods? If you both believe that's out of scope of the doc that's ok to me then! Maybe we don't want to get into Kubernetes territory.

In some way I would infer from the content that I probably need an initContainer to set up the directory + link + permissions, and then define the env var in the pod spec to make all this working.

Anyway if the doc just want to state the goal and what Elasticsearch needs, the content is really good. Sorry for the noise (again)!

[DaveCTurner]

Yes I'm going to call that out-of-scope for these docs. This whole thing applies to users running ES in (something like) EKS which isn't something we specifically support, or even explain how to do, so they're already taking charge of all the orchestration work needed to get it working. Let's stick to explaining how to set up the environment from ES's point of view and leave the details of how to achieve that to the user.