Application API reference

Fleet defines the fleet to dispatch the artifact.

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

Source defines the artifact source.

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

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.

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

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

HelmRelease defines the desired state of a Helm release.

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

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

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

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 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 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.

Minimum value

Maximum value

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

Annotations to be added to the object’s metadata.

Labels to be added to the object’s metadata.

API version of the referent

Kind of the referent

Name of the referent

Namespace of the referent

ObjectMeta holds the template for metadata like labels and annotations.

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

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 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/

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

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

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

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.

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.

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

Interval at which to reconcile the Helm release.

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

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

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

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

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 is the number of revisions saved by Helm for this HelmRelease. Use ‘0’ for an unlimited number of revisions; defaults to ‘10’.

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

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 holds the configuration for Helm install actions for this HelmRelease.

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

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

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

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

Values holds the values for this Helm release.

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 may contain a meta.NamespacedObjectReference slice with references to Kustomization resources that must be ready before this Kustomization can be reconciled.

The interval at which to reconcile the Kustomization.

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

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 enables garbage collection.

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

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.

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

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

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

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

Components specifies relative paths to specifications of other Components.

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 defines metrics query interval. Defaults to 60.

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

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

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 defines traffic routing provider. Kurator supports istio,kuma,nginx for now. Other provider will be added later.

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

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

Port exposed by the service.

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 is the labels and annotations are added to the preview service. The name of the preview service in the cluster is -canary

RolloutPolicy defines the release strategy of workload.

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

TrafficAnalysis defines the validation process of a release

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 promotes the preview release without analyzing it.

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, 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.

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

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

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

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

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.

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 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.

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.

Webhook list for this traffic analysis

SessionAffinity represents the session affinity settings for a analysis run.

TimeoutSeconds of the HTTP or gRPC request.

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

Defaults to the RolloutConfig.ServiceName

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 operations for the Request. e.g.

headers:
request:
add:
x-some-header: "value"

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

corsPolicy:
allowHeaders:
- x-some-header
allowMethods:
- GET
allowOrigin:
- example.com
maxAge: 24h

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 defines the protocol used by Kuma Only for kuma Defaults to http

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 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 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.

TimeoutSeconds defines request timeout for this webhook Defaults to 60

Commands define to commands that executed by webhook.