gocosi

README

gocosi

A Container Object Storage Interface (COSI) library and other helpful utilities created with Go, that simplify process of writing your own Object Storage Plugin (OSP).

Table of contents

• gocosi
  • Table of contents
  • Quick Start
    • Bootstrap parameters
  • Features
    • Automatic Starting of Traces
    • Automatic Panic Recovery
    • Control Over Permissions by Default
    • Configuration via Environment
    • Supports Any Logger Through logr
  • Configuration
    • Environment variables
  • Contributing
  • Prior Art

Quick Start

The following example illustrates using gocosi Object Storage Plugin bootstrapper to create a new COSI Object Storage Plugin from scratch:

go run \
  github.com/doomshrine/gocosi/cmd/bootstrap@main \
  -module example.com/your/cosi-osp \
  -dir cosi-osp

You will obtain the following file structure in the cosi-osp folder:

cosi-osp
├── .dockerignore
├── .gitignore
├── Dockerfile
├── README.md
├── go.mod
├── go.sum
├── main.go
└── servers
    ├── identity
    │   └── identity.go
    └── provisioner
        └── provisioner.go

4 directories, 9 files

Bootstrap parameters

Flag	Default	Description
-module	example.com/cosi-osp	Override name for your new module.
-dir	cosi-osp	Location/Path, where the module will be created.

Features

Automatic Starting of Traces

The gocosi package includes an automatic trace initialization feature using the otelgrpc.UnaryServerInterceptor() function. This functionality enables the automatic creation of traces for each incoming request. Alongside the tracing capability, this interceptor adds detailed events to the traces, enhancing the visibility into the request lifecycle.

Automatic Panic Recovery

In the event of a panic occurring during the execution of your COSI driver, the package offers seamless recovery through the use of recovery.UnaryServerInterceptor. This interceptor employs a custom panic handler that captures the panic message and the associated debug stack trace. Every panic is logged for thorough error analysis. Additionally, the package provides a default OpenTelemetry (OTEL) Counter metric that tracks the occurrence of panics, aiding in monitoring and troubleshooting.

Control Over Permissions by Default

The gocosi package introduces a built-in mechanism designed to grant users control over the permissions and access rights associated with the UNIX socket. This inherent feature empowers you to define specific user and group ownership for the socket, along with customizable permission settings. This level of control ensures that the socket's security and accessibility align with your application's requirements.

Configuration via Environment

Streamlining the configuration process, the gocosi package exclusively employs environment variables for end-user configuration. This design choice simplifies setup and customization, as users can conveniently adjust various aspects of the COSI driver's behavior by modifying environment variables.

Supports Any Logger Through logr

To cater to diverse logging preferences, the gocosi package seamlessly integrates with a wide range of loggers by leveraging the versatile logr library. This compatibility enables you to use your preferred logger implementation, ensuring consistency with your existing logging practices and enhancing your debugging and monitoring capabilities.

Configuration

Environment variables

gocosi defines several constants used to specify environment variables for configuring the COSI (Container Object Storage Interface) endpoint. The COSI endpoint is used to interact with an object storage plugin in a containerized environment.

• COSI_ENDPOINT (default: unix:///var/lib/cosi/cosi.sock) - it should be set to the address or location of the COSI endpoint, such as the URL or file path.
• X_COSI_ENDPOINT_PERMS (default: 0755) - it should be set when the COSI endpoint is a UNIX socket file. It determines the file permissions (in octal notation) of the UNIX socket file. If the COSI endpoint is a TCP socket, this setting has no effect.
• X_COSI_ENDPOINT_USER (default: The user that starts the process) - it should be set when the COSI endpoint is a UNIX socket file. It determines the owner (user) of the UNIX socket file. If the COSI endpoint is a TCP socket, this setting has no effect.
• X_COSI_ENDPOINT_GROUP (default: The group that starts the process) - it should be set when the COSI endpoint is a UNIX socket file. It determines the group ownership of the UNIX socket file. If the COSI endpoint is a TCP socket, this setting has no effect.
• Endpoint OTLP/HTTP (default: https://localhost:4317 or https://localhost:4318) - target URL to which the exporter is going to send spans or metrics. The endpoint MUST be a valid URL with scheme (http or https) and host, MAY contain a port, SHOULD contain a path and MUST NOT contain other parts (such as query string or fragment). [spec]
  • OTEL_EXPORTER_OTLP_ENDPOINT
  • OTEL_EXPORTER_OTLP_TRACES_ENDPOINT
  • OTEL_EXPORTER_OTLP_METRICS_ENDPOINT
• Certificate File - the trusted certificate to use when verifying a server's TLS credentials. Should only be used for a secure connection. [spec]
  • OTEL_EXPORTER_OTLP_CERTIFICATE
  • OTEL_EXPORTER_OTLP_TRACES_CERTIFICATE
  • OTEL_EXPORTER_OTLP_METRICS_CERTIFICATE
• Headers - key-value pairs to be used as headers associated with gRPC or HTTP requests. [spec]
  • OTEL_EXPORTER_OTLP_HEADERS
  • OTEL_EXPORTER_OTLP_TRACES_HEADERS
  • OTEL_EXPORTER_OTLP_METRICS_HEADERS
• Compression - compression key for supported compression types. Supported compression: gzip. [spec]
  • OTEL_EXPORTER_OTLP_COMPRESSION
  • OTEL_EXPORTER_OTLP_TRACES_COMPRESSION
  • OTEL_EXPORTER_OTLP_METRICS_COMPRESSION
• Timeout (default: 10s) - maximum time the OTLP exporter will wait for each batch export. [spec]
  • OTEL_EXPORTER_OTLP_TIMEOUT
  • OTEL_EXPORTER_OTLP_TRACES_TIMEOUT
  • OTEL_EXPORTER_OTLP_METRICS_TIMEOUT

Contributing

You want to contibute? Hop into the CONTRIBUTING.md and find how you can help the project!

Prior Art

This project was inspired by rexray/gocsi and dell/gocsi.

Documentation

Overview

Package gocosi is a Container Object Storage Interface (COSI) library that simplifies process of writing your own Object Storage Plugin (OSP).

## Quick Start

The following example illustrates using `gocosi` Object Storage Plugin bootstrapper to create a new COSI Object Storage Plugin from scratch:

go run \
  github.com/doomshrine/gocosi/cmd/bootstrap@main \
  -module example.com/your/cosi-osp \
  -dir cosi-osp

You will obtain the following file structure in the `cosi-osp` folder:

cosi-osp
├── go.mod
├── go.sum
├── main.go
└── servers
├── identity
│   └── identity.go
└── provisioner
    └── provisioner.go

4 directories, 5 files

Index

• Constants
• Variables
• func HealthcheckFunc(ctx context.Context, addr string) error
• func SetLogger(l logr.Logger)
• type COSIIdentityServer
• type COSIProvisionerServer
• type Driver
  • func New(identity cosi.IdentityServer, provisioner cosi.ProvisionerServer, ...) (*Driver, error)
  • func (d *Driver) Run(ctx context.Context) error
• type Endpoint
  • func (e *Endpoint) Close() error
  • func (e *Endpoint) Listener(ctx context.Context) (net.Listener, error)
• type ErrHealthCheckFailure
  • func (err *ErrHealthCheckFailure) Error() string
• type ExporterKind
• type Option
  • func WithCOSIEndpoint(url *url.URL) Option
  • func WithDefaultGRPCOptions() Option
  • func WithDefaultMetricExporter(kind ExporterKind) Option
  • func WithDefaultTraceExporter(kind ExporterKind) Option
  • func WithGRPCMetricExporter(opt ...otlpmetricgrpc.Option) Option
  • func WithGRPCOptions(opts ...grpc.ServerOption) Option
  • func WithGRPCTraceExporter(opt ...otlptracegrpc.Option) Option
  • func WithHTTPMetricExporter(opt ...otlpmetrichttp.Option) Option
  • func WithHTTPTraceExporter(opt ...otlptracehttp.Option) Option
  • func WithHealthcheck(options ...health.Option) Option
  • func WithSocketGroup(group *user.Group) Option
  • func WithSocketPermissions(perm os.FileMode) Option
  • func WithSocketUser(user *user.User) Option

Constants

const (
	SchemeUNIX = "unix"
	SchemeTCP  = "tcp"
)

Schemes supported by COSI.

const (
	// CosiEndpoint is the name of the environment variable used to
	// specify the COSI endpoint.
	EnvCOSIEndpoint = "COSI_ENDPOINT"

	// EnvVarEndpointPerms is the name of the environment variable used
	// to specify the file permissions for the COSI endpoint when it is
	// a UNIX socket file. This setting has no effect if COSI_ENDPOINT
	// specifies a TCP socket. The default value is 0755.
	EnvCOSIEndpointPerms = "X_COSI_ENDPOINT_PERMS"

	// EnvVarEndpointUser is the name of the environment variable used
	// to specify the UID or name of the user that owns the endpoint's
	// UNIX socket file. This setting has no effect if COSI_ENDPOINT
	// specifies a TCP socket. The default value is the user that starts
	// the process.
	EnvCOSIEndpointUser = "X_COSI_ENDPOINT_USER"

	// EnvVarEndpointGroup is the name of the environment variable used
	// to specify the GID or name of the group that owns the endpoint's
	// UNIX socket file. This setting has no effect if COSI_ENDPOINT
	// specifies a TCP socket. The default value is the group that starts
	// the process.
	EnvCOSIEndpointGroup = "X_COSI_ENDPOINT_GROUP"
)

const (
	// HealthcheckEndpoint is the HTTP endpoint path for the healthcheck service.
	HealthcheckEndpoint = "/healthz"

	// HealthcheckAddr.
	HealthcheckAddr = "http://localhost:8080" + HealthcheckEndpoint
)

Variables

var (
	ErrNilMux                   = errors.New("nil mux")
	ErrHealthcheckStatusUnknown = errors.New("healthcheck status unknown")
)

var (
	DefaultMeter = otel.Meter("github.com/doomshrine/gocosi")

	PanicsTotal = must.Do(DefaultMeter.Int64Counter("grpc_req_panics_recovered_total"))
)

Functions

func HealthcheckFunc

func HealthcheckFunc(ctx context.Context, addr string) error

HealthcheckFunc.

func SetLogger

func SetLogger(l logr.Logger)

SetLogger is used to set the default global logger for the gocosi library.

Types

type COSIIdentityServer

type COSIIdentityServer interface {
	cosi.IdentityServer
}

COSIIdentityServer is a wrapper around cosi.IdentityServer so the mock can be generated.

type COSIProvisionerServer

type COSIProvisionerServer interface {
	cosi.ProvisionerServer
}

COSIProvisionerServer is a wrapper around cosi.ProvisionerServer so the mock can be generated.

type Driver

type Driver struct {
	// contains filtered or unexported fields
}

Driver represents a COSI driver implementation.

func New

func New(identity cosi.IdentityServer, provisioner cosi.ProvisionerServer, res *resource.Resource, opts ...Option) (*Driver, error)

New creates a new instance of the COSI driver.

func (*Driver) Run

func (d *Driver) Run(ctx context.Context) error

Run starts the COSI driver and serves requests.

type Endpoint

type Endpoint struct {
	// contains filtered or unexported fields
}

Endpoint represents COSI Endpoint.

func (*Endpoint) Close

func (e *Endpoint) Close() error

Close ensures that the UNIX socket is removed after the application is closed.

func (*Endpoint) Listener

func (e *Endpoint) Listener(ctx context.Context) (net.Listener, error)

Listener will return listener (and error) after first configuring it. Listener is configured only once, on the first call, and the error is captured. Every subsequent call will return the same values.

type ErrHealthCheckFailure

type ErrHealthCheckFailure struct {
	// contains filtered or unexported fields
}

func (*ErrHealthCheckFailure) Error

func (err *ErrHealthCheckFailure) Error() string

type ExporterKind

type ExporterKind int

ExporterKind is an enumeration representing different exporter types.

const (
	// HTTPExporter represents an HTTP telemetry exporter.
	HTTPExporter ExporterKind = iota

	// GRPCExporter represents a gRPC telemetry exporter.
	GRPCExporter ExporterKind = iota
)

type Option

type Option func(*Driver) error

Option represents a functional option to configure the Driver.

func WithCOSIEndpoint

func WithCOSIEndpoint(url *url.URL) Option

WithCOSIEndpoint overrides the default COSI endpoint.

func WithDefaultGRPCOptions

func WithDefaultGRPCOptions() Option

WithGRPCOptions overrides all previously applied gRPC ServerOptions by a default options.

Default gRPC SeverOptions are: - ChainUnaryInterceptor - consists of:

• grpc.UnaryServerInterceptor() - starts and configures tracer for each request, records events for request and response (error is recorded as normal event);
• logging.UnaryServerInterceptor() - records and logs according to the global logger (wrapped around grpc/log.Logger);
• recovery.UnaryServerInterceptor() - records metric for panics, and recovers (a log is created for each panic);

func WithDefaultMetricExporter

func WithDefaultMetricExporter(kind ExporterKind) Option

WithDefaultMetricExporter returns an Option function to set the default metric exporter based on the provided kind.

func WithDefaultTraceExporter

func WithDefaultTraceExporter(kind ExporterKind) Option

WithDefaultTraceExporter returns an Option function to set the default trace exporter based on the provided kind.

func WithGRPCMetricExporter

func WithGRPCMetricExporter(opt ...otlpmetricgrpc.Option) Option

WithGRPCMetricExporter returns an Option function to configure a gRPC metric exporter.

func WithGRPCOptions

func WithGRPCOptions(opts ...grpc.ServerOption) Option

WithGRPCOptions overrides all previously applied gRPC ServerOptions by a set provided as argument to this call.

func WithGRPCTraceExporter

func WithGRPCTraceExporter(opt ...otlptracegrpc.Option) Option

WithGRPCTraceExporter returns an Option function to configure a gRPC trace exporter.

func WithHTTPMetricExporter

func WithHTTPMetricExporter(opt ...otlpmetrichttp.Option) Option

WithHTTPMetricExporter returns an Option function to configure an HTTP metric exporter.

func WithHTTPTraceExporter

func WithHTTPTraceExporter(opt ...otlptracehttp.Option) Option

WithHTTPTraceExporter returns an Option function to configure an HTTP trace exporter.

func WithHealthcheck

func WithHealthcheck(options ...health.Option) Option

WithHealthcheck returns an Option function that sets up a healthcheck service for the driver. It accepts options for configuring the healthcheck service.

func WithSocketGroup

func WithSocketGroup(group *user.Group) Option

WithSocketGroup is used to override default group owning the socket (current user's group).

func WithSocketPermissions

func WithSocketPermissions(perm os.FileMode) Option

WithSocketPermissions is used to override default permissions (0o660). Permissions that are being set must be between:

• 0o600 - the minimum permissions
• 0o766 - the maximum permissions

func WithSocketUser

func WithSocketUser(user *user.User) Option

WithSocketUser is used to override default user owning the socket (current user).