Skip to content

Commit 4d36c3d

Browse files
stefanprodanstefanprodan
authored
Merge pull request #15 from fluxcd/controller-spec
Add controller specification
2 parents d1ba857 + 75f659d commit 4d36c3d

File tree

2 files changed

+201
-6
lines changed

2 files changed

+201
-6
lines changed

‎README.md‎

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -5,14 +5,14 @@
55
[![license](https://img.shields.io/github/license/fluxcd/kustomize-controller.svg)](https://github.com/fluxcd/kustomize-controller/blob/master/LICENSE)
66
[![release](https://img.shields.io/github/release/fluxcd/kustomize-controller/all.svg)](https://github.com/fluxcd/kustomize-controller/releases)
77

8-
The kustomize-controller is a continuous delivery tool for Kubernetes, specialized in running
9-
CD pipelines inside the cluster for workloads and infrastructure manifests
10-
coming from source control systems.
8+
The kustomize-controller is a Kubernetes operator, specialized in running
9+
continuous delivery pipelines for infrastructure and workloads
10+
defined with Kubernetes manifests and assembled with Kustomize.
1111

1212
![overview](docs/diagrams/kustomize-controller-overview.png)
1313

1414
Features:
15-
* watches for [Kustomization](docs/spec/v1alpha1/README.md) objects
15+
* watches for `Kustomization` objects
1616
* fetches artifacts produced by [source-controller](https://github.com/fluxcd/source-controller) from `Source` objects
1717
* watches `Source` objects for revision changes
1818
* generates the `kustomization.yaml` file if needed
@@ -24,6 +24,10 @@ Features:
2424
* runs `Kustomizations` in a specific order, taking into account the depends-on relationship
2525
* reports on Slack or Discord whenever a `Kustomization` status changes
2626

27+
Specifications:
28+
* [API](docs/spec/v1alpha1/README.md)
29+
* [Controller](docs/spec/README.md)
30+
2731
## Usage
2832

2933
The kustomize-controller is part of a composable GitOps toolkit and depends on
@@ -256,8 +260,6 @@ set in the Git repository manifest.
256260

257261
The kustomize controller can post message to Slack or Discord whenever a kustomization status changes.
258262

259-
![pipeline](docs/diagrams/kustomize-controller-pipeline.png)
260-
261263
Alerting can be configured by creating a profile that targets a list of kustomizations:
262264

263265
```yaml

‎docs/spec/README.md‎

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
# Kustomize Controller
2+
3+
The Kustomize Controller is a Kubernetes operator, specialized in running
4+
continuous delivery pipelines for infrastructure and workloads
5+
defined with Kubernetes manifests and assembled with Kustomize.
6+
7+
## Motivation
8+
9+
The main goal is to provide an automated operator that can
10+
bootstrap and continuously reconcile the cluster state
11+
from multiple sources (e.g. infrastructure and application repositories).
12+
13+
When provisioning a new cluster, one may wish to install workloads in a specific order,
14+
for example a validation controller such as OPA Gatekeeper should be up and running before
15+
applying other manifests on the cluster. Another example is a service mesh admission controller,
16+
the proxy injector must be functional before deploying applications into the mesh.
17+
18+
When operating a cluster, different teams may wish to receive notification about the status
19+
of their CD pipelines. For example, the on-call team would receive alerts about all
20+
failures in the prod namespace, while the frontend team may wish to be alerted when a new version
21+
of the frontend app was deployed and if the deployment is healthy, no matter the namespace.
22+
23+
When dealing with an incident, one may wish to suspend the reconciliation of some workloads and
24+
pin the reconciliation of others to a specific Git revision, without having to stop the reconciler
25+
and affect the whole cluster.
26+
27+
## Design
28+
29+
The reconciliation process can be defined with a Kubernetes custom resource
30+
that describes a pipeline such as:
31+
- **check** if depends-on conditions are meet
32+
- **fetch** manifests from Git repository X
33+
- **generate** a kustomization if needed
34+
- **build** the manifest using kustomization X
35+
- **validate** the resulting objects
36+
- **apply** the objects
37+
- **prune** the objects removed from source
38+
- **verify** the deployment status
39+
- **alert** if something went wrong
40+
- **notify** if the cluster state changed
41+
42+
![pipeline](../diagrams/kustomize-controller-pipeline.png)
43+
44+
The controller the runs these pipelines relies on
45+
[source-controller](https://github.com/fluxcd/source-controller)
46+
for providing the raw manifests from Git repositories or any
47+
other sources that source-controller could support in the future.
48+
49+
If a Git repository contains no Kustomize manifests, the controller will
50+
generate the `kustomization.yaml` automatically and label
51+
the objects for garbage collection (GC).
52+
53+
A pipeline runs on-a-schedule and ca be triggered manually by a
54+
cluster admin or automatically by a source event such as a Git revision change.
55+
56+
When a pipeline is removed from the cluster, the controller's GC terminates
57+
all the objects previously created by that pipeline.
58+
59+
A pipeline can be suspended, while in suspension the controller will
60+
stop the scheduler and will ignore any source events.
61+
Deleting a suspended pipeline does not trigger garbage collection.
62+
63+
Alerting can be configured with a Kubernetes custom resource
64+
that specifies a webhook address, and a group of pipelines to be monitored.
65+
66+
The API design of the controller can be found at [kustomize.fluxcd.io/v1alpha1](v1alpha1/README.md).
67+
68+
## Example
69+
70+
After installing kustomize-controller and its companion source-controller, we
71+
can create a series of pipelines for deploying Istio, and an application made of
72+
multiple services.
73+
74+
Create a source that points to where the Istio control plane manifests are,
75+
and a kustomization for installing/upgrading Istio:
76+
77+
```yaml
78+
apiVersion: source.fluxcd.io/v1alpha1
79+
kind: GitRepository
80+
metadata:
81+
name: istio
82+
namespace: kustomize-system
83+
spec:
84+
interval: 5m
85+
url: https://github.com/stefanprodan/gitops-istio
86+
ref:
87+
branch: master
88+
---
89+
apiVersion: kustomize.fluxcd.io/v1alpha1
90+
kind: Kustomization
91+
metadata:
92+
name: istio
93+
namespace: kustomize-system
94+
spec:
95+
interval: 10m
96+
path: "./istio/"
97+
generate: true
98+
sourceRef:
99+
kind: GitRepository
100+
name: istio
101+
healthChecks:
102+
- kind: Deployment
103+
name: istiod
104+
namespace: istio-system
105+
timeout: 2m
106+
```
107+
108+
Create a source for the app repo, a kustomization for each service defining depends-on relationships:
109+
110+
```yaml
111+
apiVersion: source.fluxcd.io/v1alpha1
112+
kind: GitRepository
113+
metadata:
114+
name: webapp
115+
namespace: kustomize-system
116+
spec:
117+
interval: 1m
118+
url: https://github.com/stefanprodan/podinfo-deploy
119+
ref:
120+
branch: master
121+
---
122+
apiVersion: kustomize.fluxcd.io/v1alpha1
123+
kind: Kustomization
124+
metadata:
125+
name: webapp-common
126+
namespace: kustomize-system
127+
spec:
128+
dependsOn:
129+
- istio
130+
interval: 5m
131+
path: "./webapp/common/"
132+
prune: "part-of=webapp"
133+
sourceRef:
134+
kind: GitRepository
135+
name: webapp
136+
validate: client
137+
---
138+
apiVersion: kustomize.fluxcd.io/v1alpha1
139+
kind: Kustomization
140+
metadata:
141+
name: webapp-backend
142+
namespace: kustomize-system
143+
spec:
144+
dependsOn:
145+
- webapp-common
146+
interval: 5m
147+
path: "./webapp/backend/"
148+
prune: "part-of=webapp,component=backend"
149+
sourceRef:
150+
kind: GitRepository
151+
name: webapp
152+
validate: server
153+
healthChecks:
154+
- kind: Deployment
155+
name: backend
156+
namespace: webapp
157+
---
158+
apiVersion: kustomize.fluxcd.io/v1alpha1
159+
kind: Kustomization
160+
metadata:
161+
name: webapp-frontend
162+
namespace: kustomize-system
163+
spec:
164+
dependsOn:
165+
- webapp-backend
166+
interval: 5m
167+
path: "./webapp/frontend/"
168+
prune: "part-of=webapp,component=frontend"
169+
sourceRef:
170+
kind: GitRepository
171+
name: webapp
172+
validate: server
173+
```
174+
175+
Configure alerting for all pipelines in the `kustomize-system` namespace:
176+
177+
```yaml
178+
apiVersion: kustomize.fluxcd.io/v1alpha1
179+
kind: Profile
180+
metadata:
181+
name: default
182+
namespace: kustomize-system
183+
spec:
184+
alert:
185+
type: slack
186+
verbosity: info
187+
address: https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK
188+
username: kustomize-controller
189+
channel: general
190+
kustomizations:
191+
- '*'
192+
```
193+

0 commit comments

Comments
 (0)