Application API reference

Detailed documentation on the Application API

Packages:

apps.kurator.dev/v1alpha1

Package v1alpha1 contains API Schema definitions for the apps v1alpha1 API group

Resource Types:

Application

Application is the schema for the application’s API.

Field Description
apiVersion
string
apps.kurator.dev/v1alpha1
kind
string
Application
metadata
Kubernetes meta/v1.ObjectMeta
Refer to the Kubernetes API documentation for the fields of the metadata field.
spec
ApplicationSpec
source
ApplicationSource

Source defines the artifact source.

syncPolicies
[]ApplicationSyncPolicy

SyncPolicies controls how the artifact will be customized and where it will be synced.

destination
ApplicationDestination
(Optional)

Destination defines the destination clusters where the artifacts will be synced. It can be overridden by the syncPolicies’ destination. And if both the current field and syncPolicies’ destination are empty, the application will be deployed directly in the cluster where kurator resides.

status
ApplicationStatus

ApplicationDestination

(Appears on: ApplicationSpec, ApplicationSyncPolicy)

ApplicationDestination defines the configuration to dispatch an artifact to a fleet or specific clusters.

Field Description
fleet
string

Fleet defines the fleet to dispatch the artifact.

clusterSelector
ClusterSelector
(Optional)

ClusterSelector specifies the selectors to select the clusters within the fleet. If unspecified, all clusters in the fleet will be selected.

ApplicationSource

(Appears on: ApplicationSpec)

ApplicationSource defines the configuration to produce an artifact for git, helm or oci repository. Note only one source can be specified.

ApplicationSourceStatus

(Appears on: ApplicationStatus)

applicationSourceStatus defines the observed state of the artifact source.

ApplicationSpec

(Appears on: Application)

ApplicationSpec defines the configuration to produce an artifact and how to dispatch it.

Field Description
source
ApplicationSource

Source defines the artifact source.

syncPolicies
[]ApplicationSyncPolicy

SyncPolicies controls how the artifact will be customized and where it will be synced.

destination
ApplicationDestination
(Optional)

Destination defines the destination clusters where the artifacts will be synced. It can be overridden by the syncPolicies’ destination. And if both the current field and syncPolicies’ destination are empty, the application will be deployed directly in the cluster where kurator resides.

ApplicationStatus

(Appears on: Application)

ApplicationStatus defines the observed state of Application.

Field Description
sourceStatus
ApplicationSourceStatus
syncStatus
[]ApplicationSyncStatus

ApplicationSyncPolicy

(Appears on: ApplicationSpec)

ApplicationSyncPolicy defines the configuration to sync an artifact. Only oneof kustomization or helm can be specified to manage application sync.

Field Description
name
string
(Optional)

Name defines the name of the sync policy. If unspecified, a name of format <application name>-<index> will be generated.

kustomization
Kustomization
(Optional)

Kustomization defines the configuration to calculate the desired state from a source using kustomize.

helm
HelmRelease
(Optional)

HelmRelease defines the desired state of a Helm release.

destination
ApplicationDestination
(Optional)

Destination defines the destination for the artifact. If specified, it will override the destination specified at Application level.

rollout
RolloutConfig
(Optional)

Rollout defines the rollout configurations to be used. If specified, a uniform rollout policy is configured for this installed object.

ApplicationSyncStatus

(Appears on: ApplicationStatus)

ApplicationSyncStatus defines the observed state of Application sync.

CanaryConfig

(Appears on: TrafficRoutingConfig)

Field Description
maxWeight
int
(Optional)

Max traffic weight routed to preview service. If empty and no stepweights are set, 100 will be used by default.

stepWeight
int
(Optional)

StepWeight defines the incremental traffic weight step for analysis phase If set stepWeight: 10 and set maxWeight: 50 The flow ratio between PREVIEW and PRIMARY at each step is (10:90) (20:80) (30:70) (40:60) (50:50)

stepWeights
[]int
(Optional)

StepWeights defines the incremental traffic weight steps for analysis phase Note: Cannot configure stepWeights and stepWeight at the same time. If both stepWeights and maxWeight are configured, the traffic will be scaled according to the settings in stepWeights only. If set stepWeights: [1, 10, 20, 80] The flow ratio between PREVIEW and PRIMARY at each step is (1:99) (10:90) (20:80) (80:20)

stepWeightPromotion
int
(Optional)

StepWeightPromotion defines the incremental traffic weight step for promotion phase If maxWeight: 50 and set stepWeightPromotion: 20 After a successful test, traffic to the PRIMARY version changes as follows: 50 70 90 100.

CanaryThresholdRange

(Appears on: Metric)

CanaryThresholdRange defines the range used for metrics validation

Field Description
min
float64
(Optional)

Minimum value

max
float64
(Optional)

Maximum value

ClusterSelector

(Appears on: ApplicationDestination)

Field Description
matchLabels
map[string]string
(Optional)

MatchLabels is a map of {key,value} pairs. A single {key,value} in the matchLabels map is equivalent to an element of matchExpressions, whose key field is “key”, the operator is “In”, and the values array contains only “value”. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#label-selectors

CommonMetadata

(Appears on: Kustomization)

Field Description
annotations
map[string]string
(Optional)

Annotations to be added to the object’s metadata.

labels
map[string]string
(Optional)

Labels to be added to the object’s metadata.

CrossNamespaceObjectReference

(Appears on: RolloutConfig)

CrossNamespaceObjectReference contains enough information to let you locate the typed referenced object at cluster level

Field Description
apiVersion
string
(Optional)

API version of the referent

kind
string
(Optional)

Kind of the referent

name
string

Name of the referent

namespace
string
(Optional)

Namespace of the referent

CustomMetadata

(Appears on: RolloutConfig)

CustomMetadata holds labels and annotations to set on generated objects.

Field Description
labels
map[string]string
annotations
map[string]string

HelmChartTemplate

(Appears on: HelmRelease)

HelmChartTemplate defines the template from which the controller will generate a v1beta2.HelmChart object in the same namespace as the referenced v1beta2.Source.

Field Description
metadata
HelmChartTemplateObjectMeta
(Optional)

ObjectMeta holds the template for metadata like labels and annotations.

spec
HelmChartTemplateSpec

Spec holds the template for the v1beta2.HelmChartSpec for this HelmRelease.

chart
string

The name or path the Helm chart is available at in the SourceRef.

version
string
(Optional)

Version semver expression, ignored for charts from v1beta2.GitRepository and v1beta2.Bucket sources. Defaults to latest when omitted.

interval
Kubernetes meta/v1.Duration
(Optional)

Interval at which to check the v1beta2.Source for updates. Defaults to ‘HelmReleaseSpec.Interval’.

reconcileStrategy
string
(Optional)

Determines what enables the creation of a new artifact. Valid values are (‘ChartVersion’, ‘Revision’). See the documentation of the values for an explanation on their behavior. Defaults to ChartVersion when omitted.

valuesFiles
[]string
(Optional)

Alternative list of values files to use as the chart values (values.yaml is not included by default), expected to be a relative path in the SourceRef. Values files are merged in the order of this list with the last file overriding the first. Ignored when omitted.

HelmChartTemplateObjectMeta

(Appears on: HelmChartTemplate)

HelmChartTemplateObjectMeta defines the template for the ObjectMeta of a v1beta2.HelmChart.

Field Description
labels
map[string]string
(Optional)

Map of string keys and values that can be used to organize and categorize (scope and select) objects. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/

annotations
map[string]string
(Optional)

Annotations is an unstructured key value map stored with a resource that may be set by external tools to store and retrieve arbitrary metadata. They are not queryable and should be preserved when modifying objects. More info: https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/

HelmChartTemplateSpec

(Appears on: HelmChartTemplate)

HelmChartTemplateSpec defines the template from which the controller will generate a v1beta2.HelmChartSpec object.

Field Description
chart
string

The name or path the Helm chart is available at in the SourceRef.

version
string
(Optional)

Version semver expression, ignored for charts from v1beta2.GitRepository and v1beta2.Bucket sources. Defaults to latest when omitted.

interval
Kubernetes meta/v1.Duration
(Optional)

Interval at which to check the v1beta2.Source for updates. Defaults to ‘HelmReleaseSpec.Interval’.

reconcileStrategy
string
(Optional)

Determines what enables the creation of a new artifact. Valid values are (‘ChartVersion’, ‘Revision’). See the documentation of the values for an explanation on their behavior. Defaults to ChartVersion when omitted.

valuesFiles
[]string
(Optional)

Alternative list of values files to use as the chart values (values.yaml is not included by default), expected to be a relative path in the SourceRef. Values files are merged in the order of this list with the last file overriding the first. Ignored when omitted.

HelmRelease

(Appears on: ApplicationSyncPolicy)

Note: copied from https://github.com/fluxcd/helm-controller/blob/main/api/v2beta1/helmrelease_types.go HelmRelease defines the desired state of a Helm release.

Field Description
chart
HelmChartTemplate

Chart defines the template of the v1beta2.HelmChart that should be created for this HelmRelease.

interval
Kubernetes meta/v1.Duration

Interval at which to reconcile the Helm release.

suspend
bool
(Optional)

Suspend tells the controller to suspend reconciliation for this HelmRelease, it does not apply to already started reconciliations. Defaults to false.

releaseName
string
(Optional)

ReleaseName used for the Helm release. Defaults to a composition of ‘[TargetNamespace-]Name’.

targetNamespace
string
(Optional)

TargetNamespace to target when performing operations for the HelmRelease. Defaults to the namespace of the HelmRelease.

dependsOn
[]github.com/fluxcd/pkg/apis/meta.NamespacedObjectReference
(Optional)

DependsOn may contain a meta.NamespacedObjectReference slice with references to HelmRelease resources that must be ready before this HelmRelease can be reconciled.

timeout
Kubernetes meta/v1.Duration
(Optional)

Timeout is the time to wait for any individual Kubernetes operation (like Jobs for hooks) during the performance of a Helm action. Defaults to ‘5m0s’.

maxHistory
int
(Optional)

MaxHistory is the number of revisions saved by Helm for this HelmRelease. Use ‘0’ for an unlimited number of revisions; defaults to ‘10’.

serviceAccountName
string
(Optional)

The name of the Kubernetes service account to impersonate when reconciling this HelmRelease.

persistentClient
bool
(Optional)

PersistentClient tells the controller to use a persistent Kubernetes client for this release. When enabled, the client will be reused for the duration of the reconciliation, instead of being created and destroyed for each (step of a) Helm action.

This can improve performance, but may cause issues with some Helm charts that for example do create Custom Resource Definitions during installation outside Helm’s CRD lifecycle hooks, which are then not observed to be available by e.g. post-install hooks.

If not set, it defaults to true.

install
github.com/fluxcd/helm-controller/api/v2beta1.Install
(Optional)

Install holds the configuration for Helm install actions for this HelmRelease.

upgrade
github.com/fluxcd/helm-controller/api/v2beta1.Upgrade
(Optional)

Upgrade holds the configuration for Helm upgrade actions for this HelmRelease.

rollback
github.com/fluxcd/helm-controller/api/v2beta1.Rollback
(Optional)

Rollback holds the configuration for Helm rollback actions for this HelmRelease.

uninstall
github.com/fluxcd/helm-controller/api/v2beta1.Uninstall
(Optional)

Uninstall holds the configuration for Helm uninstall actions for this HelmRelease.

valuesFrom
[]github.com/fluxcd/helm-controller/api/v2beta1.ValuesReference

ValuesFrom holds references to resources containing Helm values for this HelmRelease, and information about how they should be merged.

values
Kubernetes /apiextensions/v1.JSON
(Optional)

Values holds the values for this Helm release.

Kustomization

(Appears on: ApplicationSyncPolicy)

Note: copied from https://github.com/fluxcd/kustomize-controller/blob/main/api/v1/kustomization_types.go Kustomization defines the configuration to calculate the desired state from a Source using Kustomize.

Field Description
commonMetadata
CommonMetadata
(Optional)

CommonMetadata specifies the common labels and annotations that are applied to all resources. Any existing label or annotation will be overridden if its key matches a common one.

dependsOn
[]github.com/fluxcd/pkg/apis/meta.NamespacedObjectReference
(Optional)

DependsOn may contain a meta.NamespacedObjectReference slice with references to Kustomization resources that must be ready before this Kustomization can be reconciled.

interval
Kubernetes meta/v1.Duration

The interval at which to reconcile the Kustomization.

retryInterval
Kubernetes meta/v1.Duration
(Optional)

The interval at which to retry a previously failed reconciliation. When not specified, the controller uses the KustomizationSpec.Interval value to retry failures.

path
string
(Optional)

Path to the directory containing the kustomization.yaml file, or the set of plain YAMLs a kustomization.yaml should be generated for. Defaults to ‘None’, which translates to the root path of the SourceRef.

prune
bool

Prune enables garbage collection.

patches
[]github.com/fluxcd/pkg/apis/kustomize.Patch
(Optional)

Strategic merge and JSON patches, defined as inline YAML objects, capable of targeting objects based on kind, label and annotation selectors.

images
[]github.com/fluxcd/pkg/apis/kustomize.Image
(Optional)

Images is a list of (image name, new name, new tag or digest) for changing image names, tags or digests. This can also be achieved with a patch, but this operator is simpler to specify.

suspend
bool
(Optional)

This flag tells the controller to suspend subsequent kustomize executions, it does not apply to already started executions. Defaults to false.

targetNamespace
string
(Optional)

TargetNamespace sets or overrides the namespace in the kustomization.yaml file.

timeout
Kubernetes meta/v1.Duration
(Optional)

Timeout for validation, apply and health checking operations. Defaults to ‘Interval’ duration.

force
bool
(Optional)

Force instructs the controller to recreate resources when patching fails due to an immutable field change.

components
[]string
(Optional)

Components specifies relative paths to specifications of other Components.

Metric

(Appears on: TrafficAnalysis)

Field Description
name
MetricName

Name of the metric. There are two built-in metrics: request-success-rate and request-duration. And you can use the metrics that come with the gateway. When you define a metric rule in CustomMetric, fill in the custom name in this field.

intervalSeconds
int

IntervalSeconds defines metrics query interval. Defaults to 60.

thresholdRange
CanaryThresholdRange
(Optional)

ThresholdRange defines valid value accepted for this metric. If no thresholdRange are set, Kurator will default every check is successful.

customMetric
github.com/fluxcd/flagger/pkg/apis/flagger/v1beta1.MetricTemplateSpec
(Optional)

CustomMetric defines the metric template to be used for this metric.

MetricName (string alias)

(Appears on: Metric)

RolloutConfig

(Appears on: ApplicationSyncPolicy)

Field Description
testLoader
bool
(Optional)

Testloader defines whether to install a private testloader for Kurator. Testloader generates traffic during rollout analysis. Default is false. Because Kurator will installs a public testloader with the flagger installation. If set it to true, Kurator will install a private testloader dedicated to requesting the workload.

trafficRoutingProvider
Kurator fleet/v1alpha1.Provider

TrafficRoutingProvider defines traffic routing provider. Kurator supports istio,kuma,nginx for now. Other provider will be added later.

workload
CrossNamespaceObjectReference

Workload specifies what workload to deploy the test to. Workload of type Deployment or DaemonSet.

serviceName
string

ServiceName holds the name of a service which matches the workload.

port
int32

Port exposed by the service.

primary
CustomMetadata
(Optional)

Primary is the labels and annotations are added to the primary service. Primary service is stable service. The name of the primary service in the cluster is -primary

preview
CustomMetadata
(Optional)

Preview is the labels and annotations are added to the preview service. The name of the preview service in the cluster is -canary

rolloutPolicy
RolloutPolicy

RolloutPolicy defines the release strategy of workload.

RolloutPolicy

(Appears on: RolloutConfig)

Field Description
trafficRouting
TrafficRoutingConfig

TrafficRouting defines the configuration of the gateway, traffic routing rules, and so on.

trafficAnalysis
TrafficAnalysis

TrafficAnalysis defines the validation process of a release

rolloutTimeoutSeconds
int32
(Optional)

RolloutTimeoutSeconds represents the maximum time in seconds for a preview deployment to make progress before it is considered to be failed. Defaults to 600.

skipTrafficAnalysis
bool
(Optional)

SkipTrafficAnalysis promotes the preview release without analyzing it.

revertOnDeletion
bool
(Optional)

RevertOnDeletion defines whether to revert a resource to its initial state when deleting rollout resource. Use of the revertOnDeletion property should be enabled when you no longer plan to rely on Kurator for deployment management. Kurator will install the Flagger to the specified cluster via a fleet plugin. If RevertOnDeletion is set to true, the Flagger will revert a resource to its initial state when the deleting Application.Spec.ApplicationSyncPolicy.Rollout or the Application.

suspend
bool
(Optional)

Suspend, if set to true will suspend the rollout, disabling any rollout runs regardless of any changes to its target, services, etc. Note that if the rollout is suspended during an analysis, its paused until the rollout is uninterrupted.

RolloutStatus

(Appears on: ApplicationSyncStatus)

RolloutStatus defines the observed state of Rollout.

Field Description
clusterName
string
(Optional)

ClusterName is the Name of the cluster where the rollout is being performed.

rolloutNameInCluster
string
(Optional)

RolloutNameInCluster is the name of the rollout being performed within this cluster.

rolloutStatusInCluster
github.com/fluxcd/flagger/pkg/apis/flagger/v1beta1.CanaryStatus
(Optional)

RolloutStatusInCluster is the current status of the Rollout performed within this cluster.

SessionAffinity

(Appears on: TrafficAnalysis)

Field Description
cookieName
string

CookieName is the key that will be used for the session affinity cookie.

maxAge
int
(Optional)

MaxAge indicates the number of seconds until the session affinity cookie will expire. ref: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#attributes The default value is 86,400 seconds, i.e. a day.

TrafficAnalysis

(Appears on: RolloutPolicy)

Field Description
checkIntervalSeconds
int

CheckIntervalSeconds defines the schedule interval for this traffic analysis. Interval is the time interval between each test. Kurator changes the traffic distribution rules (if they need to be changed) and performs a traffic analysis every so often. Defaults to 60.

checkFailedTimes
int

CheckFailedTimes defines the max number of failed checks before the traffic analysis is terminated If set “checkFailedTimes: 2”. It means Kurator will rollback when check failed 2 times.

metrics
[]Metric
(Optional)

Metric check list for this traffic analysis Flagger comes with two builtin metric checks: HTTP request success rate and duration. Can use either built-in metric checks or custom checks. If you want use custom checks, you can refer to https://docs.flagger.app/usage/metrics#custom-metrics.

webhooks
Webhook
(Optional)

Webhook list for this traffic analysis

sessionAffinity
SessionAffinity
(Optional)

SessionAffinity represents the session affinity settings for a analysis run.

TrafficRoutingConfig

(Appears on: RolloutPolicy)

Field Description
timeoutSeconds
int
(Optional)

TimeoutSeconds of the HTTP or gRPC request.

gateways
[]string
(Optional)

Gateways attached to the generated Istio virtual service. Defaults to the internal mesh gateway.

hosts
[]string
(Optional)

Defaults to the RolloutConfig.ServiceName

retries
github.com/fluxcd/flagger/pkg/apis/istio/v1alpha3.HTTPRetry
(Optional)

Retries describes the retry policy to use when a HTTP request fails. For example, the following rule sets the maximum number of retries to three, with a 2s timeout per retry attempt. e.g.:

retries:
attempts: 3
perTryTimeout: 2s
retryOn: gateway-error,connect-failure,refused-stream
headers
github.com/fluxcd/flagger/pkg/apis/istio/v1alpha3.Headers
(Optional)

Headers operations for the Request. e.g.

headers:
request:
add:
x-some-header: "value"
corsPolicy
github.com/fluxcd/flagger/pkg/apis/istio/v1alpha3.CorsPolicy
(Optional)

Cross-Origin Resource Sharing policy for the request. e.g.

corsPolicy:
allowHeaders:
- x-some-header
allowMethods:
- GET
allowOrigin:
- example.com
maxAge: 24h
host
string
(Optional)

Host defines the domain name you specify. Only for NGINX Fill in the host field with your own domain as the host of the Ingress. The actual created Ingress is as follows:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: nginx
namespace: application.syncPolicies.rollout.workload.namespace
labels:
app: application.syncPolicies.rollout.ServiceName
annotations:
kubernetes.io/ingress.class: "nginx"
spec:
rules:
- host: ""
http:
paths:
- pathType: Prefix
path: "/"
backend:
service:
name: application.syncPolicies.rollout.ServiceName
port:
number: application.syncPolicies.rollout.port
protocol
string
(Optional)

Protocol defines the protocol used by Kuma Only for kuma Defaults to http

canaryStrategy
CanaryConfig
(Optional)

CanaryStrategy defines parameters for Canary Deployment. Note: Kurator determines A/B Testing, Blue/Green Deployment, or Canary Deployment based on the presence of content in the canaryStrategy field. So can’t configure canaryStrategy and analysisTimes at the same time.

analysisTimes
int
(Optional)

AnalysisTimes defines the number of traffic analysis checks to run for A/B Testing and Blue/Green Deployment If set “analysisTimes: 10”. It means Kurator will checks the preview service ten times.

match
[]github.com/fluxcd/flagger/pkg/apis/istio/v1alpha3.HTTPMatchRequest
(Optional)

Match conditions of A/B Testing HTTP header. The header keys must be lowercase and use hyphen as the separator. values are case-sensitive and formatted as follows: - exact: "value" for exact string match - prefix: "value" for prefix-based match - regex: "value" for ECMAscript style regex-based match e.g.:

match:
- headers:
myheader:
regex: ".*XXXX.*"
- headers:
cookie:
regex: "^(.*?;)?(type=insider)(;.*)?$"

Note: If you want to use A/B Testing, you need to configure analysisTimes and match. If you only configure analysisTimes, it will trigger Blue/Green Deployment. You can configure both canaryStrategy and match. If configure both canaryStrategy and match, Traffic that meets match goes towards the preview service. Traffic that doesn’t meet the match will go to the primary service and preview service proportionally.

Webhook

(Appears on: TrafficAnalysis)

Kurator generates traffic load by invoking the testloader through a webhook to request the service. e.g.

webhooks:
- timeoutSeconds: 15
command:
- "hey -z 1m -q 10 -c 2 http://podinfo-canary.test:9898/"

The above example means that during trafficAnalysis, the cmd of “http://flagger-loadtester.test/” is invoked to execute the command “hey -z 1m -q 10 -c 2 http://podinfo-canary.test:9898/”

Field Description
timeoutSeconds
int

TimeoutSeconds defines request timeout for this webhook Defaults to 60

command
[]string
(Optional)

Commands define to commands that executed by webhook.

This page was automatically generated with gen-crd-api-reference-docs