diff --git a/config/300-clustertask.yaml b/config/300-crds/300-clustertask.yaml similarity index 100% rename from config/300-clustertask.yaml rename to config/300-crds/300-clustertask.yaml diff --git a/config/300-customrun.yaml b/config/300-crds/300-customrun.yaml similarity index 100% rename from config/300-customrun.yaml rename to config/300-crds/300-customrun.yaml diff --git a/config/300-pipeline.yaml b/config/300-crds/300-pipeline.yaml similarity index 100% rename from config/300-pipeline.yaml rename to config/300-crds/300-pipeline.yaml diff --git a/config/300-pipelinerun.yaml b/config/300-crds/300-pipelinerun.yaml similarity index 100% rename from config/300-pipelinerun.yaml rename to config/300-crds/300-pipelinerun.yaml diff --git a/config/300-resolutionrequest.yaml b/config/300-crds/300-resolutionrequest.yaml similarity index 100% rename from config/300-resolutionrequest.yaml rename to config/300-crds/300-resolutionrequest.yaml diff --git a/config/300-stepaction.yaml b/config/300-crds/300-stepaction.yaml similarity index 100% rename from config/300-stepaction.yaml rename to config/300-crds/300-stepaction.yaml diff --git a/config/300-task.yaml b/config/300-crds/300-task.yaml similarity index 100% rename from config/300-task.yaml rename to config/300-crds/300-task.yaml diff --git a/config/300-taskrun.yaml b/config/300-crds/300-taskrun.yaml similarity index 100% rename from config/300-taskrun.yaml rename to config/300-crds/300-taskrun.yaml diff --git a/config/300-verificationpolicy.yaml b/config/300-crds/300-verificationpolicy.yaml similarity index 100% rename from config/300-verificationpolicy.yaml rename to config/300-crds/300-verificationpolicy.yaml diff --git a/docs/developers/multi-tenant-support.md b/docs/developers/multi-tenant-support.md index 84a7679221c..8b3c4fbd0cd 100644 --- a/docs/developers/multi-tenant-support.md +++ b/docs/developers/multi-tenant-support.md @@ -1,5 +1,59 @@ # Support for running in multi-tenant configuration +Multi-tenancy for Tekton is intended as running multiple instances of the +Tekton control plane in a single Kubernetes cluster, with each control plane +responsible for reconciliation of the Tekton resources in a single namespace. + +This type of setup involves various aspects of Tekton that are normally +cluster-wide or associated with namespaces: + +- Namespaces +- Custom Resource Definitions (CRDs) +- RBAC (Service Accounts, Roles and Bindings) +- Validation and Mutation Webhooks +- Conversion Webhook + +## Namespaces + +The Tekton control plance namespace resource is defined in a dedicated +[sub-folder](/config/100-namespace/), folder that includes +all Tekton resources. When installing from source, the namespace folder can be +skipped, and the namespace can be created beforehand instead. + +To customize the namespace where the control plan is installed, all namespaced +resources under the [`config`](/config/) folder (or in the release file) must be updated. +That can be achieved by search and replace, or using tools like `ko`, `sed` or `kustomize`. + +More details for the installation from source are available in the +[root development document](/DEVELOPMENT.md#installing-into-custom-namespaces). + +The Tekton control plane by default watches all namespaces for Tekton resources. +To change this behaviour, and limit the Tekton controller to a single namespace, +add the `--namespace ` command line flag to the Tekton controller +[deployment file](/config/controller.yaml). + +## Custom Resource Definitions + +Custom Resource Definitions are defined in a dedicated [sub-folder](/config/300-crds/), +under the [`config`](/config/) folder that includes all Tekton resources. + +When installing from source, instead of applying resources recursively, apply only +the content of the [`config`](/config/) folder, for instance: + +```sh +ko apply -f config +``` + +Note that the namespace will have to be created beforehand. +When installing from a release file, the [`yq(https://github.com/mikefarah/yq) tool +comes in handy: + +```sh +yq e '. | select(.kind != "CustomResourceDefinition")' < release.yaml > release-nocrd.yaml +``` + +## RBAC + In order to support potential multi-tenant configurations the roles of the controller are split into two: @@ -10,4 +64,36 @@ By default the roles are cluster-scoped for backwards-compatibility and ease-of-use. If you want to start running a multi-tenant service you are able to bind `tekton-pipelines-controller-tenant-access` using a `RoleBinding` instead of a `ClusterRoleBinding`, thereby limiting the access that the controller has -to specific tenant namespaces. \ No newline at end of file +to specific tenant namespaces. + +## Validation and Mutation Webhooks + +Validation and mutation webhooks configurations by default act with cluster scope. +Normally only instance of the webhooks per cluster is enough to serve all instances +of Tekton installed. + +If different versions of Tekton must coexist in the same cluster, they might require +different webhooks. Webhook configurations can be namespaced by using the +[`namespaceSelector`](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/#matching-requests-namespaceselector). + +The name of the [configurations](/config/webhook.yaml) must also be adapted so that +many instances may coexist, one per namespace. + +Note that running multiple versions of Tekton in a single cluster might work in +certain cases, but it's not officially supported. + +## Conversion Webhook + +Kubernets only allows one specific version of all resources associated with a specific +CRD being stored in etcd. For instance, all `Tasks` will be stored as `v1`, even if +both `v1` and `v1beta1` are served by the API. + +The conversion webhook converts versions on the fly when a version other than the stored +one is used. Tekton's conversion webhook is responsible for reconciling the CRD +definitions. Since those are defined at cluster level, only once conversion webhook may +exist in the cluster. + +The conversion webhook is bundled in a single binary with the other webhooks, so today +it's not possible to run multiple validation and mutation webhooks and a single +conversion webhook. [TEP-0129](https://github.com/tektoncd/community/blob/main/teps/0129-multiple-tekton-instances-per-cluster.md) +will change that, once implemented. diff --git a/docs/install.md b/docs/install.md index 09c5dfea1e2..df0c6575888 100644 --- a/docs/install.md +++ b/docs/install.md @@ -72,6 +72,9 @@ To install Tekton Pipelines on a Kubernetes cluster: kubectl apply --filename https://storage.googleapis.com/tekton-releases/pipeline/latest/release.notags.yaml ``` +Multi-tenant installation is only partially supported today, read the [guide](./developers/multi-tenant-support.md) +for reference. + 1. Monitor the installation: ```bash