> ## Documentation Index
> Fetch the complete documentation index at: https://docs.abbyy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Secretos y Key Vault

> Cómo Vantage 3.0 autoalojado obtiene secretos y certificados: de Azure Key Vault mediante el controlador Secrets Store CSI o de recursos Secret de Kubernetes preexistentes.

Vantage 3.0 autoalojado obtiene cada cadena de conexión a la base de datos, cada API key y cada certificado TLS de un proveedor de secretos al iniciar el pod; ninguno de estos valores se almacena en archivos `values.yaml`. Se admiten dos proveedores; en cada instalación se configura exactamente uno mediante `vantage.secrets`.

<div id="supported-providers">
  ## Proveedores compatibles
</div>

| Proveedor                 | Valor de Helm                | Descripción                                                                                                                                                                                          |
| ------------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Azure Key Vault**       | `vantage.secrets.azure`      | Usa el controlador Secrets Store CSI con el proveedor de Azure Key Vault. El operador aprovisiona una `SecretProviderClass` por chart y el controlador monta los secretos en los pods como archivos. |
| **Secrets de Kubernetes** | `vantage.secrets.kubernetes` | Usa directamente recursos `Secret` de Kubernetes ya existentes. No se requiere infraestructura externa de secretos.                                                                                  |

Los dos proveedores comparten la misma convención de **alias de secreto**. Las cargas de trabajo de Vantage buscan los secretos por alias, independientemente de dónde provengan los valores. Usa el [inventario de alias](#secret-aliases) que aparece a continuación para planificar el aprovisionamiento.

<div id="azure-key-vault-provider">
  ## Proveedor de Azure Key Vault
</div>

```yaml theme={null}
vantage:
  secrets:
    azure:
      keyVaultName: mykeyvault
      tenantId: 00000000-0000-0000-0000-000000000000
      clientId: 00000000-0000-0000-0000-000000000000  # ID de cliente de la UAMI con acceso de lectura al Key Vault
      identityMode: workloadIdentity                   # workloadIdentity (predeterminado) | podIdentity | vmManagedIdentity
```

<div id="identity-modes">
  ### Modos de identidad
</div>

| Modo                                | Cómo se autentica el controlador CSI                                                                                                                                                                                                                                                     |
| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `workloadIdentity` (predeterminado) | Azure Workload Identity. El ServiceAccount de cada chart está federado con una identidad administrada asignada por el usuario (UAMI) cuyo `clientId` se proporciona aquí. Esa UAMI debe tener acceso de lectura a los objetos de Key Vault que respaldan los alias usados por ese chart. |
| `podIdentity`                       | Enlace heredado de AAD Pod Identity. Este modo no es un escenario probado; ponte en contacto con tu equipo de cuentas de ABBYY antes de confiar en él.                                                                                                                                   |
| `vmManagedIdentity`                 | Una identidad administrada asignada a una VM. El ID de cliente de la UAMI se proporciona mediante `vantage.secrets.azure.userAssignedIdentityID`. Esa identidad debe tener acceso de lectura a Key Vault.                                                                                |

<div id="how-it-works">
  ### Cómo funciona
</div>

Vantage usa el controlador Secrets Store CSI con el proveedor de Azure Key Vault. El `SecretProviderClass` de cada chart se monta como un volumen CSI en el pod que lo consume, y ese montaje hace que el controlador sincronice los valores en un `Secret` de Kubernetes específico de cada chart (la funcionalidad `secretObjects` del SPC), que el pod consume mediante `envFrom` y montajes de volumen. La secuencia es:

```
┌──────────────────────┐
│  Azure Key Vault     │  Objetos de secreto/certificado aprovisionados por el cliente
└──────────┬───────────┘
           │ ① lectura mediante la identidad configurada
           ▼
┌──────────────────────────────────────────────────┐
│  SecretProviderClass  (uno por chart)            │  Creado por el operador
│  alias → Key Vault objectName                    │
│  alias → key en el Kubernetes Secret por chart   │
└──────────┬───────────────────────────────────────┘
           │ ② el controlador Secrets Store CSI rellena
           ▼
┌──────────────────────────────────────────────────┐
│  Kubernetes Secret  (uno por chart)              │  p. ej. mail-helm-secrets
└──────────┬───────────────────────────────────────┘
           │ ③ envFrom (variables de entorno) y/o volumeMounts (archivos)
           ▼
┌──────────────────────────────────────────────────┐
│  Vantage pod                                     │
└──────────────────────────────────────────────────┘
```

1. El operador genera un `SecretProviderClass` (SPC) por chart, en el que declara qué alias de Key Vault necesita ese chart y cómo se asigna cada uno a una clave de un `Secret` de Kubernetes específico del chart.
2. Cuando un pod monta el volumen del SPC, el controlador Secrets Store CSI se autentica con la identidad seleccionada por `identityMode`, obtiene de Key Vault los objetos indicados y los sincroniza en un `Secret` de Kubernetes específico del chart mediante la funcionalidad `secretObjects` del SPC.
3. El pod del chart consume el `Secret` específico del chart:
   * **La mayoría de los secretos** se cargan como variables de entorno mediante `envFrom`.
   * **Los certificados** (`authSigningTlsCrt`, etc.) también se montan como archivos mediante `volumeMounts` (normalmente en `/var/run/certs/`).

Los valores de los secretos aparecen en el `Secret` de Kubernetes específico del chart y en el entorno del pod en tiempo de ejecución, por lo que no son invisibles para `kubectl get secret`. Pero nunca aparecen en `values.yaml`, en los diffs de ArgoCD ni en Git, porque el controlador CSI los completa al iniciarse el pod.

El controlador Secrets Store CSI y el [plugin de proveedor de Azure Key Vault](https://azure.github.io/secrets-store-csi-driver-provider-azure) deben estar instalados en el clúster antes de Vantage. Consulte [Requisitos previos](/es/vantage/self-hosted/v3.0/prerequisites).

<div id="per-chart-resources">
  ### Recursos por chart
</div>

Cada chart de Vantage que consume secretos tiene su propio conjunto de recursos:

| Recurso               | Patrón de nombre                                                                        | Propósito                                                                                                                 |
| --------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `SecretProviderClass` | `{chart}-secret-provider` (y `{chart}-migr-secret-provider` para trabajos de migración) | Enumera los alias de Key Vault que necesita el chart y cómo se asignan al `Secret` de Kubernetes específico de ese chart. |
| `Secret`              | `{chart}-secrets` (y `{chart}-migr-secrets`)                                            | El controlador CSI lo completa; se monta en el pod del chart mediante `envFrom`.                                          |
| `Secret`s de volumen  | `{chart}-secrets-volume-N`                                                              | `Secret`s adicionales por chart para el material que debe montarse como archivos (por ejemplo, certificados).             |

Esta división por chart mantiene el acceso a Key Vault con el mínimo privilegio: el SPC de un chart solo hace referencia a los alias que ese chart realmente necesita.

<div id="service-accounts-and-identity-scope">
  ### Cuentas de servicio y alcance de la identidad
</div>

El operador **no** crea ni anota recursos `ServiceAccount`. Cada chart aporta su propia SA mediante valores estándar de Helm; el cliente es responsable de federar las `ServiceAccount` de cada chart que montan los SPC con la identidad administrada asignada por el usuario (UAMI) cuyo `clientId` se proporciona en `vantage.secrets.azure.clientId`. Esa identidad debe tener acceso de lectura a los objetos de Key Vault que respaldan los alias de los charts.

<Note>
  El acceso a Key Vault y el acceso para extraer imágenes son aspectos independientes que pueden recaer en las mismas `ServiceAccount`. La federación de UAMI (esta página) concede acceso de lectura a los secretos; no autentica la extracción de imágenes. Para la extracción, agregue un secret de extracción del registry a `imagePullSecrets` de la `ServiceAccount` indicada por `vantage.serviceAccountName`, o bien conceda `AcrPull` a la identidad de kubelet de AKS. Consulte [Acceso para extraer imágenes](/es/vantage/self-hosted/v3.0/providers/azure#image-pull-access).
</Note>

<div id="kubernetes-secrets-provider">
  ## Proveedor de Secrets para Kubernetes
</div>

```yaml theme={null}
vantage:
  secrets:
    kubernetes:
      # objects:                           # opcional: anular los nombres de secretos predeterminados
      #   sendgridApiKey:
      #     secretName: my-sendgrid-secret
```

Cree previamente los recursos `Secret` en el espacio de nombres de instalación antes de ejecutar el chart. Si `objects` no está definido, se usarán los nombres predeterminados de los secretos; proporcione una asignación de `objects` (`secretName` por alias) para que apunte a Secrets con nombres distintos.

Este proveedor no requiere el controlador Secrets Store CSI ni ningún Key Vault en la nube. Los valores se leen directamente de los objetos `Secret` del clúster.

Durante la comprobación previa, el operador valida la configuración de los secretos. Los charts del operador matched y de Vantage instalan un ClusterRole con acceso de lectura a Secrets y lo vinculan a la ServiceAccount del operador solo en el espacio de nombres de la release de Vantage. Si restringe el acceso a Secret mediante `resourceNames`, incluya todos los nombres de Secret predeterminados y reemplazados.

Un sistema externo de gestión de secretos puede seguir siendo su fuente de referencia. Por ejemplo, External Secrets Operator puede materializar Secrets de Kubernetes desde HashiCorp Vault. Vantage solo consume los Secrets de Kubernetes resultantes y no se conecta directamente a External Secrets ni a Vault.

<div id="postgresql-and-per-service-secrets">
  ### PostgreSQL y Secrets por servicio
</div>

Configura `vantage.databaseProvider: PostgreSQL` para usar PostgreSQL. Cada servicio debe recibir una cadena de conexión que especifique una base de datos lógica diferente; si comparten una sola base de datos, el estado de migración de los servicios entrará en conflicto.

Algunas cargas de trabajo leen claves de cadena de conexión con nombres únicos y pueden compartir un Secret. Otras cargas de trabajo leen la clave genérica `Database__ConnectionString`; crea un Secret independiente para cada uno de esos servicios y asigna su alias mediante `vantage.secrets.kubernetes.objects`:

```yaml theme={null}
vantage:
  databaseProvider: PostgreSQL
  reportingEnabled: false
  secrets:
    kubernetes:
      objects:
        subscriptionDatabaseConnectionString:
          secretName: vantage-db-subscriptions
        workspaceDatabaseConnectionString:
          secretName: vantage-db-workspace
```

Cada Secret asignado contiene la misma clave, pero una cadena de conexión a la base de datos distinta:

```yaml theme={null}
apiVersion: v1
kind: Secret
metadata:
  name: vantage-db-subscriptions
  namespace: <install-namespace>
type: Opaque
stringData:
  Database__ConnectionString: "Host=<host>;Port=5432;Database=subscriptions;Username=<user>;Password=<password>;Ssl Mode=Require"
```

Usa tu sistema de gestión de secretos para crear estos Secrets sin subir credenciales al control de versiones. Las cadenas de conexión deben estar en una sola línea, sin caracteres de nueva línea al principio, al final ni intercalados.

La generación de informes solo está disponible para SQL Server. Deja `reportingEnabled: false` cuando uses PostgreSQL.

<div id="secret-aliases">
  ## Alias de secretos
</div>

Los siguientes alias son el acuerdo establecido entre las cargas de trabajo de Vantage y su proveedor de secretos. Con el proveedor de Azure, la forma más sencilla de configurarlo es asignar a los secretos de Key Vault el mismo nombre que el alias. Con cualquiera de los dos proveedores, puede reasignar los nombres mediante una asignación de `objects` en la configuración de secretos.

<div id="platform">
  ### Plataforma
</div>

| Alias                          | Descripción                                                                                                                               |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `sendgridApiKey`†              | API key de SendGrid. Obligatoria, a menos que configure `spec.smtp`.                                                                      |
| `redisConnectionString`        | Cadena de conexión de Redis.                                                                                                              |
| `redisCacheConnectionString`   | Cadena de conexión para la caché de Redis, los bloqueos y la caché del client. Puede reutilizar `redisConnectionString`.                  |
| `secretStorageUserKeyVaultUri` | URI de Azure Key Vault usado para el almacenamiento de secret. Puede ser el mismo Key Vault u otro distinto (se recomienda uno distinto). |

<div id="storage">
  ### Almacenamiento
</div>

Solo es obligatorio cuando se usa el backend predeterminado de Azure Blob Storage. Cuando `spec.storage.custom` está configurado para un backend respaldado por una `StorageClass` de Kubernetes (por ejemplo, NFS), estos alias no se utilizan. Cada alias es una cadena de conexión de una storage account; consulta la documentación base del sistema Vantage para ver para qué se usa cada tipo de almacenamiento.

| Alias                                    | Descripción                                                   |
| ---------------------------------------- | ------------------------------------------------------------- |
| `storageArchiveConnectionString`         | Cadena de conexión de la storage account ("archive").         |
| `storageLegacyTemporaryConnectionString` | Cadena de conexión de la storage account ("temporary (old)"). |
| `storageTemporaryConnectionString`       | Cadena de conexión de la storage account ("temporary").       |
| `storagePermanentConnectionString`       | Cadena de conexión de la storage account ("permanent").       |
| `storageStandardConnectionString`        | Cadena de conexión de la storage account ("standard").        |

<div id="databases">
  ### Bases de datos
</div>

Cadenas de conexión, una por cada base de datos distinta. Los nombres de las bases de datos son ilustrativos; cualquier nombre que genere el proceso de aprovisionamiento es válido, siempre que la cadena de conexión apunte a la base de datos correcta.

| Alias                                        | Base de datos                                                 |
| -------------------------------------------- | ------------------------------------------------------------- |
| `apiRegistryDatabaseConnectionString`        | `apiregistry`                                                 |
| `auth2DatabaseConnectionString`              | `auth`                                                        |
| `authIdentityDatabaseConnectionString`       | `auth-identity`                                               |
| `cronServiceDatabaseConnectionString`        | `cron`                                                        |
| `documentSetStorageDatabaseConnectionString` | `documentset`                                                 |
| `mailDatabaseConnectionString`               | `mail`                                                        |
| `securityAuditDatabaseConnectionString`      | `security-audit`                                              |
| `storageDatabaseConnectionString`            | `storage`                                                     |
| `workflowDatabaseConnectionString`           | `workflows`                                                   |
| `catalogStorageDatabaseConnectionString`     | `catalogstorage`                                              |
| `folderImportDatabaseConnectionString`       | `folderimport`                                                |
| `interactiveJobsDatabaseConnectionString`    | `interactive-jobs`                                            |
| `mailImportDatabaseConnectionString`         | `mailimport`                                                  |
| `permissionsDatabaseConnectionString`        | `permissions`                                                 |
| `reportingDatabaseConnectionString`          | `reporting` (debe admitir indexación de almacén de columnas). |
| `secretStorageDatabaseConnectionString`      | `secretstorage`                                               |
| `skillInfoDatabaseConnectionString`          | `skillinfo`                                                   |
| `skillMonitorDatabaseConnectionString`       | `skillmonitor`                                                |
| `subscriptionDatabaseConnectionString`       | `subscriptions`                                               |
| `tokenManagementDatabaseConnectionString`    | `tokenmanagement`                                             |
| `transactionsDatabaseConnectionString`       | `transactions`                                                |
| `urlShortenerDatabaseConnectionString`       | `urlshortener`                                                |
| `workspaceDatabaseConnectionString`          | `workspace`                                                   |

<div id="oauth">
  ### OAuth
</div>

| Alias                        | Descripción                               |
| ---------------------------- | ----------------------------------------- |
| `oAuthGoogleClientId`        | ID de cliente de OAuth de Google.         |
| `oAuthGoogleClientSecret`    | secreto de cliente de OAuth de Google.    |
| `oAuthMicrosoftClientId`     | ID de cliente de OAuth de Microsoft.      |
| `oAuthMicrosoftClientSecret` | secreto de cliente de OAuth de Microsoft. |

† `sendgridApiKey` solo es obligatorio si no se usa SMTP. Consulte [Limitaciones conocidas](/es/vantage/self-hosted/v3.0/known-limitations#smtp-supports-basic-auth-only).

<div id="certificate-aliases">
  ## Alias de certificados
</div>

Se requieren cuatro elementos TLS codificados en PEM, presentados como dos pares de alias de secretos (certificado + clave privada). Con el proveedor de Azure, guárdelos como **secretos** de Key Vault, no como objetos de certificado de Key Vault:

| Alias                   | Descripción                                                                                                                |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `authSigningTlsCrt`     | Certificado codificado en PEM para la firma de autenticación (del certificado `auth-signing` de Key Vault).                |
| `authSigningTlsKey`     | Clave privada codificada en PEM para la firma de autenticación.                                                            |
| `authDeactivatedTlsCrt` | Certificado codificado en PEM para tokens de autenticación desactivados (del certificado `auth-deactivated` de Key Vault). |
| `authDeactivatedTlsKey` | Clave privada codificada en PEM para tokens de autenticación desactivados.                                                 |

Con el proveedor de Azure, la forma más sencilla es crear dos certificados autofirmados en Key Vault llamados `auth-signing` y `auth-deactivated` (Nombre común = el valor de `dnsRecord` de Vantage) y, a continuación, crear cuatro secretos de Key Vault con nombres que coincidan con los alias anteriores. Con el proveedor de Kubernetes, cree previamente los recursos `Secret` que contengan el material PEM. Las claves de datos predeterminadas son `auth-signing-tls-crt`, `auth-signing-tls-key`, `auth-deactivated-tls-crt` y `auth-deactivated-tls-key`. Use una asignación de `objects` para reasignar los nombres de Secret.

<div id="naming-and-remapping">
  ## Nombres y reasignación
</div>

**Con el proveedor de Azure, los alias que no figuran en la asignación `objects` usan el propio alias como nombre del objeto de Key Vault** (recuperado como tipo `secret`). Si los objetos de Key Vault ya tienen nombres que coinciden con los alias, no se requiere ninguna asignación `objects`. Con el proveedor de Kubernetes, se usan los nombres predeterminados de los secrets cuando no se define `objects`.

Si el proceso de aprovisionamiento usa nombres diferentes, proporcione una asignación `objects` en la configuración de secrets:

```yaml theme={null}
vantage:
  secrets:
    azure:
      # ...
      objects:
        sendgridApiKey:
          objectName: my-sendgrid-key            # Nombre del objeto en Azure Key Vault
        reportingDatabaseConnectionString:
          objectName: vantage-reporting-conn
```

```yaml theme={null}
vantage:
  secrets:
    kubernetes:
      objects:
        sendgridApiKey:
          secretName: my-sendgrid-secret         # Nombre del Secret de Kubernetes
        reportingDatabaseConnectionString:
          secretName: my-reporting-secret
```

El alias forma parte del contrato de la API; el nombre del objeto lo eliges tú.

<div id="required-permissions">
  ## Permisos necesarios
</div>

Con el **proveedor de Azure Key Vault**, la identidad que usa el controlador Secrets Store CSI debe tener acceso de **lectura** a cada secreto y certificado indicados arriba:

* `workloadIdentity` (predeterminado): la identidad administrada asignada por el usuario cuyo `clientId` se proporciona en `vantage.secrets.azure.clientId`.
* `vmManagedIdentity`: la identidad cuyo ID de cliente se proporciona en `vantage.secrets.azure.userAssignedIdentityID`.
* `podIdentity`: no es un escenario probado; ponte en contacto con tu equipo de cuenta de ABBYY antes de confiar en él.

Con el **proveedor de secretos de Kubernetes**, no intervienen permisos de Key Vault ni permisos de identidad en la nube. Crea previamente los recursos `Secret` en el namespace de instalación; Vantage los consume directamente.

<Note>
  La identidad de carga de trabajo del **controlador CSI** (aquí) es distinta de la identidad de carga de trabajo que usan otras cargas de trabajo de tu clúster (por ejemplo, un Prometheus en la malla que implementes para la supervisión; el instalador de Vantage no implementa Prometheus). Pueden usar la misma UAMI o UAMIs diferentes.
</Note>

<div id="whats-next">
  ## Qué sigue
</div>

<CardGroup cols={2}>
  <Card title="Requisitos previos" icon="list-check" href="/es/vantage/self-hosted/v3.0/prerequisites">
    Requisitos a nivel de clúster y de servicios externos para cualquier instalación.
  </Card>

  <Card title="Instalar en Azure" icon="cloud" href="/es/vantage/self-hosted/v3.0/providers/azure">
    Inventario de Azure Key Vault y la instalación paso a paso.
  </Card>

  <Card title="Kubernetes autogestionado" icon="server" href="/es/vantage/self-hosted/v3.0/providers/self-managed">
    Secrets nativos de Kubernetes y configuración de PostgreSQL.
  </Card>
</CardGroup>