gcssessions

README

GCS Storage Implementation for Teleport

Introduction

This package enables Teleport auth server to store session recordings in GCS on GCP.

WARNING: Using GCS involves recurring charge from GCP.

Building

GCS session storage is not enabled by default. To enable it you have to compile Teleport with gcs build flag.

To build Teleport with GCS enabled, run:

ADDFLAGS='-tags gcs' make teleport

Quick Start

Configuration options are passed to the GCS handler via a URI/URL. The following is a sample configuration in teleport section of the config file (by default it's /etc/teleport.yaml):

teleport:
  storage:
    audit_sessions_uri: 'gs://teleport-session-storage-2?projectID=gcp-proj&credentialsPath=/var/lib/teleport/gcs_creds'

Full Properties

The full list of configurable properties for this backend are:

• host portion of URI is the GCS bucket used to persist session recordings
• credentialsPath (string, path to GCP creds for Firestore, not-required)
• projectID (string, project ID, required)
• endpoint (string, GCS client endpoint, not-required, ex: localhost:8618)
• path (string, the path inside the GCS bucket to use as storage root, not-required)
• keyName (string, the user-defined GCP KMS key name to use for encryption, not-required)

GCS Client Authentication Options

There are three authentication/authorization modes available;

1. With no credentialsPath and no endpoint defined, the GCS client will use Google Application Default Credentials for authentication. This only works in cases where Teleport is installed on GCE instances and have service accounts with IAM role/profile associations authorizing that GCE instance to use Firestore.
2. With endpoint defined, GCS will create a client with no auth and clients pointed at the specified endpoint. This is only used for tests, see Tests section below.
3. With credentialsPath defined, Firestore will create clients authenticating against live systems with the Service Account bound to the JSON key file referenced in the option.

Get Help

This backend has been contributed by https://github.com/joshdurbin

Documentation

Overview

Package gcssessionsHandler implements GCS storage for Teleport session recording persistence.

gcssessions package implements the Handler session recording storage for auth server. Originally contributed by https://github.com/joshdurbin

Index

• type Config
  • func (cfg *Config) SetFromURL(url *url.URL) error
• type Handler
  • func DefaultNewHandler(cfg Config) (*Handler, error)
  • func NewHandler(ctx context.Context, cancelFunc context.CancelFunc, cfg Config, ...) (*Handler, error)
  • func (h *Handler) Close() error
  • func (h *Handler) Download(ctx context.Context, sessionID session.ID, writerAt io.WriterAt) error
  • func (h *Handler) Upload(ctx context.Context, sessionID session.ID, reader io.Reader) (string, error)

Types

type Config

type Config struct {
	// Bucket is GCS bucket name
	Bucket string
	// Path is an optional bucket path
	Path string
	// Path to the credentials file
	CredentialsPath string
	// The GCS project ID
	ProjectID string
	// KMS key name
	KMSKeyName string
	// Endpoint
	Endpoint string
}

Config is handler configuration

func (*Config) SetFromURL

func (cfg *Config) SetFromURL(url *url.URL) error

SetFromURL sets values on the Config from the supplied URI

type Handler

type Handler struct {
	// Config is handler configuration
	Config
	// Entry is a logging entry
	*log.Entry
	// contains filtered or unexported fields
}

Handler handles upload and downloads to GCS object storage

func DefaultNewHandler

func DefaultNewHandler(cfg Config) (*Handler, error)

DefaultNewHandler returns a new handler with default GCS client settings derived from the config

func NewHandler

func NewHandler(ctx context.Context, cancelFunc context.CancelFunc, cfg Config, client *storage.Client) (*Handler, error)

NewHandler returns a new handler with specific context, cancelFunc, and client

func (*Handler) Close

func (h *Handler) Close() error

Closer releases connection and resources associated with log if any

func (*Handler) Download

func (h *Handler) Download(ctx context.Context, sessionID session.ID, writerAt io.WriterAt) error

Download downloads recorded session from GCS bucket and writes the results into writer return trace.NotFound error is object is not found

func (*Handler) Upload

func (h *Handler) Upload(ctx context.Context, sessionID session.ID, reader io.Reader) (string, error)

Upload uploads object to GCS bucket, reads the contents of the object from reader and returns the target GCS bucket path in case of successful upload.