Skip to content

Commit 64e6ea8

Browse files
SkarlsoSkarlso
authored
chore: add missing things to the documentation (#294)
1 parent 16dcb0c commit 64e6ea8

6 files changed

Lines changed: 375 additions & 4 deletions

File tree

‎docs/destinations/push-secrets.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# PushSecrets
2+
3+
## Overview
4+
5+
A PushSecret destination consists of a Kubernetes PushSecret Custom Resource that will be triggered to reconcile when an event arrives.
6+
7+
In order to use this destination, [external-secrets operator](https://github.com/external-secrets/external-secrets) must be installed in the cluster.
8+
9+
This can be used with any notification source to automatically trigger a PushSecret reconciliation when a secret changes.
10+
11+
- Default **UpdateStrategy** is annotations patch to trigger PushSecret reconcile.
12+
- Default **MatchStrategy** matches secret keys using:
13+
- `spec.selector.secret.name`
14+
- `spec.data[*].match.remoteRef.remoteKey`
15+
16+
## Configuration
17+
18+
PushSecret configuration is straightforward: all you need to do is add a `pushSecret` as a destination to Watch in your configuration manifest:
19+
20+
```yaml
21+
apiVersion: reloader.external-secrets.io/v1alpha1
22+
kind: Config
23+
metadata:
24+
name: reloader-sample
25+
labels:
26+
app.kubernetes.io/name: reloader
27+
spec:
28+
notificationSources:
29+
- #... any notification sources you want
30+
destinationsToWatch:
31+
- type: PushSecret
32+
pushSecret:
33+
# you may set one or more of the below:
34+
# namespace selectors restrict PushSecret destinations to be on a given namespace set.
35+
namespaceSelectors:
36+
matchLabels:
37+
specific-namespaces-auto-rollout: allowed
38+
# label selectors target specific PushSecrets within restricted namespaces.
39+
labelSelectors:
40+
matchLabels:
41+
specific-pushsecret-labels-match: "true"
42+
# Filters down to specific PushSecret names
43+
names:
44+
- optional-name-matching-for-each-pushsecret
45+
```

‎docs/quickstart.md‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -7,14 +7,16 @@ Reloader is a tool that allows to trigger kubernetes manifests updates based on
77
* [Azure EventGrid](sources/azure-eventgrid.md)
88
* [Hashicorp Vault audit Logs](sources/vault.md)
99
* [Generic Webhook](sources/webhook.md)
10+
* [TCP Socket](sources/tcp-socket.md)
1011
* [Kubernetes Secret](sources/kubernetes-secret.md)
12+
* [Kubernetes ConfigMap](sources/kubernetes-configmap.md)
1113

1214
With it, it is possible to trigger manifest changes to multiple destinations:
1315

14-
* [ExternalSecret](https://external-secrets.io/latest/introduction/getting-started/)
15-
* [Deployments](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/)
16-
17-
And many more to come!
16+
* [ExternalSecret](destinations/external-secrets.md)
17+
* [Deployments](destinations/deployments.md)
18+
* [PushSecret](destinations/push-secrets.md)
19+
* [WorkflowRunTemplate](destinations/workflows.md)
1820

1921
## Installing Reloader
2022

‎docs/reference/strategies.md‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
# Strategies
2+
3+
Each destination in the Reloader configuration supports three optional strategies that control how updates are applied, how secrets are matched, and how the Reloader waits between reconciliations.
4+
5+
When not specified, sensible defaults are used per destination type. See [Deployments](../destinations/deployments.md), [ExternalSecrets](../destinations/external-secrets.md), [PushSecrets](../destinations/push-secrets.md), and [WorkflowRunTemplate](../destinations/workflows.md) for their respective defaults.
6+
7+
## Update Strategy
8+
9+
The Update Strategy controls what action the Reloader takes when a matching event arrives.
10+
11+
### Operations
12+
13+
| Operation | Description |
14+
|---------------|-----------------------------------------------------------------------------|
15+
| `PatchStatus` | Patches the status subresource of the destination object. |
16+
| `Patch` | Patches the destination object at a custom path with a given template. |
17+
| `Delete` | Deletes the destination object entirely. |
18+
19+
### Example: Custom Patch
20+
21+
```yaml
22+
destinationsToWatch:
23+
- type: Deployment
24+
deployment:
25+
labelSelectors:
26+
matchLabels:
27+
app: my-app
28+
updateStrategy:
29+
operation: Patch
30+
patchOperationConfig:
31+
path: "/spec/template/metadata/annotations"
32+
template: '{"reloader.external-secrets.io/rotated-at": "{{ .Timestamp }}"}'
33+
```
34+
35+
### Example: Delete on Event
36+
37+
```yaml
38+
destinationsToWatch:
39+
- type: ExternalSecret
40+
externalSecret:
41+
names:
42+
- my-external-secret
43+
updateStrategy:
44+
operation: Delete
45+
```
46+
47+
## Match Strategy
48+
49+
The Match Strategy controls how the Reloader determines whether a destination is affected by a given secret event. It evaluates a JSON path on the destination object against one or more conditions.
50+
51+
### Condition Operations
52+
53+
| Operation | Description |
54+
|---------------------|------------------------------------------------|
55+
| `Equal` | Exact value match. |
56+
| `NotEqual` | Value does not match. |
57+
| `Contains` | Value contains the given substring. |
58+
| `NotContains` | Value does not contain the given substring. |
59+
| `RegularExpression` | Value matches the given regular expression. |
60+
61+
### Example: Custom Match Path
62+
63+
```yaml
64+
destinationsToWatch:
65+
- type: Deployment
66+
deployment:
67+
labelSelectors:
68+
matchLabels: {}
69+
matchStrategy:
70+
path: "spec.template.spec.containers[*].env[*].valueFrom.secretKeyRef.name"
71+
conditions:
72+
- value: "my-secret"
73+
operation: Equal
74+
```
75+
76+
### Example: Regex Match
77+
78+
```yaml
79+
destinationsToWatch:
80+
- type: ExternalSecret
81+
externalSecret:
82+
labelSelectors:
83+
matchLabels: {}
84+
matchStrategy:
85+
path: "spec.dataFrom.find.name.regexp"
86+
conditions:
87+
- value: "prod/.*"
88+
operation: RegularExpression
89+
```
90+
91+
## Wait Strategy
92+
93+
The Wait Strategy controls how the Reloader waits between reconciling multiple destination objects. This is useful to avoid overwhelming the cluster with simultaneous rollouts.
94+
95+
Two modes are available: time-based and condition-based. They can be used independently or together.
96+
97+
### Time-Based Wait
98+
99+
Waits for a fixed duration before reconciling the next object.
100+
101+
```yaml
102+
destinationsToWatch:
103+
- type: Deployment
104+
deployment:
105+
labelSelectors:
106+
matchLabels: {}
107+
waitStrategy:
108+
time: 30s
109+
```
110+
111+
### Condition-Based Wait
112+
113+
Waits until a specific condition is met on the destination object before moving to the next one. Supports retry logic with configurable timeout and maximum retries.
114+
115+
```yaml
116+
destinationsToWatch:
117+
- type: Deployment
118+
deployment:
119+
labelSelectors:
120+
matchLabels: {}
121+
waitStrategy:
122+
condition:
123+
type: Available
124+
status: "True"
125+
retryTimeout: 10s
126+
maxRetries: 18
127+
```
128+
129+
In this example, the Reloader waits for the `Available` condition to be `True` before proceeding, checking every 10 seconds up to 18 times (3 minutes total).
130+
131+
### Condition Fields
132+
133+
| Field | Description | Required |
134+
|--------------------|--------------------------------------------------------------------------|----------|
135+
| `type` | The name of the condition to wait for. | Yes |
136+
| `status` | The expected status of the condition. | No |
137+
| `message` | Optional message to match. | No |
138+
| `reason` | Optional reason to match. | No |
139+
| `retryTimeout` | Period to wait before each retry. | No |
140+
| `maxRetries` | Maximum number of retries for the condition. | No |
141+
| `transitionedAfter`| Only accept this condition after a given period from the transition time. | No |
142+
| `updatedAfter` | Only accept this condition after a given period from the update time. | No |
143+
144+
### Example: Wait for Fresh Condition
145+
146+
```yaml
147+
waitStrategy:
148+
condition:
149+
type: Available
150+
status: "True"
151+
transitionedAfter: 5s
152+
retryTimeout: 10s
153+
maxRetries: 30
154+
```
155+
156+
This ensures the `Available` condition was set at least 5 seconds ago, avoiding stale conditions from a previous rollout.

‎docs/sources/kubernetes-configmap.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# Kubernetes ConfigMap
2+
3+
This guide explains how to set up Kubernetes ConfigMap events as a notification source for the Reloader component in your environment.
4+
5+
## Overview
6+
7+
The Reloader receives events from Kubernetes ConfigMap by using permissions from an authorized kubeconfig/service account to create a `watch` over ConfigMaps in the target cluster.
8+
9+
This works identically to the [Kubernetes Secret](kubernetes-secret.md) source, but watches ConfigMap resources instead.
10+
11+
## Prerequisites
12+
13+
* A valid service account / kubeconfig with `watch` permissions over ConfigMaps available in the cluster where `reloader` is installed.
14+
15+
## Step 1: Configure Reloader
16+
17+
Update your Reloader configuration to set up the Kubernetes ConfigMap listener.
18+
19+
### Configuration Spec
20+
21+
```yaml
22+
apiVersion: reloader.external-secrets.io/v1alpha1
23+
kind: Config
24+
metadata:
25+
name: reloader-configmap-sample
26+
spec:
27+
notificationSources:
28+
- type: KubernetesConfigMap
29+
kubernetesConfigMap:
30+
serverURL: https://kubernetes.default.svc
31+
# Auth configuration for the reloader
32+
# If targeting the same cluster, this block is optional
33+
auth:
34+
# b64 encoded CaBundle for the service.
35+
caBundle: Cg==
36+
# ref for a kubeconfig file in a form of a Kubernetes Secret
37+
kubeConfigRef:
38+
secretRef:
39+
name: reloader-kubeconfig
40+
key: kubeconfig
41+
namespace: reloader-system
42+
# ref for a token in a form of a Kubernetes Secret
43+
tokenRef:
44+
secretRef:
45+
name: reloader-token
46+
key: token
47+
namespace: reloader-system
48+
# ref for a Kubernetes Service Account
49+
serviceAccountRef:
50+
name: reloader
51+
namespace: reloader-system
52+
# Optional: narrow down which ConfigMaps to watch
53+
labelSelector:
54+
matchLabels:
55+
managed-by: reloader
56+
destinationsToWatch:
57+
- type: Deployment
58+
deployment:
59+
labelSelectors:
60+
matchLabels: {}
61+
```
62+
63+
## Processing Events
64+
65+
Because reloader is only on a `watch` over ConfigMaps, it means that `get`, `list` and `watch` operations are not monitored.

‎docs/sources/tcp-socket.md‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
# TCP Socket
2+
3+
This guide explains how to set up a generic TCP Socket as a notification source for the Reloader component in your environment. Using a TCP Socket allows you to trigger secret rotation events from any system capable of sending data over a TCP connection.
4+
5+
## Overview
6+
7+
The Reloader opens a TCP listener that receives JSON payloads from external systems. When a payload arrives, the Reloader extracts the secret identifier from a configurable path in the payload and triggers reconciliation on matching destinations.
8+
9+
This is the same mechanism used internally by the [Hashicorp Vault](vault.md) source, exposed as a standalone source for custom integrations.
10+
11+
## Prerequisites
12+
13+
- Kubernetes cluster with Reloader installed.
14+
- Load Balancer Service Provider available for your Kubernetes cluster (if the sender is external).
15+
16+
## Step 1: Configure Reloader
17+
18+
Update your Reloader configuration to set up the TCP Socket listener.
19+
20+
### Configuration Spec
21+
22+
```yaml
23+
apiVersion: reloader.external-secrets.io/v1alpha1
24+
kind: Config
25+
metadata:
26+
name: reloader-tcp-sample
27+
labels:
28+
app.kubernetes.io/name: reloader
29+
spec:
30+
notificationSources:
31+
- type: TCPSocket
32+
tcpSocket:
33+
host: 0.0.0.0
34+
port: 8000
35+
identifierPathOnPayload: "0.data.ObjectName"
36+
destinationsToWatch:
37+
- type: ExternalSecret
38+
externalSecret:
39+
labelSelectors:
40+
matchLabels: {}
41+
```
42+
43+
- **`host`**: The host interface to bind the listener to. Use `0.0.0.0` to listen on all interfaces.
44+
- **`port`**: The port on which the listener will accept connections. Defaults to `8000`.
45+
- **`identifierPathOnPayload`**: The key in the payload used to identify the secret. Defaults to `0.data.ObjectName` if not specified.
46+
47+
In this configuration:
48+
49+
- The listener will accept events at `tcp://<host>:8000`.
50+
51+
## Step 2: Expose the TCP Listener
52+
53+
To allow external systems to send events to the TCP listener, you need to expose it outside the Kubernetes cluster.
54+
55+
### Create a Kubernetes Service
56+
57+
Create a LoadBalancer Service to expose the Reloader TCP listener.
58+
59+
```yaml
60+
apiVersion: v1
61+
kind: Service
62+
metadata:
63+
name: reloader-tcp-socket
64+
spec:
65+
type: LoadBalancer
66+
selector:
67+
app.kubernetes.io/name: reloader
68+
ports:
69+
- protocol: TCP
70+
port: 8000
71+
targetPort: 8000
72+
```
73+
74+
## Processing Events
75+
76+
When a message arrives on the TCP socket, the Reloader extracts the secret identifier from the payload using the configured `identifierPathOnPayload` path. It then matches the identifier against the configured destinations and triggers reconciliation on any matching resources.
77+
78+
### Example Payload
79+
80+
The default identifier path expects a payload structured like:
81+
82+
```json
83+
{
84+
"0": {
85+
"data": {
86+
"ObjectName": "my-secret"
87+
}
88+
}
89+
}
90+
```
91+
92+
You can customize `identifierPathOnPayload` to match the structure of your system's payload.
93+
94+
## Enabling External Traffic
95+
96+
To ensure the TCP listener is accessible:
97+
98+
- **Network Policies**: If using network policies, allow inbound traffic to the TCP listener.
99+
- **Firewall Rules**: Configure firewalls or security groups to allow traffic from the sending system to your cluster.

0 commit comments

Comments
 (0)