Common Configurations
This document outlines common advanced installation scenarios and configurations for Kargo.
For complete parameter documentation, refer to the chart documentation.
Standard Kubernetes Configuration
For common Kubernetes configurations, like setting a nodeSelector, labels,
annotations, affinity, tolerations, etc. Kargo supports both global and
resource-specific configurations. For example, to add labels to all resources
created by Kargo, the following configuration can be used:
global:
labels:
label.example.com/key: value
To add labels to a specific component (the kargo-controller in this example),
the following configuration can be used:
controller:
labels:
label.example.com/key: value
For a full list of supported configurations, refer to the Global Parameters or the component-specific parameter sections in the chart documentation.
API Configuration
Kargo supports a number of API-related configurations that can be set at installation time. These configurations are used to control the behavior of Kargo's API server and its web-based user interface.
The sections below outline common configurations for the API server. For a full list of supported configurations, refer to the API Parameters. section in the chart documentation.
API Host
By default, the API server host (i.e. the domain or IP address that the API is
accessible at) is set to localhost. This host is used for generation of
Ingress resources, certificates, the OpenID Connect issuer and callback URLs,
and any URLs that are exposed to users.
To configure the API host, set the following configuration:
api:
host: kargo.example.com
The host is allowed to include a port number, e.g. kargo.example.com:8080,
but should not include a protocol (e.g. http:// or https://) as this is
automatically inferred from other configuration options.
API Service
By default, Kargo will create a Service resource for the API server with the
type ClusterIP, which is only accessible within the cluster or through
port forwarding.
Changing the API server service type can expose the API server to the internet in an insecure manner. Refer to the Secure Configuration section for more information on securing the API server.
Instead of making use of a Service resource, you can also expose the API
server using an Ingress resource.
If you want to expose the API server to the internet, but do not want to make
use of an Ingress resource, you can change the service type:
api:
service:
type: LoadBalancer
In addition, when using a LoadBalancer or NodePort service type, you can
configure the service to use a specific port:
api:
service:
type: LoadBalancer
port: 443
API TLS
By default, Kargo will enable TLS directly on the API server using a self-signed certificate issued by cert-manager.
When making use of the self-signed certificate option, cert-manager must be installed in the cluster.
To supply your own certificate, set the following configuration:
api:
tls:
selfSignedCert: false
When setting selfSignedCert to false, a
TLS Secret
with the name kargo-api-cert is expected to exist in the same namespace as
the API server.
Terminating TLS
If you have opted out of all the chart's built-in TLS options, but TLS is
terminated upstream from the API server by a component such as a reverse proxy,
load balancer, or Ingress controller using a wildcard certificate, Kargo will be
unable to infer from its own configuration that any generated URLs should use
HTTPS.
For such cases, you can explicitly declare that TLS is terminated upstream and Kargo will sort out the rest:
api:
tls:
enabled: false
terminatedUpstream: true
If you exercise any of the chart's built-in TLS configuration options,
setting terminatedUpstream is never required.
API Ingress
Instead of making use of an Ingress resource, you can also expose the API
server using a LoadBalancer or NodePort service type. Refer to the
API Service section for more information.
By default, Kargo will not create an Ingress resource for the API server
and will only be accessible within the cluster or through the API server's
Service resource. To expose the API server to the internet,
an Ingress resource can be created.
Enabling the API server Ingress without proper configuration can expose the API server to the internet in an insecure manner. Refer to the Secure Configuration section for more information on securing the API server.
To configure the API server to use an Ingress resource, set the following
configuration:
api:
ingress:
enabled: true
ingressClassName: nginx
Ingress TLS
By default, Kargo will enable TLS on the Ingress resource using a self-signed
certificate using cert-manager.
When making use of the self-signed certificate option, cert-manager must be installed in the cluster.
To supply your own certificate, set the following configuration:
api:
ingress:
tls:
selfSignedCert: false
When setting selfSignedCert to false, the Ingress resource expects a
TLS Secret
with the name kargo-api-ingress-cert to exist in the same namespace as the
API server.
Git Configuration
Kargo supports a number of Git-related configurations that can be set at installation time.
Default Commit Author
To set the default commit author Kargo will use when committing changes using
the git-commit Promotion step,
the following configuration can be set (shown here with the default values):
controller:
gitClient:
name: Kargo
email: no-reply@kargo.io
Signing Commits
To sign commits made by Kargo, a reference to a Secret (in the same namespace
as Kargo is installed to) containing a signing key can be configured. The key
should be a GPG key in ASCII-armored format without a passphrase, under the
key signingKey.
apiVersion: v1
kind: Secret
metadata:
name: kargo-git-signing-key
type: Opaque
data:
signingKey: <base64-encoded-ascii-armored-gpg-key>
The Secret can then be referenced in the Kargo configuration.
controller:
gitClient:
signingKeySecret:
name: kargo-git-signing-key
type: gpg
When using a signing key, the gitClient.name and gitClient.email
configuration options must match the name and email associated with the GPG
key.
Argo CD Configuration
Kargo supports a number of Argo CD-related configurations that can be set at installation time.
Disabling the Argo CD Integration
By default, Kargo will enable the Argo CD integration, which configures Kargo
to work with Application resources created by Argo CD. This can be disabled
as follows:
controller:
argocd:
integrationEnabled: false
When disabled, the controller will not watch Argo CD Application resources
and disable Argo CD specific features.
If the integration is enabled without Argo CD installed, the controller will disable the Argo CD specific features on boot. Explicitly disabling is preferred if this integration is not desired, as it will grant fewer permissions to the controller.
Argo CD Namespace
By default, Kargo expects Argo CD to be installed to the argocd namespace,
which is also the default namespace it will use for Application resources
if a namespace is not specified in the
argocd-update Promotion step.
If you want to use a different default namespace, this can be configured as follows:
controller:
argocd:
namespace: argocd
In certain cases, you may not want Kargo to be able to look up Argo CD resources in other namespaces than the configured default. This can be enforced by setting the following configuration:
controller:
argocd:
watchArgocdNamespaceOnly: true
When enabled, the controller will only watch for Application resources in the
namespace specified by controller.argocd.namespace.
Argo Rollouts Configuration
Disabling the Argo Rollouts Integration
By default, Kargo will enable the Argo Rollouts integration, which configures
Kargo to work with Rollout resources created by Argo Rollouts as part of the
verification feature.
This can be disabled as follows:
controller:
argoRollouts:
integrationEnabled: false
When disabled, the controller will not reconcile Argo Rollouts AnalysisRun
resources and attempts to verify Stages via Analysis will fail.
If the integration is enabled without Argo Rollouts installed, the controller will disable the Argo Rollouts specific features on boot. Explicitly disabling is preferred if this integration is not desired, as it will grant fewer permissions to the controller.
Resource Management
Tuning Concurrent Reconciliation Limits
By default, Kargo will reconcile up to four resources of the same kind
concurrently (e.g. four Stage resources at a time). It is possible to tune
this limit by setting a new global value, or by setting a limit per resource
kind:
controller:
reconcilers:
# Global setting
maxConcurrentReconciles: 4
managementController:
# Kind specific setting
namespaces:
maxConcurrentReconciles: 2
For a list of resource kinds that can be configured, refer to the chart documentation.
Garbage Collection
Kargo includes a garbage collector that automatically removes old Freight and
Promotion resources. The garbage collector offers a number of configuration
options to manage the retention of these resources.
Disabling the Garbage Collector
By default, the garbage collector is enabled. To disable it, set the following configuration:
garbageCollector:
enabled: false
Disabling the garbage collector will result in old Freight and Promotion
resources accumulating in the cluster. This can lead to increased resource
usage and potential performance issues. Therefore, this is typically not
recommended and should only be done with caution.
Scheduling the Garbage Collection
By default, the garbage collector runs every 24 hours. This can be configured using a cron expression:
garbageCollector:
schedule: "0 0 * * *"
Retention Settings
The garbage collector offers a number of settings to control the retention of
Freight and Promotion resources. The following settings are available:
garbageCollector:
# The minimum age a Promotion resource must be before it can be deleted.
# This is a duration string (e.g. 336h for 14 days).
minPromotionDeletionAge: 336h
# The number of Promotion resources for each Stage to retain that are older
# than the minimum deletion age. I.e., if a Stage has 30 Promotions older
# than minPromotionDeletionAge, only the 20 most recent will be retained.
maxRetainedPromotions: 20
# The minimum age a Freight resource must be before it can be deleted.
# This is a duration string (e.g. 336h for 14 days).
minFreightDeletionAge: 336h
# The number of Freight resources for each Warehouse to retain that are older
# than the minimum deletion age. I.e., if a Warehouse has 20 Freight older
# than minFreightDeletionAge, only the 20 most recent will be retained.
maxRetainedFreight: 10
Promotion resources are only deleted if they are in a terminal state (i.e.
Succeeded or Failed). Freight resources are only deleted if they are not
actively in use by any Stage.
In both cases, this holds true even if the resource is older than the minimum deletion age.