Add k8s external secrets integration doc

docs/k8s/integrations/external-secrets.mdx

@@ -0,0 +1,136 @@
+# ngrok External Secrets integration
+
+ngrok integrates with External Secrets Operator to enable secure management of secrets used in [ngrok Traffic Policy](https://ngrok.com/blog-post/secrets-for-traffic-policy).
+This integration allows you to push Kubernetes secrets to ngrok vaults, where they can be referenced in your traffic policies for secure configuration management.
+
+## How it works
+
+External Secrets Operator watches for PushSecret resources in your cluster.
+When a PushSecret is created or updated, it reads the specified Kubernetes secret and pushes the secret data to your ngrok vault using the ngrok API.
+The secret then becomes available in ngrok for use in Traffic Policies.
+The operator continues to sync changes based on the configured refresh interval, ensuring your ngrok secrets stay up-to-date with changes in Kubernetes.
+
+### Limitations
+
+- Currently supports push operations only (Kubernetes → ngrok)
+- Pull operations (ngrok → Kubernetes) are not yet supported
+
+## Use cases
+
+- **Traffic Policy configuration**: Store API keys, tokens, and credentials used in ngrok Traffic Policy rules
+- **Multi-environment management**: Sync different secrets to different ngrok vaults for dev, staging, and production
+- **Secret rotation**: Automatically propagate rotated secrets from Kubernetes to ngrok
+- **Compliance**: Keep sensitive configuration data out of Traffic Policy definitions
+
+## What you'll need
+
+- ngrok account with API access
+- External Secrets Operator installed in your Kubernetes cluster
+- ngrok API key
+- An ngrok vault created for storing secrets
+
+## Configuration
+
+### 1. Create ngrok API credentials
+
+First, store your ngrok API key in a Kubernetes secret:
+
+```bash
+kubectl create secret generic ngrok-credentials \
+  --from-literal=api-key=<YOUR_NGROK_API_KEY>
+```
+
+### 2. Configure SecretStore
+
+Create a SecretStore that connects to ngrok's API:
+
+```yaml
+apiVersion: external-secrets.io/v1
+kind: SecretStore
+metadata:
+  name: ngrok
+spec:
+  provider:
+    ngrok:
+      # apiURL: Default "https://api.ngrok.com", for enterprise ngrok instances uncomment and use your API URL.
+      auth:
+        apiKey:
+          secretRef:
+            name: ngrok-credentials
+            key: api-key
+      vault:
+        name: my-vault  # Name of the ngrok vault to use for storing secrets
+```
+
+**Configuration properties:**
+
+- `auth.apiKey`: Reference to your ngrok API key (required)
+- `vault.name`: Name of your ngrok vault where secrets will be stored (required)
+- `apiURL`: API endpoint (optional, defaults to `https://api.ngrok.com`)
+
+## Pushing secrets to ngrok
+
+### Basic push configuration
+
+To sync a Kubernetes secret with ngrok, create a PushSecret resource:
+
+```yaml
+apiVersion: external-secrets.io/v1alpha1
+kind: PushSecret
+metadata:
+  name: ngrok-push-secret-example
+spec:
+  deletionPolicy: Delete
+  refreshInterval: 10m  # Refresh interval for which push secret will reconcile
+  secretStoreRefs:  # A list of secret stores to push secrets to
+    - name: ngrok  # Must match SecretStore on the cluster
+      kind: SecretStore
+  selector:
+    secret:
+      name: SECRET_NAME  # Source Kubernetes secret to be pushed
+  data:
+    - match:
+        # The key in the Kubernetes secret to push. Leave empty to push all keys, JSON encoded.
+        # secretKey: ""
+        secretKey: MY_K8S_SECRET_KEY
+      remoteRef:
+        remoteKey: MY_NGROK_SECRET_NAME  # The name of the secret in the ngrok vault
+```
+
+### Adding metadata to secrets
+
+You can enhance your ngrok secrets with descriptions and custom metadata:
+
+```yaml
+apiVersion: external-secrets.io/v1alpha1
+kind: PushSecret
+metadata:
+  name: ngrok-push-secret-example
+spec:
+  deletionPolicy: Delete
+  refreshInterval: 10m  # Refresh interval for which push secret will reconcile
+  secretStoreRefs:  # A list of secret stores to push secrets to
+    - name: ngrok  # Must match SecretStore on the cluster
+      kind: SecretStore
+  selector:
+    secret:
+      name: SECRET_NAME  # Source Kubernetes secret to be pushed
+  data:
+    - match:
+        # The key in the Kubernetes secret to push. Leave empty to push all keys, JSON encoded.
+        # secretKey: ""
+        secretKey: MY_K8S_SECRET_KEY
+      remoteRef:
+        remoteKey: MY_NGROK_SECRET_NAME  # The name of the secret in the ngrok vault
+      metadata:
+        apiVersion: kubernetes.external-secrets.io/v1alpha1
+        kind: PushSecretMetadata
+        spec:
+          # See https://ngrok.com/docs/api/resources/secrets/#parameters
+          # We currently support customizing the description and metadata for the secret.
+          description: "This is a secret for the API credentials"
+          # Metadata for the secret in the ngrok vault. This will be merged with auto-generated metadata.
+          metadata:
+            environment: production
+            team: devops
+```