[Internal]: Inaccurate information in ECK documentation

[greicefaustino]

Description

This page https://www.elastic.co/docs/deploy-manage/users-roles/cluster-or-deployment-auth/file-based#k8s-basic
That intents to address issues in ECK clusters when the security index is gone (it says: For example in cases where the cluster is unresponsive or the security index is unavailable)

Gives us this example for creating a new user and role:

apiVersion: v1
kind: Secret
metadata:
  name: secret-basic-auth
type: kubernetes.io/basic-auth
stringData:
  username: rdeniro    # required field for kubernetes.io/basic-auth
  password: mypassword # required field for kubernetes.io/basic-auth
  roles: kibana_admin,ingest_admin  # optional, not part of kubernetes.io/basic-auth

It lists roles inside the auth secret and lists only the auth secret in the manifest:

apiVersion: elasticsearch.k8s.elastic.co/v1
kind: Elasticsearch
metadata:
  name: elasticsearch-sample
spec:
  version: 8.16.1
  auth:
    fileRealm:
    - secretName: secret-basic-auth
  nodeSets:
  - name: default
    count: 1

However, this doesn't work (only if those roles already exists in the cluster, but we are talking about when the security index is gone just like this page description mentions).

The correct example should include the secret for user and role creation:

apiVersion: v1
kind: Secret
metadata:
  name: secret-basic-auth
type: kubernetes.io/basic-auth
stringData:
  username: my_admin
  password: my_password
  roles: new_role

apiVersion: v1
kind: Secret
metadata:
  name: my-roles-secret
stringData:
  roles.yml: |-
    new_role:
      cluster:
        - all
      indices:
        - names: [ '*' ]
          privileges: [ 'all' ]
          allow_restricted_indices: true

and the correct Elasticsearch manifest should include:

  auth:
    fileRealm:
    - secretName: secret-basic-auth
    roles:
    - secretName: my-roles-secret

Which documentation set does this change impact?

Elastic On-Prem only

Feature differences

What release is this request related to?

N/A

Serverless release

Collaboration model

The documentation team

Point of contact.

[stefnestor]

Confirming pain point but acknowledging the existing information is not "inaccurate". That is an expected basic setup. However, Greice's example highlights that when attempting to recover the security/system indices you need extra permissions on top higher than role:superuser which falls under a custom role presently.

[greicefaustino]

Yes @stefnestor because if the security index is gone as the description of this document mentions (it says at the top: For example in cases where the cluster is unresponsive or the security index is unavailable), it is misleading to reference:
roles: kibana_admin,ingest_admin # optional, not part of kubernetes.io/basic-auth inside secret-basic-auth

specially followed by the manifest that is not including roles:

spec:
  version: 8.16.1
  auth:
    fileRealm:
    - secretName: secret-basic-auth

To me is was like the correct approach in ECK is to reference roles (even new created ones with special permission) inside secret-basic-auth and not in the final manifest. The final manifest would contain only the fileRealm with the specified roles inside it

[stefnestor]

Oh great call out! AFAIK "security index is unavailable" was intended to suggest if the node doesn't host .security* and can't reach the cluster but not that .security* is red/corrupt. I will add this to the list for rewrite 💚

[kunisen]

cc @eedugon on relevant discussion:
@pebrc also mentioned in this comment, that we used to have a consolidated page and now "The new docs system has split up the documentation into two places that are quite hard to find".

(I think we could handle this in a single PR but please let me know if you prefer we do it separately)

[pebrc]

@kunisen I raised #2492 to link the two places together and make the roles documentation easier to find from the file realm one.

[eedugon]

@greicefaustino : let us know if with the implemented change in the docs this issue is solved, and users should know how to create the file-realm roles together with the file-realm users whenever they lose access to the cluster when the security index is gone :)

Very good finding by the way!!