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 syntaxspec.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.