app

package
v0.0.0-...-7b190fc Latest Latest
Warning

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

 Go to latest Published: Jan 8, 2024 License: Apache-2.0 Imports: 10 Imported by: 1

README

App Manifest

The App Manifest Format is a specification that allows application developers to define and manage the dependencies of their applications in a structured manner. This format is used in conjunction with the Terrarium tools, which handle the resolution and provisioning of these dependencies.

Overview

An application often relies on various services, databases, and other components to function properly. The App Dependency Format provides a standardized way to declare and configure these dependencies in a terrarium.yaml file. By following this format, developers can easily specify the required dependencies, their inputs, and even map their outputs to environment variables.

The Terrarium tools leverage a Terrarium platform template to resolve these dependencies. The platform template utilizes the dependency inputs and exports dependency outputs as Terraform output variables. This allows for seamless integration with infrastructure-as-code workflows.

terrarium.yaml Structure

The terrarium.yaml file is where the application's infrastructure dependencies are defined. It follows a specific structure based on the App struct, which is used to parse the YAML file. The following elements are available in the terrarium.yaml file:

App

The App section represents the main application configuration. It contains the following fields:

  • ID: A required identifier for the app in the project. It must start with an alphabet character, can only contain alphanumeric characters, and must not exceed 20 characters in length.
  • Name: A human-friendly name for the application.
  • EnvPrefix: The prefix used for environment variables in this app. If not set, it defaults to an empty string.
  • Compute: Denotes a specific dependency that best classifies the the app itself. It can only be of the type compute/*. The ID of this dependency is automatically set to the app ID, and it is used to set up the deployment pipeline in Code Pipes and allow other apps to use this app as a dependency.
  • Dependencies: Lists the required services, databases, and other components that the application relies on. This field is an array of Dependency objects.
Dependency

The dependencies section represents a single dependency of the application. It includes the following fields:

  • ID: A required identifier for the dependency in the project. It must start with an alphabet character, can only contain alphanumeric characters, and must not exceed 20 characters in length.
  • Use: Indicates the specific dependency interface ID that is used as an app dependency. It may include version as short-hand expression instead of adding version to the inputs block.
  • EnvPrefix: Used to prefix the output environment variables related to this dependency. If not set, it defaults to the dependency ID in uppercase.
  • Inputs: Represents customization options for the selected dependency interface. It is a key-value map where the keys represent the input names, and the values represent the corresponding input values.
  • Outputs: Maps dependency outputs to environment variables. Each entry in this map consists of an environment variable name as key and dependency output name in the value. The format for the environment variable name gets the prefix later automatically.
  • NoProvision: Indicates whether the dependency is provisioned in another app. If set to true, it means this dependency is shared, and its inputs are set in another app while its outputs are made available in the current app.

Example terrarium.yaml File

id: banking_app
name: Banking App
env_prefix: BA

compute:
  use: server_web
  inputs:
    port: 3000

dependencies:
  - id: user_db
    use: postgres@11
    env_prefix: USER
  - id: ledger_db
    use: postgres
    env_prefix: LEDGER
    inputs:
      db_name: ledger
      version: 11
    outputs:
      PG_CON: "host={{host}} user={{username}} password={{password}} dbname={{dbname}} port={{port}} sslmode={{sslmode}}"
  - id: user_cache
    use: redis
  - id: auth_app
    no_provision: true
    use: server_web
    outputs:
      URL: "{{endpoint}}"

In the example above, we have defined an application with the ID banking_app and the name Banking App. The environment variables in this app are prefixed with BA. The compute base used for the app is classified as a server_web and is configured with a port input set to 3000.

The application has several dependencies:

  • The user_db dependency is of type postgres@11 and has the ID user_db. It should generate standard postgres environment variables prefixed with BA_USER_ (eg: BA_USER_PGHOST). No custom inputs or outputs are specified for this dependency.
  • The ledger_db dependency is of type postgres and has the ID ledger_db. Its environment variables are prefixed with LEDGER. It takes inputs for db_name and version. Additionally, it maps the BA_LEDGER_PG_CON output to the environment variable by resolving the Mustache template with dependency outputs.
  • The user_cache dependency is of type redis and has the ID user_cache. Its environment variables are prefixed with the default prefix for the dependency ID in uppercase.
  • The auth_app dependency is of type server_web and has the ID auth_app. It is marked as no_provision, indicating that it is provisioned in another app. It exports the BA_AUTH_APP_URL output, which is mapped to the environment variable by resolving the Mustache template with dependency outputs.

By following this format and providing the necessary information in the terrarium.yaml file, developers can effectively manage and configure their application's dependencies using the Terrarium tools.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type App 

type App struct {
	// ID is a required identifier for the app in the project, which must start with
	// an alphabet character, can only contain alphanumeric characters,
	// and must not be longer than 20 characters.
	ID string `yaml:"id"`

	// Name describes the human-friendly name for the application.
	Name string `yaml:"name"`

	// EnvPrefix is the prefix used for the environment variables in this app.
	// If not set, defaults to an empty string.
	EnvPrefix string `yaml:"env_prefix"`

	// Compute denotes a specific dependency that best classifies the app itself,
	// it can only be of the type `compute/*`.
	// id of this dependency is automatically set to app id.
	// it is used to setup deployment pipeline in Code Pipes and allow other
	// apps to use this app as dependency.
	Compute Dependency `yaml:"compute"`

	// Dependencies lists the required services, databases, and other components that the application relies on.
	Dependencies Dependencies `yaml:"dependencies"`
}

App represents the main application configuration.

func NewApp 

func NewApp(content []byte) (*App, error)

func (App) GetDependencies 

func (app App) GetDependencies() Dependencies

GetDependencies returns the dependencies for the app including it's deployment dependency.

func (App) IsEquivalent 

func (e App) IsEquivalent(other App) (isEquivalent bool)

IsEquivalent returns if this and the other app generate the same infrastructure.

func (App) ProtoValue 

func (e App) ProtoValue() (*terrariumpb.App, error)

func (*App) Scan 

func (e *App) Scan(value interface{}) error

func (*App) ScanProto 

func (e *App) ScanProto(m *terrariumpb.App)

func (*App) SetDefaults 

func (app *App) SetDefaults()

Sets the default values for the optional fields in the App and its Dependencies.

func (App) ToFileBytes 

func (e App) ToFileBytes() ([]byte, error)

func (*App) Validate 

func (app *App) Validate() error

Validate ensures that the application and its dependencies have unique IDs within the scope of the given applications.

func (App) Value 

func (e App) Value() (driver.Value, error)

func (App) WrapProtoMessage 

func (e App) WrapProtoMessage() (message *anypb.Any, err error)

type Apps 

type Apps []App

App multiple apps configuration

func (Apps) GetAppByID 

func (apps Apps) GetAppByID(id string) *App

GetAppByID returns the first app found with the given ID, or nil if no such app exists.

func (Apps) GetDependenciesByAppID 

func (apps Apps) GetDependenciesByAppID(appID string) Dependencies

GetDependenciesByAppID returns the dependencies for the app with the given ID, or nil if the app does not exist.

func (Apps) GetDependenciesByType 

func (apps Apps) GetDependenciesByType(depType string) Dependencies

GetDependenciesByType returns all dependencies of a given type across all apps.

func (Apps) GetUniqueDependencyTypes 

func (apps Apps) GetUniqueDependencyTypes() []string

GetUniqueDependencyTypes returns a list of unique dependency types across all apps.

func (*Apps) SetDefaults 

func (apps *Apps) SetDefaults()

Sets the default values for the optional fields in the Apps and its Dependencies.

func (Apps) Validate 

func (apps Apps) Validate() error

Validate ensures that each application and its dependencies have unique IDs within the scope of all applications. It also checks that shared dependencies are provisioned.

type Dependencies 

type Dependencies []Dependency

func (Dependencies) GetDependenciesToProvision 

func (allDeps Dependencies) GetDependenciesToProvision() Dependencies

GetDependencies returns the dependencies for the app that needs to be provisioned including it's deployment dependency.

func (Dependencies) GetInputs 

func (allDeps Dependencies) GetInputs() map[string]interface{}

GetInputs returns a map of all inputs keyed by dependency identifier

func (Dependencies) ProtoValue 

func (e Dependencies) ProtoValue() (values []*terrariumpb.AppDependency, err error)

func (*Dependencies) ScanProto 

func (e *Dependencies) ScanProto(m []*terrariumpb.AppDependency)

type Dependency 

type Dependency struct {
	// ID is a required identifier for the dependency in the project, which must start with
	// an alphabet character, can only contain alphanumeric characters,
	// and must not be longer than 20 characters.
	ID string `yaml:"id"`

	// Use indicates the specific dependency interface ID that is used to provision an app dependency.
	Use string `yaml:"use"`

	// EnvPrefix is used to prefix the output env vars in order to avoid collision
	// Defaults to dependency id upper case.
	EnvPrefix string `yaml:"env_prefix"`

	// Inputs represents customization options for the selected dependency interface.
	Inputs map[string]interface{} `yaml:"inputs"`

	// Outputs maps environment variables to dependency outputs. Keys are app env name (without prefix) and
	// values are Mustache templates using dependency outputs.
	// The default env var name format is `<app_env_prefix>_<dependency_env_prefix>_<dependency_output_name_to_upper>`.
	Outputs map[string]string `yaml:"outputs"`

	// NoProvision indicates whether the dependency is provisioned in another app.
	// If true, this dependency is shared and its inputs are set in another app
	// and its outputs are made available here.
	NoProvision bool `yaml:"no_provision"`
}

Dependency represents a single dependency of the application, which could be a database, another service, cache, etc.

func (Dependency) IsEquivalent 

func (e Dependency) IsEquivalent(other Dependency) bool

IsEquivalent returns if this and the other dependency generate the same infrastructure.

func (Dependency) ProtoValue 

func (e Dependency) ProtoValue() (*terrariumpb.AppDependency, error)

func (*Dependency) ScanProto 

func (e *Dependency) ScanProto(m *terrariumpb.AppDependency)

func (*Dependency) SetDefaults 

func (dep *Dependency) SetDefaults()

func (*Dependency) Validate 

func (dep *Dependency) Validate() error

Validate if the dependency ID is set

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.