Top
service/v1alpha1
Stability is not guaranteed.
AbortPromotionRequest is the request for canceling a running promotion process.
| Field | Type | Description |
|---|
| project | string | project is the name of the project containing the promotion. |
| name | string | name is the name of the promotion to abort. |
AbortPromotionResponse is the response after aborting a promotion. explicitly empty
AbortVerificationRequest
AbortVerificationRequest is the request for canceling running verification processes for a stage.
| Field | Type | Description |
|---|
| project | string | project is the name of the project containing the stage. |
| stage | string | stage is the name of the stage whose verification should be aborted. |
AbortVerificationResponse
AbortVerificationResponse is the response after aborting verification. explicitly empty
AdminLoginRequest
AdminLoginRequest contains credentials for admin authentication.
| Field | Type | Description |
|---|
| password | string | password is the admin password. |
AdminLoginResponse
AdminLoginResponse contains the authentication token for admin access.
| Field | Type | Description |
|---|
| id_token | string | id_token is the JWT token for authenticated admin access. |
ApproveFreightRequest
ApproveFreightRequest is the request for approving freight for promotion to a stage.
| Field | Type | Description |
|---|
| project | string | project is the name of the project containing the freight. |
| name | string | name is the name of the freight to approve. |
| alias | string | alias is the alias of the freight to approve. |
| stage | string | stage is the name of the stage for which to approve the freight. |
ApproveFreightResponse
ApproveFreightResponse is the response after approving freight. explicitly empty
ArgoCDShard
ArgoCDShard represents configuration for a specific ArgoCD shard.
| Field | Type | Description |
|---|
| url | string | url is the base URL of the ArgoCD server. |
| namespace | string | namespace is the Kubernetes namespace where ArgoCD is installed. |
Claims
Claims represents a collection of OIDC claims for role-based access control.
ComponentVersions
ComponentVersions contains version information for different Kargo components.
| Field | Type | Description |
|---|
| server | VersionInfo | server contains version information for the Kargo server. |
| cli | VersionInfo | cli contains version information for the Kargo CLI. |
CreateClusterSecretRequest
CreateClusterSecretRequest is the request for creating a new cluster-level secret.
CreateClusterSecretRequest.DataEntry
CreateClusterSecretResponse
CreateClusterSecretResponse contains the newly created cluster secret.
| Field | Type | Description |
|---|
| secret | k8s.io.api.core.v1.Secret | secret is the created cluster-level Kubernetes Secret. |
CreateCredentialsRequest
CreateCredentialsRequest is the request for creating new credentials for accessing external resources.
| Field | Type | Description |
|---|
| project | string | project is the name of the project where the credentials will be stored. |
| name | string | name is the name of the credentials. |
| description | string | description is a human-readable description of the credentials. |
| type | string | type specifies the credential type (git, helm, image). |
| repo_url | string | repo_url is the URL of the repository or registry these credentials apply to. |
| repo_url_is_regex | bool | repo_url_is_regex indicates whether repo_url should be treated as a regular expression. |
| username | string | username is the username for authentication. |
| password | string | password is the password or token for authentication. |
CreateCredentialsResponse
CreateCredentialsResponse contains the newly created credentials.
| Field | Type | Description |
|---|
| credentials | k8s.io.api.core.v1.Secret | credentials is the created Kubernetes Secret containing the credentials. |
CreateOrUpdateResourceRequest
CreateOrUpdateResourceRequest contains Kubernetes resource manifests to be created or updated.
| Field | Type | Description |
|---|
| manifest | bytes | manifest contains the raw Kubernetes resource manifests in YAML or JSON format. |
CreateOrUpdateResourceResponse
CreateOrUpdateResourceResponse contains the results of creating or updating multiple resources.
CreateOrUpdateResourceResult
CreateOrUpdateResourceResult represents the result of attempting to create or update a single resource.
| Field | Type | Description |
|---|
| created_resource_manifest | bytes | created_resource_manifest contains the newly created resource manifest. |
| updated_resource_manifest | bytes | updated_resource_manifest contains the updated existing resource manifest. |
| error | string | error contains the error message if the operation failed. |
CreateProjectSecretRequest
CreateProjectSecretRequest is the request for creating a new secret within a project.
| Field | Type | Description |
|---|
| project | string | project is the name of the project where the secret will be created. |
| name | string | name is the name of the secret to create. |
| description | string | description is a human-readable description of the secret. |
| data | CreateProjectSecretRequest.DataEntry | data contains the key-value pairs that make up the secret data. |
CreateProjectSecretRequest.DataEntry
CreateProjectSecretResponse
CreateProjectSecretResponse contains the newly created project secret.
| Field | Type | Description |
|---|
| secret | k8s.io.api.core.v1.Secret | secret is the created Kubernetes Secret within the project. |
CreateResourceRequest
CreateResourceRequest contains Kubernetes resource manifests to be created.
| Field | Type | Description |
|---|
| manifest | bytes | manifest contains the raw Kubernetes resource manifests in YAML or JSON format. |
CreateResourceResponse
CreateResourceResponse contains the results of creating multiple resources.
| Field | Type | Description |
|---|
| results | CreateResourceResult | results contains the outcome for each resource creation attempt. |
CreateResourceResult
CreateResourceResult represents the result of attempting to create a single resource.
| Field | Type | Description |
|---|
| created_resource_manifest | bytes | created_resource_manifest contains the successfully created resource manifest. |
| error | string | error contains the error message if resource creation failed. |
CreateRoleRequest
CreateRoleRequest is the request for creating a new RBAC role.
CreateRoleResponse
CreateRoleResponse contains the newly created role information.
DeleteAnalysisTemplateRequest
DeleteAnalysisTemplateRequest is the request for deleting an analysis template.
| Field | Type | Description |
|---|
| project | string | project is the name of the project containing the analysis template. |
| name | string | name is the name of the analysis template to delete. |
DeleteAnalysisTemplateResponse
DeleteAnalysisTemplateResponse is the response returned after deleting an analysis template. explicitly empty
DeleteClusterAnalysisTemplateRequest
DeleteClusterAnalysisTemplateRequest is the request for deleting a cluster analysis template.
| Field | Type | Description |
|---|
| name | string | name is the name of the cluster analysis template to delete. |
DeleteClusterAnalysisTemplateResponse
DeleteClusterAnalysisTemplateResponse is the response returned after deleting a cluster analysis template. explicitly empty
DeleteClusterConfigRequest
explicitly empty
DeleteClusterConfigResponse
explicitly empty
DeleteClusterSecretRequest
DeleteClusterSecretRequest is the request for deleting a cluster secret.
| Field | Type | Description |
|---|
| name | string | name is the name of the cluster secret to delete. |
DeleteClusterSecretResponse
DeleteClusterSecretResponse is the response returned after deleting a cluster secret. explicitly empty
DeleteCredentialsRequest
DeleteCredentialsRequest is the request for deleting existing credentials.
| Field | Type | Description |
|---|
| project | string | project is the name of the project containing the credentials. |
| name | string | name is the name of the credentials to delete. |
DeleteCredentialsResponse
DeleteCredentialsResponse is the response returned after deleting credentials. explicitly empty
DeleteFreightRequest
DeleteFreightRequest is the request for deleting freight.
| Field | Type | Description |
|---|
| project | string | project is the name of the project containing the freight. |
| name | string | name is the name of the freight to delete. |
| alias | string | alias is the alias of the freight to delete. |
DeleteFreightResponse
DeleteFreightResponse is the response after deleting freight. explicitly empty
DeleteProjectConfigRequest
DeleteProjectConfigRequest is the request for removing project-level configuration.
| Field | Type | Description |
|---|
| project | string | project is the name of the project to delete configuration for. |
DeleteProjectConfigResponse
DeleteProjectConfigResponse is the response after deleting project configuration. explicitly empty
DeleteProjectRequest
DeleteProjectRequest is the request for deleting a project and all associated resources.
| Field | Type | Description |
|---|
| name | string | name is the name of the project to delete. |
DeleteProjectResponse
DeleteProjectResponse is the response after deleting a project. explicitly empty
DeleteProjectSecretRequest
DeleteProjectSecretRequest is the request for deleting a project secret.
| Field | Type | Description |
|---|
| project | string | project is the name of the project containing the secret. |
| name | string | name is the name of the secret to delete. |
DeleteProjectSecretResponse
DeleteProjectSecretResponse is the response returned after deleting a project secret. explicitly empty
DeleteResourceRequest
DeleteResourceRequest contains Kubernetes resource manifests to be deleted.
| Field | Type | Description |
|---|
| manifest | bytes | manifest contains the raw Kubernetes resource manifests in YAML or JSON format. |
DeleteResourceResponse
DeleteResourceResponse contains the results of deleting multiple resources.
| Field | Type | Description |
|---|
| results | DeleteResourceResult | results contains the outcome for each resource deletion attempt. |
DeleteResourceResult
DeleteResourceResult represents the result of attempting to delete a single resource.
| Field | Type | Description |
|---|
| deleted_resource_manifest | bytes | deleted_resource_manifest contains the successfully deleted resource manifest. |
| error | string | error contains the error message if resource deletion failed. |
DeleteRoleRequest
DeleteRoleRequest is the request for deleting an RBAC role.
| Field | Type | Description |
|---|
| project | string | project is the name of the project containing the role. |
| name | string | name is the name of the role to delete. |
DeleteRoleResponse
DeleteRoleResponse is the response returned after deleting a role. explicitly empty
DeleteStageRequest
DeleteStageRequest is the request for deleting a stage.
| Field | Type | Description |
|---|
| project | string | project is the name of the project containing the stage. |
| name | string | name is the name of the stage to delete. |
DeleteStageResponse
DeleteStageResponse is the response after deleting a stage. explicitly empty
DeleteWarehouseRequest
DeleteWarehouseRequest is the request for deleting a warehouse.
| Field | Type | Description |
|---|
| project | string | project is the name of the project containing the warehouse. |
| name | string | name is the name of the warehouse to delete. |
DeleteWarehouseResponse
DeleteWarehouseResponse is the response after deleting a warehouse. explicitly empty
FreightList
FreightList contains a list of freight resources.
GetAnalysisRunLogsRequest
GetAnalysisRunLogsRequest is the request for retrieving logs from an analysis run.
| Field | Type | Description |
|---|
| namespace | string | namespace is the namespace containing the analysis run. |
| name | string | name is the name of the analysis run whose logs to retrieve. |
| metric_name | string | metric_name is the specific metric whose logs to retrieve. |
| container_name | string | container_name is the specific container whose logs to retrieve. |
GetAnalysisRunLogsResponse
GetAnalysisRunLogsResponse contains a chunk of logs from the analysis run.
| Field | Type | Description |
|---|
| chunk | string | chunk is a portion of the log output from the analysis run. |
GetAnalysisRunRequest
GetAnalysisRunRequest is the request for retrieving a specific analysis run.
| Field | Type | Description |
|---|
| namespace | string | namespace is the namespace containing the analysis run. |
| name | string | name is the name of the analysis run to retrieve. |
| format | RawFormat | format specifies the desired response format (structured object or raw YAML). |
GetAnalysisRunResponse
GetAnalysisRunResponse contains the requested analysis run information.
GetAnalysisTemplateRequest
GetAnalysisTemplateRequest is the request for retrieving a specific analysis template.
| Field | Type | Description |
|---|
| project | string | project is the name of the project containing the analysis template. |
| name | string | name is the name of the analysis template to retrieve. |
| format | RawFormat | format specifies the desired response format (structured object or raw YAML). |
GetAnalysisTemplateResponse
GetAnalysisTemplateResponse contains the requested analysis template information.
GetClusterAnalysisTemplateRequest
GetClusterAnalysisTemplateRequest is the request for retrieving a specific cluster analysis template.
| Field | Type | Description |
|---|
| name | string | name is the name of the cluster analysis template to retrieve. |
| format | RawFormat | format specifies the desired response format (structured object or raw YAML). |
GetClusterAnalysisTemplateResponse
GetClusterAnalysisTemplateResponse contains the requested cluster analysis template information.
GetClusterConfigRequest
GetClusterConfigResponse
GetClusterPromotionTaskRequest is the request for retrieving a specific cluster promotion task.
| Field | Type | Description |
|---|
| name | string | name is the name of the cluster promotion task to retrieve. |
| format | RawFormat | format specifies the desired response format (structured object or raw YAML). |
GetClusterPromotionTaskResponse contains the requested cluster promotion task information.
GetConfigMapRequest
GetConfigMapRequest is the request for retrieving a specific ConfigMap.
| Field | Type | Description |
|---|
| project | string | project is the name of the project containing the ConfigMap. |
| name | string | name is the name of the ConfigMap to retrieve. |
| format | RawFormat | format specifies the desired response format (structured object or raw YAML). |
GetConfigMapResponse
GetConfigMapResponse contains the requested ConfigMap information.
| Field | Type | Description |
|---|
| config_map | k8s.io.api.core.v1.ConfigMap | config_map is the structured Kubernetes ConfigMap object. |
| raw | bytes | raw is the raw YAML representation of the ConfigMap. |
GetConfigRequest
GetConfigRequest is the request message for retrieving server configuration.
GetConfigResponse
GetConfigResponse contains server configuration information.
| Field | Type | Description |
|---|
| argocd_shards | GetConfigResponse.ArgocdShardsEntry | argocd_shards maps shard names to their ArgoCD configuration. |
| secret_management_enabled | bool | secret_management_enabled indicates if secret management features are available. |
| cluster_secrets_namespace | string | cluster_secrets_namespace is the namespace used for cluster-scoped secrets. |
| has_analysis_run_logs_url_template | bool | has_analysis_run_logs_url_template indicates if an analysis run logs URL template is configured. |
GetConfigResponse.ArgocdShardsEntry
GetCredentialsRequest
GetCredentialsRequest is the request for retrieving existing credentials.
| Field | Type | Description |
|---|
| project | string | project is the name of the project containing the credentials. |
| name | string | name is the name of the credentials to retrieve. |
| format | RawFormat | format specifies the desired response format (structured object or raw YAML). |
GetCredentialsResponse
GetCredentialsResponse contains the requested credentials information.
| Field | Type | Description |
|---|
| credentials | k8s.io.api.core.v1.Secret | credentials is the structured Kubernetes Secret containing the credentials. |
| raw | bytes | raw is the raw YAML representation of the credentials. |
GetFreightRequest
GetFreightRequest is the request for retrieving details of specific freight.
| Field | Type | Description |
|---|
| project | string | project is the name of the project containing the freight. |
| name | string | name is the name of the freight to retrieve. |
| alias | string | alias is the alias of the freight to retrieve. |
| format | RawFormat | format specifies the format for raw resource representation. |
GetFreightResponse
GetFreightResponse contains the requested freight information.
GetProjectConfigRequest
GetProjectConfigRequest is the request for retrieving project-level configuration settings.
| Field | Type | Description |
|---|
| project | string | project is the name of the project to retrieve configuration for. |
| format | RawFormat | format specifies the desired response format (structured object or raw YAML). |
GetProjectConfigResponse
GetProjectConfigResponse contains the requested project configuration.
GetProjectRequest
GetProjectRequest is the request for retrieving details of a specific project.
| Field | Type | Description |
|---|
| name | string | name is the name of the project to retrieve. |
| format | RawFormat | format specifies the format for raw resource representation. |
GetProjectResponse
GetProjectResponse contains the requested project information.
GetPromotionRequest is the request for retrieving details of a specific promotion.
| Field | Type | Description |
|---|
| project | string | project is the name of the project containing the promotion. |
| name | string | name is the name of the promotion to retrieve. |
| format | RawFormat | format specifies the format for raw resource representation. |
GetPromotionResponse contains the requested promotion information.
GetPromotionTaskRequest is the request for retrieving a specific promotion task.
| Field | Type | Description |
|---|
| project | string | project is the name of the project containing the promotion task. |
| name | string | name is the name of the promotion task to retrieve. |
| format | RawFormat | format specifies the desired response format (structured object or raw YAML). |
GetPromotionTaskResponse contains the requested promotion task information.
GetPublicConfigRequest
GetPublicConfigRequest is the request message for retrieving public configuration.
GetPublicConfigResponse
GetPublicConfigResponse contains publicly accessible configuration settings.
| Field | Type | Description |
|---|
| oidc_config | OIDCConfig | oidc_config contains OpenID Connect configuration for authentication. |
| admin_account_enabled | bool | admin_account_enabled indicates if admin account authentication is available. |
| skip_auth | bool | skip_auth indicates if authentication should be bypassed. |
GetRoleRequest
GetRoleRequest is the request for retrieving a specific RBAC role.
| Field | Type | Description |
|---|
| project | string | project is the name of the project containing the role. |
| name | string | name is the name of the role to retrieve. |
| as_resources | bool | as_resources indicates whether to return the role as resources or as a role object. |
| format | RawFormat | format specifies the desired response format (structured object or raw YAML). |
GetRoleResponse
GetRoleResponse contains the requested role information.
GetStageRequest
GetStageRequest is the request for retrieving details of a specific stage.
| Field | Type | Description |
|---|
| project | string | project is the name of the project containing the stage. |
| name | string | name is the name of the stage to retrieve. |
| format | RawFormat | format specifies the format for raw resource representation. |
GetStageResponse
GetStageResponse contains the requested stage information.
GetVersionInfoRequest
GetVersionInfoRequest is the request message for retrieving version information.
GetVersionInfoResponse
GetVersionInfoResponse contains the server's version information.
| Field | Type | Description |
|---|
| version_info | VersionInfo | version_info contains detailed version and build information. |
GetWarehouseRequest
GetWarehouseRequest is the request for retrieving details of a specific warehouse.
| Field | Type | Description |
|---|
| project | string | project is the name of the project containing the warehouse. |
| name | string | name is the name of the warehouse to retrieve. |
| format | RawFormat | format specifies the format for raw resource representation. |
GetWarehouseResponse
GetWarehouseResponse contains the requested warehouse information.
GrantRequest
GrantRequest is the request for granting a role to a user or resource.
| Field | Type | Description |
|---|
| project | string | project is the name of the project where the role will be granted. |
| role | string | role is the name of the role to grant. |
| user_claims | Claims | user_claims are the OIDC claims for the user being granted the role. |
| resource_details | github.com.akuity.kargo.api.rbac.v1alpha1.ResourceDetails | resource_details are the details of the resource being granted the role. |
GrantResponse
GrantResponse contains information about the granted role.
ImageStageMap
ImageStageMap represents the mapping of stages to the order in which an image was promoted.
| Field | Type | Description |
|---|
| stages | ImageStageMap.StagesEntry | stages maps stage names to the order in which an image was promoted to that stage. |
ImageStageMap.StagesEntry
ListAnalysisTemplatesRequest
ListAnalysisTemplatesRequest is the request for listing all analysis templates in a project.
| Field | Type | Description |
|---|
| project | string | project is the name of the project whose analysis templates will be listed. |
ListAnalysisTemplatesResponse
ListAnalysisTemplatesResponse contains a list of analysis templates for the specified project.
ListClusterAnalysisTemplatesRequest
ListClusterAnalysisTemplatesRequest is the request for listing all cluster-level analysis templates.
ListClusterAnalysisTemplatesResponse
ListClusterAnalysisTemplatesResponse contains a list of cluster-level analysis templates.
ListClusterPromotionTasksRequest is the request for listing all cluster-level promotion tasks.
ListClusterPromotionTasksResponse contains a list of cluster-level promotion tasks.
ListClusterSecretsRequest
ListClusterSecretsRequest is the request for listing all cluster-level secrets. explicitly empty
ListClusterSecretsResponse
ListClusterSecretsResponse contains a list of cluster-level secrets.
| Field | Type | Description |
|---|
| secrets | k8s.io.api.core.v1.Secret | secrets is the list of cluster-level Kubernetes Secrets. |
ListConfigMapsRequest
ListConfigMapsRequest is the request for retrieving all ConfigMaps in a project.
| Field | Type | Description |
|---|
| project | string | project is the name of the project to list ConfigMaps from. |
ListConfigMapsResponse
ListConfigMapsResponse contains the list of ConfigMaps in a project.
| Field | Type | Description |
|---|
| config_maps | k8s.io.api.core.v1.ConfigMap | config_maps is the list of ConfigMaps found in the project. |
ListCredentialsRequest
ListCredentialsRequest is the request for listing all credentials in a project.
| Field | Type | Description |
|---|
| project | string | project is the name of the project whose credentials will be listed. |
ListCredentialsResponse
ListCredentialsResponse contains a list of credentials for the specified project.
| Field | Type | Description |
|---|
| credentials | k8s.io.api.core.v1.Secret | credentials is the list of Kubernetes Secrets containing the credentials. |
ListImagesRequest
ListImagesRequest is the request for listing images and their usage across stages.
| Field | Type | Description |
|---|
| project | string | project is the name of the project whose images should be listed. |
ListImagesResponse
ListImagesResponse contains information about images and their usage across stages.
ListImagesResponse.ImagesEntry
ListProjectEventsRequest
ListProjectEventsRequest is the request for listing events in a project.
| Field | Type | Description |
|---|
| project | string | project is the name of the project whose events will be listed. |
ListProjectEventsResponse
ListProjectEventsResponse contains a list of events for the specified project.
| Field | Type | Description |
|---|
| events | k8s.io.api.core.v1.Event | events is the list of Kubernetes Events within the project. |
ListProjectSecretsRequest
ListProjectSecretsRequest is the request for listing all secrets in a project.
| Field | Type | Description |
|---|
| project | string | project is the name of the project whose secrets will be listed. |
ListProjectSecretsResponse
ListProjectSecretsResponse contains a list of secrets for the specified project.
| Field | Type | Description |
|---|
| secrets | k8s.io.api.core.v1.Secret | secrets is the list of Kubernetes Secrets within the project. |
ListProjectsRequest
ListProjectsRequest is the request for listing all projects with optional filtering and pagination.
| Field | Type | Description |
|---|
| page_size | int32 | page_size specifies the maximum number of projects to return per page. |
| page | int32 | page specifies which page of results to return. |
| filter | string | filter specifies an optional filter expression for projects. |
| uid | string | ui store starred projects uids, so it needs to filter it when looking at starred projects |
ListProjectsResponse
ListProjectsResponse contains the list of projects and pagination information.
ListPromotionTasksRequest is the request for listing promotion tasks in a project.
| Field | Type | Description |
|---|
| project | string | project is the name of the project whose promotion tasks will be listed. |
ListPromotionTasksResponse contains a list of promotion tasks for the specified project.
ListPromotionsRequest is the request for retrieving all promotions, optionally filtered by stage.
| Field | Type | Description |
|---|
| project | string | project is the name of the project whose promotions should be listed. |
| stage | string | stage is an optional stage name to filter promotions by. |
ListPromotionsResponse contains a list of promotions within a project.
ListRolesRequest
ListRolesRequest is the request for listing all roles in a project.
| Field | Type | Description |
|---|
| project | string | project is the name of the project whose roles will be listed. |
| as_resources | bool | as_resources indicates whether to return roles as resources or as role objects. |
ListRolesResponse
ListRolesResponse contains a list of roles for the specified project.
ListStagesRequest
ListStagesRequest is the request for listing stages within a project.
| Field | Type | Description |
|---|
| project | string | project is the name of the project whose stages should be listed. |
ListStagesResponse
ListStagesResponse contains a list of stages within a project.
ListWarehousesRequest
ListWarehousesRequest is the request for listing warehouses within a project.
| Field | Type | Description |
|---|
| project | string | project is the name of the project whose warehouses should be listed. |
ListWarehousesResponse
ListWarehousesResponse contains a list of warehouses within a project.
OIDCConfig
OIDCConfig contains OpenID Connect configuration for authentication.
| Field | Type | Description |
|---|
| issuer_url | string | issuer_url is the OIDC provider's issuer URL. |
| client_id | string | client_id is the OIDC client identifier for web applications. |
| scopes | string | scopes are the OIDC scopes to request during authentication. |
| cli_client_id | string | cli_client_id is the OIDC client identifier for CLI applications. |
PromoteDownstreamRequest is the request for automatically promoting freight to downstream stages.
| Field | Type | Description |
|---|
| project | string | project is the name of the project containing the stage and freight. |
| stage | string | stage is the name of the source stage from which to promote downstream. |
| freight | string | freight is the name of the freight to promote downstream. |
| freight_alias | string | freight_alias is the alias of the freight to promote downstream. |
PromoteDownstreamResponse contains the promotions created for downstream freight promotions.
PromoteToStageRequest is the request for promoting freight to a specific stage.
| Field | Type | Description |
|---|
| project | string | project is the name of the project containing the stage and freight. |
| stage | string | stage is the name of the stage to promote freight to. |
| freight | string | freight is the name of the freight to promote. |
| freight_alias | string | freight_alias is the alias of the freight to promote. |
PromoteToStageResponse contains the promotion created for the freight promotion.
QueryFreightRequest
QueryFreightRequest is the request for searching freight based on specified criteria.
| Field | Type | Description |
|---|
| project | string | project is the name of the project to search for freight. |
| stage | string | stage is the name of the stage to filter freight by. |
| group_by | string | group_by specifies how to group the freight results. |
| group | string | group specifies which group to return results for. |
| order_by | string | order_by specifies how to order the freight results. |
| reverse | bool | reverse indicates whether to reverse the order of results. |
| origins | string | origins filters freight by their origins (e.g., warehouse names). |
QueryFreightResponse
QueryFreightResponse contains the grouped freight search results.
QueryFreightResponse.GroupsEntry
RefreshClusterConfigRequest
explicitly empty
RefreshClusterConfigResponse
RefreshProjectConfigRequest
RefreshProjectConfigRequest is the request for triggering a refresh of project configuration.
| Field | Type | Description |
|---|
| project | string | project is the name of the project to refresh configuration for. |
RefreshProjectConfigResponse
RefreshProjectConfigResponse contains the refreshed project configuration.
RefreshStageRequest
RefreshStageRequest is the request for refreshing a stage's status.
| Field | Type | Description |
|---|
| project | string | project is the name of the project containing the stage. |
| name | string | name is the name of the stage to refresh. |
RefreshStageResponse
RefreshStageResponse contains the refreshed stage information.
RefreshWarehouseRequest
RefreshWarehouseRequest is the request for refreshing a warehouse's status and freight discovery.
| Field | Type | Description |
|---|
| project | string | project is the name of the project containing the warehouse. |
| name | string | name is the name of the warehouse to refresh. |
RefreshWarehouseResponse
RefreshWarehouseResponse contains the refreshed warehouse information.
ReverifyRequest
ReverifyRequest is the request for triggering re-execution of verification processes for a stage.
| Field | Type | Description |
|---|
| project | string | project is the name of the project containing the stage. |
| stage | string | stage is the name of the stage to reverify. |
ReverifyResponse
ReverifyResponse is the response after triggering reverification. explicitly empty
RevokeRequest
RevokeRequest is the request for revoking a role from a user or resource.
| Field | Type | Description |
|---|
| project | string | project is the name of the project where the role will be revoked. |
| role | string | role is the name of the role to revoke. |
| user_claims | Claims | user_claims are the OIDC claims for the user whose role is being revoked. |
| resource_details | github.com.akuity.kargo.api.rbac.v1alpha1.ResourceDetails | resource_details are the details of the resource whose role is being revoked. |
RevokeResponse
RevokeResponse contains information about the revoked role.
TagMap
TagMap represents the mapping of image tags to stages that have used them.
| Field | Type | Description |
|---|
| tags | TagMap.TagsEntry | tags maps image tag names to stages which have previously used that tag. |
TagMap.TagsEntry
UpdateClusterSecretRequest
UpdateClusterSecretRequest is the request for updating an existing cluster secret.
UpdateClusterSecretRequest.DataEntry
UpdateClusterSecretResponse
UpdateClusterSecretResponse contains the updated cluster secret information.
| Field | Type | Description |
|---|
| secret | k8s.io.api.core.v1.Secret | secret is the updated cluster-level Kubernetes Secret. |
UpdateCredentialsRequest
UpdateCredentialsRequest is the request for updating existing credentials.
| Field | Type | Description |
|---|
| project | string | project is the name of the project containing the credentials. |
| name | string | name is the name of the credentials to update. |
| description | string | description is a human-readable description of the credentials. |
| type | string | type specifies the credential type (git, helm, image). |
| repo_url | string | repo_url is the URL of the repository or registry these credentials apply to. |
| repo_url_is_regex | bool | repo_url_is_regex indicates whether repo_url should be treated as a regular expression. |
| username | string | username is the username for authentication. |
| password | string | password is the password or token for authentication. |
UpdateCredentialsResponse
UpdateCredentialsResponse contains the updated credentials information.
| Field | Type | Description |
|---|
| credentials | k8s.io.api.core.v1.Secret | credentials is the updated Kubernetes Secret containing the credentials. |
UpdateFreightAliasRequest
UpdateFreightAliasRequest is the request for updating a freight's alias.
| Field | Type | Description |
|---|
| project | string | project is the name of the project containing the freight. |
| name | string | name is the name of the freight whose alias should be updated. |
| old_alias | string | old_alias is the current alias of the freight. |
| new_alias | string | new_alias is the new alias to assign to the freight. |
UpdateFreightAliasResponse
UpdateFreightAliasResponse is the response after updating a freight's alias. explicitly empty
UpdateProjectSecretRequest
UpdateProjectSecretRequest is the request for updating an existing project secret.
| Field | Type | Description |
|---|
| project | string | project is the name of the project containing the secret. |
| name | string | name is the name of the secret to update. |
| description | string | description is a human-readable description of the secret. |
| data | UpdateProjectSecretRequest.DataEntry | data contains the key-value pairs that make up the secret data. |
UpdateProjectSecretRequest.DataEntry
UpdateProjectSecretResponse
UpdateProjectSecretResponse contains the updated project secret information.
| Field | Type | Description |
|---|
| secret | k8s.io.api.core.v1.Secret | secret is the updated Kubernetes Secret within the project. |
UpdateResourceRequest
UpdateResourceRequest contains Kubernetes resource manifests to be updated.
| Field | Type | Description |
|---|
| manifest | bytes | manifest contains the raw Kubernetes resource manifests in YAML or JSON format. |
UpdateResourceResponse
UpdateResourceResponse contains the results of updating multiple resources.
| Field | Type | Description |
|---|
| results | UpdateResourceResult | results contains the outcome for each resource update attempt. |
UpdateResourceResult
UpdateResourceResult represents the result of attempting to update a single resource.
| Field | Type | Description |
|---|
| updated_resource_manifest | bytes | updated_resource_manifest contains the successfully updated resource manifest. |
| error | string | error contains the error message if resource update failed. |
UpdateRoleRequest
UpdateRoleRequest is the request for updating an existing RBAC role.
UpdateRoleResponse
UpdateRoleResponse contains the updated role information.
VersionInfo
VersionInfo contains detailed version and build information for a Kargo component.
| Field | Type | Description |
|---|
| version | string | version is the semantic version string. |
| git_commit | string | git_commit is the Git commit hash used for the build. |
| git_tree_dirty | bool | git_tree_dirty indicates whether the Git working tree was dirty during build. |
| build_time | google.protobuf.Timestamp | build_time is the timestamp when the build was created. |
| go_version | string | go_version is the Go version used for the build. |
| compiler | string | compiler is the compiler used for the build. |
| platform | string | platform is the target platform for the build. |
WatchClusterConfigRequest
explicitly empty
WatchClusterConfigResponse
WatchFreightRequest
WatchFreightRequest is the request for watching freight changes via streaming.
| Field | Type | Description |
|---|
| project | string | project is the name of the project whose freight should be watched. |
WatchFreightResponse
WatchFreightResponse contains freight change notifications.
WatchProjectConfigRequest
WatchProjectConfigRequest is the request for streaming project configuration changes.
| Field | Type | Description |
|---|
| project | string | project is the name of the project to watch for configuration changes. |
WatchProjectConfigResponse
WatchProjectConfigResponse provides streaming updates for project configuration changes.
WatchPromotionRequest is the request for watching a specific promotion via streaming.
| Field | Type | Description |
|---|
| project | string | project is the name of the project containing the promotion. |
| name | string | name is the name of the promotion to watch. |
WatchPromotionResponse contains specific promotion change notifications.
WatchPromotionsRequest is the request for watching promotion changes via streaming.
| Field | Type | Description |
|---|
| project | string | project is the name of the project whose promotions should be watched. |
| stage | string | stage is an optional stage name to filter promotions by. |
WatchPromotionsResponse contains promotion change notifications.
WatchStagesRequest
WatchStagesRequest is the request for watching stage changes via streaming.
| Field | Type | Description |
|---|
| project | string | project is the name of the project whose stages should be watched. |
| name | string | name is the name of a specific stage to watch, if empty all stages in the project are watched. |
WatchStagesResponse
WatchStagesResponse contains stage change notifications.
WatchWarehousesRequest
WatchWarehousesRequest is the request for watching warehouse changes via streaming.
| Field | Type | Description |
|---|
| project | string | project is the name of the project whose warehouses should be watched. |
| name | string | name is the name of a specific warehouse to watch, if empty all warehouses in the project are watched. |
WatchWarehousesResponse
WatchWarehousesResponse contains warehouse change notifications.
RawFormat specifies the format for raw resource representation.
| Name | Number | Description |
|---|
| RAW_FORMAT_UNSPECIFIED | 0 | RAW_FORMAT_UNSPECIFIED indicates no specific format is requested. |
| RAW_FORMAT_JSON | 1 | RAW_FORMAT_JSON requests JSON format for raw resources. |
| RAW_FORMAT_YAML | 2 | RAW_FORMAT_YAML requests YAML format for raw resources. |
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 |
AutoPromotionOptions specifies options pertaining to auto-promotion.
| Field | Type | Description |
|---|
| selectionPolicy | string | SelectionPolicy specifies the rules for identifying new Freight that is eligible for auto-promotion to this Stage. This field is optional. When left unspecified, the field is implicitly treated as if its value were "NewestFreight". Accepted Values: - "NewestFreight": The newest Freight that is available to the Stage is eligible for auto-promotion. - "MatchUpstream": Only the Freight currently used immediately upstream from this Stage is eligible for auto-promotion. This policy may only be applied when the Stage has exactly one upstream Stage. |
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
FreightCreationCriteria
FreightCreationCriteria defines criteria that must be satisfied for Freight to be created automatically from new artifacts following discovery.
| Field | Type | Description |
|---|
| expression | string | Expression is an expr-lang expression that must evaluate to true for Freight to be created automatically from new artifacts following discovery. |
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". |
| autoPromotionOptions | AutoPromotionOptions | AutoPromotionOptions specifies options pertaining to auto-promotion. These settings have no effect if auto-promotion is not enabled for this Stage at the ProjectConfig level. |
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. |
| metadata | StageStatus.MetadataEntry | Metadata is a map of arbitrary metadata associated with the Stage. This is useful for storing additional information about the Stage that can be shared across promotions, verifications, or other processes. |
StageStatus.MetadataEntry
| Field | Type | Description |
|---|
| key | string | |
| value | k8s.io.apiextensions_apiserver.pkg.apis.apiextensions.v1.JSON | |
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. |
| freightCreationCriteria | FreightCreationCriteria | FreightCreationCriteria defines criteria that must be satisfied for Freight to be created automatically from new artifacts following discovery. This field has no effect when the FreightCreationPolicy is Manual. |
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) |