Top
KargoService
service/v1alpha1
explicitly empty
AbortVerificationRequest
AbortVerificationResponse
explicitly empty
AdminLoginRequest
| Field | Type | Description |
|---|
| password | string | |
AdminLoginResponse
| Field | Type | Description |
|---|
| id_token | string | |
ApproveFreightRequest
ApproveFreightResponse
explicitly empty
ArgoCDShard
Claims
ComponentVersions
CreateClusterSecretRequest
CreateClusterSecretRequest.DataEntry
CreateClusterSecretResponse
| Field | Type | Description |
|---|
| secret | k8s.io.api.core.v1.Secret | |
CreateCredentialsRequest
CreateCredentialsResponse
| Field | Type | Description |
|---|
| credentials | k8s.io.api.core.v1.Secret | |
CreateOrUpdateResourceRequest
| Field | Type | Description |
|---|
| manifest | bytes | |
CreateOrUpdateResourceResponse
CreateOrUpdateResourceResult
| Field | Type | Description |
|---|
| created_resource_manifest | bytes | |
| updated_resource_manifest | bytes | |
| error | string | |
CreateProjectSecretRequest
CreateProjectSecretRequest.DataEntry
CreateProjectSecretResponse
| Field | Type | Description |
|---|
| secret | k8s.io.api.core.v1.Secret | |
CreateResourceRequest
| Field | Type | Description |
|---|
| manifest | bytes | |
CreateResourceResponse
CreateResourceResult
| Field | Type | Description |
|---|
| created_resource_manifest | bytes | |
| error | string | |
CreateRoleRequest
CreateRoleResponse
DeleteAnalysisTemplateRequest
DeleteAnalysisTemplateResponse
explicitly empty
DeleteClusterAnalysisTemplateRequest
| Field | Type | Description |
|---|
| name | string | |
DeleteClusterAnalysisTemplateResponse
explicitly empty
DeleteClusterConfigRequest
explicitly empty
DeleteClusterConfigResponse
explicitly empty
DeleteClusterSecretRequest
| Field | Type | Description |
|---|
| name | string | |
DeleteClusterSecretResponse
explicitly empty
DeleteCredentialsRequest
DeleteCredentialsResponse
explicitly empty
DeleteFreightRequest
DeleteFreightResponse
explicitly empty
DeleteProjectConfigRequest
| Field | Type | Description |
|---|
| project | string | |
DeleteProjectConfigResponse
explicitly empty
DeleteProjectRequest
| Field | Type | Description |
|---|
| name | string | |
DeleteProjectResponse
explicitly empty
DeleteProjectSecretRequest
DeleteProjectSecretResponse
explicitly empty
DeleteResourceRequest
| Field | Type | Description |
|---|
| manifest | bytes | |
DeleteResourceResponse
DeleteResourceResult
| Field | Type | Description |
|---|
| deleted_resource_manifest | bytes | |
| error | string | |
DeleteRoleRequest
DeleteRoleResponse
explicitly empty
DeleteStageRequest
DeleteStageResponse
explicitly empty
DeleteWarehouseRequest
DeleteWarehouseResponse
explicitly empty
FreightList
GetAnalysisRunLogsRequest
GetAnalysisRunLogsResponse
| Field | Type | Description |
|---|
| chunk | string | |
GetAnalysisRunRequest
GetAnalysisRunResponse
GetAnalysisTemplateRequest
GetAnalysisTemplateResponse
GetClusterAnalysisTemplateRequest
GetClusterAnalysisTemplateResponse
GetClusterConfigRequest
GetClusterConfigResponse
GetConfigMapRequest
GetConfigMapResponse
| Field | Type | Description |
|---|
| config_map | k8s.io.api.core.v1.ConfigMap | |
| raw | bytes | |
GetConfigRequest
GetConfigResponse
GetConfigResponse.ArgocdShardsEntry
GetCredentialsRequest
GetCredentialsResponse
| Field | Type | Description |
|---|
| credentials | k8s.io.api.core.v1.Secret | |
| raw | bytes | |
GetFreightRequest
GetFreightResponse
GetProjectConfigRequest
GetProjectConfigResponse
GetProjectRequest
GetProjectResponse
GetPublicConfigRequest
GetPublicConfigResponse
GetRoleRequest
GetRoleResponse
GetStageRequest
GetStageResponse
GetVersionInfoRequest
GetVersionInfoResponse
GetWarehouseRequest
GetWarehouseResponse
GrantRequest
GrantResponse
ImageStageMap
| Field | Type | Description |
|---|
| stages | ImageStageMap.StagesEntry | stages maps stage names to the order which an image was promoted to that stage |
ImageStageMap.StagesEntry
ListAnalysisTemplatesRequest
| Field | Type | Description |
|---|
| project | string | |
ListAnalysisTemplatesResponse
ListClusterAnalysisTemplatesRequest
ListClusterAnalysisTemplatesResponse
ListClusterSecretsRequest
explicitly empty
ListClusterSecretsResponse
| Field | Type | Description |
|---|
| secrets | k8s.io.api.core.v1.Secret | |
ListConfigMapsRequest
| Field | Type | Description |
|---|
| project | string | |
ListConfigMapsResponse
| Field | Type | Description |
|---|
| config_maps | k8s.io.api.core.v1.ConfigMap | |
ListCredentialsRequest
| Field | Type | Description |
|---|
| project | string | |
ListCredentialsResponse
| Field | Type | Description |
|---|
| credentials | k8s.io.api.core.v1.Secret | |
ListImagesRequest
| Field | Type | Description |
|---|
| project | string | |
ListImagesResponse
ListImagesResponse.ImagesEntry
ListProjectEventsRequest
| Field | Type | Description |
|---|
| project | string | |
ListProjectEventsResponse
| Field | Type | Description |
|---|
| events | k8s.io.api.core.v1.Event | |
ListProjectSecretsRequest
| Field | Type | Description |
|---|
| project | string | |
ListProjectSecretsResponse
| Field | Type | Description |
|---|
| secrets | k8s.io.api.core.v1.Secret | |
ListProjectsRequest
ListProjectsResponse
| Field | Type | Description |
|---|
| project | string | |
ListRolesRequest
ListRolesResponse
ListStagesRequest
| Field | Type | Description |
|---|
| project | string | |
ListStagesResponse
ListWarehousesRequest
| Field | Type | Description |
|---|
| project | string | |
ListWarehousesResponse
OIDCConfig
QueryFreightRequest
QueryFreightResponse
QueryFreightResponse.GroupsEntry
RefreshClusterConfigRequest
explicitly empty
RefreshClusterConfigResponse
RefreshProjectConfigRequest
| Field | Type | Description |
|---|
| project | string | |
RefreshProjectConfigResponse
RefreshStageRequest
RefreshStageResponse
RefreshWarehouseRequest
RefreshWarehouseResponse
ReverifyRequest
ReverifyResponse
explicitly empty
RevokeRequest
RevokeResponse
TagMap
| Field | Type | Description |
|---|
| tags | TagMap.TagsEntry | tags maps image tag names to stages which have previously used that tag |
TagMap.TagsEntry
UpdateClusterSecretRequest
UpdateClusterSecretRequest.DataEntry
UpdateClusterSecretResponse
| Field | Type | Description |
|---|
| secret | k8s.io.api.core.v1.Secret | |
UpdateCredentialsRequest
UpdateCredentialsResponse
| Field | Type | Description |
|---|
| credentials | k8s.io.api.core.v1.Secret | |
UpdateFreightAliasRequest
UpdateFreightAliasResponse
explicitly empty
UpdateProjectSecretRequest
UpdateProjectSecretRequest.DataEntry
UpdateProjectSecretResponse
| Field | Type | Description |
|---|
| secret | k8s.io.api.core.v1.Secret | |
UpdateResourceRequest
| Field | Type | Description |
|---|
| manifest | bytes | |
UpdateResourceResponse
UpdateResourceResult
| Field | Type | Description |
|---|
| updated_resource_manifest | bytes | |
| error | string | |
UpdateRoleRequest
UpdateRoleResponse
VersionInfo
WatchClusterConfigRequest
explicitly empty
WatchClusterConfigResponse
WatchFreightRequest
| Field | Type | Description |
|---|
| project | string | |
WatchFreightResponse
WatchProjectConfigRequest
| Field | Type | Description |
|---|
| project | string | |
WatchProjectConfigResponse
WatchStagesRequest
WatchStagesResponse
WatchWarehousesRequest
WatchWarehousesResponse
| Name | Number | Description |
|---|
| RAW_FORMAT_UNSPECIFIED | 0 | |
| RAW_FORMAT_JSON | 1 | |
| RAW_FORMAT_YAML | 2 | |
Top
rbac/v1alpha1
Claim
ResourceDetails
Role
| Field | Type | Description |
|---|
| metadata | k8s.io.apimachinery.pkg.apis.meta.v1.ObjectMeta | |
| kargoManaged | bool | |
| claims | Claim | |
| rules | k8s.io.api.rbac.v1.PolicyRule | |
RoleResources
| Field | Type | Description |
|---|
| metadata | k8s.io.apimachinery.pkg.apis.meta.v1.ObjectMeta | |
| serviceAccount | k8s.io.api.core.v1.ServiceAccount | |
| roles | k8s.io.api.rbac.v1.Role | |
| roleBindings | k8s.io.api.rbac.v1.RoleBinding | |
Top
v1alpha1
AnalysisRunArgument
AnalysisRunArgument represents an argument to be added to an AnalysisRun.
| Field | Type | Description |
|---|
| name | string | Name is the name of the argument. |
| value | string | Value is the value of the argument. |
AnalysisRunMetadata contains optional metadata that should be applied to all AnalysisRuns.
AnalysisRunMetadata.AnnotationsEntry
AnalysisRunMetadata.LabelsEntry
AnalysisRunReference
AnalysisRunReference is a reference to an AnalysisRun.
| Field | Type | Description |
|---|
| namespace | string | Namespace is the namespace of the AnalysisRun. |
| name | string | Name is the name of the AnalysisRun. |
| phase | string | Phase is the last observed phase of the AnalysisRun referenced by Name. |
AnalysisTemplateReference
AnalysisTemplateReference is a reference to an AnalysisTemplate.
| Field | Type | Description |
|---|
| name | string | Name is the name of the AnalysisTemplate in the same project/namespace as the Stage. |
| kind | string | Kind is the type of the AnalysisTemplate. Can be either AnalysisTemplate or ClusterAnalysisTemplate, default is AnalysisTemplate. |
ApprovedStage
ApprovedStage describes a Stage for which Freight has been (manually) approved.
| Field | Type | Description |
|---|
| approvedAt | k8s.io.apimachinery.pkg.apis.meta.v1.Time | ApprovedAt is the time at which the Freight was approved for the Stage. |
ArgoCDAppHealthStatus
ArgoCDAppHealthStatus describes the health of an ArgoCD Application.
ArgoCDAppStatus
ArgoCDAppStatus describes the current state of a single ArgoCD Application.
| Field | Type | Description |
|---|
| namespace | string | Namespace is the namespace of the ArgoCD Application. |
| name | string | Name is the name of the ArgoCD Application. |
| healthStatus | ArgoCDAppHealthStatus | HealthStatus is the health of the ArgoCD Application. |
| syncStatus | ArgoCDAppSyncStatus | SyncStatus is the sync status of the ArgoCD Application. |
ArgoCDAppSyncStatus
ArgoCDAppSyncStatus describes the sync status of an ArgoCD Application.
ArtifactoryWebhookReceiverConfig
ArtifactoryWebhookReceiverConfig describes a webhook receiver that is compatible with JFrog Artifactory payloads.
| Field | Type | Description |
|---|
| secretRef | k8s.io.api.core.v1.LocalObjectReference | SecretRef contains a reference to a Secret. For Project-scoped webhook receivers, the referenced Secret must be in the same namespace as the ProjectConfig. For cluster-scoped webhook receivers, the referenced Secret must be in the designated "cluster Secrets" namespace. The Secret's data map is expected to contain a secret-token key whose value is the shared secret used to authenticate the webhook requests sent by JFrog Artifactory. For more information please refer to the JFrog Artifactory documentation: https://jfrog.com/help/r/jfrog-platform-administration-documentation/webhooks |
AzureWebhookReceiverConfig
AzureWebhookReceiverConfig describes a webhook receiver that is compatible with Azure Container Registry (ACR) and Azure DevOps payloads.
BitbucketWebhookReceiverConfig
BitbucketWebhookReceiverConfig describes a webhook receiver that is compatible with Bitbucket payloads.
| Field | Type | Description |
|---|
| secretRef | k8s.io.api.core.v1.LocalObjectReference | SecretRef contains a reference to a Secret. For Project-scoped webhook receivers, the referenced Secret must be in the same namespace as the ProjectConfig. For cluster-scoped webhook receivers, the referenced Secret must be in the designated "cluster Secrets" namespace. The Secret's data map is expected to contain a secret key whose value is the shared secret used to authenticate the webhook requests sent by Bitbucket. For more information please refer to the Bitbucket documentation: https://support.atlassian.com/bitbucket-cloud/docs/manage-webhooks/ |
Chart
Chart describes a specific version of a Helm chart.
| Field | Type | Description |
|---|
| repoURL | string | RepoURL specifies the URL of a Helm chart repository. Classic chart repositories (using HTTP/S) can contain differently named charts. When this field points to such a repository, the Name field will specify the name of the chart within the repository. In the case of a repository within an OCI registry, the URL implicitly points to a specific chart and the Name field will be empty. |
| name | string | Name specifies the name of the chart. |
| version | string | Version specifies a particular version of the chart. |
ChartDiscoveryResult
ChartDiscoveryResult represents the result of a chart discovery operation for a ChartSubscription.
| Field | Type | Description |
|---|
| repoURL | string | RepoURL is the repository URL of the Helm chart, as specified in the ChartSubscription. |
| name | string | Name is the name of the Helm chart, as specified in the ChartSubscription. |
| semverConstraint | string | SemverConstraint is the constraint for which versions were discovered. This field is optional, and only populated if the ChartSubscription specifies a SemverConstraint. |
| versions | string | Versions is a list of versions discovered by the Warehouse for the ChartSubscription. An empty list indicates that the discovery operation was successful, but no versions matching the ChartSubscription criteria were found. +optional |
ChartSubscription
ChartSubscription defines a subscription to a Helm chart repository.
| Field | Type | Description |
|---|
| repoURL | string | RepoURL specifies the URL of a Helm chart repository. It may be a classic chart repository (using HTTP/S) OR a repository within an OCI registry. Classic chart repositories can contain differently named charts. When this field points to such a repository, the Name field MUST also be used to specify the name of the desired chart within that repository. In the case of a repository within an OCI registry, the URL implicitly points to a specific chart and the Name field MUST NOT be used. The RepoURL field is required. |
| name | string | Name specifies the name of a Helm chart to subscribe to within a classic chart repository specified by the RepoURL field. This field is required when the RepoURL field points to a classic chart repository and MUST otherwise be empty. |
| semverConstraint | string | SemverConstraint specifies constraints on what new chart versions are permissible. This field is optional. When left unspecified, there will be no constraints, which means the latest version of the chart will always be used. Care should be taken with leaving this field unspecified, as it can lead to the unanticipated rollout of breaking changes. More info: https://github.com/masterminds/semver#checking-version-constraints |
| discoveryLimit | int32 | DiscoveryLimit is an optional limit on the number of chart versions that can be discovered for this subscription. The limit is applied after filtering charts based on the SemverConstraint field. When left unspecified, the field is implicitly treated as if its value were "20". The upper limit for this field is 100. |
ClusterConfig
ClusterConfig is a resource type that describes cluster-level Kargo configuration.
| Field | Type | Description |
|---|
| metadata | k8s.io.apimachinery.pkg.apis.meta.v1.ObjectMeta | |
| spec | ClusterConfigSpec | Spec describes the configuration of a cluster. |
| status | ClusterConfigStatus | Status describes the current status of a ClusterConfig. |
ClusterConfigList
ClusterConfigList contains a list of ClusterConfigs.
| Field | Type | Description |
|---|
| metadata | k8s.io.apimachinery.pkg.apis.meta.v1.ListMeta | |
| items | ClusterConfig | |
ClusterConfigSpec
ClusterConfigSpec describes cluster-level Kargo configuration.
| Field | Type | Description |
|---|
| webhookReceivers | WebhookReceiverConfig | WebhookReceivers describes cluster-scoped webhook receivers used for processing events from various external platforms |
ClusterConfigStatus
ClusterConfigStatus describes the current status of a ClusterConfig.
| Field | Type | Description |
|---|
| conditions | k8s.io.apimachinery.pkg.apis.meta.v1.Condition | Conditions contains the last observations of the ClusterConfig's current state. +patchMergeKey=type +patchStrategy=merge +listType=map +listMapKey=type |
| observedGeneration | int64 | ObservedGeneration represents the .metadata.generation that this ClusterConfig was reconciled against. |
| lastHandledRefresh | string | LastHandledRefresh holds the value of the most recent AnnotationKeyRefresh annotation that was handled by the controller. This field can be used to determine whether the request to refresh the resource has been handled. +optional |
| webhookReceivers | WebhookReceiverDetails | WebhookReceivers describes the status of cluster-scoped webhook receivers. |
| Field | Type | Description |
|---|
| metadata | k8s.io.apimachinery.pkg.apis.meta.v1.ObjectMeta | |
| spec | PromotionTaskSpec | Spec describes the desired transition of a specific Stage into a specific Freight. |
ClusterPromotionTaskList contains a list of PromotionTasks.
CurrentStage
CurrentStage reflects a Stage's current use of Freight.
| Field | Type | Description |
|---|
| since | k8s.io.apimachinery.pkg.apis.meta.v1.Time | Since is the time at which the Stage most recently started using the Freight. This can be used to calculate how long the Freight has been in use by the Stage. |
DiscoveredArtifacts
DiscoveredArtifacts holds the artifacts discovered by the Warehouse for its subscriptions.
| Field | Type | Description |
|---|
| discoveredAt | k8s.io.apimachinery.pkg.apis.meta.v1.Time | DiscoveredAt is the time at which the Warehouse discovered the artifacts. +optional |
| git | GitDiscoveryResult | Git holds the commits discovered by the Warehouse for the Git subscriptions. +optional |
| images | ImageDiscoveryResult | Images holds the image references discovered by the Warehouse for the image subscriptions. +optional |
| charts | ChartDiscoveryResult | Charts holds the charts discovered by the Warehouse for the chart subscriptions. +optional |
DiscoveredCommit
DiscoveredCommit represents a commit discovered by a Warehouse for a GitSubscription.
| Field | Type | Description |
|---|
| id | string | ID is the identifier of the commit. This typically is a SHA-1 hash. |
| branch | string | Branch is the branch in which the commit was found. This field is optional, and populated based on the CommitSelectionStrategy of the GitSubscription. |
| tag | string | Tag is the tag that resolved to this commit. This field is optional, and populated based on the CommitSelectionStrategy of the GitSubscription. |
| subject | string | Subject is the subject of the commit (i.e. the first line of the commit message). |
| author | string | Author is the author of the commit. |
| committer | string | Committer is the person who committed the commit. |
| creatorDate | k8s.io.apimachinery.pkg.apis.meta.v1.Time | CreatorDate is the commit creation date as specified by the commit, or the tagger date if the commit belongs to an annotated tag. |
DiscoveredImageReference
DiscoveredImageReference represents an image reference discovered by a Warehouse for an ImageSubscription.
| Field | Type | Description |
|---|
| tag | string | Tag is the tag of the image. |
| digest | string | Digest is the digest of the image. |
| annotations | DiscoveredImageReference.AnnotationsEntry | Annotations is a map of key-value pairs that provide additional information about the image. |
| createdAt | k8s.io.apimachinery.pkg.apis.meta.v1.Time | CreatedAt is the time the image was created. This field is optional, and not populated for every ImageSelectionStrategy. |
DiscoveredImageReference.AnnotationsEntry
DockerHubWebhookReceiverConfig
DockerHubWebhookReceiverConfig describes a webhook receiver that is compatible with Docker Hub payloads.
| Field | Type | Description |
|---|
| secretRef | k8s.io.api.core.v1.LocalObjectReference | SecretRef contains a reference to a Secret. For Project-scoped webhook receivers, the referenced Secret must be in the same namespace as the ProjectConfig. The Secret's data map is expected to contain a secret key whose value does NOT need to be shared directly with Docker Hub when registering a webhook. It is used only by Kargo to create a complex, hard-to-guess URL, which implicitly serves as a shared secret. For more information about Docker Hub webhooks, please refer to the Docker documentation: https://docs.docker.com/docker-hub/webhooks/ |
ExpressionVariable
ExpressionVariable describes a single variable that may be referenced by expressions in the context of a ClusterPromotionTask, PromotionTask, Promotion, AnalysisRun arguments, or other objects that support expressions. It is used to pass information to the expression evaluation engine, and to allow for dynamic evaluation of expressions based on the variable values.
Freight
Freight represents a collection of versioned artifacts.
| Field | Type | Description |
|---|
| metadata | k8s.io.apimachinery.pkg.apis.meta.v1.ObjectMeta | |
| alias | string | Alias is a human-friendly alias for a piece of Freight. This is an optional field. A defaulting webhook will sync this field with the value of the kargo.akuity.io/alias label. When the alias label is not present or differs from the value of this field, the defaulting webhook will set the label to the value of this field. If the alias label is present and this field is empty, the defaulting webhook will set the value of this field to the value of the alias label. If this field is empty and the alias label is not present, the defaulting webhook will choose an available alias and assign it to both the field and label. |
| origin | FreightOrigin | Origin describes a kind of Freight in terms of its origin. |
| commits | GitCommit | Commits describes specific Git repository commits. |
| images | Image | Images describes specific versions of specific container images. |
| charts | Chart | Charts describes specific versions of specific Helm charts. |
| status | FreightStatus | Status describes the current status of this Freight. |
FreightCollection
FreightCollection is a collection of FreightReferences, each of which represents a piece of Freight that has been selected for deployment to a Stage.
| Field | Type | Description |
|---|
| id | string | ID is a unique and deterministically calculated identifier for the FreightCollection. It is updated on each use of the UpdateOrPush method. |
| items | FreightCollection.ItemsEntry | Freight is a map of FreightReference objects, indexed by their Warehouse origin. |
| verificationHistory | VerificationInfo | VerificationHistory is a stack of recent VerificationInfo. By default, the last ten VerificationInfo are stored. |
FreightCollection.ItemsEntry
FreightList
FreightList is a list of Freight resources.
| Field | Type | Description |
|---|
| metadata | k8s.io.apimachinery.pkg.apis.meta.v1.ListMeta | |
| items | Freight | |
FreightOrigin
FreightOrigin describes a kind of Freight in terms of where it may have originated. +protobuf.options.(gogoproto.goproto_stringer)=false
| Field | Type | Description |
|---|
| kind | string | Kind is the kind of resource from which Freight may have originated. At present, this can only be "Warehouse". |
| name | string | Name is the name of the resource of the kind indicated by the Kind field from which Freight may originate. |
FreightReference
FreightReference is a simplified representation of a piece of Freight -- not a root resource type.
| Field | Type | Description |
|---|
| name | string | Name is a system-assigned identifier derived deterministically from the contents of the Freight. I.e., two pieces of Freight can be compared for equality by comparing their Names. |
| origin | FreightOrigin | Origin describes a kind of Freight in terms of its origin. |
| commits | GitCommit | Commits describes specific Git repository commits. |
| images | Image | Images describes specific versions of specific container images. |
| charts | Chart | Charts describes specific versions of specific Helm charts. |
FreightRequest
FreightRequest expresses a Stage's need for Freight having originated from a particular Warehouse.
| Field | Type | Description |
|---|
| origin | FreightOrigin | Origin specifies from where the requested Freight must have originated. This is a required field. |
| sources | FreightSources | Sources describes where the requested Freight may be obtained from. This is a required field. |
FreightSources
| Field | Type | Description |
|---|
| direct | bool | Direct indicates the requested Freight may be obtained directly from the Warehouse from which it originated. If this field's value is false, then the value of the Stages field must be non-empty. i.e. Between the two fields, at least one source must be specified. |
| stages | string | Stages identifies other "upstream" Stages as potential sources of the requested Freight. If this field's value is empty, then the value of the Direct field must be true. i.e. Between the two fields, at least on source must be specified. |
| requiredSoakTime | k8s.io.apimachinery.pkg.apis.meta.v1.Duration | RequiredSoakTime specifies a minimum duration for which the requested Freight must have continuously occupied ("soaked in") in an upstream Stage before becoming available for promotion to this Stage. This is an optional field. If nil or zero, no soak time is required. Any soak time requirement is in ADDITION to the requirement that Freight be verified in an upstream Stage to become available for promotion to this Stage, although a manual approval for promotion to this Stage will supersede any soak time requirement. |
| availabilityStrategy | string | AvailabilityStrategy specifies the semantics for how requested Freight is made available to the Stage. This field is optional. When left unspecified, the field is implicitly treated as if its value were "OneOf". Accepted Values: - "All": Freight must be verified and, if applicable, soaked in all upstream Stages to be considered available for promotion. - "OneOf": Freight must be verified and, if applicable, soaked in at least one upstream Stage to be considered available for promotion. - "": Treated the same as "OneOf". |
FreightStatus
FreightStatus describes a piece of Freight's most recently observed state.
| Field | Type | Description |
|---|
| currentlyIn | FreightStatus.CurrentlyInEntry | CurrentlyIn describes the Stages in which this Freight is currently in use. |
| verifiedIn | FreightStatus.VerifiedInEntry | VerifiedIn describes the Stages in which this Freight has been verified through promotion and subsequent health checks. |
| approvedFor | FreightStatus.ApprovedForEntry | ApprovedFor describes the Stages for which this Freight has been approved preemptively/manually by a user. This is useful for hotfixes, where one might wish to promote a piece of Freight to a given Stage without transiting the entire pipeline. |
| metadata | FreightStatus.MetadataEntry | Metadata is a map of arbitrary metadata associated with the Freight. This is useful for storing additional information about the Freight or Promotion that can be shared across steps or stages. |
FreightStatus.ApprovedForEntry
FreightStatus.CurrentlyInEntry
FreightStatus.MetadataEntry
| Field | Type | Description |
|---|
| key | string | |
| value | k8s.io.apiextensions_apiserver.pkg.apis.apiextensions.v1.JSON | |
FreightStatus.VerifiedInEntry
GitCommit
GitCommit describes a specific commit from a specific Git repository.
| Field | Type | Description |
|---|
| repoURL | string | RepoURL is the URL of a Git repository. |
| id | string | ID is the ID of a specific commit in the Git repository specified by RepoURL. |
| branch | string | Branch denotes the branch of the repository where this commit was found. |
| tag | string | Tag denotes a tag in the repository that matched selection criteria and resolved to this commit. |
| message | string | Message is the message associated with the commit. At present, this only contains the first line (subject) of the commit message. |
| author | string | Author is the author of the commit. |
| committer | string | Committer is the person who committed the commit. |
GitDiscoveryResult
GitDiscoveryResult represents the result of a Git discovery operation for a GitSubscription.
| Field | Type | Description |
|---|
| repoURL | string | RepoURL is the repository URL of the GitSubscription. |
| commits | DiscoveredCommit | Commits is a list of commits discovered by the Warehouse for the GitSubscription. An empty list indicates that the discovery operation was successful, but no commits matching the GitSubscription criteria were found. +optional |
GitHubWebhookReceiverConfig
GitHubWebhookReceiverConfig describes a webhook receiver that is compatible with GitHub payloads.
| Field | Type | Description |
|---|
| secretRef | k8s.io.api.core.v1.LocalObjectReference | SecretRef contains a reference to a Secret. For Project-scoped webhook receivers, the referenced Secret must be in the same namespace as the ProjectConfig. For cluster-scoped webhook receivers, the referenced Secret must be in the designated "cluster Secrets" namespace. The Secret's data map is expected to contain a secret key whose value is the shared secret used to authenticate the webhook requests sent by GitHub. For more information please refer to GitHub documentation: https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries |
GitLabWebhookReceiverConfig
GitLabWebhookReceiverConfig describes a webhook receiver that is compatible with GitLab payloads.
| Field | Type | Description |
|---|
| secretRef | k8s.io.api.core.v1.LocalObjectReference | SecretRef contains a reference to a Secret. For Project-scoped webhook receivers, the referenced Secret must be in the same namespace as the ProjectConfig. For cluster-scoped webhook receivers, the referenced Secret must be in the designated "cluster Secrets" namespace. The secret is expected to contain a secret-token key containing the shared secret specified when registering the webhook in GitLab. For more information about this token, please refer to the GitLab documentation: https://docs.gitlab.com/user/project/integrations/webhooks/ |
GitSubscription
GitSubscription defines a subscription to a Git repository.
| Field | Type | Description |
|---|
| repoURL | string | URL is the repository's URL. This is a required field. |
| commitSelectionStrategy | string | CommitSelectionStrategy specifies the rules for how to identify the newest commit of interest in the repository specified by the RepoURL field. This field is optional. When left unspecified, the field is implicitly treated as if its value were "NewestFromBranch". Accepted values: - "NewestFromBranch": Selects the latest commit on the branch specified by the Branch field or the default branch if none is specified. This is the default strategy. - "SemVer": Selects the commit referenced by the semantically greatest tag. The SemverConstraint field can optionally be used to narrow the set of tags eligible for selection. - "Lexical": Selects the commit referenced by the lexicographically greatest tag. Useful when tags embed a leading date or timestamp. The AllowTags and IgnoreTags fields can optionally be used to narrow the set of tags eligible for selection. - "NewestTag": Selects the commit referenced by the most recently created tag. The AllowTags and IgnoreTags fields can optionally be used to narrow the set of tags eligible for selection. |
| branch | string | Branch references a particular branch of the repository. The value in this field only has any effect when the CommitSelectionStrategy is NewestFromBranch or left unspecified (which is implicitly the same as NewestFromBranch). This field is optional. When left unspecified, (and the CommitSelectionStrategy is NewestFromBranch or unspecified), the subscription is implicitly to the repository's default branch. |
| strictSemvers | bool | StrictSemvers specifies whether only "strict" semver tags should be considered. A "strict" semver tag is one containing ALL of major, minor, and patch version components. This is enabled by default, but only has any effect when the CommitSelectionStrategy is SemVer. This should be disabled cautiously, as it creates the potential for any tag containing numeric characters only to be mistaken for a semver string containing the major version number only. |
| semverConstraint | string | SemverConstraint specifies constraints on what new tagged commits are considered in determining the newest commit of interest. The value in this field only has any effect when the CommitSelectionStrategy is SemVer. This field is optional. When left unspecified, there will be no constraints, which means the latest semantically tagged commit will always be used. Care should be taken with leaving this field unspecified, as it can lead to the unanticipated rollout of breaking changes. |
| allowTags | string | AllowTags is a regular expression that can optionally be used to limit the tags that are considered in determining the newest commit of interest. The value in this field only has any effect when the CommitSelectionStrategy is Lexical, NewestTag, or SemVer. This field is optional. |
| ignoreTags | string | IgnoreTags is a list of tags that must be ignored when determining the newest commit of interest. No regular expressions or glob patterns are supported yet. The value in this field only has any effect when the CommitSelectionStrategy is Lexical, NewestTag, or SemVer. This field is optional. |
| expressionFilter | string | ExpressionFilter is an expression that can optionally be used to limit the commits or tags that are considered in determining the newest commit of interest based on their metadata. For commit-based strategies (NewestFromBranch), the filter applies to commits and has access to commit metadata variables. For tag-based strategies (Lexical, NewestTag, SemVer), the filter applies to tags and has access to tag metadata variables. The filter is applied after AllowTags, IgnoreTags, and SemverConstraint fields. The expression should be a valid expr-lang expression that evaluates to true or false. When the expression evaluates to true, the commit/tag is included in the set that is considered. When the expression evaluates to false, the commit/tag is excluded. Available variables depend on the CommitSelectionStrategy: For NewestFromBranch (commit filtering): - id: The ID (sha) of the commit. - commitDate: The commit date of the commit. - author: The author of the commit message, in the format "Name <email>". - committer: The person who committed the commit, in the format "Name <email>". - subject: The subject (first line) of the commit message. For Lexical, NewestTag, SemVer (tag filtering): - tag: The name of the tag. - id: The ID (sha) of the commit associated with the tag. - creatorDate: The creation date of an annotated tag, or the commit date of a lightweight tag. - author: The author of the commit message associated with the tag, in the format "Name <email>". - committer: The person who committed the commit associated with the tag, in the format "Name <email>". - subject: The subject (first line) of the commit message associated with the tag. - tagger: The person who created the tag, in the format "Name <email>". Only available for annotated tags. - annotation: The subject (first line) of the tag annotation. Only available for annotated tags. Refer to the expr-lang documentation for more details on syntax and capabilities of the expression language: https://expr-lang.org. |
| insecureSkipTLSVerify | bool | InsecureSkipTLSVerify specifies whether certificate verification errors should be ignored when connecting to the repository. This should be enabled only with great caution. |
| includePaths | string | IncludePaths is a list of selectors that designate paths in the repository that should trigger the production of new Freight when changes are detected therein. When specified, only changes in the identified paths will trigger Freight production. When not specified, changes in any path will trigger Freight production. Selectors may be defined using: 1. Exact paths to files or directories (ex. "charts/foo") 2. Glob patterns (prefix the pattern with "glob:"; ex. "glob:.yaml") 3. Regular expressions (prefix the pattern with "regex:" or "regexp:"; ex. "regexp:^..yaml$") Paths selected by IncludePaths may be unselected by ExcludePaths. This is a useful method for including a broad set of paths and then excluding a subset of them. |
| excludePaths | string | ExcludePaths is a list of selectors that designate paths in the repository that should NOT trigger the production of new Freight when changes are detected therein. When specified, changes in the identified paths will not trigger Freight production. When not specified, paths that should trigger Freight production will be defined solely by IncludePaths. Selectors may be defined using: 1. Exact paths to files or directories (ex. "charts/foo") 2. Glob patterns (prefix the pattern with "glob:"; ex. "glob:.yaml") 3. Regular expressions (prefix the pattern with "regex:" or "regexp:"; ex. "regexp:^..yaml$") Paths selected by IncludePaths may be unselected by ExcludePaths. This is a useful method for including a broad set of paths and then excluding a subset of them. |
| discoveryLimit | int32 | DiscoveryLimit is an optional limit on the number of commits that can be discovered for this subscription. The limit is applied after filtering commits based on the AllowTags and IgnoreTags fields. When left unspecified, the field is implicitly treated as if its value were "20". The upper limit for this field is 100. |
GiteaWebhookReceiverConfig
GiteaWebhookReceiverConfig describes a webhook receiver that is compatible with Gitea payloads.
| Field | Type | Description |
|---|
| secretRef | k8s.io.api.core.v1.LocalObjectReference | SecretRef contains a reference to a Secret. For Project-scoped webhook receivers, the referenced Secret must be in the same namespace as the ProjectConfig. For cluster-scoped webhook receivers, the referenced Secret must be in the designated "cluster Secrets" namespace. The Secret's data map is expected to contain a secret key whose value is the shared secret used to authenticate the webhook requests sent by Gitea. For more information please refer to the Gitea documentation: https://docs.gitea.io/en-us/webhooks/ |
HarborWebhookReceiverConfig
HarborWebhookReceiverConfig describes a webhook receiver that is compatible with Harbor payloads.
| Field | Type | Description |
|---|
| secretRef | k8s.io.api.core.v1.LocalObjectReference | SecretRef contains a reference to a Secret. For Project-scoped webhook receivers, the referenced Secret must be in the same namespace as the ProjectConfig. For cluster-scoped webhook receivers, the referenced Secret must be in the designated "cluster Secrets" namespace. The secret is expected to contain an auth-header key containing the "auth header" specified when registering the webhook in Harbor. For more information, please refer to the Harbor documentation: https://goharbor.io/docs/main/working-with-projects/project-configuration/configure-webhooks/ |
Health
Health describes the health of a Stage.
| Field | Type | Description |
|---|
| status | string | Status describes the health of the Stage. |
| issues | string | Issues clarifies why a Stage in any state other than Healthy is in that state. This field will always be the empty when a Stage is Healthy. |
| config | k8s.io.apiextensions_apiserver.pkg.apis.apiextensions.v1.JSON | Config is the opaque configuration of all health checks performed on this Stage. |
| output | k8s.io.apiextensions_apiserver.pkg.apis.apiextensions.v1.JSON | Output is the opaque output of all health checks performed on this Stage. |
HealthCheckStep
HealthCheckStep describes a health check directive which can be executed by a Stage to verify the health of a Promotion result.
| Field | Type | Description |
|---|
| uses | string | Uses identifies a runner that can execute this step. |
| config | k8s.io.apiextensions_apiserver.pkg.apis.apiextensions.v1.JSON | Config is the configuration for the directive. |
HealthStats
HealthStats contains a summary of the collective health of some resource type.
| Field | Type | Description |
|---|
| healthy | int64 | Healthy contains the number of resources that are explicitly healthy. |
Image
Image describes a specific version of a container image.
| Field | Type | Description |
|---|
| repoURL | string | RepoURL describes the repository in which the image can be found. |
| tag | string | Tag identifies a specific version of the image in the repository specified by RepoURL. |
| digest | string | Digest identifies a specific version of the image in the repository specified by RepoURL. This is a more precise identifier than Tag. |
| annotations | Image.AnnotationsEntry | Annotations is a map of arbitrary metadata for the image. |
Image.AnnotationsEntry
ImageDiscoveryResult
ImageDiscoveryResult represents the result of an image discovery operation for an ImageSubscription.
| Field | Type | Description |
|---|
| repoURL | string | RepoURL is the repository URL of the image, as specified in the ImageSubscription. |
| platform | string | Platform is the target platform constraint of the ImageSubscription for which references were discovered. This field is optional, and only populated if the ImageSubscription specifies a Platform. |
| references | DiscoveredImageReference | References is a list of image references discovered by the Warehouse for the ImageSubscription. An empty list indicates that the discovery operation was successful, but no images matching the ImageSubscription criteria were found. +optional |
ImageSubscription
ImageSubscription defines a subscription to an image repository.
| Field | Type | Description |
|---|
| repoURL | string | RepoURL specifies the URL of the image repository to subscribe to. The value in this field MUST NOT include an image tag. This field is required. |
| imageSelectionStrategy | string | ImageSelectionStrategy specifies the rules for how to identify the newest version of the image specified by the RepoURL field. This field is optional. When left unspecified, the field is implicitly treated as if its value were "SemVer". Accepted values: - "Digest": Selects the image currently referenced by the tag specified (unintuitively) by the SemverConstraint field. - "Lexical": Selects the image referenced by the lexicographically greatest tag. Useful when tags embed a leading date or timestamp. The AllowTags and IgnoreTags fields can optionally be used to narrow the set of tags eligible for selection. - "NewestBuild": Selects the image that was most recently pushed to the repository. The AllowTags and IgnoreTags fields can optionally be used to narrow the set of tags eligible for selection. This is the least efficient and is likely to cause rate limiting affecting this Warehouse and possibly others. This strategy should be avoided. - "SemVer": Selects the image with the semantically greatest tag. The AllowTags and IgnoreTags fields can optionally be used to narrow the set of tags eligible for selection. |
| strictSemvers | bool | StrictSemvers specifies whether only "strict" semver tags should be considered. A "strict" semver tag is one containing ALL of major, minor, and patch version components. This is enabled by default, but only has any effect when the ImageSelectionStrategy is SemVer. This should be disabled cautiously, as it is not uncommon to tag container images with short Git commit hashes, which have the potential to contain numeric characters only and could be mistaken for a semver string containing the major version number only. |
| semverConstraint | string | SemverConstraint specifies constraints on what new image versions are permissible. The value in this field only has any effect when the ImageSelectionStrategy is SemVer or left unspecified (which is implicitly the same as SemVer). This field is also optional. When left unspecified, (and the ImageSelectionStrategy is SemVer or unspecified), there will be no constraints, which means the latest semantically tagged version of an image will always be used. Care should be taken with leaving this field unspecified, as it can lead to the unanticipated rollout of breaking changes. More info: https://github.com/masterminds/semver#checking-version-constraints Deprecated: Use Constraint instead. This field will be removed in v1.9.0 |
| constraint | string | Constraint specifies constraints on what new image versions are permissible. Acceptable values for this field vary contextually by ImageSelectionStrategy. The field is optional and is ignored by some strategies. When non-empty, the value in this field takes precedence over the value of the deprecated SemverConstraint field. |
| allowTags | string | AllowTags is a regular expression that can optionally be used to limit the image tags that are considered in determining the newest version of an image. This field is optional. |
| ignoreTags | string | IgnoreTags is a list of tags that must be ignored when determining the newest version of an image. No regular expressions or glob patterns are supported yet. This field is optional. |
| platform | string | Platform is a string of the form <os>/<arch> that limits the tags that can be considered when searching for new versions of an image. This field is optional. When left unspecified, it is implicitly equivalent to the OS/architecture of the Kargo controller. Care should be taken to set this value correctly in cases where the image referenced by this ImageRepositorySubscription will run on a Kubernetes node with a different OS/architecture than the Kargo controller. At present this is uncommon, but not unheard of. |
| insecureSkipTLSVerify | bool | InsecureSkipTLSVerify specifies whether certificate verification errors should be ignored when connecting to the repository. This should be enabled only with great caution. |
| discoveryLimit | int32 | DiscoveryLimit is an optional limit on the number of image references that can be discovered for this subscription. The limit is applied after filtering images based on the AllowTags and IgnoreTags fields. When left unspecified, the field is implicitly treated as if its value were "20". The upper limit for this field is 100. |
Project
Project is a resource type that reconciles to a specially labeled namespace and other TODO: TBD project-level resources.
| Field | Type | Description |
|---|
| metadata | k8s.io.apimachinery.pkg.apis.meta.v1.ObjectMeta | |
| status | ProjectStatus | Status describes the Project's current status. |
ProjectConfig
ProjectConfig is a resource type that describes the configuration of a Project.
| Field | Type | Description |
|---|
| metadata | k8s.io.apimachinery.pkg.apis.meta.v1.ObjectMeta | |
| spec | ProjectConfigSpec | Spec describes the configuration of a Project. |
| status | ProjectConfigStatus | Status describes the current status of a ProjectConfig. |
ProjectConfigList
ProjectConfigList is a list of ProjectConfig resources.
| Field | Type | Description |
|---|
| metadata | k8s.io.apimachinery.pkg.apis.meta.v1.ListMeta | |
| items | ProjectConfig | |
ProjectConfigSpec
ProjectConfigSpec describes the configuration of a Project.
| Field | Type | Description |
|---|
| promotionPolicies | PromotionPolicy | PromotionPolicies defines policies governing the promotion of Freight to specific Stages within the Project. |
| webhookReceivers | WebhookReceiverConfig | WebhookReceivers describes Project-specific webhook receivers used for processing events from various external platforms |
ProjectConfigStatus
ProjectConfigStatus describes the current status of a ProjectConfig.
| Field | Type | Description |
|---|
| conditions | k8s.io.apimachinery.pkg.apis.meta.v1.Condition | Conditions contains the last observations of the Project Config's current state. +patchMergeKey=type +patchStrategy=merge +listType=map +listMapKey=type |
| observedGeneration | int64 | ObservedGeneration represents the .metadata.generation that this ProjectConfig was reconciled against. |
| lastHandledRefresh | string | LastHandledRefresh holds the value of the most recent AnnotationKeyRefresh annotation that was handled by the controller. This field can be used to determine whether the request to refresh the resource has been handled. +optional |
| webhookReceivers | WebhookReceiverDetails | WebhookReceivers describes the status of Project-specific webhook receivers. |
ProjectList
ProjectList is a list of Project resources.
| Field | Type | Description |
|---|
| metadata | k8s.io.apimachinery.pkg.apis.meta.v1.ListMeta | |
| items | Project | |
ProjectStats
ProjectStats contains a summary of the collective state of a Project's constituent resources.
| Field | Type | Description |
|---|
| warehouses | WarehouseStats | Warehouses contains a summary of the collective state of the Project's Warehouses. |
| stages | StageStats | Stages contains a summary of the collective state of the Project's Stages. |
ProjectStatus
ProjectStatus describes a Project's current status.
| Field | Type | Description |
|---|
| conditions | k8s.io.apimachinery.pkg.apis.meta.v1.Condition | Conditions contains the last observations of the Project's current state. +patchMergeKey=type +patchStrategy=merge +listType=map +listMapKey=type |
| stats | ProjectStats | Stats contains a summary of the collective state of a Project's constituent resources. |
Promotion represents a request to transition a particular Stage into a particular Freight.
| Field | Type | Description |
|---|
| metadata | k8s.io.apimachinery.pkg.apis.meta.v1.ObjectMeta | |
| spec | PromotionSpec | Spec describes the desired transition of a specific Stage into a specific Freight. |
| status | PromotionStatus | Status describes the current state of the transition represented by this Promotion. |
PromotionList contains a list of Promotion
| Field | Type | Description |
|---|
| metadata | k8s.io.apimachinery.pkg.apis.meta.v1.ListMeta | |
| items | Promotion | |
PromotionPolicy defines policies governing the promotion of Freight to a specific Stage.
| Field | Type | Description |
|---|
| stage | string | Stage is the name of the Stage to which this policy applies. Deprecated: Use StageSelector instead. |
| stageSelector | PromotionPolicySelector | StageSelector is a selector that matches the Stage resource to which this policy applies. |
| autoPromotionEnabled | bool | AutoPromotionEnabled indicates whether new Freight can automatically be promoted into the Stage referenced by the Stage field. Note: There are may be other conditions also required for an auto-promotion to occur. This field defaults to false, but is commonly set to true for Stages that subscribe to Warehouses instead of other, upstream Stages. This allows users to define Stages that are automatically updated as soon as new artifacts are detected. |
PromotionPolicySelector is a selector that matches the resource to which this policy applies. It can be used to match a specific resource by name or to match a set of resources by label.
| Field | Type | Description |
|---|
| name | string | Name is the name of the resource to which this policy applies. It can be an exact name, a regex pattern (with prefix "regex:"), or a glob pattern (with prefix "glob:"). When both Name and LabelSelector are specified, the Name is ANDed with the LabelSelector. I.e., the resource must match both the Name and LabelSelector to be selected by this policy. NOTE: Using a specific exact name is the most secure option. Pattern matching via regex or glob can be exploited by users with permissions to match promotion policies that weren't intended to apply to their resources. For example, a user could create a resource with a name deliberately crafted to match the pattern, potentially bypassing intended promotion controls. +optional |
| labelSelector | k8s.io.apimachinery.pkg.apis.meta.v1.LabelSelector | LabelSelector is a selector that matches the resource to which this policy applies. When both Name and LabelSelector are specified, the Name is ANDed with the LabelSelector. I.e., the resource must match both the Name and LabelSelector to be selected by this policy. NOTE: Using label selectors introduces security risks as users with appropriate permissions could create new resources with labels that match the selector, potentially enabling unauthorized auto-promotion. For sensitive environments, exact Name matching provides tighter control. |
PromotionReference contains the relevant information about a Promotion as observed by a Stage.
| Field | Type | Description |
|---|
| name | string | Name is the name of the Promotion. |
| freight | FreightReference | Freight is the freight being promoted. |
| status | PromotionStatus | Status is the (optional) status of the Promotion. |
| finishedAt | k8s.io.apimachinery.pkg.apis.meta.v1.Time | FinishedAt is the time at which the Promotion was completed. |
PromotionSpec describes the desired transition of a specific Stage into a specific Freight.
| Field | Type | Description |
|---|
| stage | string | Stage specifies the name of the Stage to which this Promotion applies. The Stage referenced by this field MUST be in the same namespace as the Promotion. |
| freight | string | Freight specifies the piece of Freight to be promoted into the Stage referenced by the Stage field. |
| vars | ExpressionVariable | Vars is a list of variables that can be referenced by expressions in promotion steps. |
| steps | PromotionStep | Steps specifies the directives to be executed as part of this Promotion. The order in which the directives are executed is the order in which they are listed in this field. |
PromotionStatus describes the current state of the transition represented by a Promotion.
| Field | Type | Description |
|---|
| lastHandledRefresh | string | LastHandledRefresh holds the value of the most recent AnnotationKeyRefresh annotation that was handled by the controller. This field can be used to determine whether the request to refresh the resource has been handled. +optional |
| phase | string | Phase describes where the Promotion currently is in its lifecycle. |
| message | string | Message is a display message about the promotion, including any errors preventing the Promotion controller from executing this Promotion. i.e. If the Phase field has a value of Failed, this field can be expected to explain why. |
| freight | FreightReference | Freight is the detail of the piece of freight that was referenced by this promotion. |
| freightCollection | FreightCollection | FreightCollection contains the details of the piece of Freight referenced by this Promotion as well as any additional Freight that is carried over from the target Stage's current state. |
| healthChecks | HealthCheckStep | HealthChecks contains the health check directives to be executed after the Promotion has completed. |
| startedAt | k8s.io.apimachinery.pkg.apis.meta.v1.Time | StartedAt is the time when the promotion started. |
| finishedAt | k8s.io.apimachinery.pkg.apis.meta.v1.Time | FinishedAt is the time when the promotion was completed. |
| currentStep | int64 | CurrentStep is the index of the current promotion step being executed. This permits steps that have already run successfully to be skipped on subsequent reconciliations attempts. |
| stepExecutionMetadata | StepExecutionMetadata | StepExecutionMetadata tracks metadata pertaining to the execution of individual promotion steps. |
| state | k8s.io.apiextensions_apiserver.pkg.apis.apiextensions.v1.JSON | State stores the state of the promotion process between reconciliation attempts. |
PromotionStep describes a directive to be executed as part of a Promotion.
| Field | Type | Description |
|---|
| uses | string | Uses identifies a runner that can execute this step. |
| task | PromotionTaskReference | Task is a reference to a PromotionTask that should be inflated into a Promotion when it is built from a PromotionTemplate. |
| as | string | As is the alias this step can be referred to as. |
| if | string | If is an optional expression that, if present, must evaluate to a boolean value. If the expression evaluates to false, the step will be skipped. If the expression does not evaluate to a boolean value, the step will be considered to have failed. |
| continueOnError | bool | ContinueOnError is a boolean value that, if set to true, will cause the Promotion to continue executing the next step even if this step fails. It also will not permit this failure to impact the overall status of the Promotion. |
| retry | PromotionStepRetry | Retry is the retry policy for this step. |
| vars | ExpressionVariable | Vars is a list of variables that can be referenced by expressions in the step's Config. The values override the values specified in the PromotionSpec. |
| config | k8s.io.apiextensions_apiserver.pkg.apis.apiextensions.v1.JSON | Config is opaque configuration for the PromotionStep that is understood only by each PromotionStep's implementation. It is legal to utilize expressions in defining values at any level of this block. See https://docs.kargo.io/user-guide/reference-docs/expressions for details. |
PromotionStepRetry describes the retry policy for a PromotionStep.
| Field | Type | Description |
|---|
| timeout | k8s.io.apimachinery.pkg.apis.meta.v1.Duration | Timeout is the soft maximum interval in which a step that returns a Running status (which typically indicates it's waiting for something to happen) may be retried. The maximum is a soft one because the check for whether the interval has elapsed occurs AFTER the step has run. This effectively means a step may run ONCE beyond the close of the interval. If this field is set to nil, the effective default will be a step-specific one. If no step-specific default exists (i.e. is also nil), the effective default will be the system-wide default of 0. A value of 0 will cause the step to be retried indefinitely unless the ErrorThreshold is reached. |
| errorThreshold | uint32 | ErrorThreshold is the number of consecutive times the step must fail (for any reason) before retries are abandoned and the entire Promotion is marked as failed. If this field is set to 0, the effective default will be a step-specific one. If no step-specific default exists (i.e. is also 0), the effective default will be the system-wide default of 1. A value of 1 will cause the Promotion to be marked as failed after just a single failure; i.e. no retries will be attempted. There is no option to specify an infinite number of retries using a value such as -1. In a future release, Kargo is likely to become capable of distinguishing between recoverable and non-recoverable step failures. At that time, it is planned that unrecoverable failures will not be subject to this threshold and will immediately cause the Promotion to be marked as failed without further condition. |
| Field | Type | Description |
|---|
| metadata | k8s.io.apimachinery.pkg.apis.meta.v1.ObjectMeta | |
| spec | PromotionTaskSpec | Spec describes the composition of a PromotionTask, including the variables available to the task and the steps. |
PromotionTaskList contains a list of PromotionTasks.
| Field | Type | Description |
|---|
| metadata | k8s.io.apimachinery.pkg.apis.meta.v1.ListMeta | |
| items | PromotionTask | |
PromotionTaskReference describes a reference to a PromotionTask.
| Field | Type | Description |
|---|
| name | string | Name is the name of the (Cluster)PromotionTask. |
| kind | string | Kind is the type of the PromotionTask. Can be either PromotionTask or ClusterPromotionTask, default is PromotionTask. |
| Field | Type | Description |
|---|
| vars | ExpressionVariable | Vars specifies the variables available to the PromotionTask. The values of these variables are the default values that can be overridden by the step referencing the task. |
| steps | PromotionStep | Steps specifies the directives to be executed as part of this PromotionTask. The steps as defined here are inflated into a Promotion when it is built from a PromotionTemplate. |
PromotionTemplate defines a template for a Promotion that can be used to incorporate Freight into a Stage.
PromotionTemplateSpec describes the (partial) specification of a Promotion for a Stage. This is a template that can be used to create a Promotion for a Stage.
| Field | Type | Description |
|---|
| vars | ExpressionVariable | Vars is a list of variables that can be referenced by expressions in promotion steps. |
| steps | PromotionStep | Steps specifies the directives to be executed as part of a Promotion. The order in which the directives are executed is the order in which they are listed in this field. |
QuayWebhookReceiverConfig
QuayWebhookReceiverConfig describes a webhook receiver that is compatible with Quay.io payloads.
| Field | Type | Description |
|---|
| secretRef | k8s.io.api.core.v1.LocalObjectReference | SecretRef contains a reference to a Secret. For Project-scoped webhook receivers, the referenced Secret must be in the same namespace as the ProjectConfig. For cluster-scoped webhook receivers, the referenced Secret must be in the designated "cluster Secrets" namespace. The Secret's data map is expected to contain a secret key whose value does NOT need to be shared directly with Quay when registering a webhook. It is used only by Kargo to create a complex, hard-to-guess URL, which implicitly serves as a shared secret. For more information about Quay webhooks, please refer to the Quay documentation: https://docs.quay.io/guides/notifications.html |
RepoSubscription
RepoSubscription describes a subscription to ONE OF a Git repository, a container image repository, or a Helm chart repository.
| Field | Type | Description |
|---|
| git | GitSubscription | Git describes a subscriptions to a Git repository. |
| image | ImageSubscription | Image describes a subscription to container image repository. |
| chart | ChartSubscription | Chart describes a subscription to a Helm chart repository. |
Stage
Stage is the Kargo API's main type.
| Field | Type | Description |
|---|
| metadata | k8s.io.apimachinery.pkg.apis.meta.v1.ObjectMeta | |
| spec | StageSpec | Spec describes sources of Freight used by the Stage and how to incorporate Freight into the Stage. |
| status | StageStatus | Status describes the Stage's current and recent Freight, health, and more. |
StageList
StageList is a list of Stage resources.
| Field | Type | Description |
|---|
| metadata | k8s.io.apimachinery.pkg.apis.meta.v1.ListMeta | |
| items | Stage | |
StageSpec
StageSpec describes the sources of Freight used by a Stage and how to incorporate Freight into the Stage.
| Field | Type | Description |
|---|
| shard | string | Shard is the name of the shard that this Stage belongs to. This is an optional field. If not specified, the Stage will belong to the default shard. A defaulting webhook will sync the value of the kargo.akuity.io/shard label with the value of this field. When this field is empty, the webhook will ensure that label is absent. |
| vars | ExpressionVariable | Vars is a list of variables that can be referenced anywhere in the StageSpec that supports expressions. For example, the PromotionTemplate and arguments of the Verification. |
| requestedFreight | FreightRequest | RequestedFreight expresses the Stage's need for certain pieces of Freight, each having originated from a particular Warehouse. This list must be non-empty. In the common case, a Stage will request Freight having originated from just one specific Warehouse. In advanced cases, requesting Freight from multiple Warehouses provides a method of advancing new artifacts of different types through parallel pipelines at different speeds. This can be useful, for instance, if a Stage is home to multiple microservices that are independently versioned. |
| promotionTemplate | PromotionTemplate | PromotionTemplate describes how to incorporate Freight into the Stage using a Promotion. |
| verification | Verification | Verification describes how to verify a Stage's current Freight is fit for promotion downstream. |
StageStats
StageStats contains a summary of the collective state of a Project's Stages.
| Field | Type | Description |
|---|
| count | int64 | Count contains the total number of Stages in the Project. |
| health | HealthStats | Health contains a summary of the collective health of a Project's Stages. |
StageStatus
StageStatus describes a Stages's current and recent Freight, health, and more.
| Field | Type | Description |
|---|
| conditions | k8s.io.apimachinery.pkg.apis.meta.v1.Condition | Conditions contains the last observations of the Stage's current state. +patchMergeKey=type +patchStrategy=merge +listType=map +listMapKey=type |
| lastHandledRefresh | string | LastHandledRefresh holds the value of the most recent AnnotationKeyRefresh annotation that was handled by the controller. This field can be used to determine whether the request to refresh the resource has been handled. +optional |
| freightHistory | FreightCollection | FreightHistory is a list of recent Freight selections that were deployed to the Stage. By default, the last ten Freight selections are stored. The first item in the list is the most recent Freight selection and currently deployed to the Stage, subsequent items are older selections. |
| freightSummary | string | FreightSummary is human-readable text maintained by the controller that summarizes what Freight is currently deployed to the Stage. For Stages that request a single piece of Freight AND the request has been fulfilled, this field will simply contain the name of the Freight. For Stages that request a single piece of Freight AND the request has NOT been fulfilled, or for Stages that request multiple pieces of Freight, this field will contain a summary of fulfilled/requested Freight. The existence of this field is a workaround for kubectl limitations so that this complex but valuable information can be displayed in a column in response to kubectl get stages. |
| health | Health | Health is the Stage's last observed health. |
| observedGeneration | int64 | ObservedGeneration represents the .metadata.generation that this Stage status was reconciled against. |
| currentPromotion | PromotionReference | CurrentPromotion is a reference to the currently Running promotion. |
| lastPromotion | PromotionReference | LastPromotion is a reference to the last completed promotion. |
| autoPromotionEnabled | bool | AutoPromotionEnabled indicates whether automatic promotion is enabled for the Stage based on the ProjectConfig. |
StepExecutionMetadata tracks metadata pertaining to the execution of a promotion step.
| Field | Type | Description |
|---|
| alias | string | Alias is the alias of the step. |
| startedAt | k8s.io.apimachinery.pkg.apis.meta.v1.Time | StartedAt is the time at which the first attempt to execute the step began. |
| finishedAt | k8s.io.apimachinery.pkg.apis.meta.v1.Time | FinishedAt is the time at which the final attempt to execute the step completed. |
| errorCount | uint32 | ErrorCount tracks consecutive failed attempts to execute the step. |
| status | string | Status is the high-level outcome of the step. |
| message | string | Message is a display message about the step, including any errors. |
| continueOnError | bool | ContinueOnError is a boolean value that, if set to true, will cause the Promotion to continue executing the next step even if this step fails. It also will not permit this failure to impact the overall status of the Promotion. |
Verification
Verification describes how to verify that a Promotion has been successful using Argo Rollouts AnalysisTemplates.
| Field | Type | Description |
|---|
| analysisTemplates | AnalysisTemplateReference | AnalysisTemplates is a list of AnalysisTemplates from which AnalysisRuns should be created to verify a Stage's current Freight is fit to be promoted downstream. |
| analysisRunMetadata | AnalysisRunMetadata | AnalysisRunMetadata contains optional metadata that should be applied to all AnalysisRuns. |
| args | AnalysisRunArgument | Args lists arguments that should be added to all AnalysisRuns. |
VerificationInfo
VerificationInfo contains the details of an instance of a Verification process.
| Field | Type | Description |
|---|
| id | string | ID is the identifier of the Verification process. |
| actor | string | Actor is the name of the entity that initiated or aborted the Verification process. |
| startTime | k8s.io.apimachinery.pkg.apis.meta.v1.Time | StartTime is the time at which the Verification process was started. |
| phase | string | Phase describes the current phase of the Verification process. Generally, this will be a reflection of the underlying AnalysisRun's phase, however, there are exceptions to this, such as in the case where an AnalysisRun cannot be launched successfully. |
| message | string | Message may contain additional information about why the verification process is in its current phase. |
| analysisRun | AnalysisRunReference | AnalysisRun is a reference to the Argo Rollouts AnalysisRun that implements the Verification process. |
| finishTime | k8s.io.apimachinery.pkg.apis.meta.v1.Time | FinishTime is the time at which the Verification process finished. |
VerifiedStage
VerifiedStage describes a Stage in which Freight has been verified.
| Field | Type | Description |
|---|
| verifiedAt | k8s.io.apimachinery.pkg.apis.meta.v1.Time | VerifiedAt is the time at which the Freight was verified in the Stage. |
| longestSoak | k8s.io.apimachinery.pkg.apis.meta.v1.Duration | LongestCompletedSoak represents the longest definite time interval wherein the Freight was in CONTINUOUS use by the Stage. This value is updated as Freight EXITS the Stage. If the Freight is currently in use by the Stage, the time elapsed since the Freight ENTERED the Stage is its current soak time, which may exceed the value of this field. |
Warehouse
Warehouse is a source of Freight.
| Field | Type | Description |
|---|
| metadata | k8s.io.apimachinery.pkg.apis.meta.v1.ObjectMeta | |
| spec | WarehouseSpec | Spec describes sources of artifacts. |
| status | WarehouseStatus | Status describes the Warehouse's most recently observed state. |
WarehouseList
WarehouseList is a list of Warehouse resources.
| Field | Type | Description |
|---|
| metadata | k8s.io.apimachinery.pkg.apis.meta.v1.ListMeta | |
| items | Warehouse | |
WarehouseSpec
WarehouseSpec describes sources of versioned artifacts to be included in Freight produced by this Warehouse.
| Field | Type | Description |
|---|
| shard | string | Shard is the name of the shard that this Warehouse belongs to. This is an optional field. If not specified, the Warehouse will belong to the default shard. A defaulting webhook will sync this field with the value of the kargo.akuity.io/shard label. When the shard label is not present or differs from the value of this field, the defaulting webhook will set the label to the value of this field. If the shard label is present and this field is empty, the defaulting webhook will set the value of this field to the value of the shard label. |
| interval | k8s.io.apimachinery.pkg.apis.meta.v1.Duration | Interval is the reconciliation interval for this Warehouse. On each reconciliation, the Warehouse will discover new artifacts and optionally produce new Freight. This field is optional. When left unspecified, the field is implicitly treated as if its value were "5m0s". |
| freightCreationPolicy | string | FreightCreationPolicy describes how Freight is created by this Warehouse. This field is optional. When left unspecified, the field is implicitly treated as if its value were "Automatic". Accepted values: - "Automatic": New Freight is created automatically when any new artifact is discovered. - "Manual": New Freight is never created automatically. |
| subscriptions | RepoSubscription | Subscriptions describes sources of artifacts to be included in Freight produced by this Warehouse. |
WarehouseStats
WarehouseStats contains a summary of the collective state of a Project's Warehouses.
| Field | Type | Description |
|---|
| count | int64 | Count contains the total number of Warehouses in the Project. |
| health | HealthStats | Health contains a summary of the collective health of a Project's Warehouses. |
WarehouseStatus
WarehouseStatus describes a Warehouse's most recently observed state.
| Field | Type | Description |
|---|
| conditions | k8s.io.apimachinery.pkg.apis.meta.v1.Condition | Conditions contains the last observations of the Warehouse's current state. +patchMergeKey=type +patchStrategy=merge +listType=map +listMapKey=type |
| lastHandledRefresh | string | LastHandledRefresh holds the value of the most recent AnnotationKeyRefresh annotation that was handled by the controller. This field can be used to determine whether the request to refresh the resource has been handled. +optional |
| observedGeneration | int64 | ObservedGeneration represents the .metadata.generation that this Warehouse was reconciled against. |
| lastFreightID | string | LastFreightID is a reference to the system-assigned identifier (name) of the most recent Freight produced by the Warehouse. |
| discoveredArtifacts | DiscoveredArtifacts | DiscoveredArtifacts holds the artifacts discovered by the Warehouse. |
WebhookReceiverConfig
WebhookReceiverConfig describes the configuration for a single webhook receiver.
| Field | Type | Description |
|---|
| name | string | Name is the name of the webhook receiver. |
| bitbucket | BitbucketWebhookReceiverConfig | Bitbucket contains the configuration for a webhook receiver that is compatible with Bitbucket payloads. |
| dockerhub | DockerHubWebhookReceiverConfig | DockerHub contains the configuration for a webhook receiver that is compatible with DockerHub payloads. |
| github | GitHubWebhookReceiverConfig | GitHub contains the configuration for a webhook receiver that is compatible with GitHub payloads. |
| gitlab | GitLabWebhookReceiverConfig | GitLab contains the configuration for a webhook receiver that is compatible with GitLab payloads. |
| harbor | HarborWebhookReceiverConfig | Harbor contains the configuration for a webhook receiver that is compatible with Harbor payloads. |
| quay | QuayWebhookReceiverConfig | Quay contains the configuration for a webhook receiver that is compatible with Quay payloads. |
| artifactory | ArtifactoryWebhookReceiverConfig | Artifactory contains the configuration for a webhook receiver that is compatible with JFrog Artifactory payloads. |
| azure | AzureWebhookReceiverConfig | Azure contains the configuration for a webhook receiver that is compatible with Azure Container Registry (ACR) and Azure DevOps payloads. |
| gitea | GiteaWebhookReceiverConfig | Gitea contains the configuration for a webhook receiver that is compatible with Gitea payloads. |
WebhookReceiverDetails
WebhookReceiverDetails encapsulates the details of a webhook receiver.
| Field | Type | Description |
|---|
| name | string | Name is the name of the webhook receiver. |
| path | string | Path is the path to the receiver's webhook endpoint. |
| url | string | URL includes the full address of the receiver's webhook endpoint. |
Scalar Value Types
| .proto Type | Notes | C++ | Java | Python | Go | C# | PHP | Ruby |
|---|
| double | | double | double | float | float64 | double | float | Float |
| float | | float | float | float | float32 | float | float | Float |
| int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) |
| int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long | int64 | long | integer/string | Bignum |
| uint32 | Uses variable-length encoding. | uint32 | int | int/long | uint32 | uint | integer | Bignum or Fixnum (as required) |
| uint64 | Uses variable-length encoding. | uint64 | long | int/long | uint64 | ulong | integer/string | Bignum or Fixnum (as required) |
| sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) |
| sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long | int64 | long | integer/string | Bignum |
| fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int | uint32 | uint | integer | Bignum or Fixnum (as required) |
| fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long | uint64 | ulong | integer/string | Bignum |
| sfixed32 | Always four bytes. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) |
| sfixed64 | Always eight bytes. | int64 | long | int/long | int64 | long | integer/string | Bignum |
| bool | | bool | boolean | boolean | bool | bool | boolean | TrueClass/FalseClass |
| string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | string | string | string | String (UTF-8) |
| bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | []byte | ByteString | string | String (ASCII-8BIT) |