SessionHandling

microgateway.airlock.com/v1alpha1

SessionHandling defines how the Airlock Microgateway Engine should handle and persist sessions.

apiVersion: microgateway.airlock.com/v1alpha1
kind: SessionHandling
metadata:
  name: session-handling-example
spec:
  mode: Enforce
  persistence:
    # Specify the Redis database where sessions should be stored
    redisProviderRef:
      name: redis-provider-example
  prefix: session_prefix_example

  agent:
    logging:
      # Change session agent log level
      level: debug

  defaultTimeouts:
    # Specify idle timeout of a session
    idle: 30s
    # Specify maximum lifetime of a session
    lifetime: 16h

  cookie:
    name: SESS
    # Specify the attributes set on the session cookie
    attributes:
      domain: example.org
      path: /
      sameSite: Strict
      secure: true

  limits:
    # Specify the limits for concurrent sessions per remote IP
    sessionsPerIP:
      thresholds:
        # Specify the threshold above which an event is logged
        logging: 1000
        # Specify the threshold above which requests are blocked
        blocking: 1500
      # Define conditions under which the limit does not apply
      exceptions:
        # exceptions on remote IP CIDR ranges
        - remoteIP:
            cidrRanges:
              - 192.168.0.0/16

SessionHandling

Field	Description	Type	Required	Default	Allowed Values
metadata	defines the resource’s metadata	ObjectMeta	yes
spec	defines the desired session handling configuration.	object	yes

SessionHandling.spec

Field	Description	Type	Required	Default	Allowed Values
agent	configures the Airlock Microgateway Session Agent container.	object	no
cookie	configures the session cookie used for cookie-based session tracking.	object	no
defaultTimeouts	configures timeouts to apply to new sessions.	object	no
limits	configures session-related limits.	object	no
mode	specifies the session handling mode. Meaning of the possible values: Enforce: All requests are aggregated into sessions. For requests without a session, a new session is created. For requests with an existing session, the session is reused and the idle time reset. OnDemand: Behaves like `Enforce` for routes which have access control with OIDC authentication configured. For all other routes, sessions will be neither created nor used.	enum	no	`OnDemand`	`Enforce`, `OnDemand`
persistence	configures where to store the session state.	object	yes
prefix	specifies the prefix under which the sessions should be stored in the persistence layer. If not specified, an automatic prefix derived from the namespaced SessionHandling CR name is used, which ensures that sessions will always be isolated on Microgateways configured with different SessionHandling CRs, even if they share the same persistence backend. To allow session sharing between different Microgateway deployments, ensure that the cookie domain, prefix and persistence backend is the same across all corresponding SessionHandling CRs.	string	no

SessionHandling.spec.agent

Field	Description	Type	Required	Default	Allowed Values
logging	configures the logging behavior.	object	no
resources	specifies the compute resources for the `airlock-microgateway-session-agent` container. If undefined, default resource settings are applied: `{"requests":{"cpu":"25m","memory":"64Mi"},"limits":{"memory":"128Mi"}}`. Setting this field overrides the defaults entirely, values are not merged. Note: This setting only affects `airlock-microgateway-session-agent` containers of Gateways managed via Gateway API.	ResourceRequirements	no

SessionHandling.spec.agent.logging

Field	Description	Type	Required	Default	Allowed Values
level	specifies the log level.	enum	no	`info`	`debug`, `error`, `info`, `trace`, `warn`

SessionHandling.spec.cookie

Field	Description	Type	Required	Default	Allowed Values
attributes	specifies additional attributes set on the session cookie.	object	no
name	specifies the name of the session cookie.	string	no	`AL_SESS`

SessionHandling.spec.cookie.attributes

Field	Description	Type	Required	Default	Allowed Values
domain	attribute to set. If not present, the attribute is omitted. A typical use case is to share the session cookie with sub-domains.	string	no
path	attribute to set. If not present, the attribute is omitted. Specifies a path prefix which the requested URL must match in order for the cookie to be sent.	string	no
sameSite	attribute to set. Specifies whether and when cookies are sent with cross-site requests.	enum	no	`Lax`	`Lax`, `None`, `Strict`
secure	attribute to set. A cookie with the Secure attribute is only sent to the server with an encrypted request over the HTTPS protocol.	bool	no	`true`	`true`, `false`

SessionHandling.spec.defaultTimeouts

Field	Description	Type	Required	Default	Allowed Values
idle	specifies the maximum duration a session can remain inactive before it is considered expired.	string (duration)	no	`10m`	See link
lifetime	specifies the maximum duration a session can exist.	string (duration)	no	`12h`	See link

SessionHandling.spec.limits

Field	Description	Type	Required	Default	Allowed Values
sessionsPerIP	configures the limit of concurrently active sessions per remote IP address.	object	no

SessionHandling.spec.limits.sessionsPerIP

Field	Description	Type	Required	Allowed Values
disabled	specifies that the limit is disabled.	object	no	`{}`
exceptions	define conditions under which the limit does not apply.	object[]	no
thresholds	specifies the logging and/or blocking thresholds for the number of concurrent sessions per remote IP. If not set, default thresholds apply. Defaults: Blocking: 8192 Logging: None	object	no

SessionHandling.spec.limits.sessionsPerIP.exceptions[]

Field	Description	Type	Required	Default	Allowed Values
remoteIP	restricts the exception to requests originating from matching remote IP CIDR ranges.	object	yes

SessionHandling.spec.limits.sessionsPerIP.exceptions[].remoteIP

Field	Description	Type	Required	Default	Allowed Values
cidrRanges	defines the IPv4 or IPv6 CIDR ranges, e.g. `196.148.3.128/26` or `2001:db8::/28`.	string[]	yes
invert	indicates whether the match should be inverted.	bool	no	`false`	`true`, `false`

SessionHandling.spec.limits.sessionsPerIP.thresholds

Field	Description	Type	Required	Default	Allowed Values
blocking	specifies the threshold above which requests are blocked.	int32	no		`[0, 2147483647]`
logging	specifies the threshold above which an event is logged.	int32	no		`[0, 2147483647]`

SessionHandling.spec.persistence

Field	Description	Type	Required	Default	Allowed Values
redisProviderRef	specifies to cache session information in the provided Redis instance.	object	yes

SessionHandling.spec.persistence.redisProviderRef

Field	Description	Type	Required	Default	Allowed Values
name	of the resource	string	yes