Storj COSI Driver

A Container Object Storage Interface (COSI) driver for Storj decentralized cloud storage. It allows Kubernetes workloads to provision Storj buckets and obtain S3-compatible credentials through the standard COSI API.

Status: ALPHA

How it works

The driver uses the Storj satellite REST API to manage API keys and the uplink library for bucket operations:

• Create/delete buckets: Creates a temporary API key via the REST API, performs the bucket operation using uplink, then deletes the temporary key.
• Grant access: Creates an API key via REST API, derives a restricted access grant scoped to the bucket, registers it with the auth service to obtain S3-compatible credentials.
• Revoke access: Deletes the API key via the REST API, immediately invalidating the associated S3 credentials.

Prerequisites

1. A Storj account with a REST API key and project ID (create at https://www.storj.io/).
2. The COSI controller and CRDs installed in the cluster:

kubectl apply -k 'github.com/kubernetes-sigs/container-object-storage-interface//?ref=v0.2.2'

Installation

1. Create the credentials Secret

kubectl create namespace storj-cosi-system

kubectl create secret generic storj-cosi-credentials \
  --namespace storj-cosi-system \
  --from-literal=api-key="<YOUR_STORJ_REST_API_KEY>" \
  --from-literal=project-id="<YOUR_STORJ_PROJECT_ID>" \
  --from-literal=satellite-address="<NODE_ID>@<SATELLITE_HOST>:7777" \
  --from-literal=satellite-url="https://us1.storj.io"

Or apply the manifest directly (replace the placeholders):

apiVersion: v1
kind: Secret
metadata:
  name: storj-cosi-credentials
  namespace: storj-cosi-system
type: Opaque
stringData:
  api-key: "<YOUR_STORJ_REST_API_KEY>"
  project-id: "<YOUR_STORJ_PROJECT_ID>"
  satellite-address: "<NODE_ID>@<SATELLITE_HOST>:7777"
  satellite-url: "https://us1.storj.io"

2. Deploy the driver

kubectl apply -k deploy/kustomize

This creates a Deployment with two containers:

• storj-cosi-driver — the Storj COSI driver
• objectstorage-sidecar — the COSI controller sidecar

They communicate over a shared Unix socket at /var/lib/cosi/cosi.sock.

Environment variables used by the binary

Variable	Default	Description
STORJ_API_KEY	(required)	Storj REST API key for satellite console API
STORJ_PROJECT_ID	(required)	Storj project UUID
STORJ_SATELLITE_ADDRESS	(required)	Satellite address (e.g. <nodeID>@us1.storj.io:7777)
STORJ_SATELLITE_URL	https://us1.storj.io	Satellite console REST API base URL
STORJ_AUTH_SERVICE	auth.storjshare.io:7777	Auth service address for S3 credential registration
STORJ_S3_ENDPOINT	https://gateway.storjshare.io	Fallback S3 endpoint if auth service doesn't return one
COSI_ENDPOINT	unix:///var/lib/cosi/cosi.sock	gRPC socket path for COSI communication

Usage

The COSI workflow has three steps: define classes, claim a bucket, then request access credentials.

1. Create a BucketClass

apiVersion: objectstorage.k8s.io/v1alpha1
kind: BucketClass
metadata:
  name: storj-bucket-class
driverName: cosi.storj.io
deletionPolicy: Delete

2. Create a BucketAccessClass

apiVersion: objectstorage.k8s.io/v1alpha1
kind: BucketAccessClass
metadata:
  name: storj-bucket-access-class
driverName: cosi.storj.io
authenticationType: Key

Parameters

The BucketAccessClass supports the following optional parameters:

Parameter	Example	Description
expiry	"30d", "24h", "2h30m"	How long the access grant remains valid. Accepts days (30d), or any Go duration (24h, 2h30m). If omitted, the access grant does not expire.

Example with expiry:

apiVersion: objectstorage.k8s.io/v1alpha1
kind: BucketAccessClass
metadata:
  name: storj-bucket-access-class-30d
driverName: cosi.storj.io
authenticationType: Key
parameters:
  expiry: "30d"

3. Create a BucketClaim

This triggers bucket creation on Storj:

apiVersion: objectstorage.k8s.io/v1alpha1
kind: BucketClaim
metadata:
  name: my-bucket
spec:
  bucketClassName: storj-bucket-class
  protocols:
    - S3

4. Create a BucketAccess

This triggers access grant creation and registration, producing S3 credentials stored in a Kubernetes Secret:

apiVersion: objectstorage.k8s.io/v1alpha1
kind: BucketAccess
metadata:
  name: my-bucket-access
spec:
  bucketAccessClassName: storj-bucket-access-class
  protocol: S3
  bucketClaimName: my-bucket
  credentialsSecretName: my-bucket-credentials

5. Use the credentials

Once the BucketAccess status shows accessGranted: true, a Secret named my-bucket-credentials is created containing S3 credentials:

• endpoint — S3-compatible gateway URL
• region — region identifier (e.g. us-1)
• accessKeyID — S3 access key
• accessSecretKey — S3 secret key

Mount this Secret into your application pod to access the bucket via any S3 client.

Testing

Unit tests

go test ./...

Integration test

The integration test exercises the full lifecycle (create bucket, create access key, upload/download via S3, cleanup) against a real Storj satellite.

STORJ_TEST_REST_KEY="your-rest-api-key" \
STORJ_TEST_PROJECT_ID="your-project-id" \
STORJ_TEST_SATELLITE_ADDRESS="nodeID@satellite.host:7777" \
STORJ_TEST_AUTH_SERVICE="auth.storjshare.io:7777" \
  go test ./pkg/driver/ -run TestRestClient -v

Environment variable	Default	Description
STORJ_TEST_REST_KEY	(required)	Storj REST API key
STORJ_TEST_PROJECT_ID	(required)	Storj project UUID
STORJ_TEST_SATELLITE_ADDRESS	(required)	Satellite address
STORJ_TEST_SATELLITE_URL	(derived from address)	Satellite console URL
STORJ_TEST_AUTH_SERVICE	auth.storjshare.io:7777	Auth service address
STORJ_TEST_S3_ENDPOINT	https://gateway.storjshare.io	S3 gateway endpoint

End-to-end test

The e2e tests use Robot Framework and run against a local kind cluster.

Prerequisites: kind, kubectl, kustomize, docker, jq, aws CLI, python3 (with PyYAML), and robot (pip install robotframework).

STORJ_TEST_REST_KEY="your-rest-api-key" \
STORJ_TEST_PROJECT_ID="your-project-id" \
STORJ_TEST_SATELLITE_ADDRESS="nodeID@satellite.host:7777" \
STORJ_TEST_AUTH_SERVICE="auth.storjshare.io:7777" \
  robot test/e2e/cosi.robot

# Keep the kind cluster alive after tests for manual inspection.
SKIP_CLEANUP=1 \
STORJ_TEST_REST_KEY="your-rest-api-key" \
STORJ_TEST_PROJECT_ID="your-project-id" \
STORJ_TEST_SATELLITE_ADDRESS="nodeID@satellite.host:7777" \
  robot test/e2e/cosi.robot

Environment variable	Default	Description
STORJ_TEST_REST_KEY	(required)	Storj REST API key
STORJ_TEST_PROJECT_ID	(required)	Storj project UUID
STORJ_TEST_SATELLITE_ADDRESS	(required)	Satellite address
STORJ_TEST_SATELLITE_URL	(derived from address)	Satellite console URL
STORJ_TEST_AUTH_SERVICE	auth.storjshare.io:7777	Auth service address
STORJ_TEST_S3_ENDPOINT	https://gateway.storjshare.io	S3 gateway endpoint
SKIP_CLEANUP	0	Set to 1 to keep the kind cluster after the test

References

• COSI Introduction
• COSI GitHub Repository
• Storj Documentation