External Secrets Operator¶

Overview¶

Big Bang deploys the External Secrets Operator (ESO) wrapper into the external-secrets namespace. ESO reconciles its API resources against a configured external provider and writes the resulting Kubernetes Secrets. Consult the upstream API documentation and provider documentation for product behavior and provider-specific configuration.

Big Bang integration¶

Enable the package through the canonical packages.externalSecrets configuration entry. Legacy aliases are compatibility-only; use .packages for all new configuration. The umbrella owns the package source, release selection, provider identity and credentials, and cross-package dependency ordering; this chart owns the ESO wrapper and its Big Bang integration resources.

The wrapper installs the vendored ESO CRD bundle. It disables the upstream CRD installation by default, so do not manage a competing CRD installation without coordinating the lifecycle and upgrade plan. General ESO options are passed through the upstream parent. Per ADR 10, use the versioned upstream chart values for the complete upstream configuration surface rather than copying nested upstream settings into Big Bang values.

Stores and generated Secrets¶

The optional clusterSecretStoreConfiguration helper renders ClusterSecretStore resources for the AWS and Vault shapes implemented by this chart. A ClusterSecretStore is cluster-scoped: scope provider access, identity, role, service account, and referenced Secret deliberately. Namespace-scoped SecretStore resources and provider credentials are deployment-owned.

The optional externalSecretsConfiguration helper renders namespaced ExternalSecret resources that reference a ClusterSecretStore. It supports the template’s data and dataFrom mappings. Its default target creationPolicy is Owner; changing target names, mappings, refresh settings, or ownership policies can replace or remove generated Kubernetes Secrets. See the upstream ExternalSecret API before changing those lifecycle settings.

For the package-supported helper inputs and operational boundaries, see the deployment guide, AWS integration guide, and Vault integration guide. Those guides do not grant provider permissions or create credentials: use least-privilege, identity-based access where possible and keep credential material in deployment-managed Secrets.

Network, mesh, and admission¶

When network policies are enabled, the chart configures controller, webhook, and certificate-controller Kubernetes API access. The webhook’s API-server path is only opened when the upstream webhook is enabled. In an Istio-enabled deployment, the umbrella adds the required webhook Service HTTPS post-renderer when that webhook is enabled.

Provider connectivity is environment-specific. Hardened Istio uses restricted egress, so add only the explicit provider reachability required by the selected provider through the package’s supported network and bb-common.istio.serviceEntries.custom configuration. Do not broadly allow egress to resolve a provider failure. The chart includes a Vault egress rule when the Big Bang Vault package is enabled and labels ESO pods for Vault’s ingress policy; Vault-side authorization and Vault authentication remain owned by the Vault deployment and provider policy.

Granting Egress to Blocked Services¶

A valid Store configuration and provider credentials do not grant network access. ESO must reach the provider API and any identity endpoints used to obtain credentials, such as the appropriate regional AWS STS endpoint. Check the selected provider, region, endpoint overrides, and identity mechanism rather than allowing every endpoint for that cloud.

In sidecar mode, traffic captured by a proxy with effective REGISTRY_ONLY policy can be denied if its destination is unregistered. The chart exposes bb-common.istio.sidecar.outboundTrafficPolicyMode; a rendered Sidecar does not itself inject a proxy. Check namespace enrollment, actual pod injection, and capture exceptions before attributing a provider error to mesh policy.

Discovering Blocked Hosts¶

Confirm the intended kubeconfig. Inspect the failing Store/ExternalSecret’s status conditions and controller logs without printing the synchronized Secret or provider credentials. List the controller pods using the default chart label:

kubectl -n external-secrets get pods -l app.kubernetes.io/name=external-secrets --show-labels

Select a controller pod, not the optional webhook or certificate controller, and inspect both regular and init containers:

SOURCE_POD="replace-with-controller-pod-name"
kubectl -n external-secrets get pod "$SOURCE_POD" \
  -o jsonpath='{.spec.containers[*].name}{"\n"}{.spec.initContainers[*].name}{"\n"}'

If it has an istio-proxy, inspect recent proxy logs while ESO retries the failed reconciliation:

kubectl -n external-secrets logs "$SOURCE_POD" -c istio-proxy --since=10m \
  | grep -i 'BlackHoleCluster'

With proxy access logging enabled, BlackHoleCluster entries can help identify unregistered destinations. No match does not prove connectivity. Distinguish DNS, NetworkPolicy, TLS trust, and provider authentication/authorization errors. In ambient mode, use the relevant ztunnel/waypoint path instead of assuming an application-pod proxy; see the umbrella’s ambient guidance. Redact sensitive request metadata before sharing logs.

Registering External Destinations¶

These umbrella values register a single HTTPS provider endpoint using the supported custom ServiceEntry interface. Replace the example host with the actual provider API host; add separately reviewed identity endpoints if needed:

packageConfiguration:
  version: v1
packages:
  externalSecrets:
    values:
      bb-common:
        istio:
          enabled: true
          serviceEntries:
            custom:
              - name: provider-api
                spec:
                  hosts:
                    - secrets.example.com
                  exportTo: ["."]
                  location: MESH_EXTERNAL
                  resolution: DNS
                  ports:
                    - number: 443
                      name: https
                      protocol: TLS

When upgrading to this package version, move Big Bang overrides for this package’s istio, networkPolicies, and routes under values.bb-common. In Big Bang values, use packages.externalSecrets.values.bb-common.istio, packages.externalSecrets.values.bb-common.networkPolicies, and packages.externalSecrets.values.bb-common.routes; direct chart values use bb-common.<key> (for example, bb-common.istio). The mesh and its APIs must already be available; bb-common.istio.enabled does not enable injection. The custom array replaces existing entries, so retain any that are still required. Do not use the old istioGateway example for ESO connectivity.

ServiceEntries register destinations; they do not grant NetworkPolicy access or provider permissions. Review bb-common.networkPolicies.egress.definitions and the controller’s bb-common.networkPolicies.egress.from.external-secrets references. The default secrets-api-subnets definition permits a broad TCP 443 range; review and narrow it for your provider’s actual network path rather than adding another broad exception. Account for endpoint IP changes and DNS access. Commit reviewed changes through GitOps, then verify Store readiness and a synthetic secret sync without displaying the target Secret contents.

Consult the bundled bb-common 1.6.1 Istio and NetworkPolicy guides; match the version to Chart.yaml. Do not switch to ALLOW_ANY as a routine fix.

Monitoring and operations¶

The upstream ServiceMonitor is optional and requires both upstream.serviceMonitor.enabled and the monitoring API to be available. When the umbrella monitoring package is enabled, it orders monitoring before this release. Use ESO status conditions and the upstream metrics documentation to investigate Store and ExternalSecret reconciliation; provider reachability and credentials require environment-specific validation.

The package’s Helm test fixtures validate a synthetic secret sync only. They do not validate cloud or Vault identity, provider permissions, webhook admission, or secret rotation in a deployment. Test those paths with non-production data and targets before relying on a provider configuration.