app

package
v0.0.0-...-3bfe646 Latest Latest
Warning

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

 Go to latest Published: Jun 28, 2023 License: Apache-2.0 Imports: 20 Imported by: 15

README

Application Format

Gravity application is a tarball, i.e. any .tar.gz file. The file has the following structure:

app.tar.gz
  ├── registry
  │   └── docker
  │       └── registry
  │           └── v2 ...
  │           ... 
  └── resources
      ├── app.yaml
      └── skydns.yaml

Only the registry and resources directories are mandatory, the rest is application-specific.

In this example:

  1. registry stores docker image layers in the registry v2 format. See assets/dns-app/Makefile to get an understanding about how it is produced.
  2. resources contains the application manifest.

The rest is application-specific.

Documentation

Overview

Package app implements gravity application support for import and configuration and management

Index

Constants

View Source 
const (
	// DefaultNamespace is the name of the default application namespace.
	DefaultNamespace = "default"

	// LabelName defines the name label every application resource is annotated with
	LabelName = "g-app-name"
	// LabelVersion defines the version label every application resource is annotated with
	LabelVersion = "g-app-ver"

	// AppOperationImport defines an application import operation type
	AppOperationImport = "operation_app_import"
)

Variables

View Source 
var (
	// OptionalDependencies specifies what dependencies can be disabled
	OptionalDependencies = []loc.Locator{
		{Name: defaults.LoggingAppName},
		{Name: defaults.MonitoringAppName},
		{Name: defaults.IngressAppName},
		{Name: defaults.TillerAppName},
		{Name: defaults.StorageAppName},
		{Name: defaults.BandwagonPackageName},
	}
)

Functions

func AppsToExclude 

func AppsToExclude(manifest schema.Manifest) []loc.Locator

AppsToExclude returns a list of apps that should be excluded

func CheckHasAppHook 

func CheckHasAppHook(apps Applications, req HookRunRequest) (*schema.Hook, error)

CheckHasAppHook checks if the app has specified hook

func DeleteAppHookJob 

func DeleteAppHookJob(ctx context.Context, client *kubernetes.Clientset, req DeleteAppHookJobRequest) error

DeleteAppHookJob deletes app hook job

func GetDirectDeps 

func GetDirectDeps(app Application) (deps []loc.Locator, err error)

GetDirectDeps returns the direct application dependencies, without base app resolution

func GetUpdatedDependencies 

func GetUpdatedDependencies(installed, update Application, installedManifest, updateManifest schema.Manifest) ([]loc.Locator, error)

GetUpdatedDependencies compares dependencies of the "installed" and "update" apps and returns locators of updated (or new) dependencies.

Only direct dependencies are compared, without base app resolution.

func StreamAppHookLogs 

func StreamAppHookLogs(ctx context.Context, client *kubernetes.Clientset, ref HookRef, out io.Writer) error

StreamAppHookLogs streams app hook logs to output writer, this is a blocking call

func Unwrap 

func Unwrap(deps []schema.Dependency) (result []loc.Locator)

Unwrap unwraps []Locator from []Dependency

func VerifyDependencies 

func VerifyDependencies(app *Application, apps Applications, packages pack.PackageService) error

VerifyDependencies verifies that the specified application app has all the dependent packages available in the provided package service

func WaitAppHook 

func WaitAppHook(ctx context.Context, client *kubernetes.Clientset, ref HookRef) error

WaitAppHook waits for app hook to complete or fail

func Wrap 

func Wrap(locators []loc.Locator) (result []schema.Dependency)

Wrap wraps a []Locator into []Dependency

Types

type Application 

type Application struct {
	// Package identifies the application package
	Package loc.Locator `json:"package"`
	// PackageEnvelope is the complete underlying package information
	PackageEnvelope pack.PackageEnvelope `json:"envelope"`
	// Manifest defines the application install configuration
	Manifest schema.Manifest `json:"manifest"`
}

Application defines a Gravity application 

var Phony *Application

Phony describes a broken application reference. It is used to refer to missing applications in sites that have invalid application reference. This is a temporary measure in absence of the enforcing FOREIGN KEY constraint to bridge the transition to when it is either possible to update an application in-use or application packages are never invalidated (and instead new versions are released)

func (Application) Name 

func (a Application) Name() string

Name returns the application name

func (Application) Namespace 

func (a Application) Namespace() string

Namespace returns the application namespace

func (Application) RequiresLicense 

func (a Application) RequiresLicense() bool

RequiresLicense returns true/false depending on whether the app allows some or all of its flavors to work without a license

func (Application) String 

func (a Application) String() string

String formats the specified application for output

type Applications 

type Applications interface {
	Operations

	// ListApps lists applications of given type in the specified repository.
	// If the repository is empty, all applications are listed.
	ListApps(ListAppsRequest) ([]Application, error)

	// GetApp obtains an application specified with locator.
	// If no application can be found, nil is returned.
	GetApp(locator loc.Locator) (*Application, error)

	// GetAppResources obtains application resources,
	// if the app does not exist, returns NotFound
	GetAppResources(locator loc.Locator) (io.ReadCloser, error)

	// ExportApp exports the containers of an existing application
	// to the docker registry specified in the request
	ExportApp(ExportAppRequest) error

	// UninstallApp uninstalls a running application from the local cluster
	UninstallApp(locator loc.Locator) (*Application, error)

	// StatusApp retrieves the status of a running application
	StatusApp(locator loc.Locator) (*Status, error)

	// CreateApp creates a new application from the specified package bytes (reader)
	// and an optional set of package labels using locator as destination for the
	// resulting package
	CreateApp(locator loc.Locator, reader io.Reader, labels map[string]string) (*Application, error)

	// CreateAppWithManifest creates a new application from the specified package bytes (reader)
	// and an optional set of package labels using locator as destination for the
	// resulting package, with supplied manifest
	CreateAppWithManifest(locator loc.Locator, manifest []byte, reader io.Reader, labels map[string]string) (*Application, error)

	// UpsertApp creates a new application or updates the existing one
	UpsertApp(locator loc.Locator, reader io.Reader, labels map[string]string) (*Application, error)

	// DeleteApp deletes an application record
	DeleteApp(DeleteRequest) error

	// GetAppManifest returns a reader to the application
	// manifest
	GetAppManifest(locator loc.Locator) (io.ReadCloser, error)

	// GetAppInstaller builds an installer package for the
	// specified application and returns a reader to the package
	// compressed as gzipped tar archive
	GetAppInstaller(InstallerRequest) (io.ReadCloser, error)

	// StartAppHook starts application hook specified with req asynchronously
	StartAppHook(ctx context.Context, req HookRunRequest) (*HookRef, error)

	// WaitAppHook waits for app hook to complete or fail
	WaitAppHook(ctx context.Context, ref HookRef) error

	// DeleteAppHookJob deletes app hook job
	DeleteAppHookJob(ctx context.Context, req DeleteAppHookJobRequest) error

	// StreamAppHookLogs streams app hook logs to output writer, this is a blocking call
	StreamAppHookLogs(ctx context.Context, ref HookRef, out io.Writer) error

	// FetchChart returns Helm chart package with the specified application.
	FetchChart(loc.Locator) (io.ReadCloser, error)

	// FetchIndexFile returns Helm chart repository index file data.
	FetchIndexFile() (io.Reader, error)
}

Applications manages a collection of applications

func ApplicationsWithACL 

func ApplicationsWithACL(applications Applications, users users.Users, user storage.User, checker teleservices.AccessChecker) Applications

ApplicationsWithACL returns an instance of the Applications interface with the specified security context

type ApplicationsACL 

type ApplicationsACL struct {
	// contains filtered or unexported fields
}

ApplicationsACL defines a security aware wrapper around Applications

func (*ApplicationsACL) CreateApp 

func (r *ApplicationsACL) CreateApp(locator loc.Locator, reader io.Reader, labels map[string]string) (*Application, error)

func (*ApplicationsACL) CreateAppWithManifest 

func (r *ApplicationsACL) CreateAppWithManifest(locator loc.Locator, manifest []byte, reader io.Reader, labels map[string]string) (*Application, error)

CreateAppWithManifest creates a new application from the specified package bytes (reader) and an optional set of package labels using locator as destination for the resulting package, with supplied manifest

func (*ApplicationsACL) CreateImportOperation 

func (r *ApplicationsACL) CreateImportOperation(req *ImportRequest) (*storage.AppOperation, error)

func (*ApplicationsACL) DeleteApp 

func (r *ApplicationsACL) DeleteApp(req DeleteRequest) error

func (*ApplicationsACL) DeleteAppHookJob 

func (r *ApplicationsACL) DeleteAppHookJob(ctx context.Context, req DeleteAppHookJobRequest) error

DeleteAppHookJob deletes app hook job to complete or fail

func (*ApplicationsACL) ExportApp 

func (r *ApplicationsACL) ExportApp(req ExportAppRequest) error

func (*ApplicationsACL) FetchChart 

func (r *ApplicationsACL) FetchChart(locator loc.Locator) (io.ReadCloser, error)

FetchChart returns Helm chart package with the specified application.

func (*ApplicationsACL) FetchIndexFile 

func (r *ApplicationsACL) FetchIndexFile() (io.Reader, error)

FetchIndexFile returns Helm chart repository index file data.

func (*ApplicationsACL) GetApp 

func (r *ApplicationsACL) GetApp(locator loc.Locator) (*Application, error)

func (*ApplicationsACL) GetAppInstaller 

func (r *ApplicationsACL) GetAppInstaller(req InstallerRequest) (io.ReadCloser, error)

func (*ApplicationsACL) GetAppManifest 

func (r *ApplicationsACL) GetAppManifest(locator loc.Locator) (io.ReadCloser, error)

func (*ApplicationsACL) GetAppResources 

func (r *ApplicationsACL) GetAppResources(locator loc.Locator) (io.ReadCloser, error)

func (*ApplicationsACL) GetImportedApplication 

func (r *ApplicationsACL) GetImportedApplication(op storage.AppOperation) (*Application, error)

func (*ApplicationsACL) GetOperationCrashReport 

func (r *ApplicationsACL) GetOperationCrashReport(op storage.AppOperation) (io.ReadCloser, error)

func (*ApplicationsACL) GetOperationLogs 

func (r *ApplicationsACL) GetOperationLogs(op storage.AppOperation) (io.ReadCloser, error)

func (*ApplicationsACL) GetOperationProgress 

func (r *ApplicationsACL) GetOperationProgress(op storage.AppOperation) (*ProgressEntry, error)

func (*ApplicationsACL) ListApps 

func (r *ApplicationsACL) ListApps(req ListAppsRequest) ([]Application, error)

func (*ApplicationsACL) StartAppHook 

func (r *ApplicationsACL) StartAppHook(ctx context.Context, req HookRunRequest) (*HookRef, error)

StartAppHook starts application hook specified with req asynchronously

func (*ApplicationsACL) StatusApp 

func (r *ApplicationsACL) StatusApp(locator loc.Locator) (*Status, error)

func (*ApplicationsACL) StreamAppHookLogs 

func (r *ApplicationsACL) StreamAppHookLogs(ctx context.Context, ref HookRef, out io.Writer) error

StreamAppHookLogs streams app hook logs to output writer, this is a blocking call

func (*ApplicationsACL) UninstallApp 

func (r *ApplicationsACL) UninstallApp(locator loc.Locator) (*Application, error)

func (*ApplicationsACL) UpsertApp 

func (r *ApplicationsACL) UpsertApp(locator loc.Locator, reader io.Reader, labels map[string]string) (*Application, error)

func (*ApplicationsACL) WaitAppHook 

func (r *ApplicationsACL) WaitAppHook(ctx context.Context, ref HookRef) error

WaitAppHook waits for app hook to complete or fail

type DeleteAppHookJobRequest 

type DeleteAppHookJobRequest struct {
	// HookRef is the hook job reference.
	HookRef
	// Cascade specifies whether dependent pods should be deleted as well.
	Cascade bool `json:"cascade"`
}

DeleteAppHookJobRequest is a request to delete a hook job.

type DeleteRequest 

type DeleteRequest struct {
	// Package is the app package
	Package loc.Locator
	// Force allows to ignore constraints during deletion
	Force bool
}

DeleteRequest describes a request to delete an application

type Dependencies 

type Dependencies struct {
	// Packages defines a set of package dependencies
	Packages []loc.Locator
	// Apps defines a set of application package dependencies
	Apps []loc.Locator
}

Dependencies defines a set of package and application dependencies for an application

func GetDependencies 

func GetDependencies(app *Application, apps Applications) (result *Dependencies, err error)

GetDependencies transitively collects dependencies for the specified application package

type ExportAppRequest 

type ExportAppRequest struct {
	// Package represents the package name and version to be exported
	Package loc.Locator

	// RegistryAddress specifies a registry address to export the application
	// images to.
	//
	// Either a registry address or a local directory can be specified, not both.
	RegistryAddress string

	// CertName represents the name of the certificate to use for TLS connecting to the registry
	CertName string
}

ExportAppRequest defines a set of parameters for exporting an application to a docker registry

type HookRef 

type HookRef struct {
	// Application identifies the application package to run hook for
	Application loc.Locator `json:"application"`
	// Hook identifies the hook type to run
	Hook schema.HookType `json:"hook"`
	// Namespace is a resource namespace
	Namespace string `json:"namespace"`
	// Name is a resource name
	Name string `json:"name"`
}

HookRef is a reference to a hook running as a kubernetes job

func RunAppHook 

func RunAppHook(ctx context.Context, apps Applications, req HookRunRequest) (*HookRef, []byte, error)

RunAppHook launches the specified hook, waits for its completion and returns its output and job reference

func StreamAppHook 

func StreamAppHook(ctx context.Context, apps Applications, req HookRunRequest, wc io.WriteCloser) (*HookRef, error)

StreamAppHook launches the specified hook and starts streaming its output into the provided writer until the job completes

type HookRunRequest 

type HookRunRequest struct {
	// Application identifies the application package to run hook for
	Application loc.Locator `json:"application"`
	// Hook defines the hook to run
	Hook schema.HookType `json:"hook"`
	// Volumes lists additional volumes to add inside a hook's job container
	Volumes []v1.Volume `json:"volumes"`
	// VolumeMounts lists additional volume mounts to create inside a hook's job container
	VolumeMounts []v1.VolumeMount `json:"volume_mounts"`
	// NodeSelector defines a set of labels to use to select a node for this hook's job.
	// If unspecified - the default behavior is to schedule job on a master node
	NodeSelector map[string]string `json:"node_selector"`
	// Env defines additional environment variables to pass to the hook job
	Env map[string]string `json:"env"`
	// Values are helm values in a marshaled yaml format
	Values []byte `json:"values,omitempty"`
	// SkipInitContainers skips injection of init containers
	SkipInitContainers bool `json:"skip_init_containers"`
	// HostNetwork specifies whether the hook job runs in host network namespace
	HostNetwork bool `json:"host_network"`
	// Timeout allows to set timeout for the hook job to override default value
	// or value from manifest
	Timeout time.Duration `json:"timeout"`
	// GravityPackage specifies the gravity binary package to run hook with.
	// If empty, the hooks will use the binary from host.
	GravityPackage loc.Locator `json:"gravity_package"`
	// ServiceUser specifies a user for system services inside the planet container.
	// Also some system kubernetes resources are executed in the context of the
	// service user unless permission elevation is necessary.
	//
	// The application resources that do not require explicit permission elevation
	// should use a special placeholder user ID (defaults.PlaceholderServiceUserID)
	// which will be replaced with the ID of the effective service user during
	// installation and when running application hooks.
	ServiceUser storage.OSUser
}

HookRunRequest defines a request to run a specific application hook

func (HookRunRequest) Check 

func (r HookRunRequest) Check() error

Check validates this request

type ImportRequest 

type ImportRequest struct {
	// Source defines the source of the application data
	Source io.ReadCloser `json:"-"`
	// Repository is an optional repository name, overrides the one specified in the app manifest
	Repository string `json:"repository"`
	// PackageName is an optional app name, overrides the one specified in the app manifest
	PackageName string `json:"package_name"`
	// PackageVersion is an optional app version, overrides the one specified in the app manifest
	PackageVersion string `json:"package_version"`
	// Email is email address of a user who imported the application
	Email string `json:"email"`
	// ProgressC is an chan to receive progress events on
	// Callers are expected to receive on this chan to avoid
	// blocking the import operation.
	// Note, that ProgressC can closed before producing a single value
	ProgressC chan *ProgressEntry `json:"-"`
	// ErrorC is a chan to receive errors on
	// It is expected to be buffered to receive at least a single error
	ErrorC chan error `json:"-"`
	// Vendor defines whether the import operation will rewrite container images to point
	// to the private docker registry
	Vendor bool `json:"vendor"`
	// Force flag allows to overwrite existing application
	Force bool `json:"force"`
	// ResourcePatterns defines a list of file path patterns to consider for container
	// image references.
	ResourcePatterns []string `json:"resource_directories"`
	// IgnoreResourcePatterns defines a list of regular expressions to exclude files from searching
	// for container image references.
	IgnoreResourcePatterns []string `json:"ignore_resource_patterns"`
	// ExcludePatterns defines a set of file path patterns to exclude from the resulting
	// tarball. The patterns use the extended path pattern syntax (incl. double-star (`**`)
	// to denote arbitrary sub-directories)
	ExcludePatterns []string `json:"exclude_patterns"`
	// IncludePaths defines a list of directories to consider when creating a resulting
	// application tarball. If unspecified, all directories will be considered.
	IncludePaths []string `json:"include_paths"`
	// SetImages defines the list of docker image references with each item defining
	// a new tag to update for an image matching the specified registry/repository
	SetImages []loc.DockerImage `json:"set_images"`
	// SetDeps defines a list of package dependencies that will be set to the specified version
	SetDeps []loc.Locator `json:"set_deps"`
}

ImportRequest is a request to import an application

type ImportState 

type ImportState string

ImportState defines a set of application import states 

const (
	// ImportStatePullingImages defines the state of pulling docker images
	ImportStatePullingImages ImportState = "import_pulling_images"
	// ImportStateStoringRegistry defines the state of storing image layers into temporary registry
	ImportStateStoringRegistry ImportState = "import_storing_registry"
	// ImportStateCreatingPackage defines the state of creating an application package
	ImportStateCreatingPackage ImportState = "import_creating_package"
)

func (ImportState) Completion 

func (r ImportState) Completion() int

Completion returns a completion value of this import state

func (ImportState) Message 

func (r ImportState) Message() string

Message returns user-friendly message about what's going on

func (ImportState) State 

func (r ImportState) State() string

State returns a text representation of this import state

func (ImportState) String 

func (r ImportState) String() string

type InstallAppRequest 

type InstallAppRequest struct {
	// Locator identifies the application package to install
	Locator loc.Locator `json:"locator"`
	// Env specifies optional environment varibales to provide to the install hook
	Env map[string]string `json:"env"`
}

InstallAppRequest defines a request to install an application

type InstallerRequest 

type InstallerRequest struct {
	// Account specifies which account the local site entries will use
	// when the remote sites `dial back` on the initial OpsCenter connection
	// handshake (AcceptRemoteCluster)
	Account storage.Account `json:"account_id"`
	// Application identifies the application package to create installer for
	Application loc.Locator `json:"application"`
	// TrustedCluster is used to preserve information about Ops Center
	// installer is being downloaded from so clusters can connect back
	TrustedCluster storage.TrustedCluster `json:"trusted_cluster"`
	// CACert is certificate authority cert to package with installer
	CACert string `json:"ca_cert,omitempty"`
	// EncryptionKey is encryption key to encrypt installer packages with
	EncryptionKey string `json:"encryption_key,omitempty"`
}

InstallerRequest defines a request to create an installer tarball

func (InstallerRequest) Check 

func (r InstallerRequest) Check() error

Check validates this request

func (InstallerRequest) ToRaw 

func (r InstallerRequest) ToRaw() (*InstallerRequestRaw, error)

ToRaw converts the request to the format understood by API calls

type InstallerRequestRaw 

type InstallerRequestRaw struct {
	// Account is the request account
	Account storage.Account `json:"account_id"`
	// Application is the application to make installer for
	Application loc.Locator `json:"application"`
	// TrustedCluster preserves original Ops Center information
	TrustedCluster json.RawMessage `json:"trusted_cluster"`
	// CACert is certificate authority cert to package with installer
	CACert string `json:"ca_cert,omitempty"`
	// EncryptionKey is encryption key to encrypt installer packages with
	EncryptionKey string `json:"encryption_key,omitempty"`
}

InstallerRequestRaw is the same as InstallerRequest but can be marshaled and unmarshaled when passed in API call

func (InstallerRequestRaw) ToNative 

func (r InstallerRequestRaw) ToNative() (*InstallerRequest, error)

ToNative converts the request from API-friendly to its regular format

type ListAppsRequest 

type ListAppsRequest struct {
	// Repository is repository to show apps for
	Repository string `json:"repository"`
	// Type is the app type to filter by
	Type storage.AppType `json:"type"`
	// ExcludeHidden is whether to exclude apps marked as 'hidden' from the output
	ExcludeHidden bool `json:"exclude_hidden"`
	// Pattern is an optional search pattern.
	//
	// Treated as an application name substring.
	Pattern string `json:"pattern,omitempty"`
}

ListAppsRequest is a request to show applications in a repository

func (ListAppsRequest) Check 

func (r ListAppsRequest) Check() error

Check validates the request

type Logger 

type Logger interface {
	io.Writer

	Infof(format string, arg ...interface{})
}

Logger defines an interface to log messages

type Operations 

type Operations interface {
	// CreateImportOperation initiates application import and returns the operation
	// key to use to query the operation progress
	CreateImportOperation(*ImportRequest) (*storage.AppOperation, error)

	// GetOperationProgress retrieves the progress of the application import
	// operation
	GetOperationProgress(storage.AppOperation) (*ProgressEntry, error)

	// GetOperationLogs retrieves the log for the specified import operation
	GetOperationLogs(storage.AppOperation) (io.ReadCloser, error)

	// GetImportedApplication queries the application data for the specified import operation
	GetImportedApplication(storage.AppOperation) (*Application, error)

	// GetOperationCrashReport retrieves the crash report for a failed import attempt
	GetOperationCrashReport(storage.AppOperation) (io.ReadCloser, error)
}

Operations defines a set of operations on applications

type ProgressEntry 

type ProgressEntry storage.AppProgressEntry

ProgressEntry defines a single progress step in a complex operation (i.e. import)

func (ProgressEntry) IsCompleted 

func (r ProgressEntry) IsCompleted() bool

IsCompleted returns whether this progress entry identifies a completed (successful or failed) operation

type ProgressFailure 

type ProgressFailure string

ProgressFailure defines a set of failed states 

var ProgressStateFailed ProgressFailure

ProgressStateFailed is a final progress state that signifies a failed operation

func (ProgressFailure) Completion 

func (r ProgressFailure) Completion() int

Completion returns a completion value for this progress state

func (ProgressFailure) Message 

func (r ProgressFailure) Message() string

Message returns an error message associated with this failure progress state

func (ProgressFailure) State 

func (r ProgressFailure) State() string

State returns the state of this progress step

func (ProgressFailure) String 

func (r ProgressFailure) String() string

String returns a text representation of this progress state

type ProgressSuccess 

type ProgressSuccess string

ProgressSuccess defines a set of success states 

const (
	// ProgressStateInProgress defines an operation in progress
	ProgressStateInProgress ProgressSuccess = "in_progress"
	// ProgressStateCompleted defines a successful operation
	ProgressStateCompleted ProgressSuccess = "completed"
)

func (ProgressSuccess) Completion 

func (r ProgressSuccess) Completion() int

Completion returns a completion value for this progress state

func (ProgressSuccess) Message 

func (r ProgressSuccess) Message() string

Message returns a message associated with this progress state

func (ProgressSuccess) State 

func (r ProgressSuccess) State() string

State returns the state of this progress step

func (ProgressSuccess) String 

func (r ProgressSuccess) String() string

String returns a text representation of this progress state

type Status 

type Status struct {
	Endpoints []struct {
		Protocol string `json:"protocol"`
		NodePort string `json:"node_port"`
	} `json:"endpoints"`
}

type UpdateAppRequest 

type UpdateAppRequest struct {
	// Locator identifies the application package to update
	Locator loc.Locator `json:"locator"`
	// Env specifies optional environment varibales to provide to the update hook
	Env map[string]string `json:"env"`
}

UpdateAppRequest defines a request to update an application

Source Files

View all Source files

Directories

Path Synopsis
+groupName=gravitational.io
 +groupName=gravitational.io
test
package suite contains a backend-independent application service acceptance test suite
 package suite contains a backend-independent application service acceptance test suite

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.