certs

README

Certificate Manager Lite

This package provides lightweight certificate management functionality for a controller manager's webhook server. It is intended for developers who want to avoid depending on cert-manager just to manage self-signed certificates for webhooks.

Certificate Manager is designed to be invoked in your controller manager. It runs in the background as a goroutine, rotates certificates required by the webhook server in a secret and keeps the {Mutating,Validating}WebhookConfiguration's caBundle up-to-date.

Usage

Certificate Manager requires the following setup to be used by a controller manager.

Create an empty secret to hold webhook certs

Certificate Manager updates the certificate data to this secret whenever a rotation occurs.

apiVersion: v1
kind: Secret
metadata:
  annotations:
    tanzu.vmware.com/foo-webhook-rotation-interval: 6h
  name: tanzu-foo-webhook-server-cert
  namespace: default
type: Opaque

By default, Certificate Manager rotates certificates every 24 hours (plus a 30m grace period). To customize the rotation interval, use an annotation like tanzu.vmware.com/foo-webhook-rotation-interval: 6h above.

The Start Certificate Manager in the Controller Manager section shows how to configure Certificate Manager to look for this annotation.

Add a label to the WebhookConfiguration objects

Add a label of your choosing to the {Mutating,Validating}WebhookConfiguration objects to denote that their certificates are being managed by the Certificate Manager (the example below uses tanzu.vmware.com/foo-webhook-managed-certs: "true" label). This label will be used by the Certificate Manager to select these {Mutating,Validating}WebhookConfiguration objects and write caBundle to them.

The Start Certificate Manager in the Controller Manager section shows how to configure Certificate Manager to look for this label.

apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingWebhookConfiguration
metadata:
  name: tanzu-foo-validating-webhook-core
  labels:
    tanzu.vmware.com/foo-webhook-managed-certs: "true"
webhooks:
...

Configure your Controller Manager deployment

1. Mount the secret created above to the controller manager pod.
2. Pass the configuration necessary for the Certificate Manager as arguments to the controller manager binary. You will need to declare appropriate flags in the controller manager for passing arguments. Certificate Manager requires the following configuration options:
   • {Mutating,Validating}WebhookConfiguration label (added in the previous step).
   • Namespace of the webhook Service.
   • Name of the webhook Service.
   • Namespace of the webhook Secret (created above).
   • Name of the webhook Secret.

apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    app: tanzu-foo-manager
  name: tanzu-foo-controller-manager
  namespace: default
spec:
  ...
  spec:
    ...
    containers:
        - image: foo-controller-manager:latest
          name: manager
          args:
            - "--webhook-config-label=tanzu.vmware.com/foo-webhook-managed-certs=true"
            - "--webhook-service-namespace=default"
            - "--webhook-service-name=tanzu-foo-webhook-service"
            - "--webhook-secret-namespace=default"
            - "--webhook-secret-name=tanzu-foo-webhook-server-cert"
          volumeMounts:
            - mountPath: /tmp/k8s-webhook-server/serving-certs
              name: cert
              readOnly: true
          ...
    volumes:
      - name: cert
        secret:
          defaultMode: 420
          secretName: tanzu-foo-webhook-server-cert

1. Add RBAC rules to your controller manager deployment to read and write Secret, MutatingWebhookConfiguration and ValidatingWebhookConfiguration objects.

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  annotations:
  name: tanzu-foo-manager-clusterrole
rules:
  - apiGroups:
      - ""
    resources:
      - secrets
    verbs:
      - get
      - list
      - patch
      - update
      - watch
  - apiGroups:
      - "admissionregistration.k8s.io"
    resources:
      - mutatingwebhookconfigurations
      - validatingwebhookconfigurations
    verbs:
      - get
      - list
      - patch
      - update
      - watch

Start Certificate Manager in the Controller Manager

In the controller manager's main.go, initialize a CertificateManager object and invoke the Start method to start certificate management.

package main

import "github.com/vmware-tanzu/tanzu-framework/util/webhook/certs"

func main() {
    // Declare flags.
    flag.StringVar(&webhookConfigLabel, "webhook-config-label", defaultWebhookConfigLabel, "The label used to select webhook configurations to update the certs for.")
    flag.StringVar(&webhookServiceNamespace, "webhook-service-namespace", defaultWebhookServiceNamespace, "The namespace in which webhook service is installed.")
    flag.StringVar(&webhookServiceName, "webhook-service-name", defaultWebhookServiceName, "The name of the webhook service.")
    flag.StringVar(&webhookSecretNamespace, "webhook-secret-namespace", defaultWebhookSecretNamespace, "The namespace in which webhook secret is installed.")
    flag.StringVar(&webhookSecretName, "webhook-secret-name", defaultWebhookSecretName, "The name of the webhook secret.")

    // Initialize CertificateManager.
    certManagerOpts := certs.Options{
        Logger:                        ctrl.Log.WithName("foo-webhook-cert-manager"),
        CertDir:                       webhookSecretVolumeMountPath,
        WebhookConfigLabel:            webhookConfigLabel,
        RotationIntervalAnnotationKey: "tanzu.vmware.com/foo-webhook-rotation-interval",
        NextRotationAnnotationKey:     "tanzu.vmware.com/foo-webhook-next-rotation",
        RotationCountAnnotationKey:    "tanzu.vmware.com/featuregates-webhook-rotation-count",
        SecretName:                    webhookSecretName,
        SecretNamespace:               webhookSecretNamespace,
        ServiceName:                   webhookServiceName,
        ServiceNamespace:              webhookServiceNamespace,
    }

    // Other setup code...

    // Initialize certificate manager.
    signalHandler := ctrl.SetupSignalHandler()

    certManager, err := certs.New(certManagerOpts)
    if err != nil {
        log.Error(err, "failed to create certificate manager")
        os.Exit(1)
    }

    // Start cert manager.
    if err := certManager.Start(signalHandler); err != nil {
        log.Error(err, "failed to start certificate manager")
        os.Exit(1)
    }

    // Wait for cert dir to be ready.
    if err := certManager.WaitForCertDirReady(); err != nil {
        log.Error(err, "certificates not ready")
        os.Exit(1)
    }

    // Start controller manager.
    if err := mgr.Start(signalHandler); err != nil {
        log.Error(err, "problem running manager")
        os.Exit(1)
    }
}

Documentation

Overview

Package certs contains APIs to manage certificates for a controller manager's webhooks.

Index

• Constants
• type CertificateManager
  • func New(options *Options) (*CertificateManager, error)
  • func (cm *CertificateManager) Start(ctx context.Context) error
  • func (cm *CertificateManager) WaitForCertDirReady() error
• type Options

Constants

const (
	// CACertName is the name of the CA certificate.
	CACertName = "ca.crt"
	// ServerCertName is the name of the serving certificate.
	ServerCertName = "tls.crt"
	// ServerKeyName is the name of the server private key.
	ServerKeyName = "tls.key"
)

Types

type CertificateManager

type CertificateManager struct {
	// contains filtered or unexported fields
}

CertificateManager creates and rotates certificates required by a controller manager's webhook server.

func New

func New(options *Options) (*CertificateManager, error)

New returns a new instance of a CertificateManager.

func (*CertificateManager) Start

func (cm *CertificateManager) Start(ctx context.Context) error

Start starts certificate management for a controller manager's webhooks. This method calls os.Exit when an error is encountered.

func (*CertificateManager) WaitForCertDirReady

func (cm *CertificateManager) WaitForCertDirReady() error

WaitForCertDirReady blocks until certs are written to the cert directory or until a timeout occurs.

type Options

type Options struct {
	// Client is used by the certificate manager to read and write secrets and webhook configurations.
	Client client.Client

	// Logger is used to emit log events.
	Logger logr.Logger

	// CertDir is the path on the local filesystem where the certificates should be created once the secret is
	// mounted to the controller manager pod. This value is only required if WaitForCertDirReady() method is used.
	CertDir string

	// WebhookConfigLabel is the label used to select the mutating and validating webhook configurations to
	// which the certificate authority data is written.
	WebhookConfigLabel string

	// SecretName is the name of the secret that contains the webhook server's certificate data.
	SecretName string

	// SecretNamespace is the namespace of the secret that contains the webhook server's certificate data
	SecretNamespace string

	// ServiceName is the name of the webhook service.
	ServiceName string

	// ServiceNamespace is the namespace of the webhook service.
	ServiceNamespace string

	// RotationIntervalAnnotationKey specifies the annotation on the webhook server secret parseable by
	// time.ParseDuration and controls how often the certificates are rotated. If this annotation is not present on the
	// webhook secret specified by SecretName and SecretNamespace, rotation interval is defaulted to 24 hours.
	//
	// The generated certificates have their NotAfter property assigned to a value of 30 minutes greater than rotation
	// interval. This is to ensure a buffer between the generation of new certificates and expiration of old ones in
	// case of unexpected failures.
	RotationIntervalAnnotationKey string

	// NextRotationAnnotationKey specifies the annotation on the webhook server secret and is the UNIX epoch which
	// indicates when the next rotation will occur. This annotation is managed by the certificate manager.
	NextRotationAnnotationKey string

	// RotatationCountAnnotationKey specifies an annotation on the webhook server
	// secret. The annotation's value is the number of times the certificates
	// have been rotated. This is primarily used for testing and the count may not always be accurate.
	RotationCountAnnotationKey string
}

Options defines the configuration used to create a new CertificateManager.