{"id":36492990,"url":"https://github.com/bedag/storagegrid-sdk-go","last_synced_at":"2026-01-12T01:57:46.193Z","repository":{"id":322997593,"uuid":"1058687358","full_name":"bedag/storagegrid-sdk-go","owner":"bedag","description":null,"archived":false,"fork":false,"pushed_at":"2025-12-22T14:28:34.000Z","size":78,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-22T15:52:00.331Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bedag.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-17T12:19:55.000Z","updated_at":"2025-12-20T16:55:30.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/bedag/storagegrid-sdk-go","commit_stats":null,"previous_names":["bedag/storagegrid-sdk-go"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/bedag/storagegrid-sdk-go","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bedag%2Fstoragegrid-sdk-go","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bedag%2Fstoragegrid-sdk-go/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bedag%2Fstoragegrid-sdk-go/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bedag%2Fstoragegrid-sdk-go/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bedag","download_url":"https://codeload.github.com/bedag/storagegrid-sdk-go/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bedag%2Fstoragegrid-sdk-go/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28331417,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-12T00:36:25.062Z","status":"ssl_error","status_checked_at":"2026-01-12T00:36:15.229Z","response_time":60,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-12T01:57:46.064Z","updated_at":"2026-01-12T01:57:46.183Z","avatar_url":"https://github.com/bedag.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# StorageGRID SDK for Go\n\n[![Go Reference](https://pkg.go.dev/badge/github.com/bedag/storagegrid-sdk-go.svg)](https://pkg.go.dev/github.com/bedag/storagegrid-sdk-go)\n[![Go Report Card](https://goreportcard.com/badge/github.com/bedag/storagegrid-sdk-go)](https://goreportcard.com/report/github.com/bedag/storagegrid-sdk-go)\n\n\u003e **⚠️ Community-Maintained SDK**\n\u003e \n\u003e This SDK was created by the community due to the lack of an official NetApp StorageGRID SDK for Go. It is designed to fulfill the needs of its maintainers and contributors. If you find something missing or spot a bug, please open an [issue](https://github.com/bedag/storagegrid-sdk-go/issues) or submit a [pull request](https://github.com/bedag/storagegrid-sdk-go/pulls)! Contributions are highly encouraged.\n\n\u003e [!NOTE]  \n\u003e This SDK was originally developed by an employee and it's history can be seen in the [original repository](https://github.com/bedag/storagegrid-sdk-go). The original repository is no longer actively maintained, and this copy serves as the new home for ongoing development and contributions from the community.\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Features](#features)\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [Usage](#usage)\n  - [Grid Management](#grid-management)\n  - [Tenant Management](#tenant-management)\n- [Examples](#examples)\n- [API Coverage](#api-coverage)\n- [Testing](#testing)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Overview\n\n`storagegrid-sdk-go` is an unofficial Go SDK for interacting with NetApp StorageGRID. It provides programmatic access to StorageGRID's REST APIs, enabling you to manage tenants, buckets, users, S3 access keys, health, regions, gateway configs, and more.\n\nNetApp StorageGRID exposes two distinct REST API surfaces:\n- **Grid Management API**: For grid administrators to manage the entire StorageGRID system\n- **Tenant Management API**: For tenant users to manage their specific tenant resources\n\nThis SDK reflects this architecture with corresponding client types. For more details on StorageGRID APIs, see the [official documentation](https://docs.netapp.com/us-en/storagegrid-115/s3/storagegrid-s3-rest-api-operations.html).\n\n## Features\n\n### Grid Management\n- **Tenants**: Create, list, update, delete, and monitor tenant usage\n- **Health**: Monitor grid health status (alarms, alerts, node connectivity)\n- **Regions**: List available regions for grid and tenant contexts\n- **HA Groups**: Manage High Availability groups\n- **Gateway Configs**: Configure load balancer endpoints\n\n### Tenant Management\n- **Buckets**: Create, list, delete, drain buckets; monitor bucket usage and compliance settings\n- **Users**: Manage tenant users with password management\n- **Groups**: Manage tenant groups with policies and permissions\n- **S3 Access Keys**: Generate and manage S3 access keys for users\n- **Regions**: List tenant-specific regions\n\n### Additional Features\n- **Auto-authentication**: Automatic token management with expiration handling\n- **Context support**: All operations support Go context for cancellation and timeouts\n- **Interface-based design**: Easy mocking and testing with provided mock implementations\n- **SSL configuration**: Optional SSL verification skip for development environments\n\n## Requirements\n- Go 1.25 or newer (see `go.mod` for the exact version)\n- Access to a NetApp StorageGRID instance with appropriate credentials\n\n## Installation\n\n```sh\ngo get github.com/bedag/storagegrid-sdk-go\n```\n\n## Quick Start\n\n```go\npackage main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"log\"\n\n\t\"github.com/bedag/storagegrid-sdk-go/client\"\n\t\"github.com/bedag/storagegrid-sdk-go/models\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\n\t// Create a grid client for system administration\n\tgridClient, err := client.NewGridClient(\n\t\tclient.WithEndpoint(\"https://your-storagegrid-endpoint\"),\n\t\tclient.WithCredentials(\u0026models.Credentials{\n\t\t\tUsername: \"admin\",\n\t\t\tPassword: \"your-password\",\n\t\t}),\n\t)\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n\n\t// Check grid health\n\thealth, err := gridClient.Health().Get(ctx)\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n\n\tfmt.Printf(\"Grid Status: %s\\n\", func() string {\n\t\tif health.AllGreen() {\n\t\t\treturn \"✅ Healthy\"\n\t\t}\n\t\treturn \"⚠️  Issues detected\"\n\t}())\n}\n```\n\n## Usage\n\n### Client Configuration\n\nBoth client types support the same configuration options:\n\n```go\nimport (\n\t\"github.com/bedag/storagegrid-sdk-go/client\"\n\t\"github.com/bedag/storagegrid-sdk-go/models\"\n)\n\n// Common configuration options\nopts := []client.ClientOption{\n\tclient.WithEndpoint(\"https://your-storagegrid.example.com\"),\n\tclient.WithCredentials(\u0026models.Credentials{\n\t\tUsername: \"your-username\",\n\t\tPassword: \"your-password\",\n\t\t// AccountId: \u0026accountID, // Required for tenant operations only\n\t}),\n\t// client.WithSkipSSL(), // Skip SSL verification (development only)\n}\n```\n\n### Grid Management\n\nUse `GridClient` for system-wide administration operations. This requires grid administrator privileges.\n\n\u003cdetails\u003e\n\u003csummary\u003e🔧 \u003cstrong\u003eSetup Grid Client\u003c/strong\u003e\u003c/summary\u003e\n\n```go\ngridClient, err := client.NewGridClient(\n\tclient.WithEndpoint(\"https://your-storagegrid.example.com\"),\n\tclient.WithCredentials(\u0026models.Credentials{\n\t\tUsername: \"grid-admin\",\n\t\tPassword: \"admin-password\",\n\t\t// No AccountId needed for grid operations\n\t}),\n)\nif err != nil {\n\treturn fmt.Errorf(\"failed to create grid client: %w\", err)\n}\n```\n\u003c/details\u003e\n\n#### Managing Tenants\n\n```go\n// List all tenant accounts\ntenants, err := gridClient.Tenant().List(ctx)\nif err != nil {\n\treturn fmt.Errorf(\"failed to list tenants: %w\", err)\n}\n\n// Create a new tenant\ntenant := \u0026models.Tenant{\n\tName:         \"my-tenant\",\n\tDescription:  \"Some description\",\n\tCapabilities: []string{\"management\", \"s3\"},\n\tPolicy: \u0026models.TenantPolicy{\n\t\tUseAccountIdentitySource: false,\n\t\tAllowPlatformServices:    true,\n\t\tQuotaObjectBytes:         100 * 1024 * 1024 * 1024, // 100GB\n\t},\n}\n\ncreatedTenant, err := gridClient.Tenant().Create(ctx, tenant)\nif err != nil {\n\treturn fmt.Errorf(\"failed to create tenant: %w\", err)\n}\n\nfmt.Printf(\"Created tenant: %s (ID: %s)\\n\", *createdTenant.Name, createdTenant.Id)\n```\n\n#### Monitoring Grid Health\n\n```go\nhealth, err := gridClient.Health().Get(ctx)\nif err != nil {\n\treturn fmt.Errorf(\"failed to get health status: %w\", err)\n}\n\n// Check overall status\nif health.AllGreen() {\n\tlog.Println(\"✅ Grid is healthy\")\n} else {\n\tlog.Printf(\"⚠️  Grid has issues - Connected nodes: %d, Alerts: %d\", \n\t\t*health.Nodes.Connected, \n\t\t*health.Alerts.Critical + *health.Alerts.Major)\n}\n```\n\n### Tenant Management\n\nUse `TenantClient` for tenant-specific operations. This requires tenant user credentials and an account ID.\n\n\u003cdetails\u003e\n\u003csummary\u003e🔧 \u003cstrong\u003eSetup Tenant Client\u003c/strong\u003e\u003c/summary\u003e\n\n```go\naccountID := \"12345678901234567890\"\ntenantClient, err := client.NewTenantClient(\n\tclient.WithEndpoint(\"https://your-storagegrid.example.com\"),\n\tclient.WithCredentials(\u0026models.Credentials{\n\t\tUsername:  \"tenant-admin\",\n\t\tPassword:  \"tenant-password\",\n\t\tAccountId: \u0026accountID, // Required for tenant operations\n\t}),\n)\nif err != nil {\n\treturn fmt.Errorf(\"failed to create tenant client: %w\", err)\n}\n```\n\u003c/details\u003e\n\n#### Managing Buckets\n\n```go\n// Create a bucket with versioning enabled\nbucket := \u0026models.Bucket{\n\tName:             \"my-application-data\",\n\tRegion:           \"us-east-1\",\n\tEnableVersioning: true,\n\tS3ObjectLock: \u0026models.BucketS3ObjectLockSettings{\n\t\tEnabled: false,\n\t},\n}\n\ncreatedBucket, err := tenantClient.Bucket().Create(ctx, bucket)\nif err != nil {\n\treturn fmt.Errorf(\"failed to create bucket: %w\", err)\n}\n\n// List all buckets in the tenant\nbuckets, err := tenantClient.Bucket().List(ctx)\nif err != nil {\n\treturn fmt.Errorf(\"failed to list buckets: %w\", err)\n}\n\nfor _, bucket := range *buckets {\n\tfmt.Printf(\"Bucket: %s (Created: %s)\\n\", bucket.Name, bucket.CreationTime.Format(\"2006-01-02\"))\n}\n```\n\n#### Managing Users and Access Keys\n\n```go\n// Create a new user\nuser := \u0026models.User{\n\tUniqueName:  \"application-user\", // Will be prefixed with \"user/\"\n\tDisplayName: \"Application Service User\",\n\tDisable:     false,\n}\n\ncreatedUser, err := tenantClient.Users().Create(ctx, user)\nif err != nil {\n\treturn fmt.Errorf(\"failed to create user: %w\", err)\n}\n\n// Generate S3 access keys for the user\naccessKey := \u0026models.S3AccessKey{\n\tExpires: nil, // No expiration\n}\n\nkeys, err := tenantClient.S3AccessKeys().CreateForUser(ctx, *createdUser.Id, accessKey)\nif err != nil {\n\treturn fmt.Errorf(\"failed to create access keys: %w\", err)\n}\n\nfmt.Printf(\"Access Key: %s\\n\", *keys.AccessKey)\nfmt.Printf(\"Secret Key: %s\\n\", *keys.SecretAccessKey)\n```\n\n## Examples\n\n## Examples\n\nComprehensive examples are available in the [`examples/`](examples/) directory:\n\n- **[Grid Management](examples/grid/)**: Health monitoring, tenant management\n- **[Tenant Operations](examples/tenant/)**: Bucket operations, user management\n- **[Testing](examples/testing/)**: Unit tests with mocks, integration tests\n\n### Quick Examples\n\n#### Health Check\n```go\nhealth, err := gridClient.Health().Get(ctx)\nif err != nil {\n    log.Fatalf(\"Health check failed: %v\", err)\n}\nfmt.Printf(\"Grid Status: All Green = %v\\n\", health.AllGreen())\n```\n\n#### Create Tenant\n```go\ntenant := \u0026models.Tenant{\n    Name:         \"my-tenant\",\n    Capabilities: []string{\"s3\", \"management\"},\n}\ncreatedTenant, err := gridClient.Tenant().Create(ctx, tenant)\n```\n\n#### Create Bucket\n```go\nbucket := \u0026models.Bucket{\n    Name:   \"my-bucket\",\n    Region: \"us-east-1\",\n}\ncreatedBucket, err := tenantClient.Bucket().Create(ctx, bucket)\n```\n\nFor complete working examples, see the [`examples/`](examples/) directory.\n\n## API Coverage\n\n## Testing\n\n### Unit Testing with Mocks\n\nThe SDK provides comprehensive mock implementations for all service interfaces, making unit testing straightforward:\n\n```go\npackage main\n\nimport (\n\t\"context\"\n\t\"testing\"\n\n\t\"github.com/bedag/storagegrid-sdk-go/models\"\n\t\"github.com/bedag/storagegrid-sdk-go/testing\"\n)\n\nfunc TestTenantOperations(t *testing.T) {\n\tctx := context.Background()\n\n\t// Create mock tenant service\n\tmockService := \u0026testing.MockTenantService{\n\t\tListFunc: func(ctx context.Context) (*[]models.Tenant, error) {\n\t\t\treturn \u0026[]models.Tenant{\n\t\t\t\t{\n\t\t\t\t\tId:   \"tenant-123\",\n\t\t\t\t\tName: \"Test Tenant\",\n\t\t\t\t},\n\t\t\t}, nil\n\t\t},\n\t\tCreateFunc: func(ctx context.Context, tenant *models.Tenant) (*models.Tenant, error) {\n\t\t\ttenant.Id = \"new-tenant-456\"\n\t\t\treturn tenant, nil\n\t\t},\n\t}\n\n\t// Use mock in your application code\n\ttenants, err := mockService.List(ctx)\n\tif err != nil {\n\t\tt.Fatalf(\"Expected no error, got %v\", err)\n\t}\n\n\tif len(*tenants) != 1 {\n\t\tt.Fatalf(\"Expected 1 tenant, got %d\", len(*tenants))\n\t}\n\n\tif (*tenants)[0].Id != \"tenant-123\" {\n\t\tt.Fatalf(\"Expected tenant ID 'tenant-123', got %s\", (*tenants)[0].Id)\n\t}\n}\n```\n\n### Integration Testing\n\nFor integration tests against a real StorageGRID instance:\n\n```go\nfunc TestIntegration(t *testing.T) {\n\tif testing.Short() {\n\t\tt.Skip(\"Skipping integration test in short mode\")\n\t}\n\n\tendpoint := os.Getenv(\"STORAGEGRID_ENDPOINT\")\n\tusername := os.Getenv(\"STORAGEGRID_USERNAME\")\n\tpassword := os.Getenv(\"STORAGEGRID_PASSWORD\")\n\n\tif endpoint == \"\" || username == \"\" || password == \"\" {\n\t\tt.Skip(\"Missing required environment variables for integration test\")\n\t}\n\n\tctx := context.Background()\n\t\n\tclient, err := client.NewGridClient(\n\t\tclient.WithEndpoint(endpoint),\n\t\tclient.WithCredentials(\u0026models.Credentials{\n\t\t\tUsername: username,\n\t\t\tPassword: password,\n\t\t}),\n\t)\n\tif err != nil {\n\t\tt.Fatalf(\"Failed to create client: %v\", err)\n\t}\n\n\t// Test actual API calls\n\thealth, err := client.Health().Get(ctx)\n\tif err != nil {\n\t\tt.Fatalf(\"Failed to get health: %v\", err)\n\t}\n\n\tt.Logf(\"Grid health status: operative=%v\", health.Operative(1))\n}\n```\n\n### Available Mocks\n\nThe `testing` package provides mocks for all service interfaces:\n\n- `MockTenantService` - Grid tenant management\n- `MockBucketService` - Bucket operations  \n- `MockTenantUserService` - Tenant user management\n- `MockTenantGroupService` - Tenant group management\n- `MockS3AccessKeyService` - S3 access key management\n- `MockHealthService` - Health monitoring\n- `MockHAGroupService` - HA group management\n- `MockGatewayConfigService` - Gateway configuration\n- `MockRegionService` - Region management\n\n## API Coverage\n\nThis SDK provides access to StorageGRID's dual API architecture:\n\n### Grid Management APIs (GridClient)\nUsed for system-wide administration with grid administrator credentials:\n\n| Service | Endpoint | Operations | Description |\n|---------|----------|------------|-------------|\n| **Tenants** | `/grid/accounts` | Create, Read, Update, Delete, List | Manage tenant accounts |\n| **Health** | `/grid/health` | Read | Monitor grid health, alarms, alerts, node status |\n| **Regions** | `/grid/regions` | List | Manage grid-wide regions |\n| **HA Groups** | `/private/ha-groups` | Create, Read, Update, Delete, List | Configure High Availability groups |\n| **Gateways** | `/private/gateway-configs` | Create, Read, Update, Delete, List | Manage load balancer endpoints |\n\n### Tenant Management APIs (TenantClient)\nUsed for tenant-specific operations with tenant user credentials:\n\n| Service | Endpoint | Operations | Description |\n|---------|----------|------------|-------------|\n| **Buckets** | `/org/containers` | Create, Read, Delete, List, Drain | Manage S3 buckets within tenant |\n| **Users** | `/org/users` | Create, Read, Update, Delete, List | Manage tenant users |\n| **Groups** | `/org/groups` | Create, Read, Update, Delete, List | Manage tenant groups and permissions |\n| **S3 Keys** | `/org/users/*/s3-access-keys` | Create, Read, Delete, List | Generate and manage S3 access credentials |\n| **Regions** | `/org/regions` | List | List tenant-accessible regions |\n| **Usage** | `/org/usage` | Read | Monitor tenant usage statistics |\n\n\u003e 📚 **Official Documentation**: For comprehensive API documentation, refer to the [NetApp StorageGRID REST API Reference](https://docs.netapp.com/us-en/storagegrid-115/s3/storagegrid-s3-rest-api-operations.html).\n\n## Project Structure\n\n```\nstoragegrid-sdk-go/\n├── client/             # Client implementations\n│   ├── client.go       # Base HTTP client with authentication\n│   ├── grid.go         # Grid administrator client\n│   └── tenant.go       # Tenant client\n├── models/             # Data models for API requests/responses\n│   ├── auth.go         # Authentication models\n│   ├── buckets.go      # Bucket-related models\n│   ├── tenants.go      # Tenant models\n│   ├── users.go        # User models\n│   ├── health.go       # Health status models\n│   └── ...             # Other model files\n├── services/           # Service interfaces and implementations\n│   ├── interface.go    # Base HTTP client interface\n│   ├── tenant.go       # Tenant management service\n│   ├── buckets.go      # Bucket management service\n│   ├── health.go       # Health monitoring service\n│   └── ...             # Other service files\n└── testing/            # Mock implementations for testing\n    ├── tenant_mock.go  # Mock tenant service\n    ├── bucket_mock.go  # Mock bucket service\n    └── ...             # Other mock files\n```\n\n## Contributing\n\nWe welcome contributions! Here's how you can help:\n\n1. **Report Issues**: Found a bug or missing feature? [Open an issue](https://github.com/bedag/storagegrid-sdk-go/issues)\n2. **Submit Pull Requests**: Have a fix or new feature? [Submit a PR](https://github.com/bedag/storagegrid-sdk-go/pulls)\n3. **Improve Documentation**: Help make this README and code comments better\n4. **Add Tests**: Increase test coverage for reliability\n\n### Development Guidelines\n\n- Follow Go conventions and best practices\n- Add appropriate error handling and logging\n- Include tests for new functionality\n- Update documentation for new features\n- Maintain interface compatibility when possible\n\n## License\n\nThis project is licensed under the Apache 2.0 License. See the [LICENSE](LICENSE) file for details.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbedag%2Fstoragegrid-sdk-go","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbedag%2Fstoragegrid-sdk-go","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbedag%2Fstoragegrid-sdk-go/lists"}