Skip to content

IAM_SUPPORT.md

Latest commit

 

History

History
286 lines (233 loc) · 8.33 KB

IAM_SUPPORT.md

File metadata and controls

286 lines (233 loc) · 8.33 KB

IAM Service Support in SeaweedFS Operator

This document describes the IAM (Identity and Access Management) service support in the SeaweedFS Operator.

Overview

Starting from SeaweedFS version 4.03, the IAM API is now embedded in the S3 server by default. This follows the pattern used by MinIO and Ceph RGW, providing a simpler deployment model where both S3 and IAM APIs are available on the same port (8333).

Configuration

Enabling S3 with Embedded IAM (Default)

When you enable S3, IAM is automatically enabled on the same port:

apiVersion: seaweed.seaweedfs.com/v1
kind: Seaweed
metadata:
  name: seaweed-sample
spec:
  image: chrislusf/seaweedfs:latest

  master:
    replicas: 1
  volume:
    replicas: 1
  filer:
    replicas: 1
    s3:
      enabled: true
    # iam: true  # Default - IAM is enabled when S3 is enabled

The IAM API is accessible on the same port as S3 (8333).

Disabling Embedded IAM

To run S3 without IAM:

filer:
  replicas: 1
  s3:
    enabled: true
  iam: false  # Explicitly disable embedded IAM

API Reference

FilerSpec.IAM

// IAM enables/disables IAM API embedded in S3 server.
// When S3 is enabled, IAM is enabled by default (on the same S3 port: 8333).
// Set to false to explicitly disable embedded IAM.
// +kubebuilder:default:=true
IAM bool `json:"iam,omitempty"`

Service Discovery

The IAM API is accessible through the filer S3 service:

  • Internal: <seaweed-name>-filer.<namespace>.svc.cluster.local:8333
  • Port: 8333 (same as S3)

Examples

Complete examples are available in the config/samples/ directory:

  • seaweed_v1_seaweed_with_iam_embedded.yaml: Embedded IAM configuration

Quick Start

Deploy SeaweedFS with S3 and embedded IAM:

kubectl apply -f config/samples/seaweed_v1_seaweed_with_iam_embedded.yaml

Verify deployment:

# Check all resources
kubectl get seaweed,statefulset,service,pod

# Test S3/IAM endpoint (both on same port)
kubectl port-forward svc/seaweed-sample-filer 8333:8333

# S3 operations
aws --endpoint-url http://localhost:8333 s3 ls

# IAM operations (same endpoint)
aws --endpoint-url http://localhost:8333 iam list-users

Architecture

┌─────────────────────────────────────────────┐
│                Filer Pod                     │
│  ┌────────────────────────────────────────┐ │
│  │           weed filer -s3               │ │
│  │  ┌──────────────────────────────────┐  │ │
│  │  │  S3 API Server (port 8333)       │  │ │
│  │  │  ├── S3 Operations (GET/PUT/...)  │  │ │
│  │  │  └── IAM Operations (POST /)      │  │ │
│  │  └──────────────────────────────────┘  │ │
│  └────────────────────────────────────────┘ │
└─────────────────────────────────────────────┘

Benefits

  1. Simple deployment: Single service, single port
  2. Reduced resource usage: No separate IAM pods
  3. Industry standard: Matches MinIO and Ceph RGW patterns
  4. Automatic scaling: IAM scales with S3/filer instances

Migration from Standalone IAM

If you were previously using standalone IAM, simply:

  1. Remove the iam: section from your Seaweed CRD
  2. Ensure filer.s3.enabled: true
  3. Update clients to use the S3 port (8333) for IAM operations

OIDC Configuration

The IAM service supports OIDC (OpenID Connect) authentication. Configuration is provided via ConfigMap or Secret.

Creating IAM Configuration

Create a ConfigMap with your IAM configuration:

apiVersion: v1
kind: ConfigMap
metadata:
  name: seaweed-iam-config
data:
  iam.json: |
    {
      "sts": {
        "tokenDuration": "1h",
        "maxSessionLength": "12h",
        "issuer": "seaweedfs-sts",
        "signingKey": "your-base64-encoded-signing-key"
      },
      "providers": [
        {
          "name": "keycloak",
          "type": "oidc",
          "enabled": true,
          "config": {
            "issuer": "https://keycloak.example.com/realms/seaweedfs",
            "clientId": "seaweedfs-s3",
            "clientSecret": "optional-secret",
            "jwksUri": "https://keycloak.example.com/realms/seaweedfs/protocol/openid-connect/certs",
            "tlsCaCert": "/etc/seaweedfs/certs/ca.pem",
            "tlsInsecureSkipVerify": false,
            "roleMapping": {
              "rules": [
                { "claim": "groups", "value": "admins", "role": "arn:aws:iam::role/S3AdminRole" }
              ],
              "defaultRole": "arn:aws:iam::role/S3ReadOnlyRole"
            }
          }
        }
      ],
      "policies": [...],
      "roles": [...]
    }

TLS Configuration Options

Field Description
tlsCaCert Path to CA certificate file for custom/self-signed certificates
tlsInsecureSkipVerify Skip TLS verification (development only, never use in production)

Note

The clientSecret field is optional and only required for confidential OIDC clients. Public clients (like single-page applications) can omit this field.

Complete Configuration Example

Here's a complete example showing how to configure OIDC with custom CA certificates for embedded IAM (running within the filer):

# Step 1: Create ConfigMap with IAM configuration
apiVersion: v1
kind: ConfigMap
metadata:
  name: seaweed-iam-config
  namespace: default
data:
  iam.json: |
    {
      "sts": {
        "tokenDuration": "1h",
        "maxSessionLength": "12h",
        "issuer": "seaweedfs-sts",
        "signingKey": "your-base64-encoded-signing-key"
      },
      "providers": [
        {
          "name": "keycloak",
          "type": "oidc",
          "enabled": true,
          "config": {
            "issuer": "https://keycloak.example.com/realms/seaweedfs",
            "clientId": "seaweedfs-s3",
            "clientSecret": "optional-only-for-confidential-clients",
            "jwksUri": "https://keycloak.example.com/realms/seaweedfs/protocol/openid-connect/certs",
            "tlsCaCert": "/etc/seaweedfs/certs/ca.pem",
            "tlsInsecureSkipVerify": false,
            "roleMapping": {
              "rules": [
                { "claim": "groups", "value": "admins", "role": "arn:aws:iam::role/S3AdminRole" }
              ],
              "defaultRole": "arn:aws:iam::role/S3ReadOnlyRole"
            }
          }
        }
      ],
      "policies": [...],
      "roles": [...]
    }
---
# Step 2: Create Secret with CA certificate (if using custom CA)
apiVersion: v1
kind: Secret
metadata:
  name: oidc-ca-cert
  namespace: default
type: Opaque
data:
  ca.pem: <base64-encoded-ca-cert>
---
# Step 3: Configure Seaweed CRD with embedded IAM
apiVersion: seaweed.seaweedfs.com/v1
kind: Seaweed
metadata:
  name: seaweed-sample
  namespace: default
spec:
  image: chrislusf/seaweedfs:latest
  
  master:
    replicas: 1
  
  volume:
    replicas: 1
  
  # Filer with embedded IAM and OIDC configuration
  filer:
    replicas: 1
    s3:
      enabled: true
    # Mount both IAM config and CA certificate
    volumeMounts:
      - name: iam-config
        mountPath: /etc/seaweedfs/iam
      - name: oidc-ca
        mountPath: /etc/seaweedfs/certs
    volumes:
      - name: iam-config
        configMap:
          name: seaweed-iam-config
      - name: oidc-ca
        secret:
          secretName: oidc-ca-cert
    # Configure S3 to use IAM config
    s3Args:
      - "-iam.config=/etc/seaweedfs/iam/iam.json"

Tip

If you don't need custom CA certificates, you can omit the oidc-ca-cert Secret and the corresponding volume mount. Simply remove tlsCaCert from the OIDC provider configuration.

For more details on OIDC configuration, see the SeaweedFS OIDC Integration Wiki.

Further Reading