External Secrets Operator

External Secrets Operator integrates with Devolutions Server for secret management.

The values in this guide (e.g., your-application-id) are placeholders, replace them with the specific values of your environment.

Authentication

Devolutions Server authentication uses Application ID and Application secret credentials.

Creating an application identity in Devolutions Server

1. Log into your Devolutions Server's web interface.
2. Navigate to Administration – Applications identities.
3. Click Add (+) to create a new application.
4. Configure the application with the permissions required to access the desired vaults and entries.
5. Save the Application ID and Application secret.

Creating the Kubernetes secret

Create a Kubernetes secret containing your Devolutions Server credentials using the following script:

kubectl create secret generic dvls-credentials \
  --from-literal=app-id="your-application-id" \
  --from-literal=app-secret="your-application-secret"

Creating a SecretStore

apiVersion: external-secrets.io/v1
kind: SecretStore
metadata:
  name: dvls-store
  namespace: default
spec:
  provider:
    dvls:
      serverUrl: 'https://devolutions-server.example.com'
      vault: 'my-vault'
      auth:
        secretRef:
          appId:
            name: dvls-credentials
            key: app-id
          appSecret:
            name: dvls-credentials
            key: app-secret

Field	Description
serverUrl	The URL of the Devolutions Server instance (e.g., https://devolutions-server.example.com)
vault	The name or UUID of the vault from which to fetch secrets. When omitted, the vault must be specified in the secret key using the legacy <vault-id>/<entry-id> format. This field is optional.
insecure	Set to true to allow plain HTTP connections. Not recommended for production. This field is optional.
auth.secretRef.appId	Reference to the secret containing the Application ID.
auth.secretRef.appSecret	Reference to the secret containing the Application secret.

For ClusterSecretStore, ensure you specify the namespace in the secret references.

Referencing secrets

Entries can be referenced by UUID or name:

Format	Example
Entry UUID	7c9e6679-7425-40de-944b-e07fc1f90ae7
Entry name	db-credentials
Entry name with folder path	infrastructure/databases/db-credentials
Folder path with backslashes	infrastructure\databases\db-credentials

The vault is configured in the SecretStore's vault field (name or UUID), so the key only needs to identify the entry.

Folder paths

If an entry is inside a folder, you can include the folder path before the entry name. Both forward slashes (/) and backslashes (\) are accepted as path separators:

folder/subfolder/entry-name
folder\subfolder\entry-name

When using backslashes in YAML, you must escape them with a double backslash (\\):

key: "folder\\subfolder\\entry-name"

Forward slashes do not need escaping and are recommended for simplicity.

Entry names containing forward slashes (/) or backslashes (</code>) are not supported with name-based lookups, as those characters are interpreted as path separators. Use the entry UUID instead.

The folder path is optional. Without a path, the provider searches across all folders in the vault. If multiple entries share the same name in different folders, you can either specify the folder path or use the entry UUID to disambiguate.

Name-based lookups resolve the name to a UUID at runtime via an API call. If multiple credential entries match, an error is returned. For write-heavy scenarios (frequent PushSecret operations), prefer UUID references to avoid the extra lookup per operation.

You can find UUIDs in the Devolutions Server web interface by viewing the entry properties.

Supported credential types

Devolutions Server supports multiple credential types. The provider maps each type to specific properties:

Credential type	Devolutions Server entry type	Available properties
Default	Credential	username, password, domain
Access Code	Secret	password
API Key	Credential	api-id, api-key, tenant-id
Azure Service Principal	Credential	client-id, client-secret, tenant-id
Connection String	Credential	connection-string
Private Key	Credential	username, password, private-key, public-key, passphrase

All entries also include entry-id and entry-name metadata properties.

When no property is specified, the password field is returned by default.

In the Devolutions Server web interface, "Secret" entries appear as a distinct entry type and are mapped to the Access Code credential subtype internally.

Examples

Fetching individual properties

To fetch specific properties from a credential entry:

---
# Fetch a single property from a credential entry by name
apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: database-credentials
spec:
  refreshInterval: 1h
  secretStoreRef:
    kind: SecretStore
    name: dvls-store
  target:
    name: database-secret
    creationPolicy: Owner
  data:
    - secretKey: username
      remoteRef:
        key: 'db-credentials'
        property: username
    - secretKey: password
      remoteRef:
        key: 'db-credentials'
        property: password
---
# Fetch all fields from a credential entry with folder path
apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: api-credentials
spec:
  refreshInterval: 1h
  secretStoreRef:
    kind: SecretStore
    name: dvls-store
  target:
    name: api-secret
    creationPolicy: Owner
  dataFrom:
    - extract:
        key: 'infrastructure/apis/my-api-key'
---
# Fetch a Secret entry (Access Code type) by UUID
apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: app-secret
spec:
  refreshInterval: 1h
  secretStoreRef:
    kind: SecretStore
    name: dvls-store
  target:
    name: app-secret
    creationPolicy: Owner
  data:
    - secretKey: secret
      remoteRef:
        key: '<entry-uuid>'
        property: password

Using dataFrom to extract all fields

When using dataFrom.extract, all available properties from the credential entry will be synced to the Kubernetes secret.

Push secrets

The Devolutions Server provider supports pushing secrets back to Devolutions Server:

apiVersion: external-secrets.io/v1alpha1
kind: PushSecret
metadata:
  name: push-to-dvls
spec:
  refreshInterval: 1h
  secretStoreRefs:
    - name: dvls-store
      kind: SecretStore
  selector:
    secret:
      name: my-k8s-secret
  data:
    - match:
        secretKey: password
        remoteRef:
          # When vault is set in the SecretStore, remoteKey is the entry name
          # (or path/name). Without vault, use the legacy 'vault-uuid/entry-uuid' format.
          remoteKey: 'db-credentials'

Note: Push secret updates an existing entry's password field. The entry must already exist in Devolutions Server.

Limitations

• GetAllSecrets: The find operation for discovering secrets is not currently supported.
• Custom CA Certificates: Custom TLS certificates for self-signed Devolutions Server instances are not yet supported. Use the SSL_CERT_FILE environment variable as a workaround.
• Certificate entries: Certificate entry types (Document/Certificate) are not currently supported. Only Credential entries are supported.

Troubleshooting

Authentication errors

If you receive authentication errors:

1. Verify the Application ID and Secret are correct.
2. Ensure the application has the necessary permissions in Devolutions Server.
3. Check that the Devolutions Server server URL is accessible from your Kubernetes cluster.

Entry not found

If an entry cannot be found:

1. Verify the vault and entry references are correct (UUID or name)
2. Ensure the application has at least read access to the vault
3. Check that the entry exists and is a Credential or Secret type entry
4. Ensure the application has at least read, view password, and connect (execute) permissions on the entry

Multiple entries found

If you receive a "multiple entries found" error when using name-based references, it means more than one credential entry shares the same name in the vault. Use the entry UUID instead of the name to target the correct entry.