Skip to content

Commit d5587aa

Browse files
jorteljortel
authored
👻 Add Settings README. (#786)
Add README.md for settings and reaper. --------- Signed-off-by: Jeff Ortel <[email protected]>
1 parent a8f955f commit d5587aa

File tree

3 files changed

+173
-1
lines changed

3 files changed

+173
-1
lines changed

‎reaper/README.md

+58
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
2+
## Reaper ##
3+
4+
The hub inventory contains a set of entities that are garbage collected (reaped)
5+
rather than deleted through cascading. These entities may be referenced by multiple
6+
types of entities so managing deletion though cascade delete can be complex. Instead,
7+
the relation between objects is modeled as _references_. When the reference count
8+
is zero(0), it is considered an _orphan_ and the referenced object is assigned
9+
an expiration TTL (time-to-live). This _grace-period_ is designed to account for
10+
transient conditions such as a transfer of ownership. If not re-associated when the
11+
TTL has expired, the orphan is deleted.
12+
13+
There are also non-referenced entities that need to be reaped.
14+
15+
### Buckets ###
16+
17+
Buckets represent file trees and may be referenced by:
18+
- Application
19+
- Task
20+
- TaskGroup
21+
22+
TTL after orphaned (default: 1 minute).
23+
24+
### Files ###
25+
26+
Files represent files and may be referenced by:
27+
- Task
28+
- TaskReport
29+
- Target
30+
- Rule
31+
32+
TTL after orphaned (default: 1 minute).
33+
34+
### Tasks ###
35+
36+
Tasks may be created then submitted in a _two-phase_ process. The reason is to support
37+
a workflow that involves uploading files into the task's bucket. To do this, the user
38+
must create the task, upload the files, then submit the task. To prevent leaking tasks
39+
that are created and never submitted, the reaper will delete tasks that have not been
40+
submitted after a defined period (default: 72 hours).
41+
42+
Submitted tasks are never reaped. As a result, there is a need for objects
43+
referenced by tasks to be reaped. Tasks reference:
44+
- Bucket
45+
- File
46+
- Pod
47+
48+
Reaped objects such as buckets and files are said to be _released_ when the task is
49+
reaped. Releasing simply means to remove the reference to allow them to be
50+
naturally reaped (garbage-collected).
51+
52+
**Succeeded** tasks:
53+
- Released after a defined period (default: 72 hours).
54+
- Pod deleted after a defined period (default: 1 minute)
55+
56+
**Failed** tasks:
57+
- Released after a defined period (default: 30 days).
58+
- Pod deleted after a defined period (default 72 hours).

‎settings/README.md

+115
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
## Settings ##
2+
3+
Settings provide hub configuration.
4+
5+
The `T` specifies the type:
6+
- `I` = integer
7+
- `S` = string
8+
- `B` = boolean (0|1|true|false)
9+
10+
### Main ###
11+
12+
These settings pertain to the Hub in general.
13+
14+
| Name | T | Envar | Default | Definition |
15+
|---------------------------|---|-----------------------|-----------------|---------------------------------------------------|
16+
| Build | S | BUILD | | Hub build version. |
17+
| Namespace | S | NAMESPACE | konveyor-tackle | Home k8s Namespace. |
18+
| **DB**.Path | S | DB_PATH | /tmp/tackle.db | Path to sqlite file. |
19+
| **DB**.MaxConnections | I | DB_MAX_CONNECTION | 1 | Number of DB connections. |
20+
| **DB**.SeedPath | S | DB_SEED_PATH | /tmp/seed | Path to seed files. |
21+
| **Bucket**.Path | S | BUCKET_PATH | /tmp/bucket | Path to bucket storage directory. |
22+
| **Bucket**.TTL | I | BUCKET_TTL | 1 (minute) | Orphaned buckets TTL (minutes). |
23+
| **File**.TTL | I | FILE_TTL | 1 (minute) | Orphaned files TTL (minutes). |
24+
| **Cache**.RWX | B | RWX_SUPPORTED | FALSE | Cache volume supports RWX. |
25+
| **Cache**.Path | S | CACHE_PATH | /cache | Cache volume mount path. |
26+
| **Cache**.PVC | S | CACHE_PVC | cache | Cache PVC name. Used when RWX suppored. |
27+
| **Shared**.Path | S | SHARED_PATH | /shared | Shared volume mount path. |
28+
| **Encryption**.Passphrase | S | ENCRYPTION_PASSPHRASE | tackle | RSA encryption passphrase. |
29+
| Development | B | DEVELOPMENT | FALSE | Development mode. |
30+
| Disconnected | B | DISCONNECTED | FALSE | Not connected to a cluster. |
31+
| Product | S | APP_NAME | tackle | Product/application name. Affects target seeding. |
32+
| **Metrics**.Enabled | B | METRICS_ENABLED | TRUE | Metrics reporting enabled. |
33+
| **Metrics**.Port | I | METRICS_PORT | | Metrics reporting (listen) port number. |
34+
35+
### Auth ###
36+
37+
These settings pertain to authentication and authorization.
38+
39+
| Name | T | Envar | Default | Definition |
40+
|-----------|---|---------------|-----------------|--------------------------------------------|
41+
| Required | B | AUTH_REQUIRED | FALSE | API enforces authentication/authorization. |
42+
| RolePath | S | RULE_PATH | /tmp/roles.yaml | Path to file used to seed roles. |
43+
| UserPath | S | USER_PATH | /tmp/users/yaml | Path to file used to seed users. |
44+
| Token.Key | S | ADDON_TOKEN | | Key used to sign tokens. |
45+
46+
### Task Manager ###
47+
48+
These settings pertain to the tasking system.
49+
50+
| Name | T | Envar | Default | Definition |
51+
|-------------------------|---|---------------------------|------------|----------------------------------------------------------------------------------|
52+
| SA | S | TASK_SA | | Task pod service account name. |
53+
| Retries | I | TASK_RETRIES | 1 | Task pod creation retires. |
54+
| Reaper.Created | I | TASK_REAP_CREATED | 72 (hour) | (seconds) task may remain in state=CREATED before deleted. |
55+
| Reaper.Succeeded | I | TASK_REAP_SUCCEEDED | 72 (hour) | (seconds) before SUCCEEDED task's bucket released. |
56+
| Reaper.Failed | I | TASK_REAP_FAILED | 30 (day) | (seconds) before FAILED task's bucket is bucket released. |
57+
| Preemption.Enabled | B | TASK_PREEMPT_ENABLED | FALSE | Task.Policy.Preempt.Enabled default. |
58+
| Preemption.Delayed | I | TASK_PREEMPT_DELAYED | 1 (minute) | (seconds) before READY task is deemed to be _blocked_ and my trigger preemption. |
59+
| Preemption.Postponed | I | TASK_PREEMPT_POSTPONED | 1 (minute) | (seconds) before task with PREEMPTED event will be postponed. |
60+
| Preemption.Rate | I | TASK_PREEMPT_RATE | 10% | (percent) of lower priority RUNNING tasks to be preempted each pass. |
61+
| Pod.Retention.Succeeded | I | TASK_POD_RETAIN_SUCCEEDED | 1 (minute) | (minutes) before SUCCEEDED task pod is reaped (deleted). |
62+
| Pod.Retention.Failed | I | TASK_POD_RETAIN_FAILED | 72 (hour) | (minutes) before FAILED task pod is reaped (deleted). |
63+
| Pod.UID | S | TASK_UID | | Task pod run-as user id. |
64+
65+
### Intervals/Frequencies ###
66+
67+
These settings pertain to the frequency of _manager_ main loops.
68+
69+
| Name | T | Envar | Default | Definition |
70+
|--------|---|------------------|------------|--------------------------------------|
71+
| Task | I | FREQUENCY_TASK | 1 (second) | (seconds) between each manager pass. |
72+
| Reaper | I | FREQUENCY_REAPER | 1 (minute) | (minutes) between each reaper pass. |
73+
74+
### Analysis ###
75+
76+
These settings pertain to analysis.
77+
78+
| Name | T | Envar | Default | Definition |
79+
|-----------------|---|---------------------------|-----------------------|---------------------------------|
80+
| ReportPath | S | ANALYSIS_REPORT_PATH | /tmp/analysis/report | Path to static analysis report. |
81+
| ArchiverEnabled | B | ANALYSIS_ARCHIVER_ENABLED | TRUE | Analysis report auto-archived. |
82+
83+
### Discovery ###
84+
85+
These settings pertain to the auto-create of lang-discovery tasks.
86+
87+
| Name | T | Envar | Default | Definition |
88+
|---------|---|-------------------|----------------------------|-----------------------------------------------|
89+
| Enabled | B | DISCOVERY_ENABLED | TRUE when not DISCONNECTED | Trigger discover tasks on application update. |
90+
| Label | S | DISCOVERY_LABEL | konveyor.io/discovery | k8s label use to select lang-discover tasks. |
91+
92+
### Addon ###
93+
94+
These settings are intended to be shared by the hub and the (Go) addons.
95+
96+
| Name | T | Envar | Default | Definition |
97+
|-----------|---|--------------|-----------------------|---------------------------------|
98+
| HomeDir | S | ADDON_HOME | /addon | Addon home (working) directory. |
99+
| Hub.URL | S | HUB_BASE_URL | http://localhost:8080 | Hub (base) URL. |
100+
| Hub.Token | S | TOKEN | | Auth token for hub API. |
101+
| Task.ID | I | TASK | | Task addon working on. |
102+
103+
104+
### KEYCLOAK ###
105+
106+
| Name | T | Envar | Default | Definition |
107+
|------------------------|---|--------------------------|---------|----------------------------|
108+
| RequirePasswordUpdate | B | KEYCLOAK_REQ_PASS_UPDATE | TRUE | User must change password. |
109+
| Host | S | KEYCLOAK_HOST | | Service hostname. |
110+
| Realm | S | KEYCLOAK_REALM | | Realm name. |
111+
| ClientID | S | KEYCLOAK_CLIENT_ID | | Client id. |
112+
| ClientSecret | S | KEYCLOAK_CLIENT_SECRET | | Client secret. |
113+
| Admin.User | S | KEYCLOAK_ADMIN_USER | | Admin client user. |
114+
| Admin.Password | S | KEYCLOAK_ADMIN_PASS | | Admin client password. |
115+
| Admin.Realm | S | KEYCLOAK_ADMIN_REALM | | Admin client realm. |

‎settings/hub.go

-1
Original file line numberDiff line numberDiff line change
@@ -106,7 +106,6 @@ type Hub struct {
106106
Frequency struct {
107107
Task int
108108
Reaper int
109-
Volume int
110109
}
111110
// Development environment
112111
Development bool

0 commit comments

Comments
 (0)