<!-- /*
* Copyright (c) 2025 Broadcom. All rights reserved.
* The term "Broadcom" refers to Broadcom Inc. and/or its subsidiaries.
* All trademarks, trade names, service marks, and logos referenced
* herein belong to their respective companies.
*
* This software and all information contained therein is confidential
* and proprietary and shall not be duplicated, used, disclosed or
* disseminated in any way except as authorized by the applicable
* license agreement, without the express written permission of Broadcom.
* All authorized reproductions must be marked with this language.
*
* EXCEPT AS SET FORTH IN THE APPLICABLE LICENSE AGREEMENT, TO THE
* EXTENT PERMITTED BY APPLICABLE LAW OR AS AGREED BY BROADCOM IN ITS
* APPLICABLE LICENSE AGREEMENT, BROADCOM PROVIDES THIS DOCUMENTATION
* "AS IS" WITHOUT WARRANTY OF ANY KIND, INCLUDING WITHOUT LIMITATION,
* ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
* PURPOSE, OR. NONINFRINGEMENT. IN NO EVENT WILL BROADCOM BE LIABLE TO
* THE END USER OR ANY THIRD PARTY FOR ANY LOSS OR DAMAGE, DIRECT OR
* INDIRECT, FROM THE USE OF THIS DOCUMENTATION, INCLUDING WITHOUT LIMITATION,
* LOST PROFITS, LOST INVESTMENT, BUSINESS INTERRUPTION, GOODWILL, OR
* LOST DATA, EVEN IF BROADCOM IS EXPRESSLY ADVISED IN ADVANCE OF THE
* POSSIBILITY OF SUCH LOSS OR DAMAGE.
*
* AI assistance has been used to generate some or all contents of this file. That includes, but is not limited to, new code, modifying existing code, stylistic edits.
 */ -->
# L7StateStore Custom Resource
This section contains more contextual information about the L7StateStore Custom Resource.

## API Docs
These API Docs are autogenerated using Layer7 Operator's CRDs using [crdoc](https://github.com/fybrik/crdoc)
* [L7StateStore](https://github.com/CAAPIM/layer7-operator/blob/main/docs/l7statestores.md)

## Index
This section is complimentary to the API Docs above providing a comprehensive view of configuration options.
* [Overview](#overview)
* [Redis Configuration](#redis-configuration)
  * [Standalone Mode](#standalone-mode)
  * [Sentinel Mode](#sentinel-mode)
* [Authentication](#authentication)
  * [Using Existing Secret](#using-existing-secret)
  * [Inline Credentials](#inline-credentials)
* [TLS Configuration](#tls-configuration)
* [Advanced Configuration](#advanced-configuration)

## Overview
The L7StateStore Custom Resource enables the Layer7 Operator to connect to external state stores for sharing configuration and data across Gateway deployments and Repository controllers. Currently, only Redis is supported as a state store type.

L7StateStore is used for:
- Storing and retrieving Repository bundles (particularly for dynamic repositories > 1MB)
- Sharing configuration across multiple Gateway clusters
- Enabling repository reference delete functionality with state tracking
- Supporting bootstrap of dynamic repository references

### Note
- This is an **alpha** API (`security.brcmlabs.com/v1alpha1`)
- Currently only Redis (standalone and sentinel modes) is supported
- The L7StateStore must be created before it can be referenced by Repositories or Gateways

[Back to Index](#index)

# Redis Configuration

## Standalone Mode
Standalone mode connects to a single Redis instance.

Config - Read more [here](https://github.com/CAAPIM/layer7-operator/blob/main/docs/l7statestores.md#l7statestorespecredisstandalone)

### Basic Standalone Configuration
```
apiVersion: security.brcmlabs.com/v1alpha1
kind: L7StateStore
metadata:
  name: redis-statestore
spec:
  type: redis
  redis:
    type: standalone
    standalone:
      host: redis.default.svc.cluster.local
      port: 6379
    database: 0
    username: default
    masterPassword: myredispassword
```

### Standalone with TLS
```
apiVersion: security.brcmlabs.com/v1alpha1
kind: L7StateStore
metadata:
  name: redis-statestore-tls
spec:
  type: redis
  redis:
    type: standalone
    standalone:
      host: redis.default.svc.cluster.local
      port: 6380
    database: 0
    username: default
    masterPassword: myredispassword
    tls:
      enabled: true
      verifyPeer: true
      redisCrt: |+
        -----BEGIN CERTIFICATE-----
        MIIEPzCCAyegAwIBAgIQeU+e4GXMcNWtPvtYtGsxejANBgkqhkiG9w0BAQsFADAT
        ...certificate content...
        -----END CERTIFICATE-----
```

### Note
- `host`: Redis server hostname or IP address
- `port`: Redis server port (default: 6379, or 6380 for TLS)
- `database`: Redis database number (default: 0)
- `username`: Redis username (default: "default")
- `masterPassword`: Redis password for authentication

[Back to Index](#index)

## Sentinel Mode
Sentinel mode provides high availability by connecting to a Redis Sentinel cluster.

Config - Read more [here](https://github.com/CAAPIM/layer7-operator/blob/main/docs/l7statestores.md#l7statestorespecredissentinel)

### Basic Sentinel Configuration
```
apiVersion: security.brcmlabs.com/v1alpha1
kind: L7StateStore
metadata:
  name: redis-sentinel-statestore
spec:
  type: redis
  redis:
    type: sentinel
    sentinel:
      master: mymaster
      nodes:
      - host: sentinel-node-1.default.svc.cluster.local
        port: 26379
      - host: sentinel-node-2.default.svc.cluster.local
        port: 26379
      - host: sentinel-node-3.default.svc.cluster.local
        port: 26379
    database: 0
    username: default
    masterPassword: myredispassword
```

### Sentinel with TLS
```
apiVersion: security.brcmlabs.com/v1alpha1
kind: L7StateStore
metadata:
  name: redis-sentinel-statestore-tls
spec:
  type: redis
  redis:
    type: sentinel
    sentinel:
      master: mymaster
      nodes:
      - host: sentinel-node-1.default.svc.cluster.local
        port: 26379
      - host: sentinel-node-2.default.svc.cluster.local
        port: 26379
      - host: sentinel-node-3.default.svc.cluster.local
        port: 26379
    database: 0
    username: default
    masterPassword: myredispassword
    tls:
      enabled: true
      verifyPeer: true
      redisCrt: |+
        -----BEGIN CERTIFICATE-----
        MIIEPzCCAyegAwIBAgIQeU+e4GXMcNWtPvtYtGsxejANBgkqhkiG9w0BAQsFADAT
        ...certificate content...
        -----END CERTIFICATE-----
```

### Note
- `master`: Name of the Redis master set in Sentinel configuration
- `nodes`: List of Sentinel node endpoints
  - At least 3 Sentinel nodes are recommended
  - Each node requires `host` and `port`
- Sentinel mode provides automatic failover and high availability

[Back to Index](#index)

# Authentication
Redis authentication can be configured using inline credentials or by referencing an existing Kubernetes Secret.

Config - Read more [here](https://github.com/CAAPIM/layer7-operator/blob/main/docs/l7statestores.md#l7statestorespecredis)

## Using Existing Secret
The recommended approach is to store Redis credentials in a Kubernetes Secret.

### Creating the Secret
```bash
kubectl create secret generic redis-credentials \
  --from-literal=username=default \
  --from-literal=password=myredispassword
```

### L7StateStore Configuration
```
apiVersion: security.brcmlabs.com/v1alpha1
kind: L7StateStore
metadata:
  name: redis-statestore
spec:
  type: redis
  redis:
    type: standalone
    standalone:
      host: redis.default.svc.cluster.local
      port: 6379
    database: 0
    existingSecret: redis-credentials
```

### Note
- The referenced secret should contain: `masterPassword`
- `username` is optional
- Using `existingSecret` takes precedence over inline credentials
- This is the recommended approach

[Back to Index](#index)

## Inline Credentials
Credentials can be provided directly in the L7StateStore resource (not recommended for production).

```
apiVersion: security.brcmlabs.com/v1alpha1
kind: L7StateStore
metadata:
  name: redis-statestore
spec:
  type: redis
  redis:
    type: standalone
    standalone:
      host: redis.default.svc.cluster.local
      port: 6379
    database: 0
    username: default
    masterPassword: myredispassword
```

### Note
- Inline credentials are stored in plain text in the Custom Resource
- Use `existingSecret` instead
- `masterPassword` is used for both standalone and sentinel modes

[Back to Index](#index)

# TLS Configuration
Configure TLS/SSL encryption for Redis connections.

Config - Read more [here](https://github.com/CAAPIM/layer7-operator/blob/main/docs/l7statestores.md#l7statestorespecredistls)

## Basic TLS Configuration
```
apiVersion: security.brcmlabs.com/v1alpha1
kind: L7StateStore
metadata:
  name: redis-statestore-tls
spec:
  type: redis
  redis:
    type: standalone
    standalone:
      host: redis.default.svc.cluster.local
      port: 6380
    database: 0
    existingSecret: redis-credentials
    tls:
      enabled: true
      verifyPeer: true
      redisCrt: |+
        -----BEGIN CERTIFICATE-----
        MIIEPzCCAyegAwIBAgIQeU+e4GXMcNWtPvtYtGsxejANBgkqhkiG9w0BAQsFADAT
        MREwDwYDVQQDEwhyZWRpcy1jYTAeFw0yMzEyMDgxNzA0MjRaFw0yNDEyMDcxNzA0
        MjRaMBkxFzAVBgNVBAMTDnNlbnRpbmVsLXJlZGlzMIIBIjANBgkqhkiG9w0BAQEF
        AAOCAQ8AMIIBCgKCAQEAsWKC5hOfxscAxaqnkz/u4zCImNNhxrBn6mJUIsDQk+0r
        ...certificate content...
        -----END CERTIFICATE-----
```

## TLS without Peer Verification
For development or testing with self-signed certificates:

```
apiVersion: security.brcmlabs.com/v1alpha1
kind: L7StateStore
metadata:
  name: redis-statestore-tls-noverify
spec:
  type: redis
  redis:
    type: standalone
    standalone:
      host: redis.default.svc.cluster.local
      port: 6380
    database: 0
    existingSecret: redis-credentials
    tls:
      enabled: true
      verifyPeer: false
```

### Note
- `enabled`: Set to `true` to enable TLS
- `verifyPeer`: When `true`, verifies the Redis server certificate
  - Set to `false` for self-signed certificates (not recommended)
- `redisCrt`: The Redis server's CA certificate or certificate chain
  - Required when `verifyPeer` is `true`
  - Should be in PEM format

[Back to Index](#index)

# Advanced Configuration
Additional configuration options for specialized use cases.

Config - Read more [here](https://github.com/CAAPIM/layer7-operator/blob/main/docs/l7statestores.md#l7statestorespecredis)

## StoreId and GroupName
```
apiVersion: security.brcmlabs.com/v1alpha1
kind: L7StateStore
metadata:
  name: redis-statestore-advanced
spec:
  type: redis
  redis:
    type: standalone
    standalone:
      host: redis.default.svc.cluster.local
      port: 6379
    database: 0
    existingSecret: redis-credentials
    storeId: my-store-id
    groupName: my-group
```

### Note
- `storeId`: identifier for this state store instance (used to build key)
- `groupName`: group name for organizing multiple state stores (used to build key)
- `database`: Redis database number (0-15 typically, depending on Redis configuration)

## Complete Configuration Example
Here's a complete example with all common options:

```
apiVersion: security.brcmlabs.com/v1alpha1
kind: L7StateStore
metadata:
  name: example-state-store
spec:
  type: redis
  redis:
    type: sentinel
    sentinel:
      master: mymaster
      nodes:
      - host: sentinel-node-1.default.svc.cluster.local
        port: 26379
      - host: sentinel-node-2.default.svc.cluster.local
        port: 26379
      - host: sentinel-node-3.default.svc.cluster.local
        port: 26379
    database: 0
    existingSecret: redis-credentials
    storeId: my-store
    groupName: my-group
    tls:
      enabled: true
      verifyPeer: true
      redisCrt: |+
        -----BEGIN CERTIFICATE-----
        ...certificate content...
        -----END CERTIFICATE-----
```

[Back to Index](#index)

## Using L7StateStore with Repositories
Once an L7StateStore is configured, it can be referenced in Repository Custom Resources:

```
apiVersion: security.brcmlabs.com/v1
kind: Repository
metadata:
  name: my-statestore-repository
spec:
  type: statestore
  enabled: true
  stateStoreReference: redis-statestore
  stateStoreKey: my-repository-bundle
```

See the [Repository Custom Resource](./Repository-Custom-Resource#statestore-repository) documentation for more details.

[Back to Index](#index)

## Troubleshooting

### Connection Issues
- Verify Redis server is accessible from the Kubernetes cluster
- Check that the correct port is specified (6379 for standard, 6380 for TLS)
- Ensure credentials are correct in the referenced secret

### TLS Issues
- Verify the Redis certificate is in PEM format
- Check that the certificate is valid and not expired
- For self-signed certificates, consider setting `verifyPeer: false` for testing

### Sentinel Issues
- Ensure all Sentinel nodes are accessible
- Verify the master name matches your Sentinel configuration
- Check that at least 3 Sentinel nodes are configured

### Status Check
Check the status of your L7StateStore:
```bash
kubectl get l7statestore redis-statestore -o yaml
```

Look for the `status.ready` field to confirm the state store is ready for use.

[Back to Index](#index)