You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: Documentation/howto/deployment.md
+53-20Lines changed: 53 additions & 20 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,22 +1,27 @@
1
1
# Deploying Clair
2
2
3
-
Clair v4 was designed with flexible deployment architectures in mind. The operator is free to choose a deployment model which scales to their use cases.
3
+
Clair v4 was designed with flexible deployment architectures in mind.
4
+
An operator is free to choose a deployment model which scales to their use cases.
4
5
5
6
## Configuration
6
7
7
-
Before jumping directly into the models its important to note that Clair is designed to use a single configuration file across all node types. This design decision makes it very easy to deploy on systems like Kubernetes and OpenShift.
8
+
Before jumping directly into the models, its important to note that Clair is designed to use a single configuration file across all node types.
9
+
This design decision makes it very easy to deploy on systems like Kubernetes and OpenShift.
8
10
9
11
See [Config Reference](../reference/config.md)
10
12
11
13
## Combined Deployment
12
14
13
-
In a combined deployment, all the Clair processes run in a single OS process. This is by far the easiest deployment model to configure as it involves the least moving parts.
15
+
In a combined deployment, all the Clair processes run in a single OS process.
16
+
This is by far the easiest deployment model to configure as it involves the least moving parts.
14
17
15
-
A load balancer is still recommended if you plan on performing TLS termination. Typically this will be a OpenShift route or a Kubernetes ingress.
18
+
A load balancer is still recommended if you plan on performing TLS termination.
19
+
Typically this will be a OpenShift route or a Kubernetes ingress.
16
20
17
21
18
22
19
-
In the above diagram, Clair is running in combo mode and talking to a single database. To configure this model you will provide all node types the same database and start Clair in **combo** mode.
23
+
In the above diagram, Clair is running in combo mode and talking to a single database.
24
+
To configure this mode, you will provide all node types the same database and start Clair in **combo** mode.
In this mode, any configuration informing Clair how to talk to other nodes is ignored, it is not needed as all intra-process communication is done directly.
37
+
In this mode, any configuration informing Clair how to talk to other nodes is ignored;
38
+
it is not needed as all intra-process communication is done directly.
33
39
34
40
For added flexibility, it's also supported to split the databases while in combo mode.
35
41
36
42
37
43
38
-
In the above diagram, Clair is running in combo mode but database load is split between multiple databases. Since Clair is conceptually a set of micro-services, its processes do not share database tables even when combined into the same OS process.
44
+
In the above diagram, Clair is running in combo mode but database load is split between multiple databases.
45
+
Since Clair is conceptually a set of micro-services, its processes do not share database tables even when combined into the same OS process.
39
46
40
-
To configure this model, you would provide each process its own "connstring" in the configuration.
47
+
To configure this mode, you would provide each process its own "connstring" in the configuration.
41
48
```
42
49
...
43
50
indexer:
@@ -54,18 +61,26 @@ notifier:
54
61
55
62
If your application needs to asymmetrically scale or you expect high load you may want to consider a distributed deployment.
56
63
57
-
In a distributed deployment, each Clair process runs in its own OS process. Typically this will be a Kubernetes or OpenShift Pod.
64
+
In a distributed deployment, each Clair process runs in its own OS process.
65
+
Typically this will be a Kubernetes or OpenShift Pod.
66
+
67
+
A load balancer **must** be setup in this deployment model.
68
+
The load balancer will route traffic between Clair nodes along with routing API requests via [path based routing] to the correct services.
69
+
In a Kubernetes or OpenShift deployment this is usually handled with the `Service` and `Route` abstractions.
70
+
If deploying on bare metal, a load balancer will need to be configured appropriately.
58
71
59
-
A load balancer **must** be setup in this deployment model. The load balancer will route traffic between Clair nodes along with routing API requests via [path based routing](https://devcentral.f5.com/s/articles/the-three-http-routing-patterns-you-should-know-30764) to the correct services. In a Kubernetes or OpenShift deployment this is usually handled with the Service and Routes abstractions. If deploying on bare metal, a load balancer will need to be configured appropriately.
60
72
61
73
62
74
63
-
In the above diagram, a load balancer is configured to route traffic coming from the client to the correct service. This routing is path based routing and requires a layer 7 load balancer. Traefik, Nginx, and HAProxy are all capable of this. As mentioned above, this functionality is native to OpenShift and Kubernetes.
75
+
In the above diagram, a load balancer is configured to route traffic coming from the client to the correct service.
76
+
This routing is path based and requires a layer 7 load balancer.
77
+
Traefik, Nginx, and HAProxy are all capable of this.
78
+
As mentioned above, this functionality is native to OpenShift and Kubernetes.
64
79
65
-
In this configuration, you'd supply each process with database connection strings and addresses for their dependent services. Each OS process will need to have its "mode" CLI flag or environment variable set to the appropriate value.
80
+
In this configuration, you'd supply each process with database connection strings and addresses for their dependent services.
81
+
Each OS process will need to have its "mode" CLI flag or environment variable set to the appropriate value.
66
82
See [Config Reference](../reference/config.md)
67
83
68
-
69
84
```
70
85
...
71
86
indexer:
@@ -81,19 +96,34 @@ notifier:
81
96
...
82
97
```
83
98
84
-
Keep in mind a config file per process is not need. Processes only use the values necessary for their configured mode.
99
+
Keep in mind a config file per process is not need.
100
+
Processes only use the values necessary for their configured mode.
85
101
86
102
## TLS Termination
87
103
88
-
Currently Clair offloads TLS termination to the load balancing infrastructure. This design choice is due to the ubiquity of Kubernetes and OpenShift infrastructure already providing this facility.
104
+
It's recommended to offload TLS termination to the load balancing infrastructure.
105
+
This design choice is due to the ubiquity of Kubernetes and OpenShift infrastructure already providing this facility.
106
+
107
+
If this is not possible for some reason, it is possible to have processes terminate TLS by using the `$.tls` configuration key.
108
+
A load balancer is still required.
109
+
110
+
## Disk Usage Considerations
111
+
112
+
By default, Clair will store container layers in `/var/tmp` while in use.
113
+
This can be changed by setting the `TMPDIR` environment variable.
114
+
There's currently no way to change this in the configuration file.
115
+
116
+
The disk space needed depends on the precise layers being indexed at any one time,
117
+
but a good approximation is twice as large as the largest (uncompressed size) layer in the corpus.
89
118
90
119
## More On Path Routing
91
120
92
-
If you are considering a distributed deployment you will need more details on [path based routing](https://devcentral.f5.com/s/articles/the-three-http-routing-patterns-you-should-know-30764).
121
+
If you are considering a distributed deployment you will need more details on [path based routing].
93
122
94
-
Learn how to grab our OpenAPI spec [here](./api.md) and either start up a local dev instance of the swagger editor or load the spec file into the [online editor](https://petstore.swagger.io/#/)
123
+
Learn how to grab our OpenAPI spec [here](./api.md) and either start up a local dev instance of the swagger editor or load the spec file into the [online editor](https://petstore.swagger.io/#/).
95
124
96
-
You will notice particular API paths are grouped by the services which implement them. This is your guide to configure your layer 7 load balancer correctly.
125
+
You will notice particular API paths are grouped by the services which implement them.
126
+
This is your guide to configure your layer 7 load balancer correctly.
97
127
98
128
When the load balancer encounters a particular path prefix it must send those request to the correct set of Clair nodes.
99
129
@@ -106,6 +136,9 @@ For example, this is how we configure Traefik in our local development environme
0 commit comments