This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

clustersecret-operator

clustersecret-operator adds a new resource type clustersecrets.core.cs.sap.com, with kind ClusterSecret, to Kubernetes clusters. It allows to define secrets at cluster scope, along with an optional selector defining in which namespaces the according Kubernetes secrets shall exist. The controlller provided by this repository takes care of distributing the secrets, and keeping everything in sync.

This website provides the full technical documentation for the project, and can be used as a reference; if you feel that there’s anything missing, please let us know or raise a PR to add it.

1 - Installation

Overview on available installation methods

clustersecret-operator introduces one custom resource type, clustersecrets.core.cs.sap.com, with kind ClusterSecret. The according definitions can be found here. This definition must be deployed before the executables provided by this repository can be started. The core of the clustersecret-operator installation are the controller and webhook executables built from this repository. Docker images are available here:

  • controller: ghcr.io/sap/clustersecret-operator/controller
  • webhook: ghcr.io/sap/clustersecret-operator/webhook

A complete deployment consists of:

  • the custom resource definition
  • the controller deployment
  • the webhook deployment
  • rbac objects for controller and webhook (service accounts, (cluster) roles, according (cluster) role bindings)
  • a service for the webhooks
  • webhook configurations.

Note that it is highly recommended to always activate the webhooks, as they are not only validating, but also adding essential defaulting logic. Running without this mutating functionality might lead to unexpected behavior.

The following deployment methods are available (recommended is Helm).

1.1 - Helm

Installation by Helm

Helm deployment

The recommended way to deploy clustersecret-operator is to use the Helm chart, also available in packaged form:

The chart does not require any mandatory parameters, so deploying clustersecret-operator is as easy as

helm repo add clustersecret-operator https://sap.github.io/clustersecret-operator-helm
helm -n clustersecret-operator upgrade -i clustersecret-operator clustersecret-operator/clustersecret-operator

2 - Configuration

Configuration options

Below you will find details on configuration options.

2.1 - Controller startup options

Command line configuration options, environment variables

Command line parameters

This repository ships two executables, controller and webhook. The controller accepts the following command line flags:

Usage of ./go/bin/controller:
      --kubeconfig string                Path to a kubeconfig. Only required/allowed if running out-of-cluster
      --lease_namespace string           Lease namespace. Required if running out-of-cluster;
                                         otherwise defaults to controller's namespace
      --lease_name string                Lease name. Required
      --lease_id string                  Lease ID. Optional; if unspecified, a unique ID will be generated
      --add_dir_header                   If true, adds the file directory to the header of the log messages
      --alsologtostderr                  log to standard error as well as files
      --log_backtrace_at traceLocation   when logging hits line file:N, emit a stack trace (default :0)
      --log_dir string                   If non-empty, write log files in this directory
      --log_file string                  If non-empty, use this log file
      --log_file_max_size uint           Defines the maximum size a log file can grow to. Unit is megabytes. 
                                         If the value is 0, the maximum file size is unlimited. (default 1800)
      --logtostderr                      log to standard error instead of files (default true)
      --one_output                       If true, only write logs to their native severity level
                                         (vs also writing to each lower severity level)
      --skip_headers                     If true, avoid header prefixes in the log messages
      --skip_log_headers                 If true, avoid headers when opening log files
      --stderrthreshold severity         logs at or above this threshold go to stderr (default 2)
  -v, --v Level                          number for the log level verbosity
      --vmodule moduleSpec               comma-separated list of pattern=N settings for file-filtered logging

Environment variables

The controller executable honors the following environment variables:

  • $KUBECONFIG the path to the kubeconfig used by the operator executable; note that this has lower precedence than the command line flag -kubeconfig.

Logging

The controller uses klog v2 for logging. Please check the according documentation for details about how to configure logging.

2.2 - Webhook startup options

Command line configuration options, environment variables

Command line parameters

This repository ships two executables, controller and webhook. The webhook accepts the following command line flags:

Usage of ./go/bin/webhook:
      --bind_address string              Bind address (default ":1080")
      --tls_enabled                      Enable TlS
      --tls_key_file string              Path to TLS key
      --tls_cert_file string             Path to TLS certificate
      --add_dir_header                   If true, adds the file directory to the header of the log messages
      --alsologtostderr                  log to standard error as well as files
      --log_backtrace_at traceLocation   when logging hits line file:N, emit a stack trace (default :0)
      --log_dir string                   If non-empty, write log files in this directory
      --log_file string                  If non-empty, use this log file
      --log_file_max_size uint           Defines the maximum size a log file can grow to. Unit is megabytes.
                                         If the value is 0, the maximum file size is unlimited. (default 1800)
      --logtostderr                      log to standard error instead of files (default true)
      --one_output                       If true, only write logs to their native severity level
                                         (vs also writing to each lower severity level)
      --skip_headers                     If true, avoid header prefixes in the log messages
      --skip_log_headers                 If true, avoid headers when opening log files
      --stderrthreshold severity         logs at or above this threshold go to stderr (default 2)
  -v, --v Level                          number for the log level verbosity
      --vmodule moduleSpec               comma-separated list of pattern=N settings for file-filtered logging

Logging

The webhook uses klog v2 for logging. Please check the according documentation for details about how to configure logging.

3 - Usage

How to use ClusterSecrets

A typical ClusterSecret resource looks like this:

apiVersion: core.cs.sap.com/v1alpha1
kind: ClusterSecret
metadata:
  name: my-secret
spec:
  namespaceSelector:
    matchLabels:
      mylabel: myvalue
  template:
    type: Opaque
    data:
      mykey: bXl2YWx1ZQ==

The ClusterSecret spec consists of two parts:

  • spec.namespaceSeletor follows the usual syntax
  • spec.template mirrors the usual secret spec, at least partially, allowing to specify type (mandatory), and at least one of data or stringData; if stringData is provided, it will be rewritten to data by the mutating admission webhook.

The controller will then ensure that an according secret (having the same name as the ClusterSecret) exists in all selected namespaces; in addition to ClusterSecret resources, the controller watches namespaces, and immediately reacts to creation of namespaces, or label changes.