We need to introduce a new CRD into the Faros ecosystem. This document outlines the problem and attempts to provide detail on the solution to this problem and how it will interact with the existing operation of Faros.
There are a few ways in which operators may want to run their Faros instance(s), this document will try to explain the different modes of operation given the new ClusterGitTrack type.
Problem
The way in which Faros uses OwnerReferences to manage the relationship between GitTracks and ClusterGitTrackObjects is unsupported by Kubernetes and can lead to garbage collection issues with catastrophic consequences(entire clusters can be deleted).
Solution
By introducing a new type, ClusterGitTrack, we can modify the behaviour of Faros to forbid GitTracks from owning cluster scoped resources and ensure that cross namespace management is also disallowed.
A ClusterGitTrack will look identical to the GitTrack but will be defined at the cluster scope. We can introduce an interface implemented by both GitTrack and ClusterGitTrack to enable us to re-use the same controller code for both resource types.
The introduction of the new type substantially complicates the modes in which Faros can operate. The rest of this document explains the flags that will be needed to configure the different operational modes of Faros and the use cases for the different operational modes in which I envisage people will use Faros.
Flags to define modes of operation
To enable different use cases for Faros, we will introduce two new flags that will configure how Faros will manage GitTrack and ClusterGitTrack resources. This will allow cluster operators to deploy Faros in multiple different configurations based on their security requirements.
Flag Name
Description
Default
--gittrack-mode
Should Faros be managing GitTrack resources
Available options:
Disabled: Do not manage GitTracks
Enabled: Manage GitTracks
Disabled
--clustergittrack-mode
Which mode should Faros operate in for ClusterGitTracks. Available options are:
Disabled: Do not manage ClusterGitTracks
IncludeNamespaced: Manage ClusterGitTracks and allow them to manage namespaced resources
ExcludeNamespaced: Manage ClusterGitTracks but disallow them from managing namespaced resources
IncludeNamespaced
--namespace
Restrict Faros to only managing GitTracks and GitTrackObjects from within the given namespace
(For use with--gittrack-mode=enabled)
""
Resource Ownership Matrix
The following matrix details which GitTrack/ClusterGitTrack resources should be allowed to own which GitTrackObject/ClusterGitTrackObject resources depending on configuration of the Faros instance managing them
Owner Type(.kind)
Owner Namespace(.metadata.namespace)
ClusterGitTrackMode
GitTrackObject(NS: Foo)
GitTrackObject(NS: Bar)
ClusterGitTrackObject
GitTrack
Foo
N/A
Y
N(Cross namespace never allowed)
N(GitTrack can never own cluster-scoped resource)
GitTrack
Bar
N/A
N(Cross namespace never allowed)
Y
N(GitTrack can never own cluster-scoped resource)
ClusterGitTrack
N/A
ExcludeNamespaced
N
N
Y(ClusterGitTrackscan always own CGTO)
ClusterGitTrack
N/A
IncludeNamespaced
Y
Y
Y(ClusterGitTrackscan always own CGTO)
Controller Reconcile Matrix
Within Faros, the following modes will be implemented by enabling and disabling“Watches” as the controllers are initialised.
For example, by wrapping the watch of GitTrack and GitTrackObjects owned by GitTracks(in this code) within an if statement, the--gittrack-mode flag can prevent GitTracks and their children from causing the GitTrack controller to reconcile them.
The following matrices show which resources should and shouldn’t be reconciled by a given instance of Faros based on the configuration of the above flags.
ClusterGitTrack modes
The following determines which resources the Faros instance should watch based on the configuration of the--clustergittrack-mode flag
ClusterGitTrack Mode
GitTrack
GitTrackObject
ClusterGitTrack
ClusterGitTrackObject
A
IncludeNamespaced
N
Y
Y
Y
B
ExcludeNamespaced
N
N
Y
Y
C
Disabled
N
N
N
N
GitTrack modes
The following determines which resources the Faros instance should watch based on the configuration of the--gittrack-mode and--namespace flags
Problem
Solution
Flags to define modes of operation
Resource Ownership Matrix
Controller Reconcile Matrix
ClusterGitTrack modes
GitTrack modes