Documentation
¶
Index ¶
- Constants
- Variables
- func AttachComputedDomains(ctx context.Context, ws string, env cfg.Context, cluster Planner, ...) ([]*schema.IngressFragment, error)
- func CalculateDomains(env *schema.Environment, computed *schema.ComputedNaming, ...) ([]*schema.Domain, error)
- func ComputeIngress(ctx context.Context, env cfg.Context, planner Planner, sch *schema.Stack_Entry, ...) ([]*schema.IngressFragment, error)
- func ComputeNaming(ctx context.Context, moduleName string, env cfg.Context, planner Planner, ...) (*schema.ComputedNaming, error)
- func DeployableCategory(spec Deployable) string
- func DeployableToProto(spec Deployable) *runtimepb.Deployable
- func HasRuntime(name string) bool
- func InjectCluster(ns ClusterNamespace) execution.MakeInjectionInstance
- func OwnedByDeployable(spec Deployable) string
- func Prepare(ctx context.Context, key string, env cfg.Configuration, cluster Cluster) (any, error)
- func PrepareKeyed(ctx context.Context, stateKey string, env cfg.Configuration, cluster Cluster, ...) (any, error)
- func Register(name string, r InstantiateClassFunc)
- func RegisterKeyedPrepare(key string, ...)
- func RegisterPrepare(key string, ...)
- func ResolveResolvables[V LikeResolvable](ctx context.Context, rt *runtimepb.RuntimeConfig, ...) error
- func RunAttached(ctx context.Context, config cfg.Context, planner Planner, spec DeployableSpec, ...) error
- func RunAttachedStdio(ctx context.Context, config cfg.Context, planner Planner, spec DeployableSpec) error
- func SelectInstance(rt *runtimepb.RuntimeConfig, instance *schema.ResolvableSource) (any, error)
- func SelectService(rt *runtimepb.RuntimeConfig, ref *schema.ServiceRef) (*runtimepb.Server_Service, error)
- func SelectServiceEndpoint(svc *runtimepb.Server_Service) (string, error)
- func SelectServiceIngress(service *runtimepb.Server_Service) (string, error)
- func SelectServiceValue(rt *runtimepb.RuntimeConfig, ref *schema.ServiceRef, ...) (string, error)
- func WriteToWriter(w io.Writer) func(ContainerLogLine)
- func WriteToWriterWithTimestamps(w io.Writer) func(ContainerLogLine)
- type AttachableKind
- type Class
- type Cluster
- type ClusterNamespace
- type ComputedResource
- type ContainerLogLine
- type ContainerLogLineEvent
- type ContainerRunOpts
- type ContainerStatus
- type Deployable
- type DeployableSpec
- type DeploymentPlan
- type DeploymentSpec
- type DomainsRequest
- type EndpointPortForwarder
- type ErrContainerExitStatus
- type ErrContainerFailed
- type ErrContainerFailed_Failure
- type FetchLogsOpts
- type ForwardedPort
- type ForwardedPortEvent
- type IngressClass
- type InstantiateClassFunc
- type LikeResolvable
- type ObserveEvent
- type ObserveOpts
- type Planner
- type PortForwardedFunc
- type ResolvableSecretSource
- type ResolvableSink
- type ResolvableSinkMap
- func (x *ResolvableSinkMap) SetExperimentalFromDownwardsFieldPath(key, value string) error
- func (x *ResolvableSinkMap) SetLateBoundResourceFieldSelector(key string, _ runtimepb.SetContainerField_ValueSource, ...) error
- func (x *ResolvableSinkMap) SetSecret(key string, secret *SecretRef) error
- func (x *ResolvableSinkMap) SetValue(key, value string) error
- type RunAs
- type SecretRef
- type SecretResourceDependency
- type SidecarRunOpts
- type SinglePortForwardedFunc
- type TerminalIO
Constants ¶
const ( FnServiceLivez = "foundation.namespacelabs.dev/livez" FnServiceReadyz = "foundation.namespacelabs.dev/readyz" )
const LocalIngressPort = 40080
Variables ¶
var ( NamingNoTLS = false // Set to true in CI. WorkInProgressUseShortAlias = false )
var ClusterInjection = execution.Define[Cluster]("ns.runtime.cluster")
ClusterInjection is used in execution.Execute to provide access to the cluster instance.
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 ComputeNaming ¶
func DeployableCategory ¶
func DeployableCategory(spec Deployable) string
func DeployableToProto ¶
func DeployableToProto(spec Deployable) *runtimepb.Deployable
func HasRuntime ¶
func InjectCluster ¶
func InjectCluster(ns ClusterNamespace) execution.MakeInjectionInstance
func OwnedByDeployable ¶
func OwnedByDeployable(spec Deployable) string
func PrepareKeyed ¶
func Register ¶
func Register(name string, r InstantiateClassFunc)
func RegisterKeyedPrepare ¶
func RegisterPrepare ¶
func ResolveResolvables ¶ added in v0.0.167
func ResolveResolvables[V LikeResolvable](ctx context.Context, rt *runtimepb.RuntimeConfig, secrets ResolvableSecretSource, resolvables []V, out ResolvableSink) error
func RunAttached ¶
func RunAttached(ctx context.Context, config cfg.Context, planner Planner, spec DeployableSpec, io TerminalIO) error
func RunAttachedStdio ¶
func SelectInstance ¶ added in v0.0.167
func SelectInstance(rt *runtimepb.RuntimeConfig, instance *schema.ResolvableSource) (any, error)
func SelectService ¶ added in v0.0.116
func SelectService(rt *runtimepb.RuntimeConfig, ref *schema.ServiceRef) (*runtimepb.Server_Service, error)
func SelectServiceEndpoint ¶ added in v0.0.116
func SelectServiceEndpoint(svc *runtimepb.Server_Service) (string, error)
func SelectServiceIngress ¶ added in v0.0.116
func SelectServiceIngress(service *runtimepb.Server_Service) (string, error)
func SelectServiceValue ¶ added in v0.0.116
func SelectServiceValue(rt *runtimepb.RuntimeConfig, ref *schema.ServiceRef, selector func(*runtimepb.Server_Service) (string, error)) (string, error)
func WriteToWriter ¶ added in v0.0.92
func WriteToWriter(w io.Writer) func(ContainerLogLine)
func WriteToWriterWithTimestamps ¶ added in v0.0.92
func WriteToWriterWithTimestamps(w io.Writer) func(ContainerLogLine)
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.Context, string) (Cluster, error) // Planner produces a planner for this runtime class. This may instantiate a // new cluster, but will attempt to do so lazily. Planner(context.Context, cfg.Context, string) (Planner, 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.
type Cluster ¶
type Cluster interface { // Returns a namespace'd cluster -- one for a particular application use, // bound to the workspace identified by the cfg.Context. Bind(context.Context, 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, container *runtimepb.ContainerReference, opts FetchLogsOpts, callback func(ContainerLogLine)) 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) // EnsureState ensures that a cluster-specific bit of initialization is done once per instance. EnsureKeyedState(context.Context, string, 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.
type ClusterNamespace ¶
type ClusterNamespace interface { // Returns a reference to the cluster where this namespace exists. Cluster() Cluster // 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, port *schema.Endpoint_Port) (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 ¶
type ComputedResource ¶ added in v0.0.117
type ComputedResource struct { ResourceInstanceID string InstanceType *schema.ResourceType InstanceSerializedJSON []byte }
A resource whose instance is known.
type ContainerLogLine ¶ added in v0.0.92
type ContainerLogLineEvent ¶ added in v0.0.92
type ContainerLogLineEvent string
const ( ContainerLogLineEvent_LogLine ContainerLogLineEvent = "ns.logline" ContainerLogLineEvent_Connected ContainerLogLineEvent = "ns.connected" ContainerLogLineEvent_Resuming ContainerLogLineEvent = "ns.resuming" )
type ContainerRunOpts ¶
type ContainerRunOpts struct { WorkingDir string Image oci.ImageID Command []string Args []string Env []*schema.BinaryConfig_EnvEntry RunAs *RunAs ReadOnlyFilesystem bool Privileged bool HostNetwork bool Capabilities []string Mounts []*schema.Mount ContainerPorts []*schema.Endpoint_Port ResourceLimits *schema.Container_ResourceLimits ResourceRequests *schema.Container_ResourceLimits TerminationGracePeriodSeconds int64 }
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 Permissions *schema.ServerPermissions Replicas int32 Tolerations []*schema.Server_Toleration Annotations []*schema.NamedResolvable // Annotations that apply to individual pods. NodeSelector []*schema.NodeSelectorItem MainContainer ContainerRunOpts Sidecars []SidecarRunOpts Inits []SidecarRunOpts ConfigImage *oci.ImageID RuntimeConfig *runtimepb.RuntimeConfig BuildVCS *runtimepb.BuildVCS ResourceDeps []*resources.ResourceDependency PlannedResourceDeps []*resources.ResourceDependency ComputedResources []ComputedResource Secrets secrets.GroundedSecrets // The list of primitive std/runtime:Secret that this deployable depends 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. Probes []*schema.Probe }
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
}
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. RequiresTLS bool UserSpecified []*schema.DomainSpec }
type EndpointPortForwarder ¶
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 ForwardedPort ¶
type ForwardedPortEvent ¶
type ForwardedPortEvent struct { Endpoint *schema.Endpoint Added []ForwardedPort Removed bool Error error }
type IngressClass ¶ added in v0.0.113
type IngressClass interface { Name() string // ComputeBaseNaming returns a base naming configuration that is specific // to the target runtime (e.g. kubernetes cluster). ComputeNaming(context.Context, *schema.Environment, *schema.Naming) (*schema.ComputedNaming, error) }
type InstantiateClassFunc ¶
type LikeResolvable ¶ added in v0.0.167
type LikeResolvable interface { GetName() string GetValue() *schema.Resolvable }
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. PrepareProvision(context.Context) (*rtypes.RuntimeProvisionProps, error) // Returns the set of platforms that the target runtime operates on, e.g. linux/amd64. TargetPlatforms(context.Context) ([]specs.Platform, error) // The registry we should upload to. Registry() registry.Manager // The ingress class this runtime implementation uses. Ingress() IngressClass // Returns DNS-resolvable names for a particular service; the first one // being a short-hand usable within the same namespace, and the latter being // a fully qualified domain name. MakeServiceName(string) (string, string) EnsureClusterNamespace(context.Context) (ClusterNamespace, 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.
type PortForwardedFunc ¶
type PortForwardedFunc func(ForwardedPortEvent)
type ResolvableSecretSource ¶ added in v0.0.167
type ResolvableSink ¶ added in v0.0.167
type ResolvableSink interface { SetValue(key, value string) error SetSecret(key string, secret *SecretRef) error SetExperimentalFromDownwardsFieldPath(key, value string) error // XXX replace with late bound FieldSelector. SetLateBoundResourceFieldSelector(key string, _ runtimepb.SetContainerField_ValueSource, src *schema.ResourceConfigFieldSelector) error }
type ResolvableSinkMap ¶ added in v0.0.167
func (*ResolvableSinkMap) SetExperimentalFromDownwardsFieldPath ¶ added in v0.0.167
func (x *ResolvableSinkMap) SetExperimentalFromDownwardsFieldPath(key, value string) error
func (*ResolvableSinkMap) SetLateBoundResourceFieldSelector ¶ added in v0.0.167
func (x *ResolvableSinkMap) SetLateBoundResourceFieldSelector(key string, _ runtimepb.SetContainerField_ValueSource, src *schema.ResourceConfigFieldSelector) error
func (*ResolvableSinkMap) SetSecret ¶ added in v0.0.167
func (x *ResolvableSinkMap) SetSecret(key string, secret *SecretRef) error
func (*ResolvableSinkMap) SetValue ¶ added in v0.0.167
func (x *ResolvableSinkMap) SetValue(key, value string) error
type SecretResourceDependency ¶
type SecretResourceDependency struct { SecretRef *schema.PackageRef ResourceRef *schema.PackageRef }
type SidecarRunOpts ¶
type SidecarRunOpts struct { Name string BinaryRef *schema.PackageRef ContainerRunOpts }
type SinglePortForwardedFunc ¶
type SinglePortForwardedFunc func(ForwardedPort)