Controller Options
You can customize the Capsule Proxy with the following configurations. See User scope for identity eligibility, administrator exclusions, RoleBinding reflection, and grants for non-Capsule users.
Controller Options
You can provide additional options via the helm chart:
options:
extraArgs:
- --disable-caching=true
Options are also available as dedicated configuration values:
# Controller Options
options:
# -- Set the listening port of the capsule-proxy
listeningPort: 9001
# -- Set leader election to true if you are running n-replicas
leaderElection: false
# -- Set the log verbosity of the capsule-proxy with a value from 1 to 10
logLevel: 4
# -- Name of the CapsuleConfiguration custom resource used by Capsule, required to identify the user groups
capsuleConfigurationName: default
# -- Require Capsule identities for proxy grants. Set false to allow authenticated non-Capsule callers to use matching GlobalProxySettings; Capsule is optional. Requires ProxyClusterScoped for global grants.
requireCapsuleUser: true
# -- Define which groups must be ignored while proxying requests
ignoredUserGroups: []
# -- Define which usernames must be ignored while proxying requests
ignoredUsernames: []
# -- Names of the groups which are not used for impersonation (considered after impersonation-group-regexp)
ignoredImpersonationGroups: []
# -- Regular expression to match the groups which are considered for impersonation
impersonationGroupRegexp: ""
# -- Specify if capsule-proxy will use SSL
oidcUsernameClaim: preferred_username
# -- Specify if capsule-proxy will use SSL
enableSSL: true
# -- Set the directory, where SSL certificate and keyfile will be located
SSLDirectory: /opt/capsule-proxy
# -- Set the name of SSL certificate file
SSLCertFileName: tls.crt
# -- Set the name of SSL key file
SSLKeyFileName: tls.key
# -- Specify if capsule-proxy will generate self-signed SSL certificates
generateCertificates: false
# -- Specify additional subject alternative names for the self-signed SSL
additionalSANs: []
# -- Specify an override for the Secret containing the certificate for SSL. Default value is empty and referring to the generated certificate.
certificateVolumeName: ""
# -- Set the role bindings reflector resync period, a local cache to store mappings between users and their namespaces. [Use a lower value in case of flaky etcd server connections.](https://github.com/projectcapsule/capsule-proxy/issues/174)
rolebindingsResyncPeriod: 10h
# -- Disable the go-client caching to hit directly the Kubernetes API Server, it disables any local caching as the rolebinding reflector.
disableCaching: false
# -- Enable RoleBinding reflection. Namespaced resource LIST grants require the reflection.proxy.projectcapsule.dev/enabled label.
roleBindingReflector: false
# -- Authentication types to be used for requests. Possible Auth Types: [BearerToken, TLSCertificate, XForwardedClientCert]
authPreferredTypes: "BearerToken,TLSCertificate"
# -- QPS to use for interacting with Kubernetes API Server.
clientConnectionQPS: 20
# -- Burst to use for interacting with kubernetes API Server.
clientConnectionBurst: 30
# -- Enable Pprof for profiling
pprof: false
# -- CIDR ranges of trusted proxies allowed to make requests to the proxy
trustedProxyCidrs: []
The following options are available for the Capsule Proxy Controller:
--allowed-paths strings URL paths which are not inspected by capsule-proxy (still require valid authentication) (default [/api,/apis,/version])
--auth-preferred-types string Authentication types to be used for requests. Possible Auth Types: [BearerToken, TLSCertificate, XForwardedClientCert]
First match is used and can be specified multiple times as comma separated values or by using the flag multiple times. (default "[TLSCertificate,BearerToken]")
--capsule-configuration-name string Name of the CapsuleConfiguration used to retrieve the Capsule user groups names (default "default")
--client-connection-burst int32 Burst to use for interacting with kubernetes apiserver. (default 30)
--client-connection-qps float32 QPS to use for interacting with kubernetes apiserver. (default 20)
--disable-caching Disable the go-client caching to hit directly the Kubernetes API Server, it disables any local caching as the rolebinding reflector (default: false)
--enable-leader-election Enable leader election for controller manager. Enabling this will ensure there is only one active controller manager.
--enable-pprof Enables Pprof endpoint for profiling (not recommend in production)
--enable-reflector Enable reflection for RoleBindings labelled reflection.proxy.projectcapsule.dev/enabled=true
--enable-ssl Enable the bind on HTTPS for secure communication (default: true) (default true)
--feature-gates mapStringBool A set of key=value pairs that describe feature gates for alpha/experimental features. Options are:
AllAlpha=true|false (ALPHA - default=false)
AllBeta=true|false (BETA - default=false)
ProxyAllNamespaced=true|false (ALPHA - default=false)
ProxyClusterScoped=true|false (ALPHA - default=false)
SkipImpersonationReview=true|false (ALPHA - default=false)
--ignored-impersonation-group strings Names of the groups which are not used for impersonation (considered after impersonation-group-regexp)
--ignored-user-group strings Names of the groups which requests must be ignored and proxy-passed to the upstream server
--ignored-username strings Usernames whose requests must be ignored and proxy-passed to the upstream server
--impersonation-group-regexp string Regular expression to match the groups which are considered for impersonation
--listening-port uint HTTP port the proxy listens to (default: 9001) (default 9001)
--metrics-addr string The address the metric endpoint binds to. (default ":8080")
--oidc-username-claim string The OIDC field name used to identify the user (default: preferred_username) (default "preferred_username")
--require-capsule-user Require Capsule identity membership for proxy grants; when false, authenticated non-Capsule callers may use matching GlobalProxySettings and Capsule is optional (default true)
--rolebindings-resync-period duration Resync period for rolebindings reflector (default 10h0m0s)
--ssl-cert-path string Path to the TLS certificate (default: /opt/capsule-proxy/tls.crt)
--ssl-key-path string Path to the TLS certificate key (default: /opt/capsule-proxy/tls.key)
--trusted-proxy-cidrs strings CIDR ranges of trusted proxies allowed to make requests to the proxy
--webhook-port int The port the webhook server binds to. (default 9443)
--xfcc-header-name string Name of the header inspected for forwarded client certificates (default "X-Forwarded-Client-Cert")
--zap-devel Development Mode defaults(encoder=consoleEncoder,logLevel=Debug,stackTraceLevel=Warn). Production Mode defaults(encoder=jsonEncoder,logLevel=Info,stackTraceLevel=Error)
--zap-encoder encoder Zap log encoding (one of 'json' or 'console')
--zap-log-level level Zap Level to configure the verbosity of logging. Can be one of 'debug', 'info', 'error', 'panic'or any integer value > 0 which corresponds to custom debug levels of increasing verbosity
--zap-stacktrace-level level Zap Level at and above which stacktraces are captured (one of 'info', 'error', 'panic').
--zap-time-encoding time-encoding Zap time encoding (one of 'epoch', 'millis', 'nano', 'iso8601', 'rfc3339' or 'rfc3339nano'). Defaults to 'epoch'.
User scope and reflection
By default, options.requireCapsuleUser: true (--require-capsule-user=true)
requires callers to be recognized Capsule identities before receiving proxy
grants. Configure eligible users and groups in the CapsuleConfiguration selected
by options.capsuleConfigurationName (--capsule-configuration-name). See
User scope for the
CapsuleConfiguration example, including system:authenticated and administrator
exclusions.
For Capsule users, the following Helm values enable RoleBinding reflection and exclude your administrators from proxy filtering:
options:
capsuleConfigurationName: default
requireCapsuleUser: true
ignoredUserGroups:
- platform-admins
ignoredUsernames:
- platform-admin
disableCaching: false
roleBindingReflector: true
Replace the example administrator group and username with your actual identities.
The corresponding exclusion flags are --ignored-user-group and
--ignored-username. Ignored identities retain their native Kubernetes RBAC
permissions; these settings do not grant administrator access.
options.roleBindingReflector: true sets --enable-reflector=true.
Reflection requires Capsule integration and caching, so keep
options.disableCaching: false (--disable-caching=false). For namespaced
resource LIST grants, also set
reflection.proxy.projectcapsule.dev/enabled: "true" on the Tenant’s
spec.additionalRoleBindings[].labels. See
RoleBinding reflection
for the Tenant example and access boundaries.
Global grants for non-Capsule users
To allow authenticated callers to receive matching GlobalProxySettings grants
without becoming Capsule users, use these Helm values:
options:
requireCapsuleUser: false
extraArgs:
- --feature-gates=ProxyClusterScoped=true
These values set --require-capsule-user=false and
--feature-gates=ProxyClusterScoped=true. A global rule must still match the
caller, resource, operation, and selected objects. This does not grant tenant
delegation or reflected access to non-Capsule callers. Capsule is optional in
this mode; see
Global grants for non-Capsule users
for startup behavior and supported operations.
Feature Gates
Feature Gates are a set of key/value pairs that can be used to enable or disable certain features of the Capsule Proxy. The following feature gates are available:
| Feature Gate | Default Value | Description |
|---|---|---|
SkipImpersonationReview | false | SkipImpersonationReview allows to skip the impersonation review for all requests containing impersonation headers (user and groups). DANGER: Enabling this flag allows any user to impersonate as any user or group essentially bypassing any authorization. Only use this option in trusted environments where authorization/authentication is offloaded to external systems. |
ProxyClusterScoped | false | ProxyClusterScoped allows to proxy all clusterScoped objects for all tenant users. These can be defined via ProxySettings |