External Secrets Operator

External Secrets Operator se integra con Devolutions Server para la gestión de secretos.

Los valores de esta guía (p. ej., your-application-id) son marcadores de posición; sustitúyalos por los valores específicos de su entorno.

Autenticación

La autenticación de Devolutions Server utiliza credenciales de ID de aplicación y Secreto de aplicación.

Creación de una identidad de aplicación en Devolutions Server

1. Inicie sesión en la interfaz web de su Devolutions Server.
2. Vaya a Administración – Identidades de aplicaciones.
3. Haga clic en Añadir (+) para crear una nueva aplicación.
4. Configure la aplicación con los permisos necesarios para acceder a las bóvedas y entradas deseadas.
5. Guarde el ID de aplicación y el Secreto de aplicación.

Creación del secreto de Kubernetes

Cree un secreto de Kubernetes que contenga sus credenciales de Devolutions Server con el siguiente script:

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

Creación de un 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

Campo	Descripción
serverUrl	La URL de la instancia de Devolutions Server (p. ej., https://devolutions-server.example.com)
vault	El nombre o UUID de la bóveda de la que se obtienen los secretos. Si se omite, la bóveda debe especificarse en la clave del secreto con el formato heredado <vault-id>/<entry-id>. Este campo es opcional.
insecure	Establézcalo en true para permitir conexiones HTTP sin cifrar. No se recomienda para producción. Este campo es opcional.
auth.secretRef.appId	Referencia al secreto que contiene el ID de aplicación.
auth.secretRef.appSecret	Referencia al secreto que contiene el Secreto de aplicación.

Para ClusterSecretStore, asegúrese de especificar el namespace en las referencias del secreto.

Referenciar secretos

Las entradas pueden referenciarse por UUID o por nombre:

Formato	Ejemplo
UUID de la entrada	7c9e6679-7425-40de-944b-e07fc1f90ae7
Nombre de la entrada	db-credentials
Nombre de la entrada con ruta de carpeta	infrastructure/databases/db-credentials
Ruta de carpeta con barras invertidas	infrastructure\databases\db-credentials

La bóveda se configura en el campo vault del SecretStore (nombre o UUID), por lo que la clave solo necesita identificar la entrada.

Rutas de carpetas

Si una entrada se encuentra dentro de una carpeta, puede incluir la ruta de la carpeta antes del nombre de la entrada. Se aceptan tanto las barras (/) como las barras invertidas (\) como separadores de ruta:

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

Al utilizar barras invertidas en YAML, debe escaparlas con una barra invertida doble (\\):

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

Las barras no necesitan escaparse y se recomiendan por simplicidad.

Los nombres de entrada que contienen barras (/) o barras invertidas (</code>) are not supported with name-based lookups, as those characters are interpreted as path separators. Use the entry UUID instead.

La ruta de la carpeta es opcional. Sin una ruta, el proveedor busca en todas las carpetas de la bóveda. Si varias entradas comparten el mismo nombre en carpetas diferentes, puede especificar la ruta de la carpeta o utilizar el UUID de la entrada para desambiguar.

Las búsquedas basadas en nombre resuelven el nombre a un UUID en tiempo de ejecución mediante una llamada a la API. Si coinciden varias entradas de credenciales, se devuelve un error. Para escenarios con muchas escrituras (operaciones PushSecret frecuentes), es preferible utilizar referencias por UUID para evitar la búsqueda adicional en cada operación.

Puede encontrar los UUID en la interfaz web de Devolutions Server consultando las propiedades de la entrada.

Tipos de credenciales admitidos

Devolutions Server admite varios tipos de credenciales. El proveedor asigna cada tipo a propiedades específicas:

Tipo de credencial	Tipo de entrada de Devolutions Server	Propiedades disponibles
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

Todas las entradas incluyen también las propiedades de metadatos entry-id y entry-name.

Si no se especifica ninguna property, se devuelve el campo password de forma predeterminada.

En la interfaz web de Devolutions Server, las entradas «Secret» aparecen como un tipo de entrada distinto y se asignan internamente al subtipo de credencial Access Code.

Ejemplos

Obtención de propiedades individuales

Para obtener propiedades específicas de una entrada de credencial:

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

Uso de dataFrom para extraer todos los campos

Al utilizar dataFrom.extract, todas las propiedades disponibles de la entrada de credencial se sincronizarán con el secreto de Kubernetes.

Envío de secretos

El proveedor de Devolutions Server admite el envío de secretos de vuelta a 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'

Nota: el envío de secretos actualiza el campo de contraseña de una entrada existente. La entrada ya debe existir en Devolutions Server.

Limitaciones

• GetAllSecrets: la operación find para descubrir secretos no se admite actualmente.
• Certificados de CA personalizados: todavía no se admiten certificados TLS personalizados para instancias de Devolutions Server autofirmadas. Utilice la variable de entorno SSL_CERT_FILE como solución alternativa.
• Entradas de certificado: los tipos de entrada de certificado (Document/Certificate) no se admiten actualmente. Solo se admiten las entradas de tipo Credential.

Solución de problemas

Errores de autenticación

Si recibe errores de autenticación:

1. Verifique que el ID de aplicación y el secreto sean correctos.
2. Asegúrese de que la aplicación tenga los permisos necesarios en Devolutions Server.
3. Compruebe que la URL del servidor de Devolutions Server sea accesible desde su clúster de Kubernetes.

Entrada no encontrada

Si no se puede encontrar una entrada:

1. Verifique que las referencias de la bóveda y de la entrada sean correctas (UUID o nombre)
2. Asegúrese de que la aplicación tenga al menos acceso de lectura a la bóveda
3. Compruebe que la entrada existe y es una entrada de tipo Credential o Secret
4. Asegúrese de que la aplicación tenga al menos permisos de lectura, ver contraseña y conectar (ejecutar) sobre la entrada

Se han encontrado varias entradas

Si recibe un error de tipo «multiple entries found» al utilizar referencias basadas en nombre, significa que más de una entrada de credencial comparte el mismo nombre en la bóveda. Utilice el UUID de la entrada en lugar del nombre para apuntar a la entrada correcta.