box

package
v1.97.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 7, 2024 License: Apache-2.0 Imports: 17 Imported by: 24

Documentation

Overview

Package box implements the definitions of a box configuration file and tools to access it. This is used to configure the suite of tools that outreach provides, aka "startup in a box"

Description: This file contains development registry configuration

Description: This file contains box configuration for loft

Index

Constants

View Source 
const (
	// SnapshotLockChannelStable is a stable channel
	SnapshotLockChannelStable SnapshotLockChannel = "stable"

	// SnapshotLockChannelRC is a release candidate (less stable) channel
	SnapshotLockChannelRC SnapshotLockChannel = "rc"

	// Version is the current version of the box spec.
	Version float32 = 3
)

Variables

View Source 
var (
	// BoxConfigPath is the $HOME/<BoxConfigPath> location of the box config storage
	BoxConfigPath = ".outreach/.config/box"
	// BoxConfigFile is the name of the box config storage file
	BoxConfigFile = "box.yaml"
)

Functions

func ApplyEnvOverrides 

func ApplyEnvOverrides(s *Config)

ApplyEnvOverrides overrides a box configuration based on env vars.

func InitializeBox 

func InitializeBox(ctx context.Context, _ []string) error

InitializeBox prompts the user for a box config location, downloads it and then saves it to disk. In general EnsureBox should be used over this function.

func LoadBoxStorage 

func LoadBoxStorage() (*Storage, *Config, error)

LoadBoxStorage reads a serialized, storage wrapped box config from disk and returns it. In general LoadBox should be used over this function.

func SaveBox 

func SaveBox(_ context.Context, s *Storage) error

SaveBox takes a Storage wrapped box configuration, serializes it and then saves it to the well-known config path on disk.

Types

type AWSConfig added in v1.35.0 

type AWSConfig struct {
	// DefaultAccountID is the default Account ID to use when communicating
	// with AWS.
	DefaultAccountID string `yaml:"defaultAccountID"`

	// DefaultIAMIdPARN is the default IAM IdP ARN to use when communicating
	// with AWS.
	DefaultIAMIdPARN string `yaml:"defaultIAMIdPARN"`

	// DefaultProfile is the default profile to use when communicating
	// with AWS.
	DefaultProfile string `yaml:"defaultProfile"`

	// DefaultRole is the default role to assume when communicating
	// with AWS.
	DefaultRole string `yaml:"defaultRole"`

	// Okta contains configuration for using Okta authentication
	// with AWS.
	Okta OktaConfig `yaml:"okta"`

	// RefreshMethod is the CLI used to refresh AWS credentials.
	// Known values:
	// * okta-aws-cli (default)
	RefreshMethod string `yaml:"refreshMethod"`
}

AWSConfig configures AWS access for tools that support it

type CD added in v1.56.1 

type CD struct {
	// Concourse contains the concourse configuration settings
	Concourse struct {
		// Address is the concourse host url
		Address string `yaml:"address"`
	} `yaml:"concourse"`
	// Maestro contains the maestro configuration settings
	Maestro struct {
		// Address is the maestro host url
		Address string `yaml:"address"`
	} `yaml:"maestro"`
}

CD contains the cd configuration settings that can be set in box

type CI added in v1.41.0 

type CI struct {
	// CircleCI contains the CircleCI configuration settings
	CircleCI struct {
		// Contexts are authentication contexts that can be used
		// to authenticate with CircleCI.
		Contexts struct {
			// AWS is the AWS authentication context
			// The context should contain the following values:
			// AWS_ACCESS_KEY_ID: <access key id>
			// AWS_SECRET_ACCESS_KEY: <secret access key>
			AWS string `yaml:"aws"`

			// Github is the Github authentication context
			// The context should contain the following values:
			// GHACCESSTOKEN_GHAPP_1: <github app>
			// GHACCESSTOKEN_PAT_1: <github personal access token>
			//
			// For more information on this, see:
			// https://github.com/getoutreach/ci/blob/main/cmd/ghaccesstoken/token.go
			Github string `yaml:"github"`

			// Docker is the docker authentication context
			// Currently all that is supported is gcp.
			// The context should contain the following values:
			// GCLOUD_SERVICE_ACCOUNT: <gcp service account json>
			Docker string `yaml:"docker"`

			// NPM is the npm authentication context
			// The context should contain the following values:
			// NPM_TOKEN: <npm token>
			NPM string `yaml:"npm"`

			// ExtraContexts is a list of extra contexts to include
			// for every job
			ExtraContexts []string `yaml:"extraContexts"`
		} `yaml:"contexts"`
	} `yaml:"circleci"`
}

CI contains the ci configuration settings that can be set in box

type Config 

type Config struct {
	// RefreshInterval is the interval to use when refreshing a box configuration
	RefreshInterval time.Duration `yaml:"refreshInterval"`

	// Org is the Github org for this box, e.g. getoutreach
	Org string `yaml:"org"`

	// DeveloperEnvironmentConfig is the configuration for the developer environment for this box
	DeveloperEnvironmentConfig DeveloperEnvironmentConfig `yaml:"devenv"`

	// AWS is the configuration for communicating with AWS.
	AWS AWSConfig `yaml:"aws"`

	// CI is the configuration for the CI environment
	CI CI `yaml:"ci"`

	// CD is the configuration
	CD CD `yaml:"cd"`

	// Docker is the configuration for pull/push registries
	Docker Docker `yaml:"docker"`
}

Config is the basis of a box configuration

func EnsureBox 

func EnsureBox(ctx context.Context, defaults []string, log logrus.FieldLogger) (*Config, error)

EnsureBox loads a box if it already exists, or prompts the user for the box if not found. If it exists, remote is querired periodically for a new version. Deprecated: Use EnsureBoxWithOptions instead.

func EnsureBoxWithOptions added in v1.17.0 

func EnsureBoxWithOptions(ctx context.Context, optFns ...LoadBoxOption) (*Config, error)

EnsureBoxWithOptions loads a box if it already exists or returns an error. The box config is periodically refreshed based on the configured interval and based on a min version requirement, if set.

func LoadBox 

func LoadBox() (*Config, error)

LoadBox loads the default box or returns an error

func NewConfig 

func NewConfig() *Config

NewConfig makes a full initialized Config

type DeveloperEnvironmentConfig 

type DeveloperEnvironmentConfig struct {
	// SnapshotConfig is the snapshot configuration for the devenv
	SnapshotConfig SnapshotConfig `yaml:"snapshots"`

	// VaultConfig denotes how to talk to Vault
	VaultConfig VaultConfig `yaml:"vault"`

	// ImagePullSecret is a path to credentials used to pull images with
	// currently the only supported value is a vault key path with
	// VaultEnabled being true
	ImagePullSecret string `yaml:"imagePullSecret"`

	// ImageRegistry is the registry to use for detecting your apps
	// e.g. gcr.io/outreach-docker
	ImageRegistry string `yaml:"imageRegistry"`

	// RuntimeConfig stores configuration specific to different devenv
	// runtimes.
	RuntimeConfig DeveloperEnvironmentRuntimeConfig `yaml:"runtimeConfig"`

	// VersionResolvers stores the configuration for version resolvers
	VersionResolvers DevenvVersionResolvers `yaml:"versionResolvers"`
}

type DeveloperEnvironmentRuntimeConfig added in v1.15.0 

type DeveloperEnvironmentRuntimeConfig struct {
	// EnabledRuntimes dictates which runtimes are enabled, generally defaults to all.
	EnabledRuntimes []string `yaml:"enabledRuntimes"`

	// DevelopmentRegistries are image registries that should be used for
	// development docker images. These are only ever used for remote devenvs.
	DevelopmentRegistries DevelopmentRegistries `yaml:"developmentRegistries"`

	// Loft is configuration for the loft runtime in the devenv
	Loft LoftRuntimeConfig `yaml:"loft"`
}

DeveloperEnvironmentRuntimeConfig stores configuration specific to different runtimes.

type DevelopmentRegistries added in v1.23.0 

type DevelopmentRegistries struct {
	// Path is a go-template string of the path to append to the end of the endpoint
	// for the docker image registry to use. This is useful for namespacing images.
	Path string `yaml:"path"`

	// Clouds is a CloudName -> DevelopmentRegistriesSlice
	Clouds map[region.CloudName]DevelopmentRegistriesSlice
}

DevelopmentRegistries contains a slice of DevelopmentRegistrys

type DevelopmentRegistriesSlice added in v1.23.0 

type DevelopmentRegistriesSlice []DevelopmentRegistry

DevelopmentRegistriesSlice is a slice of DevelopmentRegistry

func (DevelopmentRegistriesSlice) Regions added in v1.23.0 

func (dr DevelopmentRegistriesSlice) Regions() []region.Name

Regions returns all of the regions of the development registries

type DevelopmentRegistry added in v1.23.0 

type DevelopmentRegistry struct {
	// Endpoint is the endpoint of this registry, e.g.
	// gcr.io/outreach-docker or docker.io/getoutreach
	Endpoint string `yaml:"endpoint"`

	// Region that this registry should be used in. If not set will be randomly selected.
	Region region.Name `yaml:"region"`
}

DevelopmentRegistry is a docker image registry used for development

type DevenvVersionResolvers added in v1.65.0 

type DevenvVersionResolvers struct {
	// Enabled is a list of image resolvers to use. If none are specified Maestro will be used
	// ordered based on priority. External customers should default to git
	Enabled []string `yaml:"enabled"`

	// Config is the configuration information for all version resolvers
	Config VersionResolverConfig `yaml:"config"`
}

DevenvVersionResolvers is the configurations used to get the latest version

type Docker added in v1.95.0 

type Docker struct {
	// ImagePullRegistry is the container image registry used to pull images from during deployment.
	ImagePullRegistry string `yaml:"imagePullRegistry"`
	// ImagePushRegistries is a list of container image registry URLs used to publish to when containers are generated for consumption.
	ImagePushRegistries []string `yaml:"imagePushRegistries"`
}

type LoadBoxOption added in v1.17.0 

type LoadBoxOption func(*LoadBoxOptions)

func WithAgent added in v1.87.0 

func WithAgent(sshAgent agent.Agent) LoadBoxOption

WithAgent sets the SSH agent for fetching the box repository. If not specified, it creates a new one and uses the existing SSH config to load the github.com SSH key specified.

func WithDefaults added in v1.17.0 

func WithDefaults(defaults []string) LoadBoxOption

WithDefaults sets the default URLs to provided to a user when a box configuration doesn't exist locally. Deprecated: Do not use. See field on LoadBoxOptions

func WithLogger added in v1.17.0 

func WithLogger(log logrus.FieldLogger) LoadBoxOption

WithLogger sets the logger to use when outputting to the user.

func WithMinVersion added in v1.17.0 

func WithMinVersion(version float32) LoadBoxOption

WithMinVersion sets a minimum version of a box configuration being required. If this version is not currently downloaded it will be force a box re-download. This is useful for using new fields. Version in box.go should be bumped when this is required.

type LoadBoxOptions added in v1.17.0 

type LoadBoxOptions struct {
	// MinVersion of a box configuration that is required for this
	// LoadBox call.
	MinVersion *float32

	// DefaultBoxSources is a list of URLs to present to the user
	// as being the default locations of box configuration.
	// Deprecated: Configure before running an application instead.
	DefaultBoxSources []string

	// Agent is the SSH agent used when fetching the box git repository.
	Agent agent.Agent
	// contains filtered or unexported fields
}

type LoftCluster added in v1.23.0 

type LoftCluster struct {
	// Name is the name of the cluster in loft
	Name string `yaml:"name"`

	// Region is the region that this cluster is in
	Region region.Name `yaml:"region"`

	// Cloud is the cloud that this loft cluster is in. Not currently used anywhere.
	Cloud region.CloudName `yaml:"cloud"`
}

LoftCluster is a loft cluster

type LoftClusters added in v1.23.0 

type LoftClusters []LoftCluster

LoftClusters is a container for a slice of LoftClusters

func (LoftClusters) Regions added in v1.23.0 

func (lc LoftClusters) Regions() []region.Name

Regions returns all of the regions of the regions for the loft clusters in a []LoftCluster

type LoftRuntimeConfig added in v1.15.0 

type LoftRuntimeConfig struct {
	// Clusters is a list of clusters provided by this loft instance
	Clusters LoftClusters `yaml:"clusters"`

	// DefaultCloud is the default cloud to use. Currently the only way to specify
	// which cloud.
	DefaultCloud region.CloudName `yaml:"defaultCloud"`

	// DefaultRegion is the default region to use when a nearest one couldn't
	// be calculated
	DefaultRegion region.Name `yaml:"regionName"`

	// URL is the URL of a loft instance.
	URL string `yaml:"URL"`
}

LoftRuntimeConfig is configuration for loft runtimes

type MaestroConfig added in v1.65.0 

type MaestroConfig struct {
	// VaultSecretPath vault path that contains the auth secret to access maestro API
	VaultSecretPath string `yaml:"vaultSecretPath"`

	// VaultSecretKey the key within the VaultSecretPath that contains the API token
	VaultSecretKey string `yaml:"vaultSecretKey"`

	// Channels list of channels that maestro should retrieve version from
	Channels []string `yaml:"channels"`
}

MaestroConfig contains configuration used by the maestro version resolver

type OktaConfig added in v1.78.0 

type OktaConfig struct {
	// FederationAppID is the Okta app ID for the AWS federation app.
	FederationAppID string `yaml:"federationAppID"`
	// OIDCClientID is the Okta app ID for the AWS OIDC app (not the
	// federation one).
	OIDCClientID string `yaml:"oidcClientID"`
	// OrgDomain is the hostname of the Okta instance.
	OrgDomain string `yaml:"orgDomain"`
	// SessionDuration is the TTL for the session in seconds.
	SessionDuration uint `yaml:"sessionDuration"`
}

OktaConfig is the Okta-specific config used for AWS access.

type RestoreStep added in v1.73.0 

type RestoreStep struct {
	// Description describes what resources are restored in this step
	Description string

	// IncludedNamespaces defines what namespaces are restored in this step. It maps to Velero IncludedNamespaces restore parameter
	IncludedNamespaces []string `yaml:"included_namespaces"`

	// ExcludedNamespaces defines what namespaces are not restored in this step. It maps to Velero ExcludedNamespaces restore parameter
	ExcludedNamespaces []string `yaml:"excluded_namespaces"`
}

RestoreStep maps to a set of resources included in the snapshot.

Examples:

- a "databases" step specifies "IncludedNamespaces" of all database namespaces

- a "all the rest" step only specifies "ExcludedNamespaces" used in previous steps

type SnapshotConfig 

type SnapshotConfig struct {
	// Endpoint is the S3 compatible endpoint to fetch a snapshot from
	Endpoint string `yaml:"endpoint"`

	// Region is the region to use for this bucket
	Region string `yaml:"region"`

	// Bucket is the bucket that the snapshots are in
	Bucket string `yaml:"bucket"`

	// DefaultName is the default name (snapshot) to use, e.g. flagship
	DefaultName string `yaml:"defaultName"`

	// ReadAWSRole is the role to use, if set, for RO access to AWS
	ReadAWSRole string `yaml:"readAWSRole"`

	// WriteAWSRole is the role to use, if set, for RW access to AWS
	WriteAWSRole string `yaml:"writeAWSRole"`
}

SnapshotConfig stores configuration for generated and accessing snapshots

type SnapshotGenerateConfig 

type SnapshotGenerateConfig struct {
	// Targets are all of the snapshots that can be generated. The key equates
	// the name of the generated snapshot
	Targets map[string]*SnapshotTarget `yaml:"targets"`
}

SnapshotGenerateConfig stores configuration for snapshots that should be generated

type SnapshotLock 

type SnapshotLock struct {
	// Version is the version of this configuration, used for breaking changes
	Version int `yaml:"version"`

	// GeneratedAt is when this lock was generated
	GeneratedAt time.Time `yaml:"generatedAt"`

	// Deprecated: Use TargetsV2 instead
	// Targets is a single snapshot for each target
	Targets map[string]*SnapshotLockTarget `yaml:"targets"`

	// TargetsV2 is a target -> lock list for snapshots
	TargetsV2 map[string]*SnapshotLockList `yaml:"targets_v2"`
}

SnapshotLock is an manifest of all the available snapshots

type SnapshotLockChannel 

type SnapshotLockChannel string

SnapshotLockChannel is used to determine the quality of a given snapshot

type SnapshotLockList 

type SnapshotLockList struct {
	// Snapshots is a channel separated list of snapshots for a given target
	Snapshots map[SnapshotLockChannel][]*SnapshotLockListItem `yaml:"snapshots"`
}

SnapshotLockList contains a channel (different releases of snapshots) separated list of snapshots

type SnapshotLockListItem 

type SnapshotLockListItem struct {
	// Digest is a MD5 base64 encoded digest of the archive
	Digest string `yaml:"digest"`

	// Key is the key that this snapshot is stored at, note that the bucket is
	// not set or determined here and instead come from the snapshotconfig
	URI string `yaml:"key"`

	// Config is the config used to generate this snapshot
	Config *SnapshotTarget

	// VeleroBackupName is the name of this snapshot. This is used to invoke velero
	// commands. It should not be used for uniqueness constraints.
	VeleroBackupName string `yaml:"veleroBackupName"`
}

SnapshotLockListItem is a replacement for SnapshotLockTarget which is used by SnapshotLockList to provide details about a snapshot

type SnapshotLockTarget 

type SnapshotLockTarget struct {
	// Digest is a MD5 base64 encoded digest of the archive
	Digest string `yaml:"digest"`

	// Key is the key that this snapshot is stored at, note that the bucket is
	// not set or determined here and instead come from the snapshotconfig
	URI string `yaml:"key"`

	// Config is the config used to generate this snapshot
	Config *SnapshotTarget

	// VeleroBackupName is the name of this snapshot. This is used to invoke velero
	// commands. It should not be used for uniqueness constraints.
	VeleroBackupName string `yaml:"veleroBackupName"`
}

SnapshotLockTarget is a generated snapshot and metadata on it. In general SnapshotLockListItem should be used instead.

type SnapshotTarget 

type SnapshotTarget struct {
	// Command is the command to be run to generate this snapshot,
	// note that a devenv is already provisioned and accessible at this
	// stage of the generation process
	Command string `yaml:"command"`

	// PostRestore is a path to a yaml file that contains pre-rendered manifests
	// These manifests will be ran through a special go-template that allows
	// injecting information like the current user / git email.
	PostRestore string `yaml:"post_restore"`

	// DeployApps is an array of applications to deploy via deploy-app
	// before running the Command specified.
	DeployApps []string `yaml:"deploy_apps"`

	// PostDeployApps is an array of applications to deploy via deploy-app
	// after running the Command specified.
	PostDeployApps []string `yaml:"post_deploy_apps"`

	// ReadyAddress is a URL to ping before marking the devenv as ready
	ReadyAddress string `yaml:"readyAddress"`

	// RestoreSteps defines the startup order of the resources within this snapshot.
	// If not specified, all snapshot resources are started at the same time
	RestoreSteps []RestoreStep `yaml:"restore_steps"`
}

SnapshotTarget is the defn for a generated snapshot

type Storage 

type Storage struct {
	// Config is the box configuration, see Config.
	// This is an yaml.Node because we can't guarantee that the
	// underlying type is a Config as we expect it to be.
	Config yaml.Node `yaml:"config"`

	// LastUpdated is the last time this file was checked for updates
	LastUpdated time.Time `yaml:"lastUpdated"`

	// Version is the version of this box spec.
	Version float32 `yaml:"version"`

	// StorageURL is the location that this came from
	StorageURL string `yaml:"storageURL"`
}

Storage is a wrapper type used for storing the box configuration

type VaultConfig 

type VaultConfig struct {
	// Enabled determines if we should setup vault or not
	Enabled bool `yaml:"enabled"`

	// AuthMethod is the method to talk to vault, e.g. oidc
	AuthMethod string `yaml:"authMethod"`

	// Address is the URL to talk to Vault
	Address string `yaml:"address"`

	// AddressCI is the URL to use to talk to Vault in CI
	// Defaults to Address
	AddressCI string `yaml:"addressCI"`
}

VaultConfig is the configuration for accessing Vault

type VersionResolverConfig added in v1.65.0 

type VersionResolverConfig struct {
	// Maestro configuration used by maestro image resolver
	Maestro MaestroConfig `yaml:"maestro"`
}

VersionResolverConfig contains configuration for version resolvers

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.