Skip to content

Akeyless

Akeyless Secrets Management Platform

External Secrets Operator integrates with the Akeyless Secrets Management Platform.

Create Secret Store

SecretStore resource specifies how to access Akeyless. This resource is namespaced.

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.

Akeyless provides several Authentication Methods:

Authentication with Kubernetes

Options for obtaining Kubernetes credentials include:

  1. Using a service account jwt referenced in serviceAccountRef
  2. Using the jwt from a Kind=Secret referenced by the secretRef
  3. Using transient credentials from the mounted service account token within the external-secrets operator

Create the Akeyless Secret Store Provider with Kubernetes Auth-Method

apiVersion: external-secrets.io/v1
kind: SecretStore
metadata:
  name: akeyless-secret-store
spec:
  provider:
    akeyless:
      # URL of your akeyless API
      akeylessGWApiURL: "https://api.akeyless.io"
      authSecretRef:
        kubernetesAuth:
          accessID: "p-XXXXXX"
          k8sConfName: "my-conf-name"

          # Optional service account field containing the name
          # 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.
          # For ClusterSecretStore, namespace is required.
          secretRef:
            name: "my-secret"
            key: "token"
            # namespace: "my-namespace"  # required for ClusterSecretStore

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

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
access_key The access key (alias for api_key)
k8s The k8s configuration name

For more information see Akeyless Authentication Methods

Creating an Akeyless Credentials Secret

Create a secret containing your credentials using the following example as a guide:

apiVersion: v1
kind: Secret
metadata:
  name: akeyless-secret-creds
type: Opaque
stringData:
  accessId: "p-XXXX"
  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

Create the Akeyless Secret Store Provider with the Credentials Secret

apiVersion: external-secrets.io/v1
kind: SecretStore
metadata:
  name: akeyless-secret-store
spec:
  provider:
    akeyless:
      # URL of your akeyless API
      akeylessGWApiURL: "https://api.akeyless.io"
      authSecretRef:
        secretRef:
          accessID:
            name: akeyless-secret-creds
            key: accessId
          accessType:
            name: akeyless-secret-creds
            key: accessType
          accessTypeParam:
            name: akeyless-secret-creds
            key: accessTypeParam

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

....
spec:
  provider:
    akeyless:
      akeylessGWApiURL: "https://your.akeyless.gw:8080/v2"

      # Optional caBundle - PEM/base64 encoded CA certificate
      caBundle: "<base64 encoded cabundle>"
      # Optional caProvider:
      # Instead of caBundle you can also specify a caProvider
      # this will retrieve the cert from a Secret or ConfigMap
      caProvider:
        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
        namespace: "my-cert-secret-namespace"
  ....

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.

apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: database-credentials
spec:
  refreshInterval: 1h0m0s

  secretStoreRef:
    kind: SecretStore
    name: akeyless-secret-store # Must match SecretStore on the cluster

  target:
    name: database-credentials # Name for the secret to be created on the cluster
    creationPolicy: Owner

  data:
    - secretKey: username # Key given to the secret to be created on the cluster
      remoteRef:
        key: db-username  # Full path of the secret on Akeyless
    - secretKey: password # Key given to the secret to be created on the cluster
      remoteRef:
        key: db-password  # Full path of the secret on Akeyless

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.

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).

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, creating one Kubernetes secret key per JSON field.

apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: database-credentials
spec:
  refreshInterval: 1h0m0s

  secretStoreRef:
    kind: SecretStore
    name: akeyless-secret-store # Must match SecretStore on the cluster

  target:
    name: database-credentials-json # Name for the secret to be created on the cluster
    creationPolicy: Owner

  # for json formatted secrets: each key in the json will be used as the secret key in the SECRET k8s target object
  dataFrom:
  - extract:
      key: database-credentials # Full path of the secret on Akeyless

Finding secrets by name or tag

Use dataFrom.find to bulk-fetch secrets matching a name pattern or tag:

# 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.

kubectl get secret database-credentials -o jsonpath='{.data.db-password}' | base64 -d

kubectl get secret database-credentials-json -o jsonpath='{.data}'

Pushing a secret

To push a secret from Kubernetes cluster and create it as a secret to Akeyless, a Kind=PushSecret resource is needed.

apiVersion: external-secrets.io/v1alpha1
kind: PushSecret
metadata:
 name: push-secret
spec:
 refreshInterval: 1h0m0s
 updatePolicy: Replace
 deletionPolicy: Delete
 secretStoreRefs:
   - name: akeyless-secret-store
     kind: SecretStore
 selector:
   secret:
     name: k8s-created-secret
 data:
   - match:
      remoteRef:
        remoteKey: eso-created/my-secret

Then when you create a matching secret as follows:

kubectl create secret generic --from-literal=cache-pass=mypassword k8s-created-secret

Then it will create a secret in akeyless eso-created/my-secret with value {"cache-pass":"mypassword"}