Skip to main content
The External Secrets Enterprise Edition is product suite is a premium product. It requires a specific subscription. Contact us for more information.
Before installing the ESI Pod Webhook, ensure your Kubernetes environment meets the following prerequisites.

​
Prerequisites

  • Kubernetes Cluster: Version 1.16 or newer.
  • External Secrets Operator (ESO) CRDs: While the full operator is beneficial for managing ExternalSecret resources, at a minimum, the ESO Custom Resource Definitions (CRDs) such as ExternalSecret and SecretStore must be installed in your cluster. The webhook relies on these CRDs to understand where to fetch secrets from.
  • 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

The ESI Pod Webhook is typically deployed using a single YAML manifest. This manifest creates all necessary Kubernetes resources, usually within the secretless-system namespace (this can be customized if needed).

​
Resources Created

The deployment manifest will set up the following:
  1. MutatingWebhookConfiguration: Configures the Kubernetes API server to forward pod creation and update events (for pods not explicitly skipped) to the webhook’s service.
  2. Service: Exposes the webhook pods internally within the cluster, typically on port 8443.
  3. Deployment: Manages the webhook pods that contain the admission control logic.
  4. ServiceAccount: Provides an identity for the webhook pods.
  5. ClusterRole and ClusterRoleBinding: Grant the webhook’s ServiceAccount necessary permissions. These typically include:
    • Reading ExternalSecret and SecretStore resources cluster-wide.
    • Permissions to get, list, and watch pods, and to patch pod specifications.
  6. Certificate (cert-manager.io/v1): A cert-manager custom resource that requests a TLS certificate from your configured Issuer or ClusterIssuer. cert-manager will then automatically issue and manage the lifecycle of this certificate, storing it in a Kubernetes Secret that is mounted by the webhook pods.

​
Installation Steps

  1. Ensure Prerequisites are Met:
    • Confirm cert-manager is installed and a suitable ClusterIssuer or Issuer is available. For example, if the default manifest refers to selfsigned-issuer, ensure such an issuer exists or update the manifest to use your issuer.
  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: 
    kubectl apply -f webhook.yaml
    This command will create all the resources in the namespace specified within the manifest (commonly secretless-system).
  4. Verify Installation:
    • Check if the webhook deployment is running: 
      kubectl get pods -n secretless-system -l app=esi-pod-webhook
    • Ensure the Certificate resource is healthy and has issued a certificate: 
      kubectl describe certificate esi-pod-webhook-cert -n secretless-system
      (The certificate name might vary based on the manifest.)
    • Check the logs of the webhook pod for any startup errors: 
      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.

​
Next Steps

With the webhook installed, the next step is to learn about the Pod Annotations used to configure secret injection for your applications.