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
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
orhttps://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
- type Endpoint
- type ErrHealthCheckFailure
- 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 ¶ added in v0.3.0
HealthcheckFunc.
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.
type Endpoint ¶
type Endpoint struct {
// contains filtered or unexported fields
}
Endpoint represents COSI Endpoint.
type ErrHealthCheckFailure ¶ added in v0.3.0
type ErrHealthCheckFailure struct {
// contains filtered or unexported fields
}
func (*ErrHealthCheckFailure) Error ¶ added in v0.3.0
func (err *ErrHealthCheckFailure) Error() string
type ExporterKind ¶ added in v0.2.0
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 ¶
Option represents a functional option to configure the Driver.
func WithCOSIEndpoint ¶
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 ¶ added in v0.2.0
func WithDefaultMetricExporter(kind ExporterKind) Option
WithDefaultMetricExporter returns an Option function to set the default metric exporter based on the provided kind.
func WithDefaultTraceExporter ¶ added in v0.2.0
func WithDefaultTraceExporter(kind ExporterKind) Option
WithDefaultTraceExporter returns an Option function to set the default trace exporter based on the provided kind.
func WithGRPCMetricExporter ¶ added in v0.2.0
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 ¶ added in v0.2.0
func WithGRPCTraceExporter(opt ...otlptracegrpc.Option) Option
WithGRPCTraceExporter returns an Option function to configure a gRPC trace exporter.
func WithHTTPMetricExporter ¶ added in v0.2.0
func WithHTTPMetricExporter(opt ...otlpmetrichttp.Option) Option
WithHTTPMetricExporter returns an Option function to configure an HTTP metric exporter.
func WithHTTPTraceExporter ¶ added in v0.2.0
func WithHTTPTraceExporter(opt ...otlptracehttp.Option) Option
WithHTTPTraceExporter returns an Option function to configure an HTTP trace exporter.
func WithHealthcheck ¶ added in v0.3.0
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 ¶
WithSocketGroup is used to override default group owning the socket (current user's group).
func WithSocketPermissions ¶
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 ¶
WithSocketUser is used to override default user owning the socket (current user).