troven/landlord-controller repository overview

⁠Landlord Controller

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.

⁠How it works

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:

1. Install Custom Resource Definition
2. Wait for secret key
3. Git clone the repository
4. Deploy the cloned YAML into the cluster

⁠Quick start

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

⁠Creating a new tenant

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: [email protected]
  domain: tenant.example.com
  git:
    repo: [email protected]: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

⁠Using Git to provision the tenancy

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

⁠Using a private repository

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.

⁠Using the OpenAPI

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

⁠License

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.