directives

package
v1.1.2-rc.2 Latest Latest
Warning

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

 Go to latest Published: Dec 23, 2024 License: Apache-2.0 Imports: 71 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	Digest         = "Digest"
	ImageAndDigest = "ImageAndDigest"
	ImageAndTag    = "ImageAndTag"
	Tag            = "Tag"
)

TODO(krancour): Remove this for v1.3.0

Variables

View Source 
var ReservedStepAliasRegex = regexp.MustCompile(`^step-\d+$`)

ReservedStepAliasRegex is a regular expression that matches step aliases that are reserved for internal use.

Functions

func ConfigToStruct added in v1.1.0 

func ConfigToStruct[T any](c Config) (T, error)

ConfigToStruct converts a Config to a (typed) configuration struct.

Types

type AppFromOrigin 

type AppFromOrigin struct {
	// The kind of origin. Currently only 'Warehouse' is supported. Required.
	Kind Kind `json:"kind"`
	// The name of the origin. Required.
	Name string `json:"name"`
}

type ArgoCDAppHealthCheck 

type ArgoCDAppHealthCheck struct {
	// Name is the name of the Argo CD Application to check.
	Name string `json:"name"`
	// Namespace is the namespace of the Argo CD Application to check. If empty,
	// the default Argo CD namespace is used.
	Namespace string `json:"namespace,omitempty"`
	// DesiredRevisions is a list of desired revisions for the Argo CD Application
	// to be synced to.
	DesiredRevisions []string `json:"desiredRevisions,omitempty"`
}

ArgoCDAppHealthCheck is the configuration for a health check on a single Argo CD Application.

type ArgoCDAppSourceUpdate 

type ArgoCDAppSourceUpdate struct {
	// If applicable, identifies a specific chart within the Helm chart repository specified by
	// the 'repoURL' field. When the source to be updated references a Helm chart repository,
	// the values of the 'repoURL' and 'chart' fields should exactly match the values of the
	// same fields in the source. i.e. Do not match the values of these two fields to your
	// Warehouse; match them to the Application source you wish to update.
	Chart string `json:"chart,omitempty"`
	// Applicable only when 'repoURL' references a Git repository, this field references the
	// 'commit' output from a previous step and uses it as the desired revision for the source.
	// Mutually exclusive with 'desiredRevision'. If both are left undefined, the desired
	// revision will be determined by Freight (if possible). Note that the source's
	// 'targetRevision' will not be updated to this commit unless 'updateTargetRevision=true' is
	// set. The utility of this field, on its own, is to specify the revision that the source
	// should be observably synced to during a health check.
	DesiredCommitFromStep string `json:"desiredCommitFromStep,omitempty"`
	// Specifies the desired revision for the source. Mutually exclusive with
	// 'desiredCommitFromStep'. If both are left undefined, the desired revision will be
	// determined by Freight (if possible). Note that the source's 'targetRevision' will not be
	// updated to this commit unless 'updateTargetRevision=true' is set. The utility of this
	// field, on its own, is to specify the revision that the source should be observably synced
	// to during a health check.
	DesiredRevision string                       `json:"desiredRevision,omitempty"`
	FromOrigin      *AppFromOrigin               `json:"fromOrigin,omitempty"`
	Helm            *ArgoCDHelmParameterUpdates  `json:"helm,omitempty"`
	Kustomize       *ArgoCDKustomizeImageUpdates `json:"kustomize,omitempty"`
	// With possible help from the 'chart' field, identifies which of an Argo CD Application's
	// sources is to be updated. When the source to be updated references a Helm chart
	// repository, the values of the 'repoURL' and 'chart' fields should exactly match the
	// values of the same fields in the source. i.e. Do not match the values of these two fields
	// to your Warehouse; match them to the Application source you wish to update.
	RepoURL string `json:"repoURL"`
	// Indicates whether the source should be updated such that its 'targetRevision' field
	// points directly at the desired revision. If set to true, exactly one of
	// 'desiredCommitFromStep' or 'desiredRevision' must be specified.
	UpdateTargetRevision bool `json:"updateTargetRevision,omitempty"`
}

type ArgoCDAppStatus 

type ArgoCDAppStatus struct {
	// Namespace is the namespace of the ArgoCD Application.
	Namespace string
	// Name is the name of the ArgoCD Application.
	Name                     string
	argocd.ApplicationStatus `json:",inline"`
}

ArgoCDAppStatus describes the current state of a single ArgoCD Application.

type ArgoCDAppUpdate 

type ArgoCDAppUpdate struct {
	FromOrigin *AppFromOrigin `json:"fromOrigin,omitempty"`
	// Specifies the name of an Argo CD Application resource to be updated.
	Name string `json:"name"`
	// Specifies the namespace of an Argo CD Application resource to be updated. If left
	// unspecified, the namespace will be the controller's configured default.
	Namespace string `json:"namespace,omitempty"`
	// Describes updates to be applied to various sources of an Argo CD Application resource.
	Sources []ArgoCDAppSourceUpdate `json:"sources,omitempty"`
}

type ArgoCDHealthConfig 

type ArgoCDHealthConfig struct {
	// Apps is a list health checks to perform on specific Argo CD Applications.
	Apps []ArgoCDAppHealthCheck `json:"apps"`
}

ArgoCDHealthConfig is the configuration for a health check to be executed by the argocd-update directive.

type ArgoCDHelmImageUpdate 

type ArgoCDHelmImageUpdate struct {
	FromOrigin *AppFromOrigin `json:"fromOrigin,omitempty"`
	// Specifies a key within an Argo CD Application source's Helm parameters that is to be
	// updated.
	Key string `json:"key"`
	// The URL of a container image repository.
	RepoURL string `json:"repoURL,omitempty"`
	// Specifies a new value for the setting within an Argo CD Application source's Helm
	// parameters identified by the 'key' field.
	Value string `json:"value"`
}

Describes how to update a Helm parameter to reference a specific version of a container image.

type ArgoCDHelmParameterUpdates 

type ArgoCDHelmParameterUpdates struct {
	FromOrigin *AppFromOrigin          `json:"fromOrigin,omitempty"`
	Images     []ArgoCDHelmImageUpdate `json:"images"`
}

Describes updates to an Argo CD Application source's Helm parameters.

type ArgoCDKustomizeImageUpdate 

type ArgoCDKustomizeImageUpdate struct {
	// Digest of the image to set. Mutually exclusive with 'tag' and 'useDigest=true'.
	Digest     string         `json:"digest,omitempty"`
	FromOrigin *AppFromOrigin `json:"fromOrigin,omitempty"`
	// Specifies a container image name override.
	NewName string `json:"newName,omitempty"`
	// The URL of a container image repository.
	RepoURL string `json:"repoURL"`
	// Tag of the image to set. Mutually exclusive with 'digest' and 'useDigest=true'.
	Tag string `json:"tag,omitempty"`
	// Specifies whether the image's digest should be used instead of its tag. Mutually
	// exclusive with 'digest' and 'tag'.
	UseDigest bool `json:"useDigest,omitempty"`
}

Describes how to update a Kustomize image to reference a specific version of a container image.

type ArgoCDKustomizeImageUpdates 

type ArgoCDKustomizeImageUpdates struct {
	FromOrigin *AppFromOrigin               `json:"fromOrigin,omitempty"`
	Images     []ArgoCDKustomizeImageUpdate `json:"images,omitempty"`
}

Describes updates to an Argo CD Application source's Kustomize images.

type ArgoCDUpdateConfig 

type ArgoCDUpdateConfig struct {
	Apps       []ArgoCDAppUpdate `json:"apps"`
	FromOrigin *AppFromOrigin    `json:"fromOrigin,omitempty"`
}

type Author 

type Author struct {
	// The email of the author.
	Email string `json:"email,omitempty"`
	// The name of the author.
	Name string `json:"name,omitempty"`
}

The author of the commit.

type Chart 

type Chart struct {
	FromOrigin *ChartFromOrigin `json:"fromOrigin,omitempty"`
	// The name of the subchart, as defined in `Chart.yaml`.
	Name string `json:"name"`
	// The repository of the subchart, as defined in `Chart.yaml`. It also supports OCI charts
	// using `oci://`.
	Repository string `json:"repository"`
	// The version of the subchart to update to. If not specified, a version referenced by the
	// Freight is used.
	Version string `json:"version,omitempty"`
}

type ChartFromOrigin 

type ChartFromOrigin struct {
	// The kind of origin. Currently only 'Warehouse' is supported. Required.
	Kind Kind `json:"kind"`
	// The name of the origin. Required.
	Name string `json:"name"`
}

type Checkout 

type Checkout struct {
	// The branch to checkout. Mutually exclusive with 'commit', 'tag', and 'fromFreight=true'.
	// If none of these are specified, the default branch is checked out.
	Branch string `json:"branch,omitempty"`
	// The commit to checkout. Mutually exclusive with 'branch', 'tag', and 'fromFreight=true'.
	// If none of these are specified, the default branch is checked out.
	Commit string `json:"commit,omitempty"`
	// Indicates whether a new, empty orphan branch should be created if the branch does not
	// already exist. Default is false.
	Create bool `json:"create,omitempty"`
	// Indicates whether the ID of a commit to check out may be obtained from Freight. A value
	// of 'true' is mutually exclusive with 'branch', 'commit', and 'tag'. If none of these are
	// specified, the default branch is checked out.
	FromFreight bool                `json:"fromFreight,omitempty"`
	FromOrigin  *CheckoutFromOrigin `json:"fromOrigin,omitempty"`
	// The path where the repository should be checked out.
	Path string `json:"path"`
	// The tag to checkout. Mutually exclusive with 'branch', 'commit', and 'fromFreight=true'.
	// If none of these are specified, the default branch is checked out.
	Tag string `json:"tag,omitempty"`
}

type CheckoutFromOrigin 

type CheckoutFromOrigin struct {
	// The kind of origin. Currently only 'Warehouse' is supported. Required.
	Kind Kind `json:"kind"`
	// The name of the origin. Required.
	Name string `json:"name"`
}

type CommonDefs 

type CommonDefs interface{}

type Config 

type Config map[string]any

Config is an opaque map of configuration values for both PromotionSteps and HealthCheckSteps. The keys and values are arbitrary and implementations of PromotionStepRunner and HealthCheckStepRunner are responsible for interpreting them.

func (Config) DeepCopy 

func (c Config) DeepCopy() Config

DeepCopy returns a deep copy of the configuration.

func (Config) ToJSON 

func (c Config) ToJSON() []byte

ToJSON marshals the configuration to JSON.

type CopyConfig 

type CopyConfig struct {
	// Ignore is a (multiline) string of glob patterns to ignore when copying files. It accepts
	// the same syntax as .gitignore files.
	Ignore string `json:"ignore,omitempty"`
	// InPath is the path to the file or directory to copy.
	InPath string `json:"inPath"`
	// OutPath is the path to the destination file or directory.
	OutPath string `json:"outPath"`
}

type Engine 

type Engine interface {
	// Promote executes the provided list of PromotionSteps in sequence and
	// returns a PromotionResult that aggregates the results of all steps.
	Promote(context.Context, PromotionContext, []PromotionStep) (PromotionResult, error)
	// CheckHealth executes the provided list of HealthCheckSteps in sequence and
	// and returns a HealthCheckResult that aggregates the results of all steps.
	CheckHealth(context.Context, HealthCheckContext, []HealthCheckStep) kargoapi.Health
}

Engine is an interface for executing user-defined promotion processes as well as corresponding health check processes.

type FakeEngine 

type FakeEngine struct {
	ExecuteFn     func(context.Context, PromotionContext, []PromotionStep) (PromotionResult, error)
	CheckHealthFn func(context.Context, HealthCheckContext, []HealthCheckStep) kargoapi.Health
}

FakeEngine is a mock implementation of the Engine interface that can be used to facilitate unit testing.

func (*FakeEngine) CheckHealth 

func (e *FakeEngine) CheckHealth(
	ctx context.Context,
	healthCtx HealthCheckContext,
	steps []HealthCheckStep,
) kargoapi.Health

CheckHealth implements the Engine interface.

func (*FakeEngine) Promote 

func (e *FakeEngine) Promote(
	ctx context.Context,
	promoCtx PromotionContext,
	steps []PromotionStep,
) (PromotionResult, error)

Promote implements the Engine interface.

type GitClearConfig 

type GitClearConfig struct {
	// Path to a working directory of a local repository from which to remove all files,
	// excluding the .git/ directory.
	Path string `json:"path"`
}

type GitCloneConfig 

type GitCloneConfig struct {
	// The commits, branches, or tags to check out from the repository and the paths where they
	// should be checked out. At least one must be specified.
	Checkout []Checkout `json:"checkout"`
	// Indicates whether to skip TLS verification when cloning the repository. Default is false.
	InsecureSkipTLSVerify bool `json:"insecureSkipTLSVerify,omitempty"`
	// The URL of a remote Git repository to clone. Required.
	RepoURL string `json:"repoURL"`
}

type GitCommitConfig 

type GitCommitConfig struct {
	// The author of the commit.
	Author *Author `json:"author,omitempty"`
	// The commit message. Mutually exclusive with 'messageFromSteps'.
	Message string `json:"message,omitempty"`
	// TODO
	MessageFromSteps []string `json:"messageFromSteps,omitempty"`
	// The path to a working directory of a local repository.
	Path string `json:"path"`
}

type GitOpenPRConfig 

type GitOpenPRConfig struct {
	// Indicates whether a new, empty orphan branch should be created and pushed to the remote
	// if the target branch does not already exist there. Default is false.
	CreateTargetBranch bool `json:"createTargetBranch,omitempty"`
	// Indicates whether to skip TLS verification when cloning the repository. Default is false.
	InsecureSkipTLSVerify bool `json:"insecureSkipTLSVerify,omitempty"`
	// The name of the Git provider to use. Currently only 'github' and 'gitlab' are supported.
	// Kargo will try to infer the provider if it is not explicitly specified.
	Provider *Provider `json:"provider,omitempty"`
	// The URL of a remote Git repository to clone.
	RepoURL string `json:"repoURL"`
	// The branch containing the changes to be merged. This branch must already exist and be up
	// to date on the remote.
	SourceBranch string `json:"sourceBranch,omitempty"`
	// References the 'branch' output from a previous step. This step will use that value as the
	// source branch.
	SourceBranchFromStep string `json:"sourceBranchFromStep,omitempty"`
	// The branch to which the changes should be merged. This branch must already exist and be
	// up to date on the remote.
	TargetBranch string `json:"targetBranch"`
}

type GitPushConfig 

type GitPushConfig struct {
	// Indicates whether to push to a new remote branch. A value of 'true' is mutually exclusive
	// with 'targetBranch'. If neither of these is provided, the target branch will be the
	// currently checked out branch.
	GenerateTargetBranch bool `json:"generateTargetBranch,omitempty"`
	// This step implements its own internal retry logic for cases where a push is determined to
	// have failed due to the remote branch having commits that that are not present locally.
	// Each attempt, including the first, rebases prior to pushing. This field configures the
	// maximum number of attempts to push to the remote repository. If not specified, the
	// default is 50.
	MaxAttempts *int64 `json:"maxAttempts,omitempty"`
	// The path to a working directory of a local repository.
	Path string `json:"path"`
	// The target branch to push to. Mutually exclusive with 'generateTargetBranch=true'. If
	// neither of these is provided, the target branch will be the currently checked out branch.
	TargetBranch string `json:"targetBranch,omitempty"`
}

type GitWaitForPRConfig 

type GitWaitForPRConfig struct {
	// Indicates whether to skip TLS verification when cloning the repository. Default is false.
	InsecureSkipTLSVerify bool `json:"insecureSkipTLSVerify,omitempty"`
	// The number of the pull request to wait for.
	PRNumber int64 `json:"prNumber,omitempty"`
	// This field references the 'prNumber' output from a previous step and uses it as the
	// number of the pull request to wait for.
	PRNumberFromStep string `json:"prNumberFromStep,omitempty"`
	// The name of the Git provider to use. Currently only 'github' and 'gitlab' are supported.
	// Kargo will try to infer the provider if it is not explicitly specified.
	Provider *Provider `json:"provider,omitempty"`
	// The URL of a remote Git repository to clone.
	RepoURL string `json:"repoURL"`
}

type HTTPConfig added in v1.1.0 

type HTTPConfig struct {
	// The body of the HTTP request.
	Body string `json:"body,omitempty"`
	// An expression to evaluate to determine if the request failed.
	FailureExpression string `json:"failureExpression,omitempty"`
	// Headers to include in the HTTP request.
	Headers []HTTPHeader `json:"headers,omitempty"`
	// Whether to skip TLS verification when making the request. (Not recommended.)
	InsecureSkipTLSVerify bool `json:"insecureSkipTLSVerify,omitempty"`
	// The HTTP method to use for the request.
	Method string `json:"method,omitempty"`
	// Outputs to extract from the HTTP response.
	Outputs []HTTPOutput `json:"outputs,omitempty"`
	// Query parameters to include in the HTTP request.
	QueryParams []HTTPQueryParam `json:"queryParams,omitempty"`
	// An expression to evaluate to determine if the request was successful.
	SuccessExpression string `json:"successExpression,omitempty"`
	// The maximum time to wait for the request to complete. If not specified, the default is 10
	// seconds.
	Timeout string `json:"timeout,omitempty"`
	// The URL to send the HTTP request to.
	URL string `json:"url"`
}

type HTTPHeader added in v1.1.0 

type HTTPHeader struct {
	// The name of the header.
	Name string `json:"name"`
	// The value of the header.
	Value string `json:"value"`
}

type HTTPOutput added in v1.1.0 

type HTTPOutput struct {
	// An expression to evaluate to extract the output from the HTTP response.
	FromExpression string `json:"fromExpression"`
	// The name of the output.
	Name string `json:"name"`
}

type HTTPQueryParam added in v1.1.0 

type HTTPQueryParam struct {
	// The name of the query parameter.
	Name string `json:"name"`
	// The value of the query parameter.
	Value string `json:"value"`
}

type HealthCheckContext 

type HealthCheckContext struct {
	// Project is the Project that the Stage is associated with.
	Project string
	// Stage is the Stage that the health check is targeting.
	Stage string
}

HealthCheckContext is the context of a health check process that is executed by the Engine.

type HealthCheckStep 

type HealthCheckStep struct {
	// Kind identifies a registered HealthCheckStepRunner that implements the
	// logic for this step of the health check process.
	Kind string
	// Config is an opaque map of configuration values to be passed to the
	// HealthCheckStepRunner executing this step.
	Config Config
}

HealthCheckStep describes a single step in a health check process. HealthCheckSteps are executed in sequence by the Engine, which delegates the execution of each step to a HealthCheckStepRunner.

type HealthCheckStepContext 

type HealthCheckStepContext struct {
	// Config is the configuration of the step that is currently being
	// executed.
	Config Config
	// Project is the Project that the Stage is associated with.
	Project string
	// Stage is the Stage that the health check is targeting.
	Stage string
	// KargoClient is a Kubernetes client that a HealthCheckStepRunner executing a
	// HealthCheckStep may use to interact with the Kargo control plane. The value
	// of this field will often be nil, as the Engine will only furnish a this to
	// specially privileged HealthCheckStepRunners.
	//
	// TODO: krancour: Longer term, we may be able to do without this.
	KargoClient client.Client
	// ArgoCDClient is a Kubernetes client that a HealthCheckStepRunner executing
	// a
	// HealthCheckStep may use to interact with an Argo CD control plane. The
	// value of this field will often be nil, as the Engine will only furnish this
	// to specially privileged HealthCheckStepRunners.
	ArgoCDClient client.Client
	// CredentialsDB is a database of credentials that a HealthCheckStepRunner
	// executing a HealthCheckStep may use to acquire credentials for interacting
	// with external systems. The value of this field will often be nil, as the
	// Engine will only furnish a CredentialsDB to specially privileged
	// HealthCheckStepRunners.
	//
	// TODO: krancour: Longer term, if we can standardize the way that
	// HealthCheckSteps express what credentials they need, we can make the Engine
	// responsible for finding them and furnishing them directly to each
	// HealthCheckStepRunner.
	CredentialsDB credentials.Database
}

HealthCheckStepContext is a type that represents the context in which a single HealthCheckStep is executed by a HealthCheckStepRunner.

type HealthCheckStepResult 

type HealthCheckStepResult struct {
	// Status is the high-level outcome of the HealthCheckStep executed by a
	// HealthCheckStepRunner.
	Status kargoapi.HealthState
	// Output is the opaque output of a HealthCheckStepResult executed by a
	// HealthCheckStepRunner. The Engine will aggregate this output and include it
	// in the final results of the health check, which will ultimately be included
	// in StageStatus.
	Output map[string]any
	// Issues is a list of issues that were encountered during the execution of
	// the HealthCheckStep by a HealthCheckStepRunner.
	Issues []string
}

HealthCheckStepResult represents the results of a single HealthCheckStep executed by a HealthCheckStepRunner.

type HealthCheckStepRunner 

type HealthCheckStepRunner interface {
	// Name returns the name of the HealthCheckStepRunner.
	Name() string
	// RunHealthCheckStep executes a health check using the provided
	// HealthCheckStepContext.
	RunHealthCheckStep(context.Context, *HealthCheckStepContext) HealthCheckStepResult
}

HealthCheckStepRunner is an interface for components that implement the logic for execution of the individual HealthCheckSteps.

type HealthCheckStepRunnerRegistration 

type HealthCheckStepRunnerRegistration struct {
	// Permissions is a set of permissions that indicate capabilities the Engine
	// should enable for the HealthCheckStepRunner.
	Permissions StepRunnerPermissions
	// Runner is a HealthCheckStepRunner executes a discrete HealthCheckStep.
	Runner HealthCheckStepRunner
}

HealthCheckStepRunnerRegistration is a registration for a single HealthCheckStepRunner. It includes the HealthCheckStepRunner itself and a set of permissions that indicate capabilities the Engine should enable for the HealthCheckStepRunner.

type Helm added in v0.9.2 

type Helm struct {
	// APIVersions allows a manual set of supported API versions to be passed when inflating a
	// Helm chart.
	APIVersions []string `json:"apiVersions,omitempty"`
	// KubeVersion allows for passing a specific Kubernetes version to use when inflating a Helm
	// chart.
	KubeVersion string `json:"kubeVersion,omitempty"`
}

Helm contains configuration for inflating a Helm chart.

type HelmTemplateConfig 

type HelmTemplateConfig struct {
	// APIVersions allows a manual set of supported API Versions to be passed when rendering the
	// manifests.
	APIVersions []string `json:"apiVersions,omitempty"`
	// Whether to disable hooks in the rendered manifests.
	DisableHooks bool `json:"disableHooks,omitempty"`
	// Whether to include CRDs in the rendered manifests.
	IncludeCRDs bool `json:"includeCRDs,omitempty"`
	// KubeVersion allows for passing a specific Kubernetes version to use when rendering the
	// manifests.
	KubeVersion string `json:"kubeVersion,omitempty"`
	// Namespace to use for the rendered manifests.
	Namespace string `json:"namespace,omitempty"`
	// OutPath to write the rendered manifests to. If it points to a .yaml or .yml file, the
	// rendered manifests will be written to that file. If it points to a directory, the
	// rendered manifests will be written to this directory joined with the chart name.
	OutPath string `json:"outPath"`
	// Path at which the Helm chart can be found.
	Path string `json:"path"`
	// ReleaseName to use for the rendered manifests.
	ReleaseName string `json:"releaseName"`
	// Whether to skip tests when rendering the manifests.
	SkipTests bool `json:"skipTests,omitempty"`
	// Whether to use the release name in the output path (instead of the chart name). This only
	// has an effect if outPath is set to a directory.
	UseReleaseName bool `json:"useReleaseName,omitempty"`
	// ValuesFiles to use for rendering the Helm chart.
	ValuesFiles []string `json:"valuesFiles,omitempty"`
}

func (HelmTemplateConfig) OutPathIsFile 

func (c HelmTemplateConfig) OutPathIsFile() bool

OutPathIsFile returns true if the output path contains a YAML extension. Otherwise, the output path is considered to target a directory where the rendered manifest will be written to.

type HelmUpdateChartConfig 

type HelmUpdateChartConfig struct {
	// A list of chart dependencies which should receive updates.
	Charts []Chart `json:"charts"`
	// The path at which the umbrella chart with the dependency can be found.
	Path string `json:"path"`
}

type HelmUpdateImageConfig 

type HelmUpdateImageConfig struct {
	// A list of images which should receive updates.
	Images []HelmUpdateImageConfigImage `json:"images"`
	// The path at which the Helm values file can be found.
	Path string `json:"path"`
}

type HelmUpdateImageConfigImage 

type HelmUpdateImageConfigImage struct {
	FromOrigin *ChartFromOrigin `json:"fromOrigin,omitempty"`
	// The container image (without tag) at which the update is targeted.
	Image string `json:"image"`
	// The key in the Helm values file of which the value needs to be updated. For nested
	// values, it takes a YAML dot notation path.
	Key string `json:"key"`
	// Specifies the new value for the specified key in the Helm values file.
	Value string `json:"value"`
}

type Kind 

type Kind string

The kind of origin. Currently only 'Warehouse' is supported. Required. 

const (
	Warehouse Kind = "Warehouse"
)

type KustomizeBuildConfig 

type KustomizeBuildConfig struct {
	// OutPath is the file path to write the built manifests to.
	OutPath string `json:"outPath"`
	// Path to the directory containing the Kustomization file.
	Path string `json:"path"`
	// Plugin contains configuration for customizing the behavior of builtin Kustomize plugins.
	Plugin *Plugin `json:"plugin,omitempty"`
}

type KustomizeSetImageConfig 

type KustomizeSetImageConfig struct {
	// Images is a list of container images to set or update in the Kustomization file.
	Images []KustomizeSetImageConfigImage `json:"images"`
	// Path to the directory containing the Kustomization file.
	Path string `json:"path"`
}

type KustomizeSetImageConfigImage 

type KustomizeSetImageConfigImage struct {
	// Digest of the image to set in the Kustomization file. Mutually exclusive with 'tag' and
	// 'useDigest=true'.
	Digest     string           `json:"digest,omitempty"`
	FromOrigin *ChartFromOrigin `json:"fromOrigin,omitempty"`
	// Image name of the repository from which to pick the version. This is the image name Kargo
	// is subscribed to, and produces Freight for.
	Image string `json:"image"`
	// Name of the image (as defined in the Kustomization file).
	Name string `json:"name,omitempty"`
	// NewName for the image. This can be used to rename the container image name in the
	// manifests.
	NewName string `json:"newName,omitempty"`
	// Tag of the image to set in the Kustomization file. Mutually exclusive with 'digest' and
	// 'useDigest=true'.
	Tag string `json:"tag,omitempty"`
	// UseDigest specifies whether to use the digest of the image instead of the tag.
	UseDigest bool `json:"useDigest,omitempty"`
}

type Plugin added in v0.9.2 

type Plugin struct {
	// Helm contains configuration for inflating a Helm chart.
	Helm *Helm `json:"helm,omitempty"`
}

Plugin contains configuration for customizing the behavior of builtin Kustomize plugins.

type PromotionContext 

type PromotionContext struct {
	// UIBaseURL may be used to construct deeper URLs for interacting with the
	// Kargo UI.
	UIBaseURL string
	// WorkDir is the working directory to use for the Promotion.
	WorkDir string
	// Project is the Project that the Promotion is associated with.
	Project string
	// Stage is the Stage that the Promotion is targeting.
	Stage string
	// Promotion is the name of the Promotion.
	Promotion string
	// FreightRequests is the list of Freight from various origins that is
	// requested by the Stage targeted by the Promotion. This information is
	// sometimes useful to PromotionSteps that reference a particular artifact
	// and, in the absence of any explicit information about the origin of that
	// artifact, may need to examine FreightRequests to determine whether there
	// exists any ambiguity as to its origin, which a user may then need to
	// resolve.
	FreightRequests []kargoapi.FreightRequest
	// Freight is the collection of all Freight referenced by the Promotion. This
	// collection contains both the Freight that is actively being promoted and
	// any Freight that has been inherited from the target Stage's current
	// state.
	Freight kargoapi.FreightCollection
	// StartFromStep is the index of the step from which the promotion should
	// begin execution.
	StartFromStep int64
	// StepExecutionMetadata tracks metadata pertaining to the execution
	// of individual promotion steps.
	StepExecutionMetadata kargoapi.StepExecutionMetadataList
	// State is the current state of the promotion process.
	State State
	// Vars is a list of variables definitions that can be used by the
	// PromotionSteps.
	Vars []kargoapi.PromotionVariable
	// Secrets is a map of secrets that can be used by the PromotionSteps.
	Secrets map[string]map[string]string
}

PromotionContext is the context of a user-defined promotion process that is executed by the Engine.

type PromotionResult 

type PromotionResult struct {
	// Status is the high-level outcome of the user-defined promotion executed by
	// the Engine.
	Status kargoapi.PromotionPhase
	// Message is an optional message that provides additional context about the
	// outcome of the user-defined promotion executed by the Engine.
	Message string
	// HealthCheckSteps collects health check configuration returned from the
	// execution of individual PromotionSteps by their corresponding
	// PromotionStepRunners. This configuration can later be used as input to
	// health check processes.
	HealthCheckSteps []HealthCheckStep
	// If the promotion process remains in-progress, perhaps waiting for a change
	// in some external state, the value of this field will indicate where to
	// resume the process in the next reconciliation.
	CurrentStep int64
	// StepExecutionMetadata tracks metadata pertaining to the execution
	// of individual promotion steps.
	StepExecutionMetadata kargoapi.StepExecutionMetadataList
	// State is the current state of the promotion process.
	State State
}

PromotionResult is the result of a user-defined promotion process executed by the Engine. It aggregates the status and output of the individual PromotionStepResults returned by the PromotionStepRunner executing each PromotionStep.

type PromotionStep 

type PromotionStep struct {
	// Kind identifies a registered PromotionStepRunner that implements the logic
	// for this step of the user-defined promotion process.
	Kind string
	// Alias is an optional identifier for this step of the use-defined promotion
	// process, which must be unique to the process. Output from execution of the
	// step will be keyed to this alias by the Engine and made accessible to
	// subsequent steps.
	Alias string
	// Retry is the retry configuration for the PromotionStep.
	Retry *kargoapi.PromotionStepRetry
	// Config is an opaque JSON to be passed to the PromotionStepRunner executing
	// this step.
	Config []byte
}

PromotionStep describes a single step in a user-defined promotion process. PromotionSteps are executed in sequence by the Engine, which delegates the execution of each step to a PromotionStepRunner.

func (*PromotionStep) GetConfig added in v1.1.0 

func (s *PromotionStep) GetConfig(
	ctx context.Context,
	cl client.Client,
	promoCtx PromotionContext,
	state State,
) (Config, error)

GetConfig returns the Config unmarshalled into a map. Any expr-lang expressions are evaluated in the context of the provided arguments prior to unmarshaling.

func (*PromotionStep) GetErrorThreshold added in v1.1.0 

func (s *PromotionStep) GetErrorThreshold(runner any) uint32

GetErrorThreshold returns the number of consecutive times the provided runner must fail to execute the step (for any reason) before retries are abandoned and the entire Promotion is marked as failed. If the runner is a RetryableStepRunner, its threshold is used as the default. Otherwise, the default is 1.

func (*PromotionStep) GetTimeout added in v1.1.0 

func (s *PromotionStep) GetTimeout(runner any) *time.Duration

GetTimeout returns the maximum interval the provided runner may spend attempting to execute the step before retries are abandoned and the entire Promotion is marked as failed. If the runner is a RetryableStepRunner, its timeout is used as the default. Otherwise, the default is 0 (no limit).

func (*PromotionStep) GetVars added in v1.1.0 

func (s *PromotionStep) GetVars(promoCtx PromotionContext) (map[string]any, error)

GetVars returns the variables defined in the PromotionStep. The variables are evaluated in the context of the provided PromotionContext.

type PromotionStepContext 

type PromotionStepContext struct {
	// UIBaseURL may be used to construct deeper URLs for interacting with the
	// Kargo UI.
	UIBaseURL string
	// WorkDir is the root directory for the execution of a step.
	WorkDir string
	// SharedState is the state shared between steps.
	SharedState State
	// Alias is the alias of the step that is currently being executed.
	Alias string
	// Config is the configuration of the step that is currently being
	// executed.
	Config Config
	// Project is the Project that the Promotion is associated with.
	Project string
	// Stage is the Stage that the Promotion is targeting.
	Stage string
	// Promotion is the name of the Promotion.
	Promotion string
	// FreightRequests is the list of Freight from various origins that is
	// requested by the Stage targeted by the Promotion. This information is
	// sometimes useful to PromotionStep that reference a particular artifact and,
	// in the absence of any explicit information about the origin of that
	// artifact, may need to examine FreightRequests to determine whether there
	// exists any ambiguity as to its origin, which a user may then need to
	// resolve.
	//
	// TODO: krancour: Longer term, if we can standardize the way that
	// PromotionSteps express the artifacts they need to work with, we can make
	// the Engine responsible for finding them and furnishing them directly to
	// each PromotionStepRunner.
	FreightRequests []kargoapi.FreightRequest
	// Freight is the collection of all Freight referenced by the Promotion. This
	// collection contains both the Freight that is actively being promoted as
	// well as any Freight that has been inherited from the target Stage's current
	// state.
	//
	// TODO: krancour: Longer term, if we can standardize the way that
	// PromotionSteps express the artifacts they need to work with, we can make
	// the Engine responsible for finding them and furnishing them directly to
	// each PromotionStepRunner.
	Freight kargoapi.FreightCollection
	// KargoClient is a Kubernetes client that a PromotionStepRunner executing a
	// PromotionStep may use to interact with the Kargo control plane. The value
	// of this field will often be nil, as the Engine will only furnish a this to
	// specially privileged PromotionStepRunners.
	//
	// TODO: krancour: Longer term, we may be able to do without this. See notes
	// on previous two fields.
	KargoClient client.Client
	// ArgoCDClient is a Kubernetes client that a PromotionStepRunner executing a
	// PromotionStep may use to interact with an Argo CD control plane. The value
	// of this field will often be nil, as the Engine will only furnish this to
	// specially privileged PromotionStepRunners.
	ArgoCDClient client.Client
	// CredentialsDB is a database of credentials that a PromotionStepRunner
	// executing a PromotionStep may use to acquire credentials for interacting
	// with external systems. The value of this field will often be nil, as the
	// Engine will only furnish a CredentialsDB to specially privileged
	// PromotionStepRunners.
	//
	// TODO: krancour: Longer term, if we can standardize the way that
	// PromotionSteps express what credentials they need, we can make the Engine
	// responsible for finding them and furnishing them directly to each
	// PromotionStepRunner.
	CredentialsDB credentials.Database
}

PromotionStepContext is a type that represents the context in which a SinglePromotion step is executed by a PromotionStepRunner.

type PromotionStepResult 

type PromotionStepResult struct {
	// Status is the high-level outcome a PromotionStep executed by a
	// PromotionStepRunner.
	Status kargoapi.PromotionPhase
	// Message is an optional message that provides additional context about the
	// outcome of a PromotionStep executed by a PromotionStepRunner.
	Message string
	// Output is the opaque output of a PromotionStep executed by a
	// PromotionStepRunner. The Engine will update shared state with this output,
	// making it available to subsequent steps.
	Output map[string]any
	// HealthCheckStep is health check opaque configuration optionally returned by
	// a PromotionStepRunner's successful execution of a PromotionStep. This
	// configuration can later be used as input to health check processes.
	HealthCheckStep *HealthCheckStep
}

PromotionStepResult represents the results of single PromotionStep executed by a PromotionStepRunner.

type PromotionStepRunner 

type PromotionStepRunner interface {
	// Name returns the name of the PromotionStepRunner.
	Name() string
	// RunPromotionStep executes an individual step of a user-defined promotion
	// process using the provided PromotionStepContext. Implementations may
	// indirectly modify that context through the returned PromotionStepResult to
	// allow subsequent promotion steps to access the results of its execution.
	RunPromotionStep(context.Context, *PromotionStepContext) (PromotionStepResult, error)
}

PromotionStepRunner is an interface for components that implement the logic for execution of the individual PromotionSteps of a user-defined promotion process.

type PromotionStepRunnerRegistration 

type PromotionStepRunnerRegistration struct {
	// Permissions is a set of permissions that indicate capabilities the
	// Engine should enable for the PromotionStepRunner.
	Permissions StepRunnerPermissions
	// Runner is a PromotionStepRunner executes a discrete PromotionStep in the
	// context of a Promotion.
	Runner PromotionStepRunner
}

PromotionStepRunnerRegistration is a registration for a single PromotionStepRunner. It includes the PromotionStepRunner itself and a set of permissions that indicate capabilities the Engine should enable for the PromotionStepRunner.

type Provider 

type Provider string

The name of the Git provider to use. Currently only 'github' and 'gitlab' are supported. Kargo will try to infer the provider if it is not explicitly specified. 

const (
	Github Provider = "github"
	Gitlab Provider = "gitlab"
)

type RetryableStepRunner added in v1.1.0 

type RetryableStepRunner interface {
	// DefaultTimeout returns the default timeout for the step.
	DefaultTimeout() *time.Duration
	// DefaultErrorThreshold returns the number of consecutive times the step must
	// fail (for any reason) before retries are abandoned and the entire Promotion
	// is marked as failed.
	DefaultErrorThreshold() uint32
}

RetryableStepRunner is an interface for PromotionStepRunners that can be retried in the event of a failure.

type SimpleEngine 

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

SimpleEngine is a simple engine that executes a list of PromotionSteps in sequence.

func NewSimpleEngine 

func NewSimpleEngine(
	credentialsDB credentials.Database,
	kargoClient client.Client,
	argoCDClient client.Client,
) *SimpleEngine

NewSimpleEngine returns a new SimpleEngine that uses the package's built-in StepRunnerRegistry.

func (*SimpleEngine) CheckHealth 

func (e *SimpleEngine) CheckHealth(
	ctx context.Context,
	healthCtx HealthCheckContext,
	steps []HealthCheckStep,
) kargoapi.Health

CheckHealth implements the Engine interface.

func (*SimpleEngine) Promote 

func (e *SimpleEngine) Promote(
	ctx context.Context,
	promoCtx PromotionContext,
	steps []PromotionStep,
) (PromotionResult, error)

Promote implements the Engine interface.

type State 

type State map[string]any

State is a type that represents shared state between executions of PromotionSteps. It is not safe for concurrent use at present, as we expect PromotionSteps to be executed sequentially.

func (*State) DeepCopy 

func (s *State) DeepCopy() State

DeepCopy returns a deep copy of the state.

func (State) Get 

func (s State) Get(key string) (any, bool)

Get retrieves a value from the shared state.

func (State) Set 

func (s State) Set(key string, value any)

Set stores a value in the shared state.

func (State) ToJSON 

func (s State) ToJSON() []byte

ToJSON marshals the State to JSON.

type StepRunnerPermissions 

type StepRunnerPermissions struct {
	// AllowCredentialsDB indicates whether the Engine may provide the step runner
	// with access to the credentials database.
	AllowCredentialsDB bool
	// AllowKargoClient indicates whether the Engine may provide the step runner
	// with access to a Kubernetes client for the Kargo control plane.
	AllowKargoClient bool
	// AllowArgoCDClient indicates whether the Engine may provide the step runner
	// with access to a Kubernetes client for the Argo CD control plane.
	AllowArgoCDClient bool
}

StepRunnerPermissions is a set of permissions that indicate capabilities the Engine should enable for a PromotionStepRunner or HealthCheckStepRunner.

type StepRunnerRegistry 

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

StepRunnerRegistry is a registry of built-in PromotionStepRunner and HealthCheckStepRunner implementations.

func NewStepRunnerRegistry 

func NewStepRunnerRegistry() *StepRunnerRegistry

NewStepRunnerRegistry returns a new StepRunnerRegistry.

func (StepRunnerRegistry) GetHealthCheckStepRunnerRegistration 

func (s StepRunnerRegistry) GetHealthCheckStepRunnerRegistration(
	name string,
) (HealthCheckStepRunnerRegistration, error)

GetHealthCheckStepRunnerRegistration returns the HealthStepRunnerRegistration for the health check step with the given name, or an error if no such HealthCheckStepRunner is registered.

func (StepRunnerRegistry) GetPromotionStepRunnerRegistration 

func (s StepRunnerRegistry) GetPromotionStepRunnerRegistration(
	name string,
) (PromotionStepRunnerRegistration, error)

GetPromotionStepRunnerRegistration returns the PromotionStepRunnerRegistration for the promotion step with the given name, or an error if no such PromotionStepRunner is registered.

func (StepRunnerRegistry) RegisterHealthCheckStepRunner 

func (s StepRunnerRegistry) RegisterHealthCheckStepRunner(
	runner HealthCheckStepRunner,
	permissions *StepRunnerPermissions,
)

RegisterHealthCheckStepRunner registers a HealthCheckStepRunner with the given name. If a HealthCheckStepRunner with the same name has already been registered, it will be overwritten.

func (StepRunnerRegistry) RegisterPromotionStepRunner 

func (s StepRunnerRegistry) RegisterPromotionStepRunner(
	runner PromotionStepRunner,
	permissions *StepRunnerPermissions,
)

RegisterPromotionStepRunner registers a PromotionStepRunner with the given name. If a PromotionStepRunner with the same name has already been registered, it will be overwritten.

type YAMLUpdate added in v1.1.0 

type YAMLUpdate struct {
	// The key whose value needs to be updated. For nested values, use a YAML dot notation path.
	Key string `json:"key"`
	// The new value for the specified key.
	Value string `json:"value"`
}

type YAMLUpdateConfig added in v1.1.0 

type YAMLUpdateConfig struct {
	// The path to a YAML file.
	Path string `json:"path"`
	// A list of updates to apply to the YAML file.
	Updates []YAMLUpdate `json:"updates"`
}

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.