terra

package
v1.0.81 Latest Latest
Warning

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

 Go to latest Published: Sep 22, 2023 License: BSD-3-Clause Imports: 4 Imported by: 0

README

terra

The terra package models Terra infrastructure. It includes data types that represents Terra environments, clusters, and releases.

Documentation

Overview

Package terra contains interfaces that model Terra's infrastructure, and support querying and updating the state of said infrastructure.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DestinationTypeNames 

func DestinationTypeNames() []string

DestinationTypeNames returns a list of destination type names as strings

func LifecycleNames 

func LifecycleNames() []string

LifecycleNames returns a slice of all Lifecycle names as strings

Types

type AppRelease 

type AppRelease interface {
	AppVersion() string
	Environment() Environment
	// Subdomain returns the slug that this AppRelease uses inside its Environment. Defaults to chart Release.Name.
	// E.g. "leonardo"
	Subdomain() string
	// Protocol returns the transport protocol to connect to the AppRelease. Defaults to "https".
	Protocol() string
	// Port returns the transport protocol port to use to connect to the AppRelease. Defaults to '443'.
	Port() int
	// Host combines Subdomain with Environment.Destination.Name (if Environment.NamePrefixesDomain) and
	// Environment.BaseDomain to form the full hostname of the AppRelease.
	// E.g. "leonardo.my-environment.bee.envs-terra.bio"
	Host() string
	// URL combines Protocol with Host (no Port) to form the URL for the AppRelease.
	// E.g. "https://leonardo.my-environment.bee.envs-terra.bio"
	URL() string
	Release
}

type AutoDelete added in v1.0.26 

type AutoDelete interface {
	// Enabled if true, this environment should be automatically deleted
	Enabled() bool
	// After point in time after which the environment should be automatically deleted
	After() time.Time
}

AutoDelete automatic deletion settings for dynamic environments

type Cluster 

type Cluster interface {
	// Address is the API address of the cluster master endpoint, eg. "https://35.36.37.38"
	Address() string
	// Project is the name of the GCP project where the cluster lives
	Project() string
	// ProjectSuffix is the last hyphen-delimited part of the GCP project name
	ProjectSuffix() string
	// Location is the name of the zone or region where the cluster lives (eg. "us-central1-a")
	Location() string
	// ArtifactBucket is the name of a GCS bucket for the cluster where Thelma can upload artifacts
	ArtifactBucket() string
	Destination
}

type ClusterRelease 

type ClusterRelease interface {
	Cluster() Cluster
	Release
}

type Clusters 

type Clusters interface {
	// All returns a list of all clusters
	All() ([]Cluster, error)
	// Get returns the cluster with the given name, or an error if no such cluster exists
	Get(name string) (Cluster, error)
	// Exists returns true if a cluster by the given name exists
	Exists(name string) (bool, error)
}

Clusters is an interface for querying clusters

type CreateOptions added in v1.0.26 

type CreateOptions struct {
	// Name to assign to the environment
	Name string
	// GenerateName if true, generate a name instead of using user-supplied name
	GenerateName bool
	// NamePrefix optional prefix to use when generating name
	NamePrefix string
	// AutoDelete optional - if enabled, schedule the BEE for automatic deletion after the given point in time
	AutoDelete struct {
		Enabled bool
		After   time.Time
	}
	// Owner optional - owner to assign to the environment
	Owner string

	// StopSchedule an optional daily time to stop the BEE
	StopSchedule struct {
		Enabled       bool
		RepeatingTime time.Time
	}

	// Start Schedule an optional daily time to start the BEE
	StartSchedule struct {
		Enabled       bool
		RepeatingTime time.Time
		Weekends      bool
	}
}

CreateOptions options for creating a new dynamic environment

type Destination 

type Destination interface {
	Named                     // Named provides the name of the environment or cluster
	Type() DestinationType    // Type is the name of the destination type, either "environment" or "cluster"
	Base() string             // Base is the base of the environment or cluster
	ReleaseType() ReleaseType // ReleaseType returns the types of releases that can be deployed to this destination
	Releases() []Release      // Releases returns the set of releases configured for this destination
	TerraHelmfileRef() string // TerraHelmfileRef this destination's generator should be pinned to
	IsCluster() bool          // IsCluster Returns true if this destination is a cluster
	IsEnvironment() bool      // IsEnvironment Returns true if this destination is an environment
	RequireSuitable() bool    // RequireSuitable Returns true if this destination requires suitability in order to modify
}

Destination is the location where a release is deployed (environment or cluster)

type DestinationFilter 

type DestinationFilter interface {
	// String returns a string representation of the filter
	String() string
	// Matches returns true if this filter matches the destination
	Matches(Destination) bool
	// And returns a new filter that matches this filter and another
	And(DestinationFilter) DestinationFilter
	// Or returns a new filter that matches this filter or another
	Or(DestinationFilter) DestinationFilter
	// Negate returns a new filter that matches the opposite of this filter
	Negate() DestinationFilter
	// Filter given a list of destinations, return the sublist that match this filter
	Filter([]Destination) []Destination
}

A DestinationFilter is a predicate for filtering lists of destinations

type DestinationType 

type DestinationType int

DestinationType is an enum type referring to the two types of destinations supported by terra-helmfile. 

const (
	EnvironmentDestination DestinationType = iota
	ClusterDestination
)

func DestinationTypes 

func DestinationTypes() []DestinationType

DestinationTypes returns all destination types

func (DestinationType) Compare 

func (t DestinationType) Compare(other DestinationType) int

Compare returns 0 if t == other, -1 if t < other, or +1 if t > other.

func (*DestinationType) FromString 

func (t *DestinationType) FromString(value string) error

FromString will set the receiver's value to the one denoted by the given string

func (DestinationType) String 

func (t DestinationType) String() string

func (*DestinationType) UnmarshalYAML 

func (t *DestinationType) UnmarshalYAML(value *yaml.Node) error

UnmarshalYAML is a custom unmarshaler so that the string "environment" or "cluster" in a yaml file can be unmarshaled into a DestinationType

type Destinations 

type Destinations interface {
	// All returns a list of all destinations
	All() ([]Destination, error)
	// Filter returns a list of clusters matching the given filter
	Filter(filter DestinationFilter) ([]Destination, error)
	// Get returns the destination with the given name, or an error if no such destination exists
	Get(name string) (Destination, error)
}

Destinations is an interface for querying release destinations

type Environment 

type Environment interface {
	// DefaultCluster Returns the default cluster for this environment.
	DefaultCluster() Cluster
	// Namespace Returns the namespace for this environment. Eg. "terra-dev"
	Namespace() string
	// Lifecycle returns the lifecycle for this environment.
	Lifecycle() Lifecycle
	// Template returns the name of this environment's configuration template, if it has one.
	// Returns the empty string if the environment has no configuration template.
	Template() string
	// BaseDomain returns static domain name part for this environment or environment type.
	// E.g. "bee.envs-terra.bio", "dsde-prod.broadinstitute.org"
	BaseDomain() string
	// NamePrefixesDomain returns whether this particular environment's name should come before its BaseDomain when
	// deriving full hostnames/URLs in this environment.
	// E.g. 'true' for dynamic/template environments, 'false' for static
	NamePrefixesDomain() bool
	// UniqueResourcePrefix (dynamic environments only) unique-to-this-environment 4-character prefix that can be referenced in configuration.
	// Format: [a-z][a-z0-9]{3}
	// Returns empty string for static / template environments
	UniqueResourcePrefix() string
	// Owner is an email address of the user or group responsible for this environment.
	// May be empty if there's no owner or if the state provider doesn't track this information.
	Owner() string
	// PreventDeletion if true, the environment should not be automatically deleted under any circumstances.
	// Applies to dynamic environments only (Thelma only supports deletion of dynamic environments).
	PreventDeletion() bool
	// AutoDelete automatic deletion settings for this environment. Applies to dynamic environments only.
	AutoDelete() AutoDelete
	// CreatedAt returns the timestamp at which this environment was created in state
	CreatedAt() time.Time
	// Offline returns whether this environment should be currently offline
	Offline() bool

	// OfflineScheduleBeginEnabled indicates whether the environment is meant to be stopped on a schedule
	OfflineScheduleBeginEnabled() bool
	OfflineScheduleBeginTime() time.Time

	// OfflineScheduleEndEnabled indicates whether the environment is meant to be started on a schedule
	OfflineScheduleEndEnabled() bool
	OfflineScheduleEndTime() time.Time

	// OfflineScheduleEndWeekends indicates whether the start schedule should only apply on weekdays
	OfflineScheduleEndWeekends() bool

	Destination
}

type EnvironmentFilter 

type EnvironmentFilter interface {
	// String returns a string representation of the filter
	String() string
	// Matches returns true if this filter matches the environment
	Matches(Environment) bool
	// And returns a new filter that matches this filter and another
	And(EnvironmentFilter) EnvironmentFilter
	// Or returns a new filter that matches this filter or another
	Or(EnvironmentFilter) EnvironmentFilter
	// Negate returns a new filter that matches the opposite of this filter
	Negate() EnvironmentFilter
	// Filter given a list of environments, return the sublist that match this filter
	Filter([]Environment) []Environment
}

An EnvironmentFilter is a predicate for filtering lists of environments

type Environments 

type Environments interface {
	// All returns a list of all environments
	All() ([]Environment, error)
	// Filter returns a list of environments matching the given filter
	Filter(filter EnvironmentFilter) ([]Environment, error)
	// Get returns the environment with the given name, or nil if no such environment exists
	Get(name string) (Environment, error)
	// Exists returns true if an environment by the given name exists
	Exists(name string) (bool, error)
	// CreateFromTemplate creates a new environment with the given options from the given template.
	// Must panic if the template environment's lifecycle is not "template".
	CreateFromTemplate(template Environment, opts CreateOptions) (string, error)
	// EnableRelease enables a release in an environment
	// TODO this should move to Environment at some point
	EnableRelease(environmentName string, releaseName string) error
	// DisableRelease disables a release in an environment
	// TODO this should move to Environment at some point
	DisableRelease(environmentName string, releaseName string) error
	// PinVersions sets a version override in the given environment
	// TODO this should move to Environment at some point
	PinVersions(environmentName string, versions map[string]VersionOverride) (map[string]VersionOverride, error)
	// UnpinVersions removes version overrides in the given environment
	// TODO this should move to Environment at some point
	UnpinVersions(environmentName string) (map[string]VersionOverride, error)
	// PinEnvironmentToTerraHelmfileRef pins an environment to a specific terra-helmfile ref
	// Note this can be overridden by individual service version overrides
	PinEnvironmentToTerraHelmfileRef(environmentName string, terraHelmfileRef string) error
	// Delete deletes the environment with the given name
	Delete(name string) error
	// SetOffline controls whether an environment is meant to be online or offline.
	SetOffline(name string, offline bool) error
}

Environments is an interface for querying and updating environments

type Fiab 

type Fiab interface {
	// IP returns the public IP address for the Fiab
	IP() string
	// Name returns the name of the Fiab
	Name() string
}

Fiab (DEPRECATED) represents a legacy Fiab ("firecloud-in-a-box") environment

func NewFiab 

func NewFiab(name string, ip string) Fiab

NewFiab constructor for a new Fiab

type Lifecycle 

type Lifecycle int

Lifecycle is an enum type that represents the different types of lifecycles a Terra environment can have 

const (
	// Static environments are long-lived environments that are created manually and never destroyed. `prod` is an example of a static environment.
	Static Lifecycle = iota
	// Template environments are never created or destroyed. They exist solely in configuration files, and are used to create dynamic environments.
	Template
	// Dynamic environments are created and destroyed on demand, from a template environment.
	Dynamic
)

func Lifecycles 

func Lifecycles() []Lifecycle

Lifecycles returns a slice of all Lifecycles

func (Lifecycle) Compare 

func (l Lifecycle) Compare(other Lifecycle) int

Compare returns 0 if r == other, -1 if r < other, or +1 if r > other.

func (*Lifecycle) FromString 

func (l *Lifecycle) FromString(value string) error

FromString will set the receiver's value to the one denoted by the given string

func (Lifecycle) IsDynamic 

func (l Lifecycle) IsDynamic() bool

func (Lifecycle) IsStatic 

func (l Lifecycle) IsStatic() bool

func (Lifecycle) IsTemplate 

func (l Lifecycle) IsTemplate() bool

func (Lifecycle) String 

func (l Lifecycle) String() string

func (*Lifecycle) UnmarshalYAML 

func (l *Lifecycle) UnmarshalYAML(value *yaml.Node) error

UnmarshalYAML is a custom unmarshaler so that the string "app" or "cluster" in a yaml file can be unmarshaled into a ReleaseType

type Named added in v1.0.6 

type Named interface {
	Name() string
}

Named is a top-level interface pulled into Release and Destination types. Having a separate interface representing this method means we can iterate over Release and Destination types the same.

type Release 

type Release interface {
	Named
	FullName() string
	Type() ReleaseType
	IsAppRelease() bool
	IsClusterRelease() bool
	ChartVersion() string
	ChartName() string
	Repo() string
	Namespace() string
	Cluster() Cluster
	ClusterName() string
	ClusterAddress() string
	Destination() Destination
	TerraHelmfileRef() string
	FirecloudDevelopRef() string
	HelmfileOverlays() []string
}

Release represents a deployed instance of a Helm chart, running in a Kubernetes cluster. The term comes from Helm.

type ReleaseFilter 

type ReleaseFilter interface {
	// String returns a string representation of the filter
	String() string
	// Matches returns true if this filter matches the release
	Matches(Release) bool
	// And returns a new filter that matches this filter and another
	And(ReleaseFilter) ReleaseFilter
	// Or returns a new filter that matches this filter or another
	Or(ReleaseFilter) ReleaseFilter
	// Negate returns a new filter that matches the opposite of this filter
	Negate() ReleaseFilter
	// Filter given a list of releases, return the sublist that match this filter
	Filter([]Release) []Release
}

A ReleaseFilter is a predicate for filtering lists of releases

type ReleaseType 

type ReleaseType int

ReleaseType is an enum type referring to the two types of releases supported by terra-helmfile. 

const (
	AppReleaseType ReleaseType = iota
	ClusterReleaseType
)

func ReleaseTypes 

func ReleaseTypes() []ReleaseType

func (ReleaseType) Compare 

func (r ReleaseType) Compare(other ReleaseType) int

Returns 0 if r == other, -1 if r < other, or +1 if r > other.

func (ReleaseType) String 

func (r ReleaseType) String() string

func (*ReleaseType) UnmarshalYAML 

func (r *ReleaseType) UnmarshalYAML(value *yaml.Node) error

UnmarshalYAML is a custom unmarshaler so that the string "app" or "cluster" in a yaml file can be unmarshaled into a ReleaseType

type Releases 

type Releases interface {
	// All returns a list of all releases
	All() ([]Release, error)
	// Filter filters releases
	Filter(filter ReleaseFilter) ([]Release, error)
}

Releases is an interface for querying releases

type State 

type State interface {
	// Destinations is an interface for querying terra.Destination instances
	Destinations() Destinations
	// Environments is an interface for querying terra.Environment instances
	Environments() Environments
	// Clusters is an interface for querying terra.Cluster instances
	Clusters() Clusters
	// Releases is an interface for querying terra.Release instances
	Releases() Releases
}

State is an interface for querying the state of Terra infrastructure.

type StateLoader 

type StateLoader interface {
	Load() (State, error)
	Reload() (State, error)
}

type StateWriter added in v0.0.63 

type StateWriter interface {
	WriteClusters([]Cluster) error
	// WriteEnvironments writes environments into thelma's state source it will return either a list of
	// newly created environment names if successful or an error
	WriteEnvironments([]Environment) ([]string, error)
	// Delete Environments is used to delete dynamic environments from Thelma's state source.
	// It returns a list of the names of deleted environments
	DeleteEnvironments([]Environment) ([]string, error)

	EnableRelease(Environment, string) error
	DisableRelease(string, string) error
}

StateWriteris an interface for exporting thelma's internal state to some external location currently this is sherlock but could also be a file or something else in the future

type VersionOverride added in v0.0.35 

type VersionOverride struct {
	AppVersion          string `json:"appVersion,omitempty" yaml:"appVersion,omitempty"`
	ChartVersion        string `json:"chartVersion,omitempty" yaml:"chartVersion,omitempty"`
	TerraHelmfileRef    string `json:"terraHelmfileRef,omitempty" yaml:"terraHelmfileRef,omitempty"`
	FirecloudDevelopRef string `json:"firecloudDevelopRef,omitempty" yaml:"firecloudDevelopRef,omitempty"`
}

VersionOverride represents version overrides for a release in an environment

Source Files

View all Source files

Directories

Path Synopsis

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.