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

# ngrok External Secrets integration

> ngrok integrates with External Secrets Operator to enable secure management of secrets used in ngrok Traffic Policy.

This guide explains how to use the External Secrets Operator with ngrok to push Kubernetes secrets to ngrok vaults, where they can be referenced in your Traffic Policies for secure configuration management.

The [External Secrets Operator integration](https://external-secrets.io/latest/provider/ngrok/) allows you to push Kubernetes secrets to ngrok vaults for use in Traffic Policies.

## Use cases

* **Traffic Policy configuration:** Store API keys, tokens, and credentials that you can use to authenticate visitors with Traffic Policy actions
* **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:** Use sensitive configuration data in Traffic Policies securely, without leaking them

## How it works

External Secrets Operator watches for [`PushSecret`](https://external-secrets.io/latest/api/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.

### Limitations

* Currently supports push operations only (Kubernetes → ngrok)
* Pull operations (ngrok → Kubernetes) are not yet supported

## What you'll need

* An ngrok account.
* Your ngrok [API key](https://dashboard.ngrok.com/api-keys).
* An [ngrok vault](https://dashboard.ngrok.com/vaults) created for storing secrets.
* External Secrets Operator installed in your Kubernetes cluster.

## Configuration

### 1. Create ngrok API credentials

First, store your ngrok API key in a Kubernetes secret:

```bash theme={null}
kubectl create secret generic ngrok-credentials \
  --from-literal=api-key=<YOUR_NGROK_API_KEY>
```

### 2. Configure SecretStore

Next, create a SecretStore that connects to ngrok's API:

```yaml theme={null}
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 theme={null}
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 theme={null}
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
```

## What's next?

* Learn how to use [secrets in Traffic Policies](/traffic-policy/secrets/) to reference your synced secrets dynamically in policy actions.
* Explore the [Traffic Policy Actions](/traffic-policy/actions/) available to secure and manage traffic to your endpoints.
* Learn more about the [ngrok Kubernetes Operator](/k8s/) and how to configure Traffic Policies directly in your Kubernetes deployments.