From 9df606c1fc1052340e3083ec8093c24c56968345 Mon Sep 17 00:00:00 2001 From: Enrique Encalada Date: Tue, 20 Oct 2020 18:58:35 +0200 Subject: [PATCH] Follow up from issue #2735 This adds documentation around HA support for the tekton pipeline controller. HA is enabled by default, therefore adding more information on the behaviour and how could devs/maintainers use it. --- docs/developers/enabling-ha.md | 72 ++++++++++++++++++++++++++++++++++ docs/install.md | 4 ++ 2 files changed, 76 insertions(+) create mode 100644 docs/developers/enabling-ha.md diff --git a/docs/developers/enabling-ha.md b/docs/developers/enabling-ha.md new file mode 100644 index 00000000000..911fbb9aca8 --- /dev/null +++ b/docs/developers/enabling-ha.md @@ -0,0 +1,72 @@ +# HA support for Tekton Pipeline controllers + +- [Overview](#overview) +- [Configuring HA](#configuring-ha) + - [Configuring the controller replicas](#configuring-the-controller-replicas) + - [Configuring the leader election](#configuring-the-leader-election) +- [Disabling leader election](#disabling-leader-election) + - [Use the disable-ha flag](#use-the-disable-ha-flag) + - [Scale down your replicas](#scale-down-your-replicas) + +## Overview + +--- +This document is aimed at helping maintainers/developers when configuring High Availability(HA) support for the Tekton Pipeline [controller deployment](../../config/controller.yaml). + +HA support allows components to remain operational when a disruption occurs. This is achieved by following an active/active model, where all replicas of the Tekton controller can receive workload. In this HA approach the reconcile space is distributed across buckets, where each replica owns a subset of those buckets and can process the load if the given replica is the leader of that bucket. + +By default HA is enabled in the Tekton pipelines controller. + +## Configuring HA + +--- +In order to achieve HA, the number of replicas for the Tekton Pipeline controller should be greater than one. This allows other instance(_s_) to take over in case of any disruption on the current active controller. + +### Configuring the controller replicas + +You can modify the replicas number in the [controller deployment](../../config/controller.yaml) under `spec.replicas` or apply an update to a running deployment: + +```sh +kubectl -n tekton-pipelines scale deployment tekton-pipelines-controller --replicas=3 +``` + +### Configuring the Leader Election + +The leader election can be configured via the [config-leader-election.yaml](../../config/config-leader-election.yaml). The configmap defines the following parameters: + +| Parameter | Default | +| -------------------- | -------- | +| `data.resourceLock` | "leases" | +| `data.leaseDuration` | 15s | +| `data.renewDeadline` | 10s | +| `data.retryPeriod` | 2s | + +## Disabling leader election + +--- + +If HA is not required and running a single instance of the Tekton Pipeline controller is enough, there are two alternatives: + +### Use the disable-ha flag + +You can modify the [controller deployment](../../config/controller.yaml), by specifying in the `tekton-pipelines-controller` container the `disable-ha` flag. For example: + +```yaml +spec: + serviceAccountName: tekton-pipelines-controller + containers: + - name: tekton-pipelines-controller + ... + args: [ + # Other flags defined here... + "-disable-ha=true" + ] +``` + +by setting `disable-ha` to `true`, HA will be disable in the controllers. + +**Note**: Please consider that when disabling HA and keeping multiple replicas of the [controller deployment](../../config/controller.yaml), each replica will act as an independent controller, leading to an unwanted behaviour when creating resources(e.g. `TaskRuns`, etc). + +### Scale down your replicas + +Although HA is enable by default, if your [controller deployment](../../config/controller.yaml) replicas are set to one, there would be no High Availability in the scenario where the running instance is deleted or fails. Therefore having a single replica even with HA enable, does not ensure high availability for the controller. diff --git a/docs/install.md b/docs/install.md index 55a0400e05b..8dc0674bd4d 100644 --- a/docs/install.md +++ b/docs/install.md @@ -349,6 +349,10 @@ data: disable-working-directory-overwrite: "true" # Tekton will not override the working directory for individual Steps. ``` +### Customizing High Availability for the Pipelines Controller + +To customize the behavior of HA for the Tekton Pipelines controller, please refer to the related [documentation](developers/enabling-ha.md). + ## Creating a custom release of Tekton Pipelines You can create a custom release of Tekton Pipelines by following and customizing the steps in [Creating an official release](https://github.com/tektoncd/pipeline/blob/master/tekton/README.md#create-an-official-release). For example, you might want to customize the container images built and used by Tekton Pipelines.