dynamo

README

DynamoDB backend implementation for Teleport.

Introduction

This package enables Teleport auth server to store secrets in DynamoDB on AWS.

WARNING: Using DynamoDB involves reccuring charge from AWS.

The table created by the backend will provision 5/5 R/W capacity. It should be covered by the free tier.

Building

DynamoDB backend is not enabled by default. To enable it you have to compile Teleport with dynamo build flag.

To build Teleport with DynamoDB enabled, run:

ADDFLAGS='-tags dynamodb' make teleport

Quick Start

Add this storage configuration in teleport section of the config file (by default it's /etc/teleport.yaml):

teleport:
  storage:
    type: dynamodb
    region: eu-west-1
    table_name: teleport.state
    access_key: XXXXXXXXXXXXXXXXXXXXX
    secret_key: YYYYYYYYYYYYYYYYYYYYY

Replace region and table_name with your own settings. Teleport will create the table automatically.

AWS IAM Role

You can use IAM role instead of hard coded access and secret key (IAM role is recommended). You must apply correct policy in order to the auth to create/get/update K/V in DynamoDB.

Example of a typical policy (change region and account ID):

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllAPIActionsOnTeleportAuth",
            "Effect": "Allow",
            "Action": "dynamodb:*",
            "Resource": "arn:aws:dynamodb:eu-west-1:123456789012:table/prod.teleport.auth"
        }
    ]
}

Get Help

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

Documentation

Overview

Package dynamodbDynamoDBBackend implements DynamoDB storage backend for Teleport auth service, similar to etcd backend.

dynamo package implements the DynamoDB storage back-end for the auth server. Originally contributed by https://github.com/apestel

limitations:

• Paging is not implemented, hence all range operations are limited to 1MB result set

Index

• Constants
• func GetName() string
• type DynamoConfig
  • func (cfg *DynamoConfig) CheckAndSetDefaults() error
• type DynamoDBBackend
  • func New(ctx context.Context, params backend.Params) (*DynamoDBBackend, error)
  • func (b *DynamoDBBackend) Clock() clockwork.Clock
  • func (b *DynamoDBBackend) Close() error
  • func (b *DynamoDBBackend) CloseWatchers()
  • func (b *DynamoDBBackend) CompareAndSwap(ctx context.Context, expected backend.Item, replaceWith backend.Item) (*backend.Lease, error)
  • func (b *DynamoDBBackend) Create(ctx context.Context, item backend.Item) (*backend.Lease, error)
  • func (b *DynamoDBBackend) Delete(ctx context.Context, key []byte) error
  • func (b *DynamoDBBackend) DeleteRange(ctx context.Context, startKey, endKey []byte) error
  • func (b *DynamoDBBackend) Get(ctx context.Context, key []byte) (*backend.Item, error)
  • func (b *DynamoDBBackend) GetRange(ctx context.Context, startKey []byte, endKey []byte, limit int) (*backend.GetResult, error)
  • func (b *DynamoDBBackend) KeepAlive(ctx context.Context, lease backend.Lease, expires time.Time) error
  • func (b *DynamoDBBackend) NewWatcher(ctx context.Context, watch backend.Watch) (backend.Watcher, error)
  • func (b *DynamoDBBackend) Put(ctx context.Context, item backend.Item) (*backend.Lease, error)
  • func (b *DynamoDBBackend) Update(ctx context.Context, item backend.Item) (*backend.Lease, error)

Constants

const (

	// BackendName is the name of this backend
	BackendName = "dynamodb"

	// DefaultReadCapacityUnits specifies default value for read capacity units
	DefaultReadCapacityUnits = 10

	// DefaultWriteCapacityUnits specifies default value for write capacity units
	DefaultWriteCapacityUnits = 10
)

Functions

func GetName

func GetName() string

GetName is a part of backend API and it returns DynamoDB backend type as it appears in `storage/type` section of Teleport YAML

Types

type DynamoConfig

type DynamoConfig struct {
	// Region is where DynamoDB Table will be used to store k/v
	Region string `json:"region,omitempty"`
	// AWS AccessKey used to authenticate DynamoDB queries (prefer IAM role instead of hardcoded value)
	AccessKey string `json:"access_key,omitempty"`
	// AWS SecretKey used to authenticate DynamoDB queries (prefer IAM role instead of hardcoded value)
	SecretKey string `json:"secret_key,omitempty"`
	// Tablename where to store K/V in DynamoDB
	Tablename string `json:"table_name,omitempty"`
	// ReadCapacityUnits is Dynamodb read capacity units
	ReadCapacityUnits int64 `json:"read_capacity_units"`
	// WriteCapacityUnits is Dynamodb write capacity units
	WriteCapacityUnits int64 `json:"write_capacity_units"`
	// BufferSize is a default buffer size
	// used to pull events
	BufferSize int `json:"buffer_size,omitempty"`
	// PollStreamPeriod is a polling period for event stream
	PollStreamPeriod time.Duration `json:"poll_stream_period,omitempty"`
	// RetryPeriod is a period between dynamo backend retries on failures
	RetryPeriod time.Duration `json:"retry_period"`
}

DynamoConfig structure represents DynamoDB confniguration as appears in `storage` section of Teleport YAML

func (*DynamoConfig) CheckAndSetDefaults

func (cfg *DynamoConfig) CheckAndSetDefaults() error

CheckAndSetDefaults is a helper returns an error if the supplied configuration is not enough to connect to DynamoDB

type DynamoDBBackend

type DynamoDBBackend struct {
	*log.Entry
	DynamoConfig
	// contains filtered or unexported fields
}

DynamoDBBackend is a DynamoDB-backed key value backend implementation.

func New

func New(ctx context.Context, params backend.Params) (*DynamoDBBackend, error)

New returns new instance of DynamoDB backend. It's an implementation of backend API's NewFunc

func (*DynamoDBBackend) Clock

func (b *DynamoDBBackend) Clock() clockwork.Clock

Clock returns wall clock

func (*DynamoDBBackend) Close

func (b *DynamoDBBackend) Close() error

Close closes the DynamoDB driver and releases associated resources

func (*DynamoDBBackend) CloseWatchers

func (b *DynamoDBBackend) CloseWatchers()

CloseWatchers closes all the watchers without closing the backend

func (*DynamoDBBackend) CompareAndSwap

func (b *DynamoDBBackend) CompareAndSwap(ctx context.Context, expected backend.Item, replaceWith backend.Item) (*backend.Lease, error)

CompareAndSwap compares and swap values in atomic operation CompareAndSwap compares item with existing item and replaces is with replaceWith item

func (*DynamoDBBackend) Create

func (b *DynamoDBBackend) Create(ctx context.Context, item backend.Item) (*backend.Lease, error)

Create creates item if it does not exist

func (*DynamoDBBackend) Delete

func (b *DynamoDBBackend) Delete(ctx context.Context, key []byte) error

Delete deletes item by key

func (*DynamoDBBackend) DeleteRange

func (b *DynamoDBBackend) DeleteRange(ctx context.Context, startKey, endKey []byte) error

DeleteRange deletes range of items with keys between startKey and endKey

func (*DynamoDBBackend) Get

func (b *DynamoDBBackend) Get(ctx context.Context, key []byte) (*backend.Item, error)

Get returns a single item or not found error

func (*DynamoDBBackend) GetRange

func (b *DynamoDBBackend) GetRange(ctx context.Context, startKey []byte, endKey []byte, limit int) (*backend.GetResult, error)

GetRange returns range of elements

func (*DynamoDBBackend) KeepAlive

func (b *DynamoDBBackend) KeepAlive(ctx context.Context, lease backend.Lease, expires time.Time) error

KeepAlive keeps object from expiring, updates lease on the existing object, expires contains the new expiry to set on the lease, some backends may ignore expires based on the implementation in case if the lease managed server side

func (*DynamoDBBackend) NewWatcher

func (b *DynamoDBBackend) NewWatcher(ctx context.Context, watch backend.Watch) (backend.Watcher, error)

NewWatcher returns a new event watcher

func (*DynamoDBBackend) Put

func (b *DynamoDBBackend) Put(ctx context.Context, item backend.Item) (*backend.Lease, error)

Put puts value into backend (creates if it does not exists, updates it otherwise)

func (*DynamoDBBackend) Update

func (b *DynamoDBBackend) Update(ctx context.Context, item backend.Item) (*backend.Lease, error)

Update updates value in the backend