diff options
Diffstat (limited to 'test/s3/iam/README-Docker.md')
| -rw-r--r-- | test/s3/iam/README-Docker.md | 241 |
1 files changed, 241 insertions, 0 deletions
diff --git a/test/s3/iam/README-Docker.md b/test/s3/iam/README-Docker.md new file mode 100644 index 000000000..3759d7fae --- /dev/null +++ b/test/s3/iam/README-Docker.md @@ -0,0 +1,241 @@ +# SeaweedFS S3 IAM Integration with Docker Compose + +This directory contains a complete Docker Compose setup for testing SeaweedFS S3 IAM integration with Keycloak OIDC authentication. + +## ๐ Quick Start + +1. **Build local SeaweedFS image:** + ```bash + make -f Makefile.docker docker-build + ``` + +2. **Start the environment:** + ```bash + make -f Makefile.docker docker-up + ``` + +3. **Run the tests:** + ```bash + make -f Makefile.docker docker-test + ``` + +4. **Stop the environment:** + ```bash + make -f Makefile.docker docker-down + ``` + +## ๐ What's Included + +The Docker Compose setup includes: + +- **๐ Keycloak** - Identity provider with OIDC support +- **๐ฏ SeaweedFS Master** - Metadata management +- **๐พ SeaweedFS Volume** - Data storage +- **๐ SeaweedFS Filer** - File system interface +- **๐ SeaweedFS S3** - S3-compatible API with IAM integration +- **๐ง Keycloak Setup** - Automated realm and user configuration + +## ๐ Service URLs + +After starting with `docker-up`, services are available at: + +| Service | URL | Credentials | +|---------|-----|-------------| +| ๐ Keycloak Admin | http://localhost:8080 | admin/admin | +| ๐ S3 API | http://localhost:8333 | JWT tokens | +| ๐ Filer | http://localhost:8888 | - | +| ๐ฏ Master | http://localhost:9333 | - | + +## ๐ฅ Test Users + +The setup automatically creates test users in Keycloak: + +| Username | Password | Role | Permissions | +|----------|----------|------|-------------| +| admin-user | adminuser123 | s3-admin | Full S3 access | +| read-user | readuser123 | s3-read-only | Read-only access | +| write-user | writeuser123 | s3-read-write | Read and write | +| write-only-user | writeonlyuser123 | s3-write-only | Write only | + +## ๐งช Running Tests + +### All Tests +```bash +make -f Makefile.docker docker-test +``` + +### Specific Test Categories +```bash +# Authentication tests only +make -f Makefile.docker docker-test-auth + +# Role mapping tests only +make -f Makefile.docker docker-test-roles + +# S3 operations tests only +make -f Makefile.docker docker-test-s3ops +``` + +### Single Test +```bash +make -f Makefile.docker docker-test-single TEST_NAME=TestKeycloakAuthentication +``` + +## ๐ง Development Workflow + +### Complete workflow (recommended) +```bash +# Build, start, test, and clean up +make -f Makefile.docker docker-build +make -f Makefile.docker docker-dev +``` +This runs: build โ down โ up โ test + +### Using Published Images (Alternative) +If you want to use published Docker Hub images instead of building locally: +```bash +export SEAWEEDFS_IMAGE=chrislusf/seaweedfs:latest +make -f Makefile.docker docker-up +``` + +### Manual steps +```bash +# Build image (required first time, or after code changes) +make -f Makefile.docker docker-build + +# Start services +make -f Makefile.docker docker-up + +# Watch logs +make -f Makefile.docker docker-logs + +# Check status +make -f Makefile.docker docker-status + +# Run tests +make -f Makefile.docker docker-test + +# Stop services +make -f Makefile.docker docker-down +``` + +## ๐ Debugging + +### View logs +```bash +# All services +make -f Makefile.docker docker-logs + +# S3 service only (includes role mapping debug) +make -f Makefile.docker docker-logs-s3 + +# Keycloak only +make -f Makefile.docker docker-logs-keycloak +``` + +### Get shell access +```bash +# S3 container +make -f Makefile.docker docker-shell-s3 + +# Keycloak container +make -f Makefile.docker docker-shell-keycloak +``` + +## ๐ File Structure + +``` +seaweedfs/test/s3/iam/ +โโโ docker-compose.yml # Main Docker Compose configuration +โโโ Makefile.docker # Docker-specific Makefile +โโโ setup_keycloak_docker.sh # Keycloak setup for containers +โโโ README-Docker.md # This file +โโโ iam_config.json # IAM configuration (auto-generated) +โโโ test_config.json # S3 service configuration +โโโ *_test.go # Go integration tests +``` + +## ๐ Configuration + +### IAM Configuration +The `setup_keycloak_docker.sh` script automatically generates `iam_config.json` with: + +- **OIDC Provider**: Keycloak configuration with proper container networking +- **Role Mapping**: Maps Keycloak roles to SeaweedFS IAM roles +- **Policies**: Defines S3 permissions for each role +- **Trust Relationships**: Allows Keycloak users to assume SeaweedFS roles + +### Role Mapping Rules +```json +{ + "claim": "roles", + "value": "s3-admin", + "role": "arn:seaweed:iam::role/KeycloakAdminRole" +} +``` + +## ๐ Troubleshooting + +### Services not starting +```bash +# Check service status +make -f Makefile.docker docker-status + +# View logs for specific service +docker-compose -p seaweedfs-iam-test logs <service-name> +``` + +### Keycloak setup issues +```bash +# Re-run Keycloak setup manually +make -f Makefile.docker docker-keycloak-setup + +# Check Keycloak logs +make -f Makefile.docker docker-logs-keycloak +``` + +### Role mapping not working +```bash +# Check S3 logs for role mapping debug messages +make -f Makefile.docker docker-logs-s3 | grep -i "role\|claim\|mapping" +``` + +### Port conflicts +If ports are already in use, modify `docker-compose.yml`: +```yaml +ports: + - "8081:8080" # Change external port +``` + +## ๐งน Cleanup + +```bash +# Stop containers and remove volumes +make -f Makefile.docker docker-down + +# Complete cleanup (containers, volumes, images) +make -f Makefile.docker docker-clean +``` + +## ๐ฏ Key Features + +- **Local Code Testing**: Uses locally built SeaweedFS images to test current code +- **Isolated Environment**: No conflicts with local services +- **Consistent Networking**: Services communicate via Docker network +- **Automated Setup**: Keycloak realm and users created automatically +- **Debug Logging**: Verbose logging enabled for troubleshooting +- **Health Checks**: Proper service dependency management +- **Volume Persistence**: Data persists between restarts (until docker-down) + +## ๐ฆ CI/CD Integration + +For automated testing: + +```bash +# Build image, run tests with proper cleanup +make -f Makefile.docker docker-build +make -f Makefile.docker docker-up +make -f Makefile.docker docker-wait-healthy +make -f Makefile.docker docker-test +make -f Makefile.docker docker-down +``` |