docs(akeyless): fix errors and expand provider documentation (#6506)

Signed-off-by: Alexander Chernov <alexander@chernov.it>

docs/provider/akeyless.md

@@ -9,7 +9,7 @@ SecretStore resource specifies how to access Akeyless. This resource is namespac
 **NOTE:** Make sure the Akeyless provider is listed in the Kind=SecretStore.
 If you use a customer fragment, define the value of akeylessGWApiURL as the URL of your Akeyless Gateway in the following format: https://your.akeyless.gw:8080/v2.
 
-Akeyelss provide several Authentication Methods:
+Akeyless provides several Authentication Methods:
 
 ### Authentication with Kubernetes
 
@@ -25,22 +25,23 @@ Options for obtaining Kubernetes credentials include:
 {% include 'akeyless-secret-store-k8s-auth.yaml' %}
 ```
 
-**NOTE:** In case of a `ClusterSecretStore`, Be sure to provide `namespace` for `serviceAccountRef` and `secretRef` according to  the namespaces where the secrets reside.
+**NOTE:** In case of a `ClusterSecretStore`, be sure to provide `namespace` for `serviceAccountRef` and `secretRef` according to the namespaces where the secrets reside.
 
-### Authentication With Cloud-Identity or Api-Access-Key
+### Authentication with Cloud-Identity or Api-Access-Key
 
-Akeyless providers require an access-id, access-type and access-Type-param
-To set your SecretStore with an authentication method from Akeyless.
+Akeyless providers require an access-id, access-type and access-type-param
+to set your SecretStore with an authentication method from Akeyless.
 
 The supported auth-methods and their parameters are:
 
-| accessType  | accessTypeParam                                                                                                                                                                                                                      |
-| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `aws_iam` |   -                                                         |
-| `gcp` |      The gcp audience                                                      |
-| `azure_ad` |  azure object id  (optional)                                                          |
-| `api_key`      | The access key.                                                                                                                                     |
-| `k8s`         | The k8s configuration name |
+| accessType     | accessTypeParam                    |
+| -------------- | ---------------------------------- |
+| `aws_iam`      | -                                  |
+| `gcp`          | The GCP audience                   |
+| `azure_ad`     | Azure object ID (optional)         |
+| `api_key`      | The access key                     |
+| `access_key`   | The access key (alias for api_key) |
+| `k8s`          | The k8s configuration name         |
 
 For more information see [Akeyless Authentication Methods](https://docs.akeyless.io/docs/access-and-authentication-methods)
 
@@ -49,15 +50,7 @@ For more information see [Akeyless Authentication Methods](https://docs.akeyless
 Create a secret containing your credentials using the following example as a guide:
 
 ```yaml
-apiVersion: v1
-kind: Secret
-metadata:
-  name: akeyless-secret-creds
-type: Opaque
-stringData:
-  accessId: "p-XXXX"
-  accessType:  # gcp/azure_ad/api_key/k8s/aws_iam
-  accessTypeParam:  # optional: can be one of the following: gcp-audience/azure-obj-id/access-key/k8s-conf-name
+{% include 'akeyless-credentials-secret.yaml' %}
 ```
 
 #### Create the Akeyless Secret Store Provider with the Credentials Secret
@@ -66,7 +59,7 @@ stringData:
 {% include 'akeyless-secret-store.yaml' %}
 ```
 
-**NOTE:** In case of a `ClusterSecretStore`, be sure to provide `namespace` for `accessID`, `accessType` and `accessTypeParam`  according to the namespaces where the secrets reside.
+**NOTE:** In case of a `ClusterSecretStore`, be sure to provide `namespace` for `accessID`, `accessType` and `accessTypeParam` according to the namespaces where the secrets reside.
 
 #### Create the Akeyless Secret Store With CAs for TLS handshake
 
@@ -83,7 +76,7 @@ spec:
       # Instead of caBundle you can also specify a caProvider
       # this will retrieve the cert from a Secret or ConfigMap
       caProvider:
-        type: "Secret/ConfigMap" # Can be Secret or ConfigMap
+        type: Secret  # Can be Secret or ConfigMap
         name: "<name of secret or configmap>"
         key: "<key inside secret>"
         # namespace is mandatory for ClusterSecretStore and not relevant for SecretStore
@@ -91,6 +84,15 @@ spec:
   ....
 ```
 
+### Supported Secret Types
+
+The provider supports the following Akeyless item types:
+
+- **Static Secret** -- standard key/value secret
+- **Dynamic Secret** -- ephemeral credentials generated on demand
+- **Rotated Secret** -- automatically rotated credentials
+- **Certificate** -- TLS/SSH certificates
+
 ### Creating an external secret
 
 To get a secret from Akeyless and create it as a secret on the Kubernetes cluster, a `Kind=ExternalSecret` is needed.
@@ -99,15 +101,57 @@ To get a secret from Akeyless and create it as a secret on the Kubernetes cluste
 {% include 'akeyless-external-secret.yaml' %}
 ```
 
+#### Fetching a specific version
+
+Use `remoteRef.version` to pin a specific secret version (integer). Omit the field or set it to `0` to get the latest version.
+
+```yaml
+data:
+  - secretKey: password
+    remoteRef:
+      key: /path/to/secret
+      version: "3"  # fetch version 3 specifically
+```
+
+#### Extracting a property from a JSON secret
+
+If the secret value is a JSON object, use `remoteRef.property` to extract a single key. Nested keys can be addressed with dot notation; literal dots in key names are escaped with a backslash (`key\.with\.dots`).
+
+```yaml
+data:
+  - secretKey: db-password
+    remoteRef:
+      key: /path/to/json-secret
+      property: password  # extracts {"password": "..."} from the JSON value
+```
 
 #### Using DataFrom
 
-DataFrom can be used to get a secret as a JSON string and attempt to parse it.
+DataFrom can be used to get a secret as a JSON string and attempt to parse it, creating one Kubernetes secret key per JSON field.
 
 ```yaml
 {% include 'akeyless-external-secret-json.yaml' %}
 ```
 
+#### Finding secrets by name or tag
+
+Use `dataFrom.find` to bulk-fetch secrets matching a name pattern or tag:
+
+```yaml
+# by name regex
+dataFrom:
+  - find:
+      path: /my/path/         # optional path prefix
+      name:
+        regexp: ".*db.*"
+
+# by tag
+dataFrom:
+  - find:
+      tags:
+        env: production
+```
+
 ### Getting the Kubernetes Secret
 
 The operator will fetch the secret and inject it as a `Kind=Secret`.
@@ -124,7 +168,9 @@ kubectl get secret database-credentials-json -o jsonpath='{.data}'
 
 To push a secret from Kubernetes cluster and create it as a secret to Akeyless, a `Kind=PushSecret` resource is needed.
 
+```yaml
 {% include 'akeyless-push-secret.yaml' %}
+```
 
 Then when you create a matching secret as follows:
 

docs/snippets/akeyless-credentials-secret.yaml

@@ -5,8 +5,5 @@ metadata:
 type: Opaque
 stringData:
   accessId: "p-XXXX"
-  accessType:  # k8s/aws_iam/gcp/azure_ad/api_key
-  accessTypeParam: # can be one of the following: k8s-conf-name/gcp-audience/azure-obj-id/access-key
-
-
-
+  accessType:  # one of: aws_iam / gcp / azure_ad / api_key / access_key / k8s
+  accessTypeParam:  # optional -- one of: gcp-audience / azure-obj-id / access-key / k8s-conf-name

docs/snippets/akeyless-secret-store-k8s-auth.yaml

@@ -13,12 +13,16 @@ spec:
           k8sConfName: "my-conf-name"
 
           # Optional service account field containing the name
-          # of a kubernetes ServiceAccount
+          # of a kubernetes ServiceAccount.
+          # For ClusterSecretStore, namespace is required.
           serviceAccountRef:
             name: "my-sa"
+            # namespace: "my-namespace"  # required for ClusterSecretStore
 
           # Optional secret field containing a Kubernetes ServiceAccount JWT
-          # used for authenticating with Akeyless
+          # used for authenticating with Akeyless.
+          # For ClusterSecretStore, namespace is required.
           secretRef:
             name: "my-secret"
             key: "token"
+            # namespace: "my-namespace"  # required for ClusterSecretStore