trafficvault

README

Implementing a new Traffic Vault backend (e.g. Foo)

1. Create a new directory in ./backends which will contain/define your new package (foo) which will provide all the functionality to support a new Foo backend for Traffic Vault.
2. In this new ./backends/foo directory, create a new file: foo.go, with package foo to define the package name.
3. In foo.go, define a struct (e.g. type Foo struct) which will act as the method receiver for all the required TrafficVault methods. This struct should contain any fields necessary to provide the required functionality. For instance, it should most likely contain all the required configuration to connect to and use the Foo data store.

type Foo struct {
    cfg Config
}

type Config struct {
    user     string
    password string
}

1. Implement all the methods required by the TrafficVault interface on your new Foo struct. Initially, you may want to simply stub out the methods and implement them later:

func (f *Foo) GetDeliveryServiceSSLKeys(xmlID string, version string, tx *sql.Tx, ctx context.Context) (tc.DeliveryServiceSSLKeysV15, bool, error) {
	return tc.DeliveryServiceSSLKeysV15{}, false, nil
}

... (snip)

func (f *Foo) Ping(tx *sql.Tx, ctx context.Context) (tc.TrafficVaultPingResponse, error) {
	return tc.TrafficVaultPingResponse{}, nil
}

1. Define a trafficvault.LoadFunc which will parse the given JSON config (from cdn.conf's traffic_vault_config option) and return a pointer to an instance of the Foo type:

func loadFoo(b json.RawMessage) (trafficvault.TrafficVault, error) {
    // unmarshal the given JSON, validate it, return an error if any
    // fooCfg, err := parseAndValidateConfig(b)
	return &Foo{cfg: fooCfg}, nil
}

1. Define a package init function which calls trafficvault.AddBackend with your backend's name and LoadFunc in order to register your new Traffic Vault Foo backend for use:

func init() {
	trafficvault.AddBackend("foo", loadFoo)
}

1. In ./backends/backends.go, import your new package:

import (
    _ "github.com/apache/trafficcontrol/traffic_ops/traffic_ops_golang/trafficvault/backends/foo"
)

This is required for the package init() function to run and register the new backend. 8. You are now able to test your new Traffic Vault Foo backend. First, in cdn.conf, you need to set traffic_vault_backend to "foo" and include your desired Foo configuration in traffic_vault_config. Once that is done, Traffic Vault is enabled, and you can use Traffic Ops API routes that require Traffic Vault. At this point, you should go back and fully implement the stubbed out TrafficVault interface methods on your Foo type.

Documentation

Overview

Package trafficvault provides the interfaces and types necessary to support various Traffic Vault backend data stores.

Index

• func AddBackend(name string, loadConfig LoadFunc)
• type LoadFunc
• type TrafficVault
  • func GetBackend(name string, cfgJson json.RawMessage) (TrafficVault, error)

Functions

func AddBackend

func AddBackend(name string, loadConfig LoadFunc)

AddBackend should be called by each TrafficVault backend package's init() function in order to register its name and LoadFunc. This name corresponds to the traffic_vault_backend option in cdn.conf.

Types

type LoadFunc

type LoadFunc func(json.RawMessage) (TrafficVault, error)

A LoadFunc is a function that takes a json.RawMessage as input (the contents of traffic_vault_config in cdn.conf) and returns a valid TrafficVault as output. Each TrafficVault implementation should define its own LoadFunc which is responsible for parsing the given configuration and returning a valid TrafficVault implementation that may be used by request handlers.

type TrafficVault

type TrafficVault interface {

	// GetDeliveryServiceSSLKeys retrieves the SSL keys of the given version for
	// the delivery service identified by the given xmlID. If version is empty,
	// the implementation should return the latest version.
	GetDeliveryServiceSSLKeys(xmlID string, version string, tx *sql.Tx, ctx context.Context) (tc.DeliveryServiceSSLKeysV15, bool, error)
	// PutDeliveryServiceSSLKeys stores the given SSL keys for a delivery service.
	PutDeliveryServiceSSLKeys(key tc.DeliveryServiceSSLKeys, tx *sql.Tx, ctx context.Context) error
	// DeleteDeliveryServiceSSLKeys removes the SSL keys of the given version (or latest
	// if version is empty) for the delivery service identified by the given xmlID.
	DeleteDeliveryServiceSSLKeys(xmlID string, version string, tx *sql.Tx, ctx context.Context) error
	// DeleteOldDeliveryServiceSSLKeys takes a set of existingXMLIDs as input and will remove
	// all SSL keys for delivery services in the CDN identified by the given cdnName that
	// do not contain an xmlID in the given set of existingXMLIDs. This method is called
	// during a snapshot operation in order to delete SSL keys for delivery services that
	// no longer exist.
	DeleteOldDeliveryServiceSSLKeys(existingXMLIDs map[string]struct{}, cdnName string, tx *sql.Tx, ctx context.Context) error
	// GetCDNSSLKeys retrieves all the SSL keys for delivery services in the CDN identified
	// by the given cdnName.
	GetCDNSSLKeys(cdnName string, tx *sql.Tx, ctx context.Context) ([]tc.CDNSSLKey, error)
	// GetDNSSECKeys retrieves all the DNSSEC keys associated with the CDN identified by the
	// given cdnName.
	GetDNSSECKeys(cdnName string, tx *sql.Tx, ctx context.Context) (tc.DNSSECKeysTrafficVault, bool, error)
	// PutDNSSECKeys stores all the DNSSEC keys for the CDN identified by the given cdnName.
	PutDNSSECKeys(cdnName string, keys tc.DNSSECKeysTrafficVault, tx *sql.Tx, ctx context.Context) error
	// DeleteDNSSECKeys removes all the DNSSEC keys for the CDN identified by the given cdnName.
	DeleteDNSSECKeys(cdnName string, tx *sql.Tx, ctx context.Context) error
	// GetURLSigKeys retrieves the URL sig keys for the delivery service identified by the
	// given xmlID.
	GetURLSigKeys(xmlID string, tx *sql.Tx, ctx context.Context) (tc.URLSigKeys, bool, error)
	// PutURLSigKeys stores the given URL sig keys for the delivery service identified by
	// the given xmlID.
	PutURLSigKeys(xmlID string, keys tc.URLSigKeys, tx *sql.Tx, ctx context.Context) error
	// DeleteURLSigKeys deletes the URL sig keys for the delivery service identified
	// by the given xmlID.
	DeleteURLSigKeys(xmlID string, tx *sql.Tx, ctx context.Context) error
	// GetURISigningKeys retrieves the URI signing keys (as raw JSON bytes) for the delivery
	// service identified by the given xmlID.
	GetURISigningKeys(xmlID string, tx *sql.Tx, ctx context.Context) ([]byte, bool, error)
	// PutURISigningKeys stores the given URI signing keys (as raw JSON bytes) for the delivery
	// service identified by the given xmlID.
	PutURISigningKeys(xmlID string, keysJson []byte, tx *sql.Tx, ctx context.Context) error
	// DeleteURISigningKeys removes the URI signing keys for the delivery service identified by
	// the given xmlID.
	DeleteURISigningKeys(xmlID string, tx *sql.Tx, ctx context.Context) error
	// Ping simply checks the health of the Traffic Vault backend, returning a status and which
	// server hostname the status was returned by.
	Ping(tx *sql.Tx, ctx context.Context) (tc.TrafficVaultPing, error)
	// GetBucketKey returns the raw bytes identified by the given bucket and key. This may not
	// apply to every Traffic Vault backend implementation.
	// Deprecated: this method and associated API routes will be removed in the future.
	GetBucketKey(bucket string, key string, tx *sql.Tx) ([]byte, bool, error)
}

TrafficVault defines the methods necessary for a struct to implement in order to provide all the necessary functionality required of a Traffic Vault backend.

func GetBackend

func GetBackend(name string, cfgJson json.RawMessage) (TrafficVault, error)

GetBackend is called with the contents of the traffic_vault_backend and traffic_vault_config options in cdn.conf, respectively, in order to lookup and load the chosen Traffic Vault backend to use.