runtime

package
v0.0.83 Latest Latest
Warning

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

 Go to latest Published: Nov 11, 2022 License: Apache-2.0 Imports: 27 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	FnServiceLivez  = "foundation.namespacelabs.dev/livez"
	FnServiceReadyz = "foundation.namespacelabs.dev/readyz"
)
View Source 
const (
	LocalBaseDomain = "nslocal.host"
	CloudBaseDomain = "nscloud.dev"
)
View Source 
const GrpcHttpTranscodeNode schema.PackageName = "namespacelabs.dev/foundation/std/grpc/httptranscoding"
View Source 
const LocalIngressPort = 40080

Variables

View Source 
var (
	NamingNoTLS = false // Set to true in CI.

	WorkInProgressUseShortAlias = false
)
View Source 
var ClusterInjection = execution.Define[Cluster]("ns.runtime.cluster")

ClusterInjection is used in execution.Execute to provide access to the cluster instance.

View Source 
var ClusterNamespaceInjection = execution.Define[ClusterNamespace]("ns.runtime.cluster-namespace")

Functions

func AttachComputedDomains 

func AttachComputedDomains(ctx context.Context, ws string, env cfg.Context, cluster Planner, sch *schema.Stack_Entry, template *schema.IngressFragment, allocatedName DomainsRequest) ([]*schema.IngressFragment, error)

func CalculateDomains 

func CalculateDomains(env *schema.Environment, computed *schema.ComputedNaming, allocatedName DomainsRequest) ([]*schema.Domain, error)

func ComputeIngress 

func ComputeIngress(ctx context.Context, env cfg.Context, planner Planner, sch *schema.Stack_Entry, allEndpoints []*schema.Endpoint) ([]*schema.IngressFragment, error)

func ComputeNaming 

func ComputeNaming(ctx context.Context, ws string, env cfg.Context, cluster Planner, source *schema.Naming) (*schema.ComputedNaming, error)

func DeployableCategory 

func DeployableCategory(spec Deployable) string

func DeployableToProto 

func DeployableToProto(spec Deployable) *runtimepb.Deployable

func HasRuntime 

func HasRuntime(name string) bool

func InjectCluster 

func InjectCluster(ns ClusterNamespace) []execution.InjectionInstance

func MaybeAllocateDomainCertificate 

func MaybeAllocateDomainCertificate(ctx context.Context, env *schema.Environment, entry *schema.Stack_Entry, template *schema.Domain) (*schema.Certificate, error)

func OwnedByDeployable 

func OwnedByDeployable(spec Deployable) string

func Prepare 

func Prepare(ctx context.Context, key string, env cfg.Configuration, cluster Cluster) (any, error)

func PrepareKeyed 

func PrepareKeyed(ctx context.Context, stateKey string, env cfg.Configuration, cluster Cluster, key string) (any, error)

func Register 

func Register(name string, r InstantiateClassFunc)

func RegisterKeyedPrepare 

func RegisterKeyedPrepare(key string, callback func(context.Context, cfg.Configuration, Cluster, string) (any, error))

func RegisterPrepare 

func RegisterPrepare(key string, callback func(context.Context, cfg.Configuration, Cluster) (any, error))

func RunAttached 

func RunAttached(ctx context.Context, config cfg.Context, cluster ClusterNamespace, spec DeployableSpec, io TerminalIO) error

func RunAttachedStdio 

func RunAttachedStdio(ctx context.Context, config cfg.Context, cluster ClusterNamespace, spec DeployableSpec) error

Types

type AttachableKind 

type AttachableKind string
const (
	AttachableKind_WITH_STDIN_ONLY AttachableKind = "stdin-only"
	AttachableKind_WITH_TTY        AttachableKind = "with-tty"
)

type Class 

type Class interface {
	// Attaches to an existing cluster. Fails if the cluster doesn't exist or
	// the provider used would have instantiated a new cluster.
	AttachToCluster(context.Context, cfg.Configuration) (Cluster, error)

	// Attaches to an existing cluster (if not is specified in the
	// configuration), or creates a new cluster as needed.
	EnsureCluster(context.Context, cfg.Configuration, string) (Cluster, error)
}

A runtime class represents a runtime implementation type, e.g. "kubernetes". The codebase seldom interacts with Class, but instead of Cluster instances obtained from a runtime class.

func ClassFor 

func ClassFor(ctx context.Context, env cfg.Context) (Class, error)

type Cluster 

type Cluster interface {
	// Returns a Planner implementation which emits deployment plans that target
	// a namespace within this cluster.
	Planner(cfg.Context) Planner

	// Returns a namespace'd cluster -- one for a particular application use,
	// bound to the workspace identified by the cfg.Context.
	Bind(cfg.Context) (ClusterNamespace, error)

	// Fetch diagnostics of a particular container reference.
	FetchDiagnostics(context.Context, *runtimepb.ContainerReference) (*runtimepb.Diagnostics, error)

	// Fetch logs of a specific container reference.
	FetchLogsTo(ctx context.Context, destination io.Writer, container *runtimepb.ContainerReference, opts FetchLogsOpts) error

	// Attaches to a running container.
	AttachTerminal(ctx context.Context, container *runtimepb.ContainerReference, io TerminalIO) error

	// Exposes the cluster's ingress, in the specified local address and port.
	// This is used to create stable localhost-bound ingress addresses (for e.g.
	// nslocal.host).
	ForwardIngress(ctx context.Context, localAddrs []string, localPort int, notify PortForwardedFunc) (io.Closer, error)

	// EnsureState ensures that a cluster-specific bit of initialization is done once per instance.
	EnsureState(context.Context, string) (any, error)

	// Deletes any runtime resource deployed by this runtime, regardless of
	// environment. If wait is true, waits until the target resources have been
	// removed. Returns true if resources were deleted.
	DeleteAllRecursively(ctx context.Context, wait bool, progress io.Writer) (bool, error)
}

A cluster represents a cluster where Namespace is capable of deployment one or more applications.

func ClusterFor 

func ClusterFor(ctx context.Context, env cfg.Context) (Cluster, error)

type ClusterNamespace 

type ClusterNamespace interface {
	// Returns a reference to the cluster where this namespace exists.
	Cluster() Cluster

	// Planner returns a Planner bound to the same namespace as this ClusterNamespace.
	Planner() Planner

	// DeployedConfigImageID retrieves the image reference of the "configuration
	// image" used to deploy the specified server. Configuration images are only
	// generated for production environments for now.
	DeployedConfigImageID(context.Context, Deployable) (oci.ImageID, error)

	// Returns a list of containers that the server has deployed.
	ResolveContainers(context.Context, Deployable) ([]*runtimepb.ContainerReference, error)

	// Fetch environment diagnostics, e.g. event list.
	FetchEnvironmentDiagnostics(context.Context) (*storage.EnvironmentDiagnostics, error)

	// Starts a new shell in the container of a previously deployed server. The
	// image of the server must contain the specified command. For ephemeral
	// containers, see #329.
	StartTerminal(ctx context.Context, server Deployable, io TerminalIO, command string, rest ...string) error

	// Forwards a single port.
	// XXX remove; callers should instead implement their own TCP net.Listener
	// and call DialServer as needed.
	ForwardPort(ctx context.Context, server Deployable, containerPort int32, localAddrs []string, notify SinglePortForwardedFunc) (io.Closer, error)

	// Dials a TCP port to one of the replicas of the target server. The
	// lifecycle of the connection is bound to the specified context.
	DialServer(ctx context.Context, server Deployable, containerPort int32) (net.Conn, error)

	// Observes lifecyle events of the specified server. Unless OneShot is set,
	// Observe runs until the context is cancelled.
	Observe(context.Context, Deployable, ObserveOpts, func(ObserveEvent) (bool, error)) error

	// WaitUntilReady blocks until the target deployable reports ready. If the
	// deployable represents a collection of replicas, readiness waits for all
	// replicas to become ready.
	WaitUntilReady(ctx context.Context, object Deployable) error

	// Waits until the specified deployable is no longer running (typically a one-shot).
	WaitForTermination(ctx context.Context, object Deployable) ([]ContainerStatus, error)

	// Deletes a previously deployed DeployableSpec.
	DeleteDeployable(ctx context.Context, deployable Deployable) error

	// Deletes the scoped environment, and all of its associated resources (e.g.
	// after a test invocation). If wait is true, waits until the target
	// resources have been removed. Returns true if resources were deleted.
	DeleteRecursively(ctx context.Context, wait bool) (bool, error)
}

ClusterNamespace represents a target deployment environment, scoped to an application (usually the combination of an environment and workspace).

func NamespaceFor 

func NamespaceFor(ctx context.Context, env cfg.Context) (ClusterNamespace, error)

type ContainerRunOpts 

type ContainerRunOpts struct {
	WorkingDir         string
	Image              oci.ImageID
	Command            []string
	Args               []string
	Env                []*schema.BinaryConfig_EnvEntry
	RunAs              *RunAs
	ReadOnlyFilesystem bool
	Mounts             []*schema.Mount
}

type ContainerStatus 

type ContainerStatus struct {
	Reference        *runtimepb.ContainerReference
	TerminationError error
}

type Deployable 

type Deployable interface {
	GetPackageRef() *schema.PackageRef

	GetId() string

	GetName() string

	// Returns a string to be compatible with the proto API.
	GetDeployableClass() string // schema.DeployableClass
}

type DeployableSpec 

type DeployableSpec struct {
	ErrorLocation fnerrors.Location

	PackageRef *schema.PackageRef
	Focused    bool // Set to true if the user explicitly asked for this object to be deployed.
	Attachable AttachableKind

	Description string
	Class       schema.DeployableClass
	Id          string // Must not be empty.
	Name        string // Can be empty.
	Volumes     []*schema.Volume

	MainContainer ContainerRunOpts
	Sidecars      []SidecarRunOpts
	Inits         []SidecarRunOpts

	ConfigImage   *oci.ImageID
	RuntimeConfig *runtimepb.RuntimeConfig
	BuildVCS      *runtimepb.BuildVCS
	Resources     []*resources.ResourceDependency

	// The list of primitive std/runtime:Secret that this server deployable on.
	// These are treated in a special way: each one of them is mounted under
	// /namespace/secrets automatically, and the corresponding SecretInstance
	// entries are generated by the runtime-specific planner.
	SecretResources []SecretResourceDependency

	// Where to mount the runtime configuration; if unset, the runtime
	// configuration is not persisted, and not mounted.
	MountRuntimeConfigPath string

	SetContainerField []*runtimepb.SetContainerField

	Extensions []*schema.DefExtension

	Endpoints         []*schema.Endpoint         // Owned by this deployable.
	InternalEndpoints []*schema.InternalEndpoint // Owned by this deployable.
}

func (DeployableSpec) GetDeployableClass 

func (d DeployableSpec) GetDeployableClass() string

func (DeployableSpec) GetId 

func (d DeployableSpec) GetId() string

func (DeployableSpec) GetName 

func (d DeployableSpec) GetName() string

func (DeployableSpec) GetPackageName 

func (d DeployableSpec) GetPackageName() string

func (DeployableSpec) GetPackageRef added in v0.0.83 

func (d DeployableSpec) GetPackageRef() *schema.PackageRef

type DeploymentPlan 

type DeploymentPlan struct {
	Definitions []*schema.SerializedInvocation
	Hints       []string

	// A unique ID that is consistent across invocations, for the same runtime,
	// that represents a tenant namespace.
	NamespaceReference string
}

type DeploymentSpec 

type DeploymentSpec struct {
	Specs   []DeployableSpec
	Secrets GroundedSecrets
}

type DomainsRequest 

type DomainsRequest struct {
	ServerID    string
	ServiceName string
	Key         string // Usually `{ServiceName}-{ServerID}`
	Alias       string

	// Set to true if the service we're allocating a domain for should be TLS
	// terminated, regardless of whether we can emit a public-CA rooted
	// certificate or not. E.g. for gRPC.
	TlsInclusterTermination bool
}

type EndpointPortForwarder 

type EndpointPortForwarder interface {
	io.Closer
	Update([]*schema.Endpoint)
}

type ErrContainerExitStatus 

type ErrContainerExitStatus struct {
	ExitCode int32
}

func (ErrContainerExitStatus) Error 

func (e ErrContainerExitStatus) Error() string

type ErrContainerFailed 

type ErrContainerFailed struct {
	Name     string
	Failures []ErrContainerFailed_Failure
}

func (ErrContainerFailed) Error 

func (e ErrContainerFailed) Error() string

type ErrContainerFailed_Failure 

type ErrContainerFailed_Failure struct {
	Reference *runtimepb.ContainerReference // A pointer that can be passed to the runtime to fetch logs.
	Reason    string
	Message   string
	ExitCode  int32
}

type FetchLogsOpts 

type FetchLogsOpts struct {
	TailLines         int // Only used if it's a positive value.
	Follow            bool
	FetchLastFailure  bool
	IncludeTimestamps bool
}

type ForwardedPort 

type ForwardedPort struct {
	LocalPort     uint
	ContainerPort uint
}

type ForwardedPortEvent 

type ForwardedPortEvent struct {
	Endpoint *schema.Endpoint

	Added   []ForwardedPort
	Removed bool
	Error   error
}

type GroundedSecret 

type GroundedSecret struct {
	Ref   *schema.PackageRef
	Spec  *schema.SecretSpec
	Value *schema.FileContents
}

type GroundedSecrets 

type GroundedSecrets struct {
	Secrets []GroundedSecret
}

func (GroundedSecrets) Get 

func (g GroundedSecrets) Get(ref *schema.PackageRef) *GroundedSecret

type InstantiateClassFunc 

type InstantiateClassFunc func(context.Context, cfg.Configuration) (Class, error)

type ObserveEvent 

type ObserveEvent struct {
	Deployable         *runtimepb.Deployable
	ContainerReference *runtimepb.ContainerReference
	Version            string
	Added              bool
	Removed            bool
}

type ObserveOpts 

type ObserveOpts struct {
}

type Planner 

type Planner interface {
	// Plans a deployment, i.e. produces a series of instructions that will
	// instantiate the required deployment resources to run the servers in the
	// specified Deployment. This method is side-effect free; mutations are
	// applied when the generated plan is applied.
	PlanDeployment(context.Context, DeploymentSpec) (*DeploymentPlan, error)

	// Plans an ingress deployment, i.e. produces a series of instructions that
	// will instantiate the required deployment resources to run the servers
	// with the specified Ingresses. This method is side-effect free; mutations
	// are applied when the generated plan is applied.
	PlanIngress(context.Context, *schema.Stack, []*schema.IngressFragment) (*DeploymentPlan, error)

	// PrepareProvision is called before invoking a provisioning tool, to offer
	// the runtime implementation a way to pass runtime-specific information to
	// the tool. E.g. what's the Kubernetes namespace we're working with.
	// XXX move to planner.
	PrepareProvision(context.Context) (*rtypes.ProvisionProps, error)

	// ComputeBaseNaming returns a base naming configuration that is specific
	// to the target runtime (e.g. kubernetes cluster).
	ComputeBaseNaming(*schema.Naming) (*schema.ComputedNaming, error)

	// Returns the set of platforms that the target runtime operates on, e.g. linux/amd64.
	TargetPlatforms(context.Context) ([]specs.Platform, error)
}

A planner is capable of generating namespace-specific deployment plans. It may obtain external data in order to produce a plan, but none of its methods mutate outside state in order to do so.

func PlannerFor 

func PlannerFor(ctx context.Context, env cfg.Context) (Planner, error)

type PortForwardedFunc 

type PortForwardedFunc func(ForwardedPortEvent)

type RunAs 

type RunAs struct {
	UserID  string
	FSGroup *string
}

type SecretResourceDependency 

type SecretResourceDependency struct {
	SecretRef   *schema.PackageRef
	ResourceRef *schema.PackageRef
	Spec        *schema.SecretSpec
}

type SidecarRunOpts 

type SidecarRunOpts struct {
	Name      string
	BinaryRef *schema.PackageRef
	ContainerRunOpts
}

type SinglePortForwardedFunc 

type SinglePortForwardedFunc func(ForwardedPort)

type TerminalIO 

type TerminalIO struct {
	TTY bool

	Stdin  io.Reader
	Stdout io.Writer
	Stderr io.Writer

	// Optional. If set, a runtime can listen on this channel for terminal resize requests.
	ResizeQueue chan termios.WinSize
}

Source Files

View all Source files

Directories

Path Synopsis
install
client
helm
kubeobserver
kubeops
kubeparser
networking/ingress
networking/ingress/nginx
toolsonk8s

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.