diff --git a/docs.json b/docs.json index 4e3f6ee..233ede0 100644 --- a/docs.json +++ b/docs.json @@ -32,10 +32,15 @@ "icon": "wind-turbine", "group": "Generators", "pages": [ + "docs/enterprise/externalsecrets/generators/basic-auth", + "docs/enterprise/externalsecrets/generators/federation", "docs/enterprise/externalsecrets/generators/iam-keys", + "docs/enterprise/externalsecrets/generators/mongodb", "docs/enterprise/externalsecrets/generators/neo4j", "docs/enterprise/externalsecrets/generators/openai", - "docs/enterprise/externalsecrets/generators/postgresql" + "docs/enterprise/externalsecrets/generators/postgresql", + "docs/enterprise/externalsecrets/generators/rabbitmq", + "docs/enterprise/externalsecrets/generators/sendgrid" ] }, { diff --git a/docs/enterprise/externalsecrets/generators/basic-auth.mdx b/docs/enterprise/externalsecrets/generators/basic-auth.mdx new file mode 100644 index 0000000..32046e2 --- /dev/null +++ b/docs/enterprise/externalsecrets/generators/basic-auth.mdx @@ -0,0 +1,130 @@ +--- +title: 'Basic Auth Generator' +description: 'Generate random usernames and passwords for Basic Authentication.' +--- + + + The External Secrets Enterprise product suite is a premium product. + It requires a specific subscription. Contact us for more information. + + + + In order to use the Basic Auth Generator, you must have the Enterprise Distribution of ESO available via [ESI Agent](/docs/enterprise/externalsecrets/esi-agent/quickstart) or via our [Helm chart bundle](/docs/enterprise/externalsecrets/get-started) + + +## Introduction + +The Basic Auth Generator allows you to automatically generate random **usernames** and **passwords** for use with Basic Authentication schemes. + +This is useful for generating credentials for internal services, CI pipelines, or any scenario where unique, scoped credentials are needed without relying on external identity providers. + +## Output Keys and Values + +| Key | Description | +|---------- |----------------------------------| +| `username` | The generated username | +| `password` | The generated password | + +## Parameters + +### `username` Configuration + +| Field | Default | Description | +|-----------------|---------|-----------------------------------------------------------------------------| +| `length` | `8` | Length of each word in the username. | +| `prefix` | `""` | Optional prefix added to the beginning of the username. | +| `sufix` | `""` | Optional suffix added to the end of the username. | +| `wordCount` | `1` | Number of words in the username. | +| `separator` | `"_"` | Character used to separate words. | +| `includeNumbers`| `false` | Whether to add 4 random digits at the end of the username after the suffix. | + +### `password` Configuration + +This field supports the same parameters as the [Password Generator](https://external-secrets.io/latest/api/generator/password/), allowing fine-grained control over password complexity. + +## Set up + +### Generator Config + + +```yaml +apiVersion: generators.external-secrets.io/v1alpha1 +kind: BasicAuth +metadata: + name: basic-auth-generator + namespace: default +spec: + username: + length: 6 + wordCount: 2 + separator: "-" + prefix: "app" + sufix: "user" + includeNumbers: true + password: + length: 20 + includeUpperCase: true + includeLowerCase: true + includeDigits: true + includeSymbols: true +``` + + +### ExternalSecret Config + +```yaml +apiVersion: external-secrets.io/v1 +kind: ExternalSecret +metadata: + name: basic-auth-secret + namespace: default +spec: + refreshInterval: 1h + dataFrom: + - sourceRef: + generatorRef: + apiVersion: generators.external-secrets.io/v1alpha1 + kind: BasicAuth + name: basic-auth-generator +``` + +### Using the Generated Secret + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: my-app + namespace: default +spec: + replicas: 1 + selector: + matchLabels: + app: my-app + template: + metadata: + labels: + app: my-app + spec: + containers: + - name: my-container + image: my-image:latest + env: + - name: BASIC_AUTH_USERNAME + valueFrom: + secretKeyRef: + name: basic-auth-secret + key: username + - name: BASIC_AUTH_PASSWORD + valueFrom: + secretKeyRef: + name: basic-auth-secret + key: password +``` + +## Notes and Considerations + +* This generator combines the behavior of the Username and Password generators for convenience. +* Password field supports full customization as described in the [Password Generator documentation](https://external-secrets.io/latest/api/generator/password/). +* The suffix and prefix are added to the username as literal strings—separated by the configured separator. +* `includeNumbers` appends 4 digits after the suffix and is useful for ensuring uniqueness. \ No newline at end of file diff --git a/docs/enterprise/externalsecrets/generators/federation.mdx b/docs/enterprise/externalsecrets/generators/federation.mdx new file mode 100644 index 0000000..17b38b7 --- /dev/null +++ b/docs/enterprise/externalsecrets/generators/federation.mdx @@ -0,0 +1,127 @@ +--- +title: 'Federation Generator' +description: 'Delegate secret generation to remote ESO clusters via federated HTTP calls.' +--- + + + The External Secrets Enterprise product suite is a premium product. + It requires a specific subscription. Contact us for more information. + + + + To use the Federation Generator, you must have the Enterprise Distribution of ESO available via [ESI Agent](/docs/enterprise/externalsecrets/esi-agent/quickstart) or via our [Helm chart bundle](/docs/enterprise/externalsecrets/get-started) + + +## Introduction + +The Federation Generator allows you to delegate secret generation to a **remote ESO instance**. +Instead of generating the secret locally, it proxies the request to a federated cluster that owns and maintains the generator logic. + +This is ideal for scenarios where: +- Secret generation must occur in a centralized or isolated environment. +- One team or cluster owns and maintains generator logic, and others consume it. +- Compliance or boundary requirements prevent running generators locally. + +## Output Keys and Values + +| Key | Description | +|---------|--------------------------------------------------------------------------| +| `` | The output keys returned by the federated generator (dynamic per target) | + +## Parameters + +| Field | Default | Description | +|-----------------------------|---------|-------------| +| `server.url` | - | URL of the remote federation server (usually another ESO instance). | +| `generator.namespace` | - | Namespace of the generator in the remote cluster. | +| `generator.kind` | - | Kind of the generator in the remote cluster (e.g., `Password`, `MongoDB`, `SSH`). | +| `generator.name` | - | Name of the generator object to call in the remote cluster. | +| `auth.tokenSecretRef` | - | Kubernetes secret reference containing a Bearer token used for authenticating with the federation server. | +| `auth.caCertSecretRef` | *Optional* | Kubernetes secret reference containing a CA certificate to validate TLS connections with the federation server. | + +## Set up + +### Remote Generator Example (MongoDB in `remote-cluster`) + +The following object exists in the **remote ESO instance**: + +```yaml +apiVersion: generators.external-secrets.io/v1alpha1 +kind: MongoDB +metadata: + name: mongodb-generator + namespace: infra +spec: + # generator spec... +``` + +### Federation Auth Secret Example + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: federation-auth + namespace: default +type: Opaque +data: + token: + ca.crt: # optional +``` + +### Federation Generator (local cluster) + +```yaml +apiVersion: generators.external-secrets.io/v1alpha1 +kind: Federation +metadata: + name: mongodb-via-federation + namespace: default +spec: + server: + url: https://remote-eso.example.com + generator: + kind: MongoDB + name: mongodb-generator + namespace: infra + auth: + tokenSecretRef: + name: federation-auth + key: token + caCertSecretRef: + name: federation-auth + key: ca.crt +``` + +### ExternalSecret Config + +```yaml +apiVersion: external-secrets.io/v1 +kind: ExternalSecret +metadata: + name: federated-mongodb-creds + namespace: default +spec: + refreshInterval: 1h + dataFrom: + - sourceRef: + generatorRef: + apiVersion: generators.external-secrets.io/v1alpha1 + kind: Federation + name: mongodb-via-federation +``` + +## Notes and Considerations + +- Federation generators **do not perform secret generation locally**. They proxy the request to a remote ESO instance. +- The `auth.tokenSecretRef` must contain a valid Bearer token accepted by the remote server. +- The remote generator must exist and be functional. +- The federation server is expected to expose an HTTP endpoint and respond with a JSON object containing key-value pairs at: +``` +POST {server.url}/generators/{namespace}/{kind}/{name} +``` +- On cleanup, a `DELETE` request is issued to the same URL. + + +Ensure the federation server is protected and only accessible from trusted environments. + diff --git a/docs/enterprise/externalsecrets/generators/iam-keys.mdx b/docs/enterprise/externalsecrets/generators/iam-keys.mdx index 68c7780..8be6bd4 100644 --- a/docs/enterprise/externalsecrets/generators/iam-keys.mdx +++ b/docs/enterprise/externalsecrets/generators/iam-keys.mdx @@ -8,7 +8,7 @@ description: 'Easily Rotate AWS IAM Keys in your setup' - In Order to use AWS IAM Keys Generator, you must have the Enterprise Distribution of ESO available via [ESI Agent](/docs/enterprise/externalsecrets/esi-agent/quickstart) + In Order to use AWS IAM Keys Generator, you must have the Enterprise Distribution of ESO available via [ESI Agent](/docs/enterprise/externalsecrets/esi-agent/quickstart) or via our [Helm chart bundle](/docs/enterprise/externalsecrets/get-started) ## Introduction diff --git a/docs/enterprise/externalsecrets/generators/mongodb.mdx b/docs/enterprise/externalsecrets/generators/mongodb.mdx new file mode 100644 index 0000000..24e978c --- /dev/null +++ b/docs/enterprise/externalsecrets/generators/mongodb.mdx @@ -0,0 +1,136 @@ +--- +title: 'MongoDB User Generator' +description: 'Dynamically create and manage MongoDB users with scoped roles.' +--- + + + The External Secrets Enterprise product suite is a premium product. + It requires a specific subscription. Contact us for more information. + + + + In order to use the MongoDB User Generator, you must have the Enterprise Distribution of ESO available via [ESI Agent](/docs/enterprise/externalsecrets/esi-agent/quickstart) or via our [Helm chart bundle](/docs/enterprise/externalsecrets/get-started) + + +## Introduction + +Managing MongoDB users manually can be error-prone and operationally expensive, especially when dealing with scoped permissions and dynamic workloads. +The MongoDB User Generator automates the creation, rotation, and deletion of MongoDB user accounts with custom roles and minimal overhead. + +This generator is especially useful for providing temporary access to applications, improving security posture through least-privilege principles, and removing the need for manual user provisioning. + +## Output Keys and Values + +| Key | Description | +|----------|------------------------------| +| `user` | The generated MongoDB username | +| `password` | The generated MongoDB password | + +## Parameters + +| Key | Default | Description | +|--------------------------|------------|-------------| +| `database.adminDB` | `"admin"` | Name of the MongoDB administrative database used to authenticate. | +| `database.host` | **Required** | Hostname or IP of the MongoDB instance. | +| `database.port` | `27017` | Port used to connect to the MongoDB instance. | +| `auth.scram.username` | Optional | Username used for SCRAM authentication. | +| `auth.scram.secretRef.usernameSecretRef` | Optional | Secret reference for the SCRAM username. | +| `auth.scram.secretRef.passwordSecretRef` | **Required** | Secret reference for the SCRAM password. | +| `user.name` | Optional | Desired username for the MongoDB user. If not specified, one is generated. | +| `user.roles` | **Required** | List of roles to assign to the user. Each role must include a `name` and `db`. | + +## Set up + +### MongoDB Permissions + +The SCRAM user used for authentication must have permission to create and manage other users and roles in the target database(s). This typically means having the `userAdmin` or `userAdminAnyDatabase` role in the admin database. + +### Generator Config + +```yaml +apiVersion: generators.external-secrets.io/v1alpha1 +kind: MongoDB +metadata: + name: mongodb-generator + namespace: default +spec: + database: + host: mongodb.default.svc.cluster.local + port: 27017 + adminDB: admin + auth: + scram: + username: admin + secretRef: + usernameSecretRef: + name: mongodb-admin-creds + key: username + passwordSecretRef: + name: mongodb-admin-creds + key: password + user: + name: my-app-user + roles: + - name: readWrite + db: my-app-db + - name: read + db: analytics +``` + +### ExternalSecret Config + +```yaml +apiVersion: external-secrets.io/v1 +kind: ExternalSecret +metadata: + name: mongodb-credentials + namespace: default +spec: + refreshInterval: 1h + dataFrom: + - sourceRef: + generatorRef: + apiVersion: generators.external-secrets.io/v1alpha1 + kind: MongoDB + name: mongodb-generator +``` + +### Using the Generated Secret + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: my-app + namespace: default +spec: + replicas: 1 + selector: + matchLabels: + app: my-app + template: + metadata: + labels: + app: my-app + spec: + containers: + - name: my-container + image: my-image:latest + env: + - name: MONGO_USER + valueFrom: + secretKeyRef: + name: mongodb-credentials + key: user + - name: MONGO_PASSWORD + valueFrom: + secretKeyRef: + name: mongodb-credentials + key: password +``` + +## Notes and Considerations + +- This generator currently supports only SCRAM authentication with secret-based credential references. +- If no `user.name` is provided, a username is automatically generated and will follow ESO's default randomization strategy. +- Roles must exist in the specified database; otherwise, MongoDB will return an error. diff --git a/docs/enterprise/externalsecrets/generators/neo4j.mdx b/docs/enterprise/externalsecrets/generators/neo4j.mdx index b443d15..dce10fd 100644 --- a/docs/enterprise/externalsecrets/generators/neo4j.mdx +++ b/docs/enterprise/externalsecrets/generators/neo4j.mdx @@ -9,7 +9,7 @@ description: 'Easily manage and rotate Neo4j Users in your setup' - In order to use the Neo4j User Generator, you must have the Enterprise Distribution of ESO available via [ESI Agent](/docs/enterprise/externalsecrets/esi-agent/quickstart). + In order to use the Neo4j User Generator, you must have the Enterprise Distribution of ESO available via [ESI Agent](/docs/enterprise/externalsecrets/esi-agent/quickstart) or via our [Helm chart bundle](/docs/enterprise/externalsecrets/get-started) ## Introduction diff --git a/docs/enterprise/externalsecrets/generators/openai.mdx b/docs/enterprise/externalsecrets/generators/openai.mdx index 6c5c40e..40531fd 100644 --- a/docs/enterprise/externalsecrets/generators/openai.mdx +++ b/docs/enterprise/externalsecrets/generators/openai.mdx @@ -9,7 +9,7 @@ description: 'Dynamically manage OpenAI Service Accounts and API Keys.' - To use the OpenAI Generator, you must have the Enterprise Distribution of ESO available via [ESI Agent](/docs/enterprise/externalsecrets/esi-agent/quickstart). + To use the OpenAI Generator, you must have the Enterprise Distribution of ESO available via [ESI Agent](/docs/enterprise/externalsecrets/esi-agent/quickstart) or via our [Helm chart bundle](/docs/enterprise/externalsecrets/get-started) ## Introduction diff --git a/docs/enterprise/externalsecrets/generators/postgresql.mdx b/docs/enterprise/externalsecrets/generators/postgresql.mdx index 7ec1982..72a6f49 100644 --- a/docs/enterprise/externalsecrets/generators/postgresql.mdx +++ b/docs/enterprise/externalsecrets/generators/postgresql.mdx @@ -9,7 +9,7 @@ description: 'Easily manage and rotate PostgreSQL Users in your setup' - In order to use the PostgreSQL User Generator, you must have the Enterprise Distribution of ESO available via [ESI Agent](../../esi-agent/quickstart.mdx). + In order to use the PostgreSQL User Generator, you must have the Enterprise Distribution of ESO available via [ESI Agent](/docs/enterprise/externalsecrets/esi-agent/quickstart) or via our [Helm chart bundle](/docs/enterprise/externalsecrets/get-started) ## Introduction diff --git a/docs/enterprise/externalsecrets/generators/rabbitmq.mdx b/docs/enterprise/externalsecrets/generators/rabbitmq.mdx new file mode 100644 index 0000000..54cd909 --- /dev/null +++ b/docs/enterprise/externalsecrets/generators/rabbitmq.mdx @@ -0,0 +1,158 @@ +--- +title: 'RabbitMQ Password Generator' +description: 'Securely rotate passwords for RabbitMQ users using ESO.' +--- + + + The External Secrets Enterprise product suite is a premium product. + It requires a specific subscription. Contact us for more information. + + + + To use the RabbitMQ Generator, you must have the Enterprise Distribution of ESO available via [ESI Agent](/docs/enterprise/externalsecrets/esi-agent/quickstart) or via our [Helm chart bundle](/docs/enterprise/externalsecrets/get-started) + + +## Introduction + +The RabbitMQ Generator allows you to rotate passwords for existing RabbitMQ users automatically. +It supports secure password generation via ESO's internal password generator or by referencing a Kubernetes Secret. + +This is useful for enforcing password rotation policies, avoiding manual interaction with RabbitMQ APIs, and improving security for RabbitMQ deployments. + +## Output Keys and Values + +| Key | Description | +|-----------|----------------------------------------------| +| `password` | The rotated RabbitMQ user password (plain text) | + +## Parameters + +| Key | Default | Description | +|------------------------------------|--------------|-------------| +| `server.host` | **Required** | The hostname of the RabbitMQ server. | +| `server.port` | `15672` | Port to connect to the RabbitMQ HTTP API. | +| `server.tls` | `false` | Use TLS for connection to the RabbitMQ API. | +| `auth.basicAuth.username` | **Required** | Admin username with sufficient privileges. | +| `auth.basicAuth.passwordSecretRef`| **Required** | Secret containing the admin password. | +| `config.username` | **Required** | The RabbitMQ user to rotate the password for. | +| `config.passwordPolicy.passwordGeneratorRef` | Optional | Reference to a Password Generator. | +| `config.passwordPolicy.secretRef` | Optional | Reference to a static password in a Secret. | + +## Set up + +### Required RabbitMQ Permissions + +The credentials provided under `auth.basicAuth` must belong to a user that has permission to view and update users via the RabbitMQ HTTP API. + +In most setups, this means the user must have the `administrator` tag in RabbitMQ. + +### Generator Config + +You can either use a Password Generator or a fixed Secret. Below are examples for both approaches. + + +```yaml Using a Password Generator +apiVersion: generators.external-secrets.io/v1alpha1 +kind: RabbitMQ +metadata: + name: rabbitmq-generator + namespace: default +spec: + server: + host: rabbitmq.default.svc.cluster.local + port: 15672 + tls: false + auth: + basicAuth: + username: admin + passwordSecretRef: + name: rabbitmq-admin-secret + key: password + config: + username: my-app-user + passwordPolicy: + passwordGeneratorRef: + name: app-password-generator + kind: Password +``` +```yaml Using a Fixed Password +apiVersion: generators.external-secrets.io/v1alpha1 +kind: RabbitMQ +metadata: + name: rabbitmq-generator + namespace: default +spec: + server: + host: rabbitmq.default.svc.cluster.local + port: 15672 + tls: false + auth: + basicAuth: + username: admin + passwordSecretRef: + name: rabbitmq-admin-secret + key: password + config: + username: my-app-user + passwordPolicy: + secretRef: + name: fixed-password + key: value +``` + + +### ExternalSecret Config + +```yaml +apiVersion: external-secrets.io/v1 +kind: ExternalSecret +metadata: + name: rabbitmq-password + namespace: default +spec: + refreshInterval: 1h + dataFrom: + - sourceRef: + generatorRef: + apiVersion: generators.external-secrets.io/v1alpha1 + kind: RabbitMQ + name: rabbitmq-generator +``` + +### Using the Generated Secret + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: my-app + namespace: default +spec: + replicas: 1 + selector: + matchLabels: + app: my-app + template: + metadata: + labels: + app: my-app + spec: + containers: + - name: my-container + image: my-image:latest + env: + - name: RABBITMQ_PASSWORD + valueFrom: + secretKeyRef: + name: rabbitmq-password + key: password +``` + +## Notes and Considerations + +- The generator does not create new users; it only updates the password for an existing RabbitMQ user. +- Passwords are hashed using the `SHA-256` algorithm and sent via the RabbitMQ HTTP API. +- If the password is already up to date (i.e., the hash matches), no update request is sent. +- Only one password source must be provided: either `passwordGeneratorRef` or `secretRef`. +- TLS should be enabled in production environments for secure communication with the RabbitMQ API. + diff --git a/docs/enterprise/externalsecrets/generators/sendgrid.mdx b/docs/enterprise/externalsecrets/generators/sendgrid.mdx new file mode 100644 index 0000000..17d7931 --- /dev/null +++ b/docs/enterprise/externalsecrets/generators/sendgrid.mdx @@ -0,0 +1,129 @@ +--- +title: 'SendGrid API Key Generator' +description: 'Automatically create and manage scoped SendGrid API keys using ESO.' +--- + + + The External Secrets Enterprise product suite is a premium product. + It requires a specific subscription. Contact us for more information. + + + + To use the SendGrid API Key Generator, you must have the Enterprise Distribution of ESO available via [ESI Agent](/docs/enterprise/externalsecrets/esi-agent/quickstart) or via our [Helm chart bundle](/docs/enterprise/externalsecrets/get-started) + + +## Introduction + +The SendGrid Generator automatically provisions **scoped API keys** for your applications using the [SendGrid Admin API](https://docs.sendgrid.com/api-reference/api-keys/create-api-key). +It eliminates the need for manually creating and managing API tokens in the SendGrid dashboard, enabling fine-grained access and secure rotation via ESO. + +This generator is especially useful when isolating credentials across services or tenants and when ensuring secure deletion of unused API tokens during cleanup. + +## Output Keys and Values + +| Key | Description | +|----------|-------------------------------------------| +| `apiKey` | The generated SendGrid API key (`SG.x...`) | + +## Parameters + +| Key | Default | Description | +|-----------------------------|-------------|-------------| +| `dataResidency` | `global` | Optional value to control SendGrid's data residency location (`"global"`, `"eu"`). | +| `scopes` | `[]` | List of scopes to apply to the API key. See [SendGrid docs](https://docs.sendgrid.com/ui/account-and-settings/api-keys) for options. | +| `auth.secretRef.apiKeySecretRef` | **Required** | Secret containing the Admin API Key with permission to manage API keys. | + +## Set up + +### Requirements + +- You must have an existing **SendGrid Admin API Key** with permission to create and delete API keys. +- The generator uses the `/v3/api_keys` endpoint to create and rotate keys. + +### Admin API Key Secret + +Example of a Kubernetes secret holding your Admin API Key: + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: sendgrid-admin-secret + namespace: default +type: Opaque +data: + api-key: +``` + +### Generator Config + +```yaml +apiVersion: generators.external-secrets.io/v1alpha1 +kind: SendgridAuthorizationToken +metadata: + name: sendgrid-generator + namespace: default +spec: + dataResidency: global + scopes: + - mail.send + - alerts.create + auth: + secretRef: + apiKeySecretRef: + name: sendgrid-admin-secret + key: api-key +``` + +### ExternalSecret Config + +```yaml +apiVersion: external-secrets.io/v1 +kind: ExternalSecret +metadata: + name: sendgrid-credentials + namespace: default +spec: + refreshInterval: 12h + dataFrom: + - sourceRef: + generatorRef: + apiVersion: generators.external-secrets.io/v1alpha1 + kind: SendgridAuthorizationToken + name: sendgrid-generator +``` + +### Using the Generated Secret + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: email-service + namespace: default +spec: + replicas: 1 + selector: + matchLabels: + app: email-service + template: + metadata: + labels: + app: email-service + spec: + containers: + - name: app + image: my-email-service:latest + env: + - name: SENDGRID_API_KEY + valueFrom: + secretKeyRef: + name: sendgrid-credentials + key: apiKey +``` + +## Notes and Considerations + +- Only one API key is created per rotation cycle. Old keys are deleted during cleanup. +- The `dataResidency` value is used to control which SendGrid API region is used (e.g., `"eu"` for EU data residency). +- API keys are uniquely named using a generated label (e.g., `Managed By ESO Generator: `).