From 78abf49fcf9a2a832b163672a65b648efc016656 Mon Sep 17 00:00:00 2001 From: Iuri Severo Date: Wed, 4 Jun 2025 09:23:55 -0300 Subject: [PATCH 1/2] feat: add destinations and triggers docs --- .../audit/destinations/quickstart.mdx | 48 +++++++++++++++++++ docs/enterprise/audit/policies/quickstart.mdx | 27 ++++++++++- mint.json | 6 +++ 3 files changed, 79 insertions(+), 2 deletions(-) create mode 100644 docs/enterprise/audit/destinations/quickstart.mdx diff --git a/docs/enterprise/audit/destinations/quickstart.mdx b/docs/enterprise/audit/destinations/quickstart.mdx new file mode 100644 index 0000000..5732940 --- /dev/null +++ b/docs/enterprise/audit/destinations/quickstart.mdx @@ -0,0 +1,48 @@ +--- +title: Quickstart +description: Configure a destination for audit triggers +icon: 'rocket' +--- + + + The External Secrets Inc. Audit & Compliance product suite is a premium product. + It requires a specific subscription. Contact us for more information. + + + + To follow this guide, ensure the [Audit Listener is installed and configured](/docs/enterprise/audit/installation). + + +This guide will walk you through creating a Destination that receives audit events triggered by policies, such as a Webhook. + +## Create a Destination + +1. Navigate to the Destinations section in the left sidebar. +2. Click "Create New Destination". +3. Fill in the following fields: + + - Name: A human-readable label (e.g., `Reloader Webhook`) + - Identifier: A unique ID (e.g., `reloader-webhook`) + - Type: Select `Webhook` from the dropdown + +4. In the Configuration section, provide: + + - URL: The endpoint that should receive the audit events + Example: `http://reloader-controller-manager-webhook.external-secrets-reloader` + - CA Bundle: *(Optional)* Include if using HTTPS with a custom certificate + - Auth method: Choose the appropriate authentication method (e.g., `NONE`, `BASIC`, or `TOKEN`) + - Event Format: Select `CLOUD_EVENTS` to send audit payloads in CloudEvents format + +5. Click "Create" to finalize the destination. + +You should now see your new destination listed and ready to be assigned to audit policies. + +--- + +### 📌 What's Next? + +After creating a destination: + +- [Create or edit a policy](/docs/enterprise/audit/policies/quickstart) to send events to this destination. You can read how to do it in the policy's [Add Triggers to the Policy](/docs/enterprise/audit/policies/quickstart#add-triggers-to-the-policy) section. + +> Destinations can be reused across multiple policies. diff --git a/docs/enterprise/audit/policies/quickstart.mdx b/docs/enterprise/audit/policies/quickstart.mdx index e2bb8f1..6b167ca 100644 --- a/docs/enterprise/audit/policies/quickstart.mdx +++ b/docs/enterprise/audit/policies/quickstart.mdx @@ -10,7 +10,7 @@ icon: 'rocket' - In order to follow this guide, be sure to already have the [Audit Listener installed and configured](./docs/audit/quickstart). + In order to follow this guide, be sure to already have the [Audit Listener installed and configured](/docs/enterprise/audit/installation). This guide will help you create a policy using Rego language within the External Secrets Dashboard. @@ -40,7 +40,30 @@ Click on `Validate Rule` and check that this rule is valid and would result in a Change the Sample `ActorIdentifier` field to `"my-credentials"`, and check that the rule is now valid and would result in a compliant state. -Submit the Rule. +Submit the Rule or add a trigger to it. + +### Add Triggers to the Policy + +Triggers define when the result of a policy evaluation should generate a notification and send it to a [destination](/docs/enterprise/audit/destinations/quickstart). + +To add a trigger: + +1. Navigate to the Triggers tab of the policy creation form. +2. Click "Add Trigger". +3. Fill in the following fields: + + - Destination: Select one or more existing destinations (e.g., `reloader-webhook`) + - Condition: Choose when the trigger should fire. Options include: + - `EvaluatedNonCompliant`: Fires every time the policy is evaluated as non-compliant + - `EvaluatedCompliant`: Fires every time the policy is evaluated as compliant + - `UpdatedToNonCompliant`: Fires only when the status transitions from compliant to non-compliant + - `UpdatedToCompliant`: Fires only when the status transitions from non-compliant to compliant + - Wait for Cycles: (Optional) Number of evaluation cycles to wait before sending the event. + - For example, setting `waitForCycles = 3` with `EvaluatedNonCompliant` means the policy must be non-compliant for 3 consecutive evaluations before the destination is notified. + +You can add multiple triggers with different conditions and destinations. + +Once configured, Submit to finalize your policy with its associated triggers. ## Assigning a Policy to a Provider diff --git a/mint.json b/mint.json index f8e8721..9b49b3b 100644 --- a/mint.json +++ b/mint.json @@ -65,6 +65,12 @@ "docs/enterprise/audit/dashboard/filters" ] }, + { + "group": "Destinations", + "pages": [ + "docs/enterprise/audit/destinations/quickstart" + ] + }, { "group": "Policies", "pages": [ From c20515b6065156f76ce99196da5131578f6c4abc Mon Sep 17 00:00:00 2001 From: Iuri Severo Date: Wed, 4 Jun 2025 10:38:11 -0300 Subject: [PATCH 2/2] fix: links and callouts --- docs/enterprise/audit/installation.mdx | 12 +- docs/enterprise/audit/introduction.mdx | 6 +- .../audit/listener/introduction.mdx | 2 +- .../audit/policies/policy-execution-types.mdx | 2 +- .../externalsecrets/esi-cli/federation.mdx | 12 +- .../externalsecrets/esi-cli/flags.mdx | 8 +- .../esi-cli/injection-mechanisms.mdx | 8 +- .../externalsecrets/esi-cli/modes.mdx | 8 +- .../esi-cli/usage-examples.mdx | 4 +- .../federation/authn-authz.mdx | 4 +- .../federation/client-setup.mdx | 6 +- .../externalsecrets/federation/example.mdx | 4 +- .../federation/server-setup.mdx | 8 +- .../externalsecrets/generators/iam-keys.mdx | 2 +- .../externalsecrets/generators/neo4j.mdx | 2 +- .../pod-webhook/annotations.mdx | 20 +- .../pod-webhook/installation.mdx | 12 +- .../pod-webhook/usage-examples.mdx | 4 +- .../enterprise/externalsecrets/quickstart.mdx | 2 +- docs/open_source/reloader/quickstart.mdx | 2 +- .../reloader/reference/api-reference.mdx | 950 ++++++------------ .../reloader/sources/gcp-pubsub-source.mdx | 2 +- mint.json | 1 + 23 files changed, 379 insertions(+), 702 deletions(-) diff --git a/docs/enterprise/audit/installation.mdx b/docs/enterprise/audit/installation.mdx index 2408ade..d537635 100644 --- a/docs/enterprise/audit/installation.mdx +++ b/docs/enterprise/audit/installation.mdx @@ -89,9 +89,9 @@ It can be installed either with Kubernetes (plain manifests/helm charts) or as a ## Next * Create a Provider: - * [Create a Hashicorp Vault Provider](/docs/audit/listener/providers/hashicorp-vault) - * [Create a AWS Secrets Manager Provider](/docs/audit/listener/providers/aws-secrets-manager) - * [Create a AWS Parameter Store Provider](/docs/audit/listener/providers/aws-parameter-store) - * [Create a Azure Key Vault Provider](/docs/audit/listener/providers/azure-key-vault) - * [Create a GCP Secret Manager Provider](/docs/audit/listener/providers/gcp-secret-manager) -* [Create your first policy](/docs/audit/policies/quickstart) \ No newline at end of file + * [Create a Hashicorp Vault Provider](/docs/enterprise/audit/listener/providers/hashicorp-vault) + * [Create a AWS Secrets Manager Provider](/docs/enterprise/audit/listener/providers/aws-secrets-manager) + * [Create a AWS Parameter Store Provider](/docs/enterprise/audit/listener/providers/aws-parameter-store) + * [Create a Azure Key Vault Provider](/docs/enterprise/audit/listener/providers/azure-key-vault) + * [Create a GCP Secret Manager Provider](/docs/enterprise/audit/listener/providers/gcp-secret-manager) +* [Create your first policy](/docs/enterprise/audit/policies/quickstart) \ No newline at end of file diff --git a/docs/enterprise/audit/introduction.mdx b/docs/enterprise/audit/introduction.mdx index 7d182f9..cf0dc99 100644 --- a/docs/enterprise/audit/introduction.mdx +++ b/docs/enterprise/audit/introduction.mdx @@ -92,6 +92,6 @@ These metrics are available directly to the end user (via a prometheus endpoint) ## Next Steps -* [Install the Audit Listener within your premises](./docs/audit/installation) -* [Create your first policy](./docs/audit/guides/policies/quickstart) -* [Create your first provider](./docs/audit/guides/providers/quickstart) +* [Install the Audit Listener within your premises](/docs/enterprise/audit/installation) +* [Create your first destination](/docs/enterprise/audit/destinations/quickstart) +* [Create your first policy](/docs/enterprise/audit/policies/quickstart) diff --git a/docs/enterprise/audit/listener/introduction.mdx b/docs/enterprise/audit/listener/introduction.mdx index 8c88263..2eab0ab 100644 --- a/docs/enterprise/audit/listener/introduction.mdx +++ b/docs/enterprise/audit/listener/introduction.mdx @@ -30,7 +30,7 @@ By default, the audit Listener will automatically compute the following informat ### Extension with Policies The Audit Listener also supports extending its behavior by allowing it to compute policies on different events. -To understand more how policies work, check [Policies](/docs/audit/policies/quickstart). +To understand more how policies work, check [Policies](/docs/enterprise/audit/policies/quickstart). Once a new policy is created, the listener will start computing it and store the following information: * Which policies a given secret is non compliant to at a given point in time diff --git a/docs/enterprise/audit/policies/policy-execution-types.mdx b/docs/enterprise/audit/policies/policy-execution-types.mdx index f3bb8b4..84ac8fc 100644 --- a/docs/enterprise/audit/policies/policy-execution-types.mdx +++ b/docs/enterprise/audit/policies/policy-execution-types.mdx @@ -20,7 +20,7 @@ The exception is the `Results` policy type, which is evaluated after the secret Every event message has a `OriginalPayload` field that contains the original event message sent from the provider. From this message, it is possible to create policy logic that depends on specific provider information (such as audit log dates, authorization fields, or generic policy parsing). -Check [Provider Session](/docs/audit/providers/quickstart) to get more information on each `OriginalPayload` format. +Check [Provider Session](/docs/enterprise/audit/listener/introduction) to get more information on each `OriginalPayload` format. ### Policy Execution Types diff --git a/docs/enterprise/externalsecrets/esi-cli/federation.mdx b/docs/enterprise/externalsecrets/esi-cli/federation.mdx index 4ace719..d5ca859 100644 --- a/docs/enterprise/externalsecrets/esi-cli/federation.mdx +++ b/docs/enterprise/externalsecrets/esi-cli/federation.mdx @@ -18,9 +18,9 @@ To use `esi-cli` in federation mode, you primarily need to specify the URL of th Setting the `--federated-server-url` flag is the key to activating federation mode. Once set, `esi-cli` will direct its secret fetching requests to this URL instead of querying the local Kubernetes API for `ExternalSecret` resources directly for those federated requests. - + When operating in federation mode, `esi-cli` still requires a valid Kubernetes environment (e.g., to access the service account token for authentication), but the source of truth for the requested secrets shifts to the ESI Federation server. - + ## Key Federation Flags @@ -38,9 +38,9 @@ These flags are specifically used to configure `esi-cli`'s interaction with an E * Specifies the name of a generator configuration to use on the ESI Federation server. * This is used when you need the federation server to generate secrets dynamically (e.g., dynamic database credentials, signed tokens). - + Typically, you will use either `--federated-store` (to fetch existing secrets) or `--federated-generators` (to request dynamically generated secrets), or sometimes both, depending on the ESI Federation server's capabilities and your needs. - + * `--federated-token=""` * Path to the Kubernetes service account token file. @@ -85,8 +85,8 @@ esi-cli --mode=init \ * `--federated-store="central-vault"`: Tells the federation server to use its `central-vault` configuration to find `federated-secret-name`. * `--federated-token`: (Optional in this example) If the pod's default service account token is not the one authorized for federation, or if a specific token with fewer privileges is desired, its path can be provided. - + The actual names like `federated-secret-name.token-key` and `central-vault` are interpreted by the ESI Federation server. Ensure these correspond to valid configurations on your federation server. - + Using `esi-cli` with ESI Federation provides a powerful way to decouple secret consumption from specific clusters, enhancing security and manageability in distributed environments. diff --git a/docs/enterprise/externalsecrets/esi-cli/flags.mdx b/docs/enterprise/externalsecrets/esi-cli/flags.mdx index f177aa6..35385b1 100644 --- a/docs/enterprise/externalsecrets/esi-cli/flags.mdx +++ b/docs/enterprise/externalsecrets/esi-cli/flags.mdx @@ -31,9 +31,9 @@ These flags are applicable to core `esi-cli` functionality. These flags are used when `esi-cli` is configured to fetch secrets from a central ESI Federation server, rather than directly from `ExternalSecret` resources in the local Kubernetes cluster. - + Using `--federated-server-url` enables federation mode. When in federation mode, flags like `--namespace` and `--external-secrets` (referring to local Kubernetes resources) are typically not the primary source of secrets, though `--namespace` might still be used for resolving local service account tokens if paths are not absolute. - + | Flag | Description | Default Value | Notes | | ----------------------------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -43,8 +43,8 @@ These flags are used when `esi-cli` is configured to fetch secrets from a centra | `--federated-token` | The file path to the Kubernetes service account token that `esi-cli` will use to authenticate with the federated ESI server. | `/var/run/secrets/kubernetes.io/serviceaccount/token` | The service account associated with this token must be authorized by the ESI Federation server. | | `--federated-ca-crt` | The file path to the CA certificate bundle used to verify the TLS certificate of the federated ESI server. | `/var/run/secrets/kubernetes.io/serviceaccount/ca.crt` | Essential for secure communication if the federation server uses a custom CA or self-signed certificates. | - + When using federation, either `--federated-store` or `--federated-generators` (or both, depending on the federation server's setup and the desired secrets) is typically required along with `--federated-server-url`. - + For more context on how these flags are used, refer to the [Modes of Operation](./modes), [Injection Mechanisms](./injection-mechanisms), [Federation](./federation), and [Usage Examples](./usage-examples) pages. diff --git a/docs/enterprise/externalsecrets/esi-cli/injection-mechanisms.mdx b/docs/enterprise/externalsecrets/esi-cli/injection-mechanisms.mdx index 64d2937..f41b603 100644 --- a/docs/enterprise/externalsecrets/esi-cli/injection-mechanisms.mdx +++ b/docs/enterprise/externalsecrets/esi-cli/injection-mechanisms.mdx @@ -30,9 +30,9 @@ There are two main ways to control environment variable injection: * This allows you to pick specific keys from different `ExternalSecret`s (referenced by `secretName`) and assign them to custom environment variable names. * **Override Behavior**: If an environment variable name defined via `--inject-on-env` conflicts with one that would be generated from `--external-secrets`, the mapping from `--inject-on-env` takes precedence. - + Environment variables are set up in the environment of the `esi-cli` process itself before it uses `syscall.Exec` to run the target binary specified by `--binary-path`. This means the target binary inherits these environment variables directly. - + ## File Injection @@ -50,9 +50,9 @@ File injection is controlled by the `--inject-on-file` flag. * **Data Encoding**: `esi-cli` writes the raw byte data from the Kubernetes Secret directly to files. It does not perform base64 decoding itself, assuming the data in the Secret is already in the desired final form (or, for full secrets, it structures the raw data as YAML). * This behavior is based on the MEMORY item: `The USER modified pkg/engine/file/file.go to remove all explicit base64 decoding logic...` - + In `init` mode, file injection specified by `--inject-on-file` typically occurs **before** environment variables are set up and before the main application binary is executed. This ensures files are present when the application starts. - + **Example Mappings for `--inject-on-file`**: diff --git a/docs/enterprise/externalsecrets/esi-cli/modes.mdx b/docs/enterprise/externalsecrets/esi-cli/modes.mdx index 1cb4cdb..a50a1a7 100644 --- a/docs/enterprise/externalsecrets/esi-cli/modes.mdx +++ b/docs/enterprise/externalsecrets/esi-cli/modes.mdx @@ -62,9 +62,9 @@ esi-cli --mode=init \ --args="--your-app-flags=true, --config-file=/app/config/settings.yaml" ``` - + The `--binary-path` flag is **required** when using `--mode=init`. - + ## `daemon` Mode (`--mode=daemon`) @@ -143,8 +143,8 @@ esi-cli --mode=daemon \ --daemon-refresh-interval=5m ``` - + Applications consuming files written by `esi-cli` in `daemon` mode should be capable of detecting changes to these files and reloading their configuration if they need to pick up updated secret values dynamically. - + Understanding these two modes is fundamental to effectively using `esi-cli` to manage secrets for your applications. Choose the mode that best fits your application's architecture and secret consumption patterns. diff --git a/docs/enterprise/externalsecrets/esi-cli/usage-examples.mdx b/docs/enterprise/externalsecrets/esi-cli/usage-examples.mdx index 4fced77..c324e77 100644 --- a/docs/enterprise/externalsecrets/esi-cli/usage-examples.mdx +++ b/docs/enterprise/externalsecrets/esi-cli/usage-examples.mdx @@ -64,8 +64,8 @@ esi-cli --mode=daemon \ * `esi-cli` will monitor the source `ExternalSecret`s for changes and update these files. Parent directories will be created if they don't exist. 4. `--daemon-refresh-interval=5m`: Sets the periodic refresh/resync interval to 5 minutes. - + Applications reading files managed by `esi-cli` in `daemon` mode should be designed to detect file changes and reload their configuration if they need to use updated secret values. - + These examples illustrate common patterns for using `esi-cli`. You can combine flags as needed to suit your specific secret injection requirements. Always refer to the [Command-Line Flags](./flags) documentation for a complete list of options. diff --git a/docs/enterprise/externalsecrets/federation/authn-authz.mdx b/docs/enterprise/externalsecrets/federation/authn-authz.mdx index 6f50847..6069642 100644 --- a/docs/enterprise/externalsecrets/federation/authn-authz.mdx +++ b/docs/enterprise/externalsecrets/federation/authn-authz.mdx @@ -60,8 +60,8 @@ The process ensures that only legitimate clients can request secrets, and they c 5. **Client Receives Secret (Client-Side)**: * The Federation Client receives the secret data and processes it (e.g., `esi-cli` injects it into the environment or files). - + This multi-step process, involving cryptographic validation of tokens and explicit policy checks via CRDs, ensures that secret data is only shared between trusted and explicitly authorized entities. - + This flow is fundamental to the security model of ESI Federation, enabling robust cross-cluster secret management. diff --git a/docs/enterprise/externalsecrets/federation/client-setup.mdx b/docs/enterprise/externalsecrets/federation/client-setup.mdx index 269c53e..a93e03b 100644 --- a/docs/enterprise/externalsecrets/federation/client-setup.mdx +++ b/docs/enterprise/externalsecrets/federation/client-setup.mdx @@ -50,7 +50,7 @@ When these flags are provided, `esi-cli`: 5. Includes the client's CA certificate (base64 encoded) in the request body, typically as `{"ca.crt": ""}`. This allows the Federation Server to trust the client cluster's OIDC discovery endpoint for JWKS. 6. Receives secret data and injects it as environment variables (`--inject-on-env`, `--external-secrets`) or files (`--inject-on-file`) as per other `esi-cli` configurations. -Refer to the [`esi-cli` documentation](./../../esi-cli/federation) for more detailed examples of `esi-cli` with federation. +Refer to the [`esi-cli` documentation](/docs/enterprise/externalsecrets/esi-cli/federation) for more detailed examples of `esi-cli` with federation. ## ESE as a Federation Client @@ -94,8 +94,8 @@ Once such a `FederationStore` is defined on the client ESE instance: * Request the secret data (e.g., by passing through the `ExternalSecret`'s `dataFrom` or `data` fields, which would be interpreted by the Federation Server in context of its own stores like `vault-backend-on-federation-server`). 3. The client ESE then creates the local Kubernetes `Secret` as usual, but populated with data received from the Federation Server. - + The precise implementation details and CRD for configuring an ESE instance as a federation client (e.g., the `FederationStore` kind) should be referred to in the specific ESE version documentation. The concept remains: abstracting the connection to the Federation Server within a store definition. - + This client-server model allows for flexible and secure secret distribution architectures, catering to various organizational needs and security postures. diff --git a/docs/enterprise/externalsecrets/federation/example.mdx b/docs/enterprise/externalsecrets/federation/example.mdx index b40b67b..fb2caa6 100644 --- a/docs/enterprise/externalsecrets/federation/example.mdx +++ b/docs/enterprise/externalsecrets/federation/example.mdx @@ -169,8 +169,8 @@ This example demonstrates a common use case for ESI Federation: a central cluste 8. `esi-cli` injects the secrets as environment variables or files (e.g., sets `MY_APP_DB_PASSWORD` or writes to `/etc/secrets/service-a.token`). 9. The init container completes, and the main Prometheus container starts with the secrets available. - + This setup successfully allows `client-cluster-alpha` to consume secrets managed by `cluster-main`'s Vault instance without `client-cluster-alpha` (or its applications) needing any direct credentials or network access to Vault. The Federation Server acts as a secure intermediary. - + This example illustrates the power and flexibility of ESI Federation for managing secrets in a distributed environment. diff --git a/docs/enterprise/externalsecrets/federation/server-setup.mdx b/docs/enterprise/externalsecrets/federation/server-setup.mdx index 18db6f1..a952ca4 100644 --- a/docs/enterprise/externalsecrets/federation/server-setup.mdx +++ b/docs/enterprise/externalsecrets/federation/server-setup.mdx @@ -77,9 +77,9 @@ _spec: namespace: federation-generators ``` - + Both `KubernetesFederation` and `Authorization` CRs must be correctly configured on the Federation Server for clients to authenticate and be authorized to access secrets. - + ## Federation Server API Endpoints @@ -101,8 +101,8 @@ The Federation Server exposes the following HTTP POST endpoints for client inter * **Purpose**: Allows an authorized client to request revocation of credentials related to a generator type within a namespace (e.g., revoking all tokens issued by a specific Vault PKI generator for that client). * **Permissions**: Depends on the generator's capabilities and specific authorization rules. - + The request body for these endpoints, beyond the authentication details (like `ca.crt` for the client cluster's JWKS endpoint), may include parameters specific to the action, such as inputs for a generator. `esi-cli` handles the construction of these requests based on its command-line flags. - + Properly configuring these CRDs and understanding the API endpoints are key to operating a secure and functional ESI Federation Server. diff --git a/docs/enterprise/externalsecrets/generators/iam-keys.mdx b/docs/enterprise/externalsecrets/generators/iam-keys.mdx index f7e335b..68c7780 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](../../esi-agent/quickstart.mdx) + 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) ## Introduction diff --git a/docs/enterprise/externalsecrets/generators/neo4j.mdx b/docs/enterprise/externalsecrets/generators/neo4j.mdx index 193cf12..cc4b4c1 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](../../esi-agent/quickstart.mdx). + 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). ## Introduction diff --git a/docs/enterprise/externalsecrets/pod-webhook/annotations.mdx b/docs/enterprise/externalsecrets/pod-webhook/annotations.mdx index a2171ed..0cf383d 100644 --- a/docs/enterprise/externalsecrets/pod-webhook/annotations.mdx +++ b/docs/enterprise/externalsecrets/pod-webhook/annotations.mdx @@ -12,9 +12,9 @@ icon: "code" The ESI Pod Webhook is configured primarily through annotations added to the `metadata` section of your Pods. These annotations instruct the webhook on how and what secrets to inject. - + All ESI Pod Webhook annotations share the prefix `secretless.externalsecrets.com/`. - + ## Core Annotations @@ -65,9 +65,9 @@ These are the fundamental annotations to control basic secret injection. secretless.externalsecrets.com/file-secrets: "true" ``` - + You can enable both `env-vars` and `file-secrets` simultaneously if needed, though this is less common. If both are true, an init container will inject environment variables, AND a sidecar will provide `/secrets/secrets.json`. - + ### `skip` @@ -106,9 +106,9 @@ These annotations provide additional control or support for the injection proces These annotations allow you to pass specific command-line arguments directly to the `esi-cli` tool when it's run by the **init container** (i.e., for environment variable injection). They provide finer-grained control over `esi-cli`'s behavior, especially for features like federation. - + **Important**: The following passthrough annotations are **only effective when `secretless.externalsecrets.com/env-vars: "true"` is also specified.** They are **not** used by the sidecar container in `file-secrets` mode. - + ### `federated-server-url` @@ -122,9 +122,9 @@ These annotations allow you to pass specific command-line arguments directly to * **Annotation**: `secretless.externalsecrets.com/inject-on-env: ""` * **Maps to `esi-cli` flag**: `--inject-on-env` * **Description**: Provides a specific mapping string for `esi-cli` to control how secrets are named or selected when injected as environment variables. The format of `` is determined by `esi-cli`'s own parsing rules (e.g., `ENV_VAR_NAME=secretKey,OTHER_VAR=anotherKey`). - + While `secretless.externalsecrets.com/env-vars: "true"` enables general environment variable injection (all keys from the `ExternalSecret`'s data), this annotation allows for more precise control via `esi-cli`'s `--inject-on-env` flag, potentially overriding or refining the default behavior. - + * **Requires**: `env-vars: "true"`. ### `federated-generator` @@ -141,9 +141,9 @@ These annotations allow you to pass specific command-line arguments directly to * **Description**: Specifies store configurations for `esi-cli` when fetching secrets from a federated ESI server. * **Requires**: `env-vars: "true"` and likely `federated-server-url`. - + For detailed information on the expected values, formats, and behavior of the `esi-cli` flags (`--federated-server-url`, `--inject-on-env`, `--federated-generators`, `--federated-store`), please consult the [ESI-CLI documentation](../esi-cli). - + ## Webhook Global Configuration (Deployment Arguments) diff --git a/docs/enterprise/externalsecrets/pod-webhook/installation.mdx b/docs/enterprise/externalsecrets/pod-webhook/installation.mdx index 3cb5aa9..92bef7e 100644 --- a/docs/enterprise/externalsecrets/pod-webhook/installation.mdx +++ b/docs/enterprise/externalsecrets/pod-webhook/installation.mdx @@ -19,9 +19,9 @@ Before installing the ESI Pod Webhook, ensure your Kubernetes environment meets * **cert-manager**: The ESI Pod Webhook requires TLS certificates for secure communication with the Kubernetes API server. `cert-manager` is the recommended tool for automatically provisioning and managing these certificates. * You will need a `ClusterIssuer` or `Issuer` (e.g., for self-signed certificates in development/testing, or a Let's Encrypt issuer for public clusters) configured in `cert-manager`. - + Verify that `cert-manager` is running and your chosen issuer is ready before proceeding. - + ## Deployment @@ -47,9 +47,9 @@ The deployment manifest will set up the following: 2. **Obtain the Deployment Manifest**: * Download or locate the official `webhook.yaml` (or similarly named) deployment manifest for the ESI Pod Webhook from the External Secrets Inc. distribution channels. - + The default manifest might specify a `ClusterIssuer` (e.g., `selfsigned-issuer`). If your `ClusterIssuer` has a different name, you **must** update the `issuerRef.name` field within the `Certificate` resource definition in the `webhook.yaml` manifest before applying it. - + 3. **Apply the Manifest**: Use `kubectl` to apply the manifest to your cluster: @@ -73,9 +73,9 @@ The deployment manifest will set up the following: kubectl logs -n secretless-system -l app=esi-pod-webhook ``` - + The ESI Pod Webhook's own `Deployment` manifest typically includes the annotation `secretless.externalsecrets.com/skip: "true"`. This is important as it prevents the webhook from attempting to process its own pods, avoiding potential loops or issues. - + Once these steps are completed and verified, the ESI Pod Webhook should be active and ready to inject secrets into annotated pods based on your configuration. diff --git a/docs/enterprise/externalsecrets/pod-webhook/usage-examples.mdx b/docs/enterprise/externalsecrets/pod-webhook/usage-examples.mdx index f428369..1a03166 100644 --- a/docs/enterprise/externalsecrets/pod-webhook/usage-examples.mdx +++ b/docs/enterprise/externalsecrets/pod-webhook/usage-examples.mdx @@ -99,9 +99,9 @@ spec: # The API_TOKEN environment variable will be available here ``` - + The `secretless.externalsecrets.com/externalsecret` annotation is still technically required by the webhook to trigger its logic, even if the primary secret source is federated. You can point it to a minimal or placeholder `ExternalSecret` in the pod's namespace. - + **Explanation:** * `env-vars: "true"` enables the init container with `esi-cli`. diff --git a/docs/enterprise/externalsecrets/quickstart.mdx b/docs/enterprise/externalsecrets/quickstart.mdx index 7b1ff13..719af81 100644 --- a/docs/enterprise/externalsecrets/quickstart.mdx +++ b/docs/enterprise/externalsecrets/quickstart.mdx @@ -8,7 +8,7 @@ icon: "play" It requires a specific subscription. Contact us for more information. -As part of [ESI Agent](../esi-agent/quickstart.mdx) default configuration, the Enterprise Distribution of +As part of [ESI Agent](/docs/enterprise/externalsecrets/esi-agent/quickstart) default configuration, the Enterprise Distribution of External Secrets Operator (ESI for ESO) is automatically used within your environments. It has many features, including: diff --git a/docs/open_source/reloader/quickstart.mdx b/docs/open_source/reloader/quickstart.mdx index 1dc1ab1..5972ad0 100644 --- a/docs/open_source/reloader/quickstart.mdx +++ b/docs/open_source/reloader/quickstart.mdx @@ -6,7 +6,7 @@ description: 'Get Up and Running with External Secrets Reloader' Reloader is a tool that allows to trigger kubernetes manifests updates based on events from different sources: * [GCP Pubsub](./sources/gcp-pubsub-source) * [AWS SQS](./sources/awssqs-source) -* [Azure EventGrid](./sources/azure-eventgrid) +* [Azure EventGrid](./sources/azure-eventgrid-source) * [Hashicorp Vault audit Logs](./sources/vault-source) * [Generic Webhook](./sources/webhook-source) * [Kubernetes Secret](./sources/kubernetes-secret-source) diff --git a/docs/open_source/reloader/reference/api-reference.mdx b/docs/open_source/reloader/reference/api-reference.mdx index ded3a0c..055695e 100644 --- a/docs/open_source/reloader/reference/api-reference.mdx +++ b/docs/open_source/reloader/reference/api-reference.mdx @@ -2,786 +2,462 @@ title: API Reference description: 'API reference for Async Rotator' --- -# Kubernetes CRDs -## reloader.external-secrets.io/v1alpha1 - -Package v1alpha1 contains API Schema definitions for the reloader v1alpha1 API group - - - - - - - - - - - -### Config - -Config is the Schema for the reloader config API - - - - - -| Field | Type | Description | Validation | -| ----- | ---- | ----------- | ---------- | -| `apiVersion` | string | `reloader.external-secrets.io/v1alpha1` | | -| `kind` | string | `Config` | | -| `metadata` |
[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#objectmeta-v1-meta)
|
Refer to Kubernetes API documentation for fields of `metadata`.
|
| -| `spec` |
[ConfigSpec](#configspec)
|
|
| - - - - - - - - - - - - - - - - - - - - - - - - +# Kubernetes CRDs +## `reloader.external-secrets.io/v1alpha1` +Package `v1alpha1` contains API Schema definitions for the Reloader `v1alpha1` API group. +### `Config` +Config is the Schema for the Reloader Config API. +| Field | Type | Description | Validation | +|------------|--------|-----------------------------------------------------------------|------------| +| `apiVersion` | string | `reloader.external-secrets.io/v1alpha1` | | +| `kind` | string | `Config` | | +| `metadata` | [ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#objectmeta-v1-meta) | Refer to Kubernetes API documentation for fields of `metadata`. | | +| `spec` | [ConfigSpec](#configspec) | | | ## Types - -### AWSSDKAuth +### `AWSSDKAuth` AWSSDKAuth contains authentication methods for AWS SDK. +**Used by:** +- [AWSSQSConfig](#awssqsconfig) +| Field | Type | Description | Validation | +|-------------------|---------------------------------------|-------------|------------| +| `authMethod` | string | | | +| `region` | string | | | +| `serviceAccountRef`| [ServiceAccountSelector](#serviceaccountselector) | | | +| `secretRef` | [AWSSDKSecretRef](#awssdksecretref) | | | -

-Used by:
- -- AWSSQSConfig
-

- -| Field | Type | Description | Validation | -| ----- | ---- | ----------- | ---------- | -| `authMethod` |
string
|
|
| -| `region` |
string
|
|
| -| `serviceAccountRef` |
[ServiceAccountSelector](#serviceaccountselector)
|
|
| -| `secretRef` |
[AWSSDKSecretRef](#awssdksecretref)
|
|
| - +### `AWSSDKSecretRef` +**Used by:** +- [AWSSDKAuth](#awssdkauth) -### AWSSDKSecretRef +| Field | Type | Description | Validation | +|--------------------------|---------------------------------------|-------------|------------| +| `accessKeyIdSecretRef` | [SecretKeySelector](#secretkeyselector) | | | +| `secretAccessKeySecretRef` | [SecretKeySelector](#secretkeyselector) | | | - - - - -

-Used by:
- -- AWSSDKAuth
-

- -| Field | Type | Description | Validation | -| ----- | ---- | ----------- | ---------- | -| `accessKeyIdSecretRef` |
[SecretKeySelector](#secretkeyselector)
|
|
| -| `secretAccessKeySecretRef` |
[SecretKeySelector](#secretkeyselector)
|
|
| - - - -### AWSSQSConfig +### `AWSSQSConfig` AWSSQSConfig contains configuration for AWS SDK. +**Used by:** +- [NotificationSource](#notificationsource) +| Field | Type | Description | Validation | +|---------------------|-----------------------------|-----------------------------------------------------------------------------|-----------------| +| `queueURL` | string | QueueURL is the URL of the AWS SDK queue. | | +| `auth` | [AWSSDKAuth](#awssdkauth) | Authentication methods for AWS. | | +| `numberOfMessages` | integer | MaxNumberOfMessages specifies the maximum number of messages to retrieve from the SDK queue in a single request. | `default: 10` | +| `waitTimeSeconds` | integer | WaitTimeSeconds specifies the duration (in seconds) to wait for messages in the SDK queue before returning. | `default: 20` | +| `visibilityTimeout` | integer | VisibilityTimeout specifies the duration (in seconds) that a message received from the SDK queue is hidden from subsequent retrievals. | `default: 30` | -

-Used by:
- -- NotificationSource
-

- -| Field | Type | Description | Validation | -| ----- | ---- | ----------- | ---------- | -| `queueURL` |
string
|
QueueURL is the URL of the AWS SDK queue.
|
| -| `auth` |
[AWSSDKAuth](#awssdkauth)
|
Authentication methods for AWS.
|
| -| `numberOfMessages` |
integer
|
MaxNumberOfMessages specifies the maximum number of messages to retrieve from the SDK queue in a single request.
|
default: 10
| -| `waitTimeSeconds` |
integer
|
WaitTimeSeconds specifies the duration (in seconds) to wait for messages in the SDK queue before returning.
|
default: 20
| -| `visibilityTimeout` |
integer
|
VisibilityTimeout specifies the duration (in seconds) that a message received from the SDK queue is hidden from subsequent retrievals.
|
default: 30
| - - - -### AzureEventGridConfig - - +### `AzureEventGridConfig` +**Used by:** +- [NotificationSource](#notificationsource) +| Field | Type | Description | Validation | +|----------------|----------------|-------------|-------------------| +| `host` | string | | | +| `port` | integer | | `default: 8080` | +| `subscriptions`| string array | | | -

-Used by:
- -- NotificationSource
-

- -| Field | Type | Description | Validation | -| ----- | ---- | ----------- | ---------- | -| `host` |
string
|
|
| -| `port` |
integer
|
|
default: 8080
| -| `subscriptions` |
string array
|
|
| - - - -### BasicAuth +### `BasicAuth` BasicAuth contains basic authentication credentials. +**Used by:** +- [WebhookAuth](#webhookauth) +| Field | Type | Description | Validation | +|--------------------|---------------------------------------|-----------------------------------------------------------|------------| +| `usernameSecretRef`| [SecretKeySelector](#secretkeyselector) | UsernameSecretRef contains a secret reference for the username | | +| `passwordSecretRef`| [SecretKeySelector](#secretkeyselector) | PasswordSecretRef contains a secret reference for the password | | -

-Used by:
- -- WebhookAuth
-

- -| Field | Type | Description | Validation | -| ----- | ---- | ----------- | ---------- | -| `usernameSecretRef` |
[SecretKeySelector](#secretkeyselector)
|
UsernameSecretRef contains a secret reference for the username
|
| -| `passwordSecretRef` |
[SecretKeySelector](#secretkeyselector)
|
PasswordSecretRef contains a secret reference for the password
|
| - - - -### BearerToken +### `BearerToken` BearerToken contains the bearer token credentials. +**Used by:** +- [WebhookAuth](#webhookauth) +| Field | Type | Description | Validation | +|------------------------|---------------------------------------|-----------------------------------------------------------------------------|------------| +| `bearerTokenSecretRef` | [SecretKeySelector](#secretkeyselector) | BearerTokenSecretRef references a Kubernetes Secret containing the bearer token. | | -

-Used by:
- -- WebhookAuth
-

- -| Field | Type | Description | Validation | -| ----- | ---- | ----------- | ---------- | -| `bearerTokenSecretRef` |
[SecretKeySelector](#secretkeyselector)
|
BearerTokenSecretRef references a Kubernetes Secret containing the bearer token.
|
| - - - -### Condition - - - - - -

-Used by:
- -- MatchStrategy
-

- -| Field | Type | Description | Validation | -| ----- | ---- | ----------- | ---------- | -| `value` |
string
|
|
| -| `operation` |
[ConditionOperation](#conditionoperation)
|
|
| - - - -### ConditionOperation _`string`_ - - - - - -

-Used by:
- -- Condition
-

- -| Field | Description | -| `Equal` | | -| `NotEqual` | | -| `Contains` | | -| `NotContains` | | -| `RegularExpression` | | +### `Condition` +**Used by:** +- [MatchStrategy](#matchstrategy) +| Field | Type | Description | Validation | +|-------------|-------------------------------------|-------------|------------| +| `value` | string | | | +| `operation` | [ConditionOperation](#conditionoperation) | | | +### `ConditionOperation` _(string)_ -### ConfigSpec +**Used by:** +- [Condition](#condition) -ConfigSpec defines the desired state of a Reloader Config +| Field | Description | +|-------------------|-------------| +| `Equal` | | +| `NotEqual` | | +| `Contains` | | +| `NotContains` | | +| `RegularExpression` | | +### `ConfigSpec` +ConfigSpec defines the desired state of a Reloader Config. -

-Used by:
+**Used by:** +- [Config](#config) -- Config
-

+| Field | Type | Description | Validation | +|----------------------|------------------------------------------------------|-----------------------------------------------------------------------------|------------| +| `notificationSources`| [NotificationSource](#notificationsource) array | NotificationSources specifies the notification systems to listen to. | | +| `destinationsToWatch`| [DestinationToWatch](#destinationtowatch) array | DestinationsToWatch specifies which secrets the controller should monitor. | | -| Field | Type | Description | Validation | -| ----- | ---- | ----------- | ---------- | -| `notificationSources` |
[NotificationSource](#notificationsource) array
|
NotificationSources specifies the notification systems to listen to.
|
| -| `destinationsToWatch` |
[DestinationToWatch](#destinationtowatch) array
|
DestinationsToWatch specifies which secrets the controller should monitor.
|
| +### `DeploymentDestination` +Defines a DeploymentDestination. Behavior is a pod template annotations patch. +- Default **UpdateStrategy** is pod template annotations patch to trigger a new rollout. +- Default **MatchStrategy** matches secret keys using: + - `spec.template.spec.containers[*].env[*].valueFrom.secretKeyRef.name` + - `spec.template.spec.containers[*].envFrom.secretRef.name` +- Default **WaitStrategy** waits for rollout completion with a 3-minute grace period. +**Used by:** +- [DestinationToWatch](#destinationtowatch) +| Field | Type | Description | Validation | +|--------------------|----------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------|------------| +| `namespaceSelectors`| [LabelSelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#labelselector-v1-meta) array | NamespaceSelectors selects namespaces based on labels. Manifest must be in a matching namespace. | | +| `labelSelectors` | [LabelSelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#labelselector-v1-meta) | LabelSelectors selects resources by labels. Supports `matchLabels` and `matchExpressions`. | | +| `names` | string array | Names specifies resource names to watch. The resource must match one of the entries. | | - -### DeploymentDestination - -Defines a DeploymentDestination. Behavior is a pod templates annotations patch. -Default UpdateStrategy is pod template annotations patch to trigger a new rollout. -Default MatchStrategy is matching secret-key with any of: -* Equality against `spec.template.spec.containers[*].env[*].valueFrom.secretKeyRef.name` -* Equality against `spec.template.spec.containers[*].envFrom.secretRef.name` -Default WaitStrategy is to wait for the rollout to be completed with 3 minutes of grace period before -moving to the next matched deployment. - - - -

-Used by:
- -- DestinationToWatch
-

- -| Field | Type | Description | Validation | -| ----- | ---- | ----------- | ---------- | -| `namespaceSelectors` |
[LabelSelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#labelselector-v1-meta) array
|
NamespaceSelectors selects namespaces based on labels.
The manifest must reside in a namespace that matches at least one of these selectors.
|
| -| `labelSelectors` |
[LabelSelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#labelselector-v1-meta)
|
LabelSelectors selects resources based on their labels.
The resource must satisfy all conditions defined in this selector.
Supports both matchLabels and matchExpressions for advanced filtering.
|
| -| `names` |
string array
|
Names specifies a list of resource names to watch.
The resource must have a name that matches one of these entries.
|
| - - - -### DestinationToWatch +### `DestinationToWatch` DestinationToWatch specifies the criteria for monitoring secrets in the cluster. +**Used by:** +- [ConfigSpec](#configspec) +| Field | Type | Description | Validation | +|------------------|-----------------------------------------------------------|-----------------------------------------------------------------------------------------------------|------------| +| `type` | enum[`ExternalSecret`, `Deployment`] | Type specifies the kind of destination to watch. | | +| `externalSecret` | [ExternalSecretDestination](#externalsecretdestination) | | | +| `deployment` | [DeploymentDestination](#deploymentdestination) | | | +| `updateStrategy` | [UpdateStrategy](#updatestrategy) | If not specified, the default update strategy is used. | | +| `matchStrategy` | [MatchStrategy](#matchstrategy) | If not specified, the default match strategy is used. | | +| `waitStrategy` | [WaitStrategy](#waitstrategy) | If not specified, the default wait strategy is used. | | -

-Used by:
- -- ConfigSpec
-

- -| Field | Type | Description | Validation | -| ----- | ---- | ----------- | ---------- | -| `type` |
enum[`ExternalSecret`, `Deployment`]
|
Type specifies the type of destination to watch.
|
| -| `externalSecret` |
[ExternalSecretDestination](#externalsecretdestination)
|
|
| -| `deployment` |
[DeploymentDestination](#deploymentdestination)
|
|
| -| `updateStrategy` |
[UpdateStrategy](#updatestrategy)
|
UpdateStrategy. If not specified, will use each destinations' default update strategy.
|
| -| `matchStrategy` |
[MatchStrategy](#matchstrategy)
|
MatchStrategy. If not specified, will use each destinations' default match strategy.
|
| -| `waitStrategy` |
[WaitStrategy](#waitstrategy)
|
WaitStrategy. If not specified, will use each destinations's default wait strategy.
|
| - - - -### ExternalSecretDestination - -Defines an ExternalSecretDestination. Behavior is an annotations patch. -Default UpdateStrategy is annotations patch to trigger externalSecret reconcile. -Default MatchStrategy is matching secret-key with any of: -* Equality against `spec.data.remoteRef.key` -* Equality against `spec.dataFrom.remoteRef.key` -* Regexp against `spec.dataFrom.find.name.regexp` - - - -

-Used by:
- -- DestinationToWatch
-

- -| Field | Type | Description | Validation | -| ----- | ---- | ----------- | ---------- | -| `namespaceSelectors` |
[LabelSelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#labelselector-v1-meta) array
|
NamespaceSelectors selects namespaces based on labels.
The manifest must reside in a namespace that matches at least one of these selectors.
|
| -| `labelSelectors` |
[LabelSelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#labelselector-v1-meta)
|
LabelSelectors selects resources based on their labels.
The resource must satisfy all conditions defined in this selector.
Supports both matchLabels and matchExpressions for advanced filtering.
|
| -| `names` |
string array
|
Names specifies a list of resource names to watch.
The resource must have a name that matches one of these entries.
|
| - - - -### GCPSMAuthSecretRef - - - - - -

-Used by:
- -- GooglePubSubAuth
-

- -| Field | Type | Description | Validation | -| ----- | ---- | ----------- | ---------- | -| `secretAccessKeySecretRef` |
[SecretKeySelector](#secretkeyselector)
|
The SecretAccessKey is used for authentication
|
| - +### `ExternalSecretDestination` +Defines an ExternalSecretDestination. Behavior is annotations patch. -### GCPWorkloadIdentity +- Default **UpdateStrategy**: annotations patch triggers externalSecret reconcile. +- Default **MatchStrategy**: + - `spec.data.remoteRef.key` + - `spec.dataFrom.remoteRef.key` + - Regex match for `spec.dataFrom.find.name.regexp` +**Used by:** +- [DestinationToWatch](#destinationtowatch) +| Field | Type | Description | Validation | +|--------------------|----------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------|------------| +| `namespaceSelectors`| [LabelSelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#labelselector-v1-meta) array | NamespaceSelectors selects namespaces based on labels. Manifest must be in a matching namespace. | | +| `labelSelectors` | [LabelSelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#labelselector-v1-meta) | LabelSelectors selects resources by labels. Supports `matchLabels` and `matchExpressions`. | | +| `names` | string array | Names specifies resource names to watch. The resource must match one of the entries. | | +### `GCPSMAuthSecretRef` +**Used by:** +- [GooglePubSubAuth](#googlepubsubauth) -

-Used by:
+| Field | Type | Description | Validation | +|---------------------------|---------------------------------------|-----------------------------------------|------------| +| `secretAccessKeySecretRef`| [SecretKeySelector](#secretkeyselector) | The SecretAccessKey is used for authentication | | -- GooglePubSubAuth
-

+### `GCPWorkloadIdentity` -| Field | Type | Description | Validation | -| ----- | ---- | ----------- | ---------- | -| `serviceAccountRef` |
[ServiceAccountSelector](#serviceaccountselector)
|
|
| -| `clusterLocation` |
string
|
|
| -| `clusterName` |
string
|
|
| -| `clusterProjectID` |
string
|
|
| +**Used by:** +- [GooglePubSubAuth](#googlepubsubauth) +| Field | Type | Description | Validation | +|-------------------|-------------------------------------|-------------|------------| +| `serviceAccountRef`| [ServiceAccountSelector](#serviceaccountselector) | | | +| `clusterLocation` | string | | | +| `clusterName` | string | | | +| `clusterProjectID`| string | | | - -### GooglePubSubAuth +### `GooglePubSubAuth` GooglePubSubAuth contains authentication methods for Google Pub/Sub. +**Used by:** +- [GooglePubSubConfig](#googlepubsubconfig) +| Field | Type | Description | Validation | +|-------------------|---------------------------------------------|-----------------------------------------|------------| +| `secretRef` | [GCPSMAuthSecretRef](#gcpsmauthsecretref) | | | +| `workloadIdentity` | [GCPWorkloadIdentity](#gcpworkloadidentity) | | | -

-Used by:
- -- GooglePubSubConfig
-

- -| Field | Type | Description | Validation | -| ----- | ---- | ----------- | ---------- | -| `secretRef` |
[GCPSMAuthSecretRef](#gcpsmauthsecretref)
|
|
| -| `workloadIdentity` |
[GCPWorkloadIdentity](#gcpworkloadidentity)
|
|
| - - - -### GooglePubSubConfig +### `GooglePubSubConfig` GooglePubSubConfig contains configuration for Google Pub/Sub. +**Used by:** +- [NotificationSource](#notificationsource) +| Field | Type | Description | Validation | +|----------------|--------------------------------------|-----------------------------------------------------------------|------------| +| `subscriptionID`| string | SubscriptionID is the ID of the Pub/Sub subscription. | | +| `projectID` | string | ProjectID is the GCP project ID where the subscription exists. | | +| `auth` | [GooglePubSubAuth](#googlepubsubauth)| Authentication methods for Google Pub/Sub. | | -

-Used by:
- -- NotificationSource
-

- -| Field | Type | Description | Validation | -| ----- | ---- | ----------- | ---------- | -| `subscriptionID` |
string
|
SubscriptionID is the ID of the Pub/Sub subscription.
|
| -| `projectID` |
string
|
ProjectID is the GCP project ID where the subscription exists.
|
| -| `auth` |
[GooglePubSubAuth](#googlepubsubauth)
|
Authentication methods for Google Pub/Sub.
|
| - - - -### HashicorpVaultConfig - -HashicorpVault contains configuration for HashicorpVault notifications. - - - -

-Used by:
- -- NotificationSource
-

- -| Field | Type | Description | Validation | -| ----- | ---- | ----------- | ---------- | -| `host` |
string
|
Host is the hostname or IP address to listen on.
|
| -| `port` |
integer
|
Port is the port number to listen on.
|
default: 8000
| - - - -### KubeConfigRef - - - - - -

-Used by:
- -- KubernetesAuth
-

- -| Field | Type | Description | Validation | -| ----- | ---- | ----------- | ---------- | -| `secretRef` |
[SecretKeySelector](#secretkeyselector)
|
|
| - - - -### KubernetesAuth - - +### `HashicorpVaultConfig` +HashicorpVault contains configuration for Hashicorp Vault notifications. +**Used by:** +- [NotificationSource](#notificationsource) -

-Used by:
+| Field | Type | Description | Validation | +|---------|---------|------------------------------------------------|-----------------| +| `host` | string | Host is the hostname or IP address to listen on. | | +| `port` | integer | Port is the port number to listen on. | `default: 8000` | -- KubernetesSecretConfig
-

+### `KubeConfigRef` -| Field | Type | Description | Validation | -| ----- | ---- | ----------- | ---------- | -| `kubeConfigRef` |
[KubeConfigRef](#kubeconfigref)
|
|
| -| `caBundle` |
string
|
Defines a CABundle if either TokenRef or ServiceAccountRef are used.
|
| -| `tokenRef` |
[TokenRef](#tokenref)
|
|
| -| `serviceAccountRef` |
[ServiceAccountSelector](#serviceaccountselector)
|
|
| +**Used by:** +- [KubernetesAuth](#kubernetesauth) +| Field | Type | Description | Validation | +|-------------|---------------------------------------|-------------|------------| +| `secretRef` | [SecretKeySelector](#secretkeyselector) | | | +### `KubernetesAuth` -### KubernetesSecretConfig +**Used by:** +- [KubernetesSecretConfig](#kubernetessecretconfig) -KubernetesConfig contains configuration for Kubernetes notifications. +| Field | Type | Description | Validation | +|-------------------|---------------------------------------------|----------------------------------------------------------------|------------| +| `kubeConfigRef` | [KubeConfigRef](#kubeconfigref) | | | +| `caBundle` | string | Defines a CABundle if either `tokenRef` or `serviceAccountRef` are used. | | +| `tokenRef` | [TokenRef](#tokenref) | | | +| `serviceAccountRef` | [ServiceAccountSelector](#serviceaccountselector) | | | +### `KubernetesSecretConfig` +KubernetesSecretConfig contains configuration for Kubernetes notifications. -

-Used by:
+**Used by:** +- [NotificationSource](#notificationsource) -- NotificationSource
-

+| Field | Type | Description | Validation | +|-------------|--------------------------------------|-----------------------------------------------------------------------------|------------| +| `serverURL` | string | Server URL | | +| `auth` | [KubernetesAuth](#kubernetesauth) | How to authenticate with Kubernetes. If not specified, default config is used. | | -| Field | Type | Description | Validation | -| ----- | ---- | ----------- | ---------- | -| `serverURL` |
string
|
Server URL
|
| -| `auth` |
[KubernetesAuth](#kubernetesauth)
|
How to authenticate with Kubernetes cluster. If not specified, the default config is used.
|
| +### `MatchStrategy` +**Used by:** +- [DestinationToWatch](#destinationtowatch) +| Field | Type | Description | Validation | +|--------------|----------------------------------|-------------|------------| +| `path` | string | | | +| `conditions` | [Condition](#condition) array | | | -### MatchStrategy - - - - - -

-Used by:
- -- DestinationToWatch
-

- -| Field | Type | Description | Validation | -| ----- | ---- | ----------- | ---------- | -| `path` |
string
|
|
| -| `conditions` |
[Condition](#condition) array
|
|
| - - - -### MockConfig +### `MockConfig` MockConfig represents configuration settings for mock notifications. +**Used by:** +- [NotificationSource](#notificationsource) +| Field | Type | Description | Validation | +|----------------|---------|-------------|------------| +| `emitInterval` | integer | | | -

-Used by:
- -- NotificationSource
-

- -| Field | Type | Description | Validation | -| ----- | ---- | ----------- | ---------- | -| `emitInterval` |
integer
|
|
| - - - -### NotificationSource +### `NotificationSource` NotificationSource represents a notification system configuration. +**Used by:** +- [ConfigSpec](#configspec) +| Field | Type | Description | Validation | +|------------------|-------------------------------------------------------|-----------------------------------------------------------------------------|------------| +| `type` | enum[`AwsSqs`, `AzureEventGrid`, `GooglePubSub`, `HashicorpVault`, `Webhook`, `TCPSocket`, `KubernetesSecret`] | Type of the notification source. | | +| `awsSqs` | [AWSSQSConfig](#awssqsconfig) | AwsSqs configuration (required if `type` is `AwsSqs`). | | +| `azureEventGrid` | [AzureEventGridConfig](#azureeventgridconfig) | | | +| `googlePubSub` | [GooglePubSubConfig](#googlepubsubconfig) | GooglePubSub configuration (required if `type` is `GooglePubSub`). | | +| `webhook` | [WebhookConfig](#webhookconfig) | Webhook configuration (required if `type` is `Webhook`). | | +| `hashicorpVault` | [HashicorpVaultConfig](#hashicorpvaultconfig) | HashicorpVault configuration (required if `type` is `HashicorpVault`). | | +| `kubernetesSecret`| [KubernetesSecretConfig](#kubernetessecretconfig) | Kubernetes Secret configuration (required if `type` is `KubernetesSecret`).| | +| `tcpSocket` | [TCPSocketConfig](#tcpsocketconfig) | TCPSocket configuration (required if `type` is `TCPSocket`). | | +| `mock` | [MockConfig](#mockconfig) | Mock configuration (optional; useful for testing). | | -

-Used by:
- -- ConfigSpec
-

- -| Field | Type | Description | Validation | -| ----- | ---- | ----------- | ---------- | -| `type` |
enum[`AwsSqs`, `AzureEventGrid`, `GooglePubSub`, `HashicorpVault`, `Webhook`, `TCPSocket`, `KubernetesSecret`]
|
Type of the notification source (e.g., AwsSqs, AzureEventGrid, GooglePubSub, HashicorpVault, Webhook, TCPSocket, KubernetesSecret).
|
| -| `awsSqs` |
[AWSSQSConfig](#awssqsconfig)
|
AwsSqs configuration (required if Type is AwsSqs).
|
| -| `azureEventGrid` |
[AzureEventGridConfig](#azureeventgridconfig)
|
|
| -| `googlePubSub` |
[GooglePubSubConfig](#googlepubsubconfig)
|
GooglePubSub configuration (required if Type is GooglePubSub).
|
| -| `webhook` |
[WebhookConfig](#webhookconfig)
|
Webhook configuration (required if Type is Webhook).
|
| -| `hashicorpVault` |
[HashicorpVaultConfig](#hashicorpvaultconfig)
|
HashicorpVault configuration (required if Type is HashicorpVault).
|
| -| `kubernetesSecret` |
[KubernetesSecretConfig](#kubernetessecretconfig)
|
Kubernetes Secret watch configuration (required if Type is KubernetesSecret).
|
| -| `tcpSocket` |
[TCPSocketConfig](#tcpsocketconfig)
|
TCPSocket configuration (required if Type is TCPSocket).
|
| -| `mock` |
[MockConfig](#mockconfig)
|
Mock configuration (optional field for testing purposes).
|
| - - - -### PatchOperationConfig - - - - - -

-Used by:
- -- UpdateStrategy
-

- -| Field | Type | Description | Validation | -| ----- | ---- | ----------- | ---------- | -| `path` |
string
|
|
| -| `template` |
string
|
|
| - - - -### RetryPolicy - - +### `PatchOperationConfig` +**Used by:** +- [UpdateStrategy](#updatestrategy) +| Field | Type | Description | Validation | +|-------------|---------|-------------|------------| +| `path` | string | | | +| `template` | string | | | -

-Used by:
+### `RetryPolicy` -- WebhookConfig
-

+**Used by:** +- [WebhookConfig](#webhookconfig) -| Field | Type | Description | Validation | -| ----- | ---- | ----------- | ---------- | -| `maxRetries` |
integer
|
MaxRetries represents the maximum times the reloader should retry to process a message. Numbers greater than 10 will be ignored and 10 will be used instead
|
| -| `algorithm` |
string
|
Algorithm represents how watiting time will change for each retry.
Currently supports "linear" and "exponential". If an invalid string or null is given, "exponential" will be used
|
| +| Field | Type | Description | Validation | +|--------------|---------|---------------------------------------------------------------------------------------------------------------|------------| +| `maxRetries` | integer | MaxRetries is the maximum number of times to retry. Values over 10 are capped at 10. | | +| `algorithm` | string | Defines how retry timing evolves. Supports `"linear"` and `"exponential"` (default if value is invalid/null). | | +### `SecretKeySelector` +SecretKeySelector references a specific key within a Kubernetes secret. -### SecretKeySelector +**Used by:** +- [AWSSDKSecretRef](#awssdksecretref) +- [BasicAuth](#basicauth) +- [BearerToken](#bearertoken) +- [GCPSMAuthSecretRef](#gcpsmauthsecretref) +- [KubeConfigRef](#kubeconfigref) +- [TokenRef](#tokenref) -SecretKeySelector is used to reference a specific secret within a Kubernetes namespace. -It contains the name of the secret and the namespace where it resides. +| Field | Type | Description | Validation | +|-------------|---------|--------------------------------------------------------------------------------|------------| +| `name` | string | Name of the referenced Kubernetes secret. | | +| `key` | string | Key within the referenced Kubernetes secret. | | +| `namespace` | string | Namespace where the secret resides. | | +### `ServiceAccountSelector` +**Used by:** +- [AWSSDKAuth](#awssdkauth) +- [GCPWorkloadIdentity](#gcpworkloadidentity) +- [KubernetesAuth](#kubernetesauth) -

-Used by:
+| Field | Type | Description | Validation | +|-------------|---------------|-----------------------------------------------------------------------------------------------------|------------| +| `name` | string | Name of the service account to select. | | +| `namespace` | string | Namespace of the service account. | | +| `audiences` | string array | Audiences for the service account token. Additional values added based on identity provider used. | | -- AWSSDKSecretRef
-- BasicAuth
-- BearerToken
-- GCPSMAuthSecretRef
-- KubeConfigRef
-- TokenRef
-

- -| Field | Type | Description | Validation | -| ----- | ---- | ----------- | ---------- | -| `name` |
string
|
Name specifies the name of the referenced Kubernetes secret.
|
| -| `key` |
string
|
Key specifies the key within the referenced Kubernetes secret.
|
| -| `namespace` |
string
|
Namespace specifies the Kubernetes namespace where the referenced secret resides.
|
| - - - -### ServiceAccountSelector - - - - - -

-Used by:
- -- AWSSDKAuth
-- GCPWorkloadIdentity
-- KubernetesAuth
-

- -| Field | Type | Description | Validation | -| ----- | ---- | ----------- | ---------- | -| `name` |
string
|
Name specifies the name of the service account to be selected.
|
| -| `namespace` |
string
|
ServiceAccountSelector represents a Kubernetes service account with a name and namespace for selection purposes.
|
| -| `audiences` |
string array
|
Audience specifies the `aud` claim for the service account token
If the service account uses a well-known annotation for e.g. IRSA or GCP Workload Identity
then this audiences will be appended to the list
|
| - - - -### TCPSocketConfig +### `TCPSocketConfig` TCPSocketConfig contains configuration for TCP Socket notifications. +**Used by:** +- [NotificationSource](#notificationsource) +| Field | Type | Description | Validation | +|------------------------|---------|----------------------------------------------------------------------------------------------------------------------|-------------------| +| `host` | string | Host is the hostname or IP address to listen on. | | +| `port` | integer | Port is the port number to listen on. | `default: 8000` | +| `identifierPathOnPayload` | string | Key in the payload used to identify the secret. Defaults to `0.data.ObjectName` if not specified. | | -

-Used by:
- -- NotificationSource
-

- -| Field | Type | Description | Validation | -| ----- | ---- | ----------- | ---------- | -| `host` |
string
|
Host is the hostname or IP address to listen on.
|
| -| `port` |
integer
|
Port is the port number to listen on.
|
default: 8000
| -| `identifierPathOnPayload` |
string
|
SecretIdentifierOnPayload is the key that the reloader will look for in the payload.
The value of this key should be the same name as in the external secret. It will default to `0.data.ObjectName` if not set
|
| - - - -### TokenRef - - - - - -

-Used by:
- -- KubernetesAuth
-

- -| Field | Type | Description | Validation | -| ----- | ---- | ----------- | ---------- | -| `secretRef` |
[SecretKeySelector](#secretkeyselector)
|
|
| - - - -### UpdateStrategy - - - +### `TokenRef` +**Used by:** +- [KubernetesAuth](#kubernetesauth) -

-Used by:
+| Field | Type | Description | Validation | +|-------------|---------------------------------------|-------------|------------| +| `secretRef` | [SecretKeySelector](#secretkeyselector) | | | -- DestinationToWatch
-

+### `UpdateStrategy` -| Field | Type | Description | Validation | -| ----- | ---- | ----------- | ---------- | -| `operation` |
[UpdateStrategyOperation](#updatestrategyoperation)
|
|
| -| `patchOperationConfig` |
[PatchOperationConfig](#patchoperationconfig)
|
Required if Operation == Patch
|
| +**Used by:** +- [DestinationToWatch](#destinationtowatch) +| Field | Type | Description | Validation | +|---------------------|------------------------------------------------|--------------------------------------|------------| +| `operation` | [UpdateStrategyOperation](#updatestrategyoperation) | | | +| `patchOperationConfig` | [PatchOperationConfig](#patchoperationconfig) | Required if `operation == Patch`. | | +### `UpdateStrategyOperation` _(string)_ -### UpdateStrategyOperation _`string`_ +**Used by:** +- [UpdateStrategy](#updatestrategy) +| Field | Description | +|---------------|-------------| +| `PatchStatus` | | +| `Patch` | | +| `Delete` | | +### `WaitForCondition` +**Used by:** +- [WaitStrategy](#waitstrategy) +| Field | Type | Description | Validation | +|--------------------|-------------|--------------------------------------------------------------------------------------------------|------------| +| `retryTimeout` | [Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#duration-v1-meta) | Period to wait before each retry. | | +| `maxRetries` | integer | Maximum number of retries for the condition. | | +| `type` | string | The name of the condition to wait for. | | +| `message` | string | Optional message to match. | | +| `reason` | string | Optional reason to match. | | +| `transitionedAfter` | [Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#duration-v1-meta) | Minimum time since last transition to accept the condition. | | +| `updatedAfter` | [Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#duration-v1-meta) | Minimum time since last update to accept the condition. | | -

-Used by:
+### `WaitStrategy` -- UpdateStrategy
-

+**Used by:** +- [DestinationToWatch](#destinationtowatch) -| Field | Description | -| `PatchStatus` | | -| `Patch` | | -| `Delete` | | +| Field | Type | Description | Validation | +|-------------|---------------------------------------|------------------------------------------------------------|------------| +| `time` | [Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#duration-v1-meta) | Wait time between reconciliations. | | +| `condition` | [WaitForCondition](#waitforcondition) | Condition that must be satisfied before continuing. | | - - -### WaitForCondition - - - - - -

-Used by:
- -- WaitStrategy
-

- -| Field | Type | Description | Validation | -| ----- | ---- | ----------- | ---------- | -| `retryTimeout` |
[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#duration-v1-meta)
|
Period to wait before each retry
|
| -| `maxRetries` |
integer
|
Maximum retries to check for a condition
|
| -| `type` |
string
|
The name of the condition to wait for
|
| -| `message` |
string
|
Optional message to match
|
| -| `reason` |
string
|
Optional reason to match
|
| -| `transitionedAfter` |
[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#duration-v1-meta)
|
Only accept this condition after a given period from the transition time
|
| -| `updatedAfter` |
[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#duration-v1-meta)
|
Only accept this condition after a given period from the update time
|
| - - - -### WaitStrategy - - - - - -

-Used by:
- -- DestinationToWatch
-

- -| Field | Type | Description | Validation | -| ----- | ---- | ----------- | ---------- | -| `time` |
[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#duration-v1-meta)
|
Waits for a given time interval to reconcile the next object
|
| -| `condition` |
[WaitForCondition](#waitforcondition)
|
Waits for a given status condition to be met
|
| - - - -### WebhookAuth +### `WebhookAuth` WebhookAuth contains authentication methods for webhooks. +**Used by:** +- [WebhookConfig](#webhookconfig) +| Field | Type | Description | Validation | +|---------------|------------------------------|----------------------------------------------------------------|------------| +| `basicAuth` | [BasicAuth](#basicauth) | Basic authentication credentials. | | +| `bearerToken` | [BearerToken](#bearertoken) | Kubernetes secret containing the bearer token. | | -

-Used by:
- -- WebhookConfig
-

- -| Field | Type | Description | Validation | -| ----- | ---- | ----------- | ---------- | -| `basicAuth` |
[BasicAuth](#basicauth)
|
BasicAuth contains basic authentication credentials.
|
| -| `bearerToken` |
[BearerToken](#bearertoken)
|
BearerToken references a Kubernetes Secret containing the bearer token.
|
| - - - -### WebhookConfig +### `WebhookConfig` WebhookConfig contains configuration for Webhook notifications. +**Used by:** +- [NotificationSource](#notificationsource) - -

-Used by:
- -- NotificationSource
-

- -| Field | Type | Description | Validation | -| ----- | ---- | ----------- | ---------- | -| `path` |
string
|
Path that the webhook will receive the notifications.
If not present `/webhook` will be used. The path always expects a POST and this is not configurable
|
| -| `address` |
string
|
Address is the address where the webhook will be served in your infrastructure.
If not present, defaults to `:8090`
|
| -| `identifierPathOnPayload` |
string
|
SecretIdentifierOnPayload is the key that the reloader will look for in the payload.
The value of this key should be the same name as in the external secret. It will default to `0.data.ObjectName` if not set
|
| -| `webhookAuth` |
[WebhookAuth](#webhookauth)
|
Auth is the authentication method for the webhook
|
| -| `retryPolicy` |
[RetryPolicy](#retrypolicy)
|
RetryPolicy represents the policy to retry when a message fails.
If it's empty, reloader will return a 4xx and won't retry.
|
| - - +| Field | Type | Description | Validation | +|--------------------------|-------------------------------|-------------------------------------------------------------------------------------------------------|------------| +| `path` | string | Endpoint path (default: `/webhook`). Always expects a POST request. | | +| `address` | string | Address where the webhook is served. Defaults to `:8090`. | | +| `identifierPathOnPayload`| string | Key in the payload used to identify the secret. Defaults to `0.data.ObjectName` if not set. | | +| `webhookAuth` | [WebhookAuth](#webhookauth) | Authentication method for the webhook. | | +| `retryPolicy` | [RetryPolicy](#retrypolicy) | Policy to retry failed messages. If not set, 4xx will be returned and no retry will be attempted. | | diff --git a/docs/open_source/reloader/sources/gcp-pubsub-source.mdx b/docs/open_source/reloader/sources/gcp-pubsub-source.mdx index b92a041..b7cd67f 100644 --- a/docs/open_source/reloader/sources/gcp-pubsub-source.mdx +++ b/docs/open_source/reloader/sources/gcp-pubsub-source.mdx @@ -322,7 +322,7 @@ After all these steps - we are ready to install & use `reloader` ### Example Configuration -Before applying this manifest, be sure to have installed [ `reloader`](../quickstart.mdx) first. +Before applying this manifest, be sure to have installed [ `reloader`](/docs/open_source/reloader/quickstart) first. ```yaml diff --git a/mint.json b/mint.json index 9b49b3b..753eefc 100644 --- a/mint.json +++ b/mint.json @@ -206,6 +206,7 @@ "docs/open_source/reloader/sources/awssqs-source", "docs/open_source/reloader/sources/vault-source", "docs/open_source/reloader/sources/azure-eventgrid-source", + "docs/open_source/reloader/sources/webhook-source", "docs/open_source/reloader/sources/kubernetes-secret-source" ] },