The Landlord Controller aims to automate the task of provisioning and maintaining Kubernetes clusters. The Landlord concept was inspired by the emerging "GitOps" movement.
We want version control for our cluster workloads - code and config. We believe it is good practice to keep our Kubernetes infrastructure config in Git so changes are audited using git commit and deployments are predictable.
The Landlord manages Tenants. A tenant is a play on words - it's not related to multi-tenancy. To the landlord it is a set of files in some GIT repo.
A Tenant may represent a project, a client or a lifecycle environment (dev, SIT, UAT, staging, etc). Each Tenant is described by a Custom Resource and is associated with a namespace.
The Landlord creates a namespace and a service account for each Tenant. We call this the environment. The Landlord runs in it's own namespace which is seperate from those created and assigned to each tenant.
Once a tenant's environment has been setup then the Landlord can download and deploy the Kubernetes resources needed to make it do something useful.
The basic workflow of the Landlord is as follows:
- Install Custom Resource Definition
- Wait for secret key
- Git clone the repository
- Deploy the cloned YAML into the cluster
The Landlord installs easily and adapts itself to the running cluster. It auto-detects the cluster and the namespace it was deployed into.
kubectl create namespace landlord
kubectl apply -f landlord-controller.yaml -n landlord
kubectl get deployments -n landlord
The Tenant is created by creating a Custom Resource (CR) in the Landlord's namespace. Each Tenant requires some basic information:
apiVersion: "k8s.troven.io/v1alpha"
kind: Tenant
metadata:
name: tenant-example
spec:
namespace: tenant-target
owner: cto@example.com
domain: tenant.example.com
git:
repo: git@github.com:troven/troven-lab-gitops.git
syncSeconds: 60
secret: tenant-example-git
path: cargo.ship/k8s/
branch_tag: master
The metadata.name is the mandatory name of the tenancy.
The metadata.namespace is the optional namespace for the tenancy. The namespace defaults to the metadata.name if not supplied.
The owner and domain are mandatory fields - they are not processed, they are only used as documentation:
owner: the email address of the main contact
domain: the sub-domain allocated to this tenancy
To instruct the Landlord to provision a Tenant, type the following:
kubectl apply -f ./build/tenants/tenant-example.yaml -n landlord
kubectl get tenants -n landlord
Once the Landlord detects the new tenancy, the following steps occurs:
- create namespace
- create service account
- bind role to service account
If configured, then:
- retrieve secret from git private key (if defined)
- git clone (optional branch/tag. defaults to 'master')
- deploy manifests
The Landlord can clone a Git repository before applying the manifests to the tenant's namespace.
The git specification:
git:
repo: the repository containing the manifests (default: none)
secret: (optional) the name of the K8s secret that contains the Git private key (default: none)
path: (optional) the path within the repository that contains the manifests (default: ".")
syncSeconds: (optiomal) time between git re-sync operations
An secret must be supplied if the repository is private. This should be an SSH private key or a github deploy key.
When using a key the landlord waits until the secret is provided.
If our secret is tenant-example-git, we might create the following key pair:
mkdir ./keys/
ssh-keygen -f ./keys/tenant-example-git.id_rsa -N ''
kubectl create secret generic tenant-example-git --from-file=key=./keys/tenant-example-git.id_rsa
NOTE: When using GitHub deploy keys then a dedicated key pair is needed for each repository.
The Landlord includes a simple Open API to read the list of tenancies and trigger a redeploy of tenancy.
To read the list of Tenant resources:
curl http://localhost:5200/landlord/
To trigger a re-deployment of a tenant:
curl -X POST http://localhost:5200/landlord/tenant-example
Additional resources include :
/metrics Prometheus metrics
/healthz Simple health check
/swagger Return the Swagger / OpenAPI v3 API docs
Copyright 2019-2020 Troven
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.