Skip to main content
Version: 3.7.0

Update Webhook Certificates

Overview​

Bonree Operator uses webhook certificates to ensure the security of service injection within a Kubernetes environment. These certificates include the CA certificate and server certificate, which are used to establish secure HTTPS communication between the Kubernetes API Server and the Bonree Webhook service.

In general, certificates are automatically managed and periodically updated, but in some cases, you may need to manually update them, such as:

  • When certificates expire and automatic renewal fails
  • When security policies require regular manual updates
  • When using kubernetes-webhook-only.yaml and deploying in a namespace other than bonree-agent (automatic update not supported)
  • When the Operator does not have permission to modify MutatingWebhookConfiguration

This document explains the certificate structure, expiration strategy, and how to manually update them.

Webhook Certificate Structure​

CA Certificate (caBundle)​

Stored in the clientConfig.caBundle field of MutatingWebhookConfiguration, it allows the Kubernetes API Server to validate the certificate and sign HTTPS requests when calling back the Webhook service through the Service.

apiVersion: admissionregistration.k8s.io/v1
kind: MutatingWebhookConfiguration
webhooks:
  - admissionReviewVersions:
      - v1beta1
      - v1
    clientConfig:
      caBundle: {CABUNDLE}
      service:
        name: bonree-webhook
        namespace: bonree-agent
        path: /inject

Server Certificate and Private Key (tls.crt, tls.key)​

Used by the bonree-webhook Deployment to validate the legitimacy of Mutating requests, stored in the Secret bonree-webhook-certs:

apiVersion: v1
kind: Secret
metadata:
  name: bonree-webhook-certs
  namespace: bonree-agent
type: Opaque
data:
  tls.crt: {tls.crt}
  tls.key: {tls.key}

Certificate Expiration Strategy​

Depending on permissions, there are two scenarios.

Has Secret Read/Write Permission in Current Namespace​

If Secret certificates are not pre-configured, they will be dynamically generated at runtime:

  • CA certificate validity: 1 year
  • Server certificate (tls.crt) validity: 7 days

The controller checks the certificate validity every 6 hours and automatically updates it if the certificate is about to expire or has expired.

Manual update can also be triggered by deleting the Secret:

kubectl delete secret bonree-webhook-certs -n bonree-agent

No Secret Read/Write Permission in Current Namespace​

When deploying the Webhook, the namespace is fixed to bonree-agent. To change the namespace, certificates must be regenerated.

The default generated CA certificate is valid for 10 years. Once expired, it must be manually regenerated and updated in the deployment YAML.

Certificate Generation​

  1. Download bonree-certs.zip

  2. Run the script

    Run the script in Linux amd64 environment
    # Extract the package
    unzip bonree-certs.zip

    cd bonree-certs

    # Generate certificates valid for <expireYears> years in namespace <namespace>, save to certs/ directory, and update <yamlFilePathToUpdate>
    bash renewCerts.sh <namespace> <expireYears> <yamlFilePathToUpdate>

Parameter Description​

<namespace>​

  • Default: bonree-agent
  • The namespace to which the certificate belongs
  • If deploying the Webhook in another namespace (e.g., test-namespace), the certificate must be reissued for that namespace

<expireYears>​

  • Default: 10
  • Certificate validity period (in years)

<yamlFilePathToUpdate> 【Optional】​

  • Path to the webhook deployment YAML file, e.g., kubernetes-webhook-only.yaml
  • After generating new certificates, the script automatically updates the new caBundle, tls.crt, and tls.key fields in the specified YAML file