Skip to content

Commit 2baacf3

Browse files
jorteljortel
authored
👻 Link settings in README files. (#787)
Replace hard coded settings defaults with link into settings README. --------- Signed-off-by: Jeff Ortel <[email protected]>
1 parent d5587aa commit 2baacf3

File tree

3 files changed

+85
-66
lines changed

3 files changed

+85
-66
lines changed

‎README.md

+6
Original file line numberDiff line numberDiff line change
@@ -6,5 +6,11 @@ Tackle (2nd generation) hub component.
66

77
<img src="https://github.com/konveyor/tackle2-hub/blob/main/arch.png" width="850" height="600">
88

9+
See [settings](https://github.com/konveyor/tackle2-hub/blob/main/settings/README.md#settings)
10+
for configuration.
11+
12+
The hub provides a REST API, inventory and
13+
[task manager](https://github.com/konveyor/tackle2-hub/blob/main/task/README.md#manager).
14+
915
## Code of Conduct
1016
Refer to Konveyor's Code of Conduct [here](https://github.com/konveyor/community/blob/main/CODE_OF_CONDUCT.md).

‎reaper/README.md

+14-7
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,8 @@ Buckets represent file trees and may be referenced by:
1919
- Task
2020
- TaskGroup
2121

22-
TTL after orphaned (default: 1 minute).
22+
The TTL after orphaned is defined by the
23+
[Bucket.TTL](https://github.com/konveyor/tackle2-hub/blob/main/settings/README.md#main) setting.
2324

2425
### Files ###
2526

@@ -29,15 +30,17 @@ Files represent files and may be referenced by:
2930
- Target
3031
- Rule
3132

32-
TTL after orphaned (default: 1 minute).
33+
The TTL after orphaned is defined by the
34+
[File.TTL](https://github.com/konveyor/tackle2-hub/blob/main/settings/README.md#main) setting.
3335

3436
### Tasks ###
3537

3638
Tasks may be created then submitted in a _two-phase_ process. The reason is to support
3739
a workflow that involves uploading files into the task's bucket. To do this, the user
3840
must create the task, upload the files, then submit the task. To prevent leaking tasks
3941
that are created and never submitted, the reaper will delete tasks that have not been
40-
submitted after a defined period (default: 72 hours).
42+
submitted after a period defined by the
43+
[Reaper.Created](https://github.com/konveyor/tackle2-hub/blob/main/settings/README.md#task-manager) setting.
4144

4245
Submitted tasks are never reaped. As a result, there is a need for objects
4346
referenced by tasks to be reaped. Tasks reference:
@@ -50,9 +53,13 @@ reaped. Releasing simply means to remove the reference to allow them to be
5053
naturally reaped (garbage-collected).
5154

5255
**Succeeded** tasks:
53-
- Released after a defined period (default: 72 hours).
54-
- Pod deleted after a defined period (default: 1 minute)
56+
- Released after a period defined by the
57+
[Reaper.Succeeded](https://github.com/konveyor/tackle2-hub/blob/main/settings/README.md#task-manager) setting.
58+
- Pod deleted after a period defined by the
59+
[Pod.Renention.Succeeded](https://github.com/konveyor/tackle2-hub/blob/main/settings/README.md#task-manager) setting.
5560

5661
**Failed** tasks:
57-
- Released after a defined period (default: 30 days).
58-
- Pod deleted after a defined period (default 72 hours).
62+
- Released after a period defined by the
63+
[Reaper.Failed](https://github.com/konveyor/tackle2-hub/blob/main/settings/README.md#task-manager) setting.
64+
- Pod deleted after a period defined by the
65+
[Pod.Retention.Failed](https://github.com/konveyor/tackle2-hub/blob/main/settings/README.md#task-manager) setting.

‎task/README.md

+65-59
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,8 @@
33

44
### Processing ###
55

6-
The manager processes tasks (default: 1 second) in a _main_ loop.
6+
The manager processes tasks at an interval defined by the
7+
[Frequency.Task](https://github.com/konveyor/tackle2-hub/tree/main/settings#intervalsfrequencies) setting.
78
1. Fetch cluster resources using a k8s cached client.
89
2. Process queued task delete and cancel requests.
910
3. Delete orphaned pods. Orphans are pod within the namespace with task
@@ -53,11 +54,14 @@ higher priority _ready_ task pod may be scheduled. Preemption is the act of kill
5354
the pod of a _running_ task, so that the higher _blocked_ task may be created/scheduled
5455
by the node-scheduler. A task is considered _blocked_ when it cannot be created due to
5556
a resource quota (state=QuotaBlocked) or cannot be scheduled by the node-scheduler
56-
(state=Pending) for a defined duration (default: 1 minute).
57+
(state=Pending) for a defined duration defined by the
58+
[Preemption.Delayed](https://github.com/konveyor/tackle2-hub/tree/main/settings#task-manager) setting.
5759
To trigger preemption, the _blocked_ task must have Policy.PreemptEnabled=TRUE. When
58-
the need for preemption is detected, the manger will preempt a percentage (default: 10%) of the
59-
newest, lower priority tasks processing cycle. To prevent _thrashing_ a preempted task will
60-
be postponed for a defined duration (default: 1 minute).
60+
the need for preemption is detected, the manger will preempt a percentage
61+
([Preemption.Rate](https://github.com/konveyor/tackle2-hub/tree/main/settings#task-manager))
62+
of the newest, lower priority tasks processing cycle. To prevent _thrashing_ a preempted task will
63+
be postponed for a defined duration defined by the
64+
[Preemption.Postponed](https://github.com/konveyor/tackle2-hub/tree/main/settings#task-manager) setting.
6165
When a task is preempted:
6266
1. The pod is deleted.
6367
2. The task state is reset to Ready.
@@ -93,24 +97,24 @@ following labels:
9397

9498
The manager injects a few environment variables:
9599

96-
| Name | Definition |
97-
|--------------|----------------------------------------------------------------------------------------------------|
98-
| ADDON_HOME | Path to an EmptyDir mounted as the working directory. (default: /addon) |
99-
| SHARED_PATH | Path to an EmptyDir mounted in all containers within the pod for sharing files. (default: /shared) |
100-
| CACHE_PATH | Path to a volume mounted in all containers in all pods for cached files. (default: /cache) |
101-
| HUB_BASE_URL | The hub API base url. |
102-
| TASK | The task id (to be acted on). |
103-
| TOKEN | An authentication token for the hub API. |
100+
| Name | Definition |
101+
|--------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
102+
| ADDON_HOME | Path to an EmptyDir mounted as the working directory. Defined by the [HomeDir](https://github.com/konveyor/tackle2-hub/tree/main/settings#addon) setting. |
103+
| SHARED_PATH | Path to an EmptyDir mounted in all containers within the pod for sharing files. Defined by the [Shared.Path](https://github.com/konveyor/tackle2-hub/tree/main/settings#main) setting. |
104+
| CACHE_PATH | Path to a volume mounted in all containers in all pods for cached files. Defined by the [Cache.Path](https://github.com/konveyor/tackle2-hub/tree/main/settings#main) setting. |
105+
| HUB_BASE_URL | The hub API base url. Defined by the [Hub.URL](https://github.com/konveyor/tackle2-hub/tree/main/settings#addon) setting. |
106+
| TASK | The task id (to be acted on). |
107+
| TOKEN | An authentication token for the hub API. |
104108

105109
#### Retention ####
106110

107111
The pod associated with completed task is retained for a defined duration. After
108112
which, the pod is deleted to prevent leaking pod resources indefinitely.
109113

110-
| State | Retention (default) |
111-
|-----------|---------------------|
112-
| Succeeded | 1 (minute) |
113-
| Failed | 72 (hour) |
114+
| State | Retention (default) |
115+
|-----------|----------------------------------------------------------------------------------------------------|
116+
| Succeeded | [Pod.Retention.Succeeded](https://github.com/konveyor/tackle2-hub/tree/main/settings#task-manager) |
117+
| Failed | [Pod.Retention.Failed](https://github.com/konveyor/tackle2-hub/tree/main/settings#task-manager) |
114118

115119
#### Containers ####
116120

@@ -134,32 +138,32 @@ Tasks are used to execute Addons.
134138

135139
`*` indicates reported by addon.
136140

137-
| Name | Definition |
138-
|-------------|--------------------------------------------------------------------------------------------------------------------|
139-
| ID | Unique identifier. |
140-
| CreateTime | The timestamp of when the task was created. |
141-
| CreateUser | The user (name) that created the task. |
142-
| UpdateUser | The user (name) that last updated the task. |
143-
| Name | The task mame (non-unique). |
144-
| Kind | The kind references a Task (kind) CR by name. |
145-
| Addon | The addon to be executed. References an Addon CR by name. When not specified, the addon is selected based on kind. |
146-
| Extension | The list of extensions to be injected into the addon pod as _sidecar_ containers. |
147-
| State | The task state. See: _States_. |
148-
| Locator | The task locator. An arbitrary user-defined value used for lookup. |
149-
| Priority | The task execution priority. See: _Priority_. |
150-
| Policy | The task execution policy. Determines when task is postponed. See: _Policy_. |
151-
| TTL | The task Time-To-Live in each state. See: _TTL_. |
152-
| Data | The data provided to the addon. The schema is dictated by each addon. This may be _ANY_ document. |
153-
| Started | The UTC timestamp when the task execution started. |
154-
| Terminated | The UTC timestamp when execution completed. |
155-
| Errors | A list of reported errors. See: _Errors_. |
156-
| Events | A list of reported task processing events. See: _Events_. |
157-
| Pod | The fully qualified name of the pod created. |
158-
| Retries | The number of times failure to create a pod is retried. This does not include when blocked by resource quota. |
159-
| Attached | Files attached to the task. |
160-
| \*Activity | The activity (log) entries are reported by the addon. Intended to reflect what the addon is doing. |
161-
| \*Total | Progress: The total number of items to be completed by the addon. |
162-
| \*Completed | Progress: The number of items completed by the addon. | |
141+
| Name | Definition |
142+
|-------------|-------------------------------------------------------------------------------------------------------------------------------------------------|
143+
| ID | Unique identifier. |
144+
| CreateTime | The timestamp of when the task was created. |
145+
| CreateUser | The user (name) that created the task. |
146+
| UpdateUser | The user (name) that last updated the task. |
147+
| Name | The task mame (non-unique). |
148+
| Kind | The kind references a Task (kind) CR by name. |
149+
| Addon | The addon to be executed. References an Addon CR by name. When not specified, the addon is selected based on kind. |
150+
| Extension | The list of extensions to be injected into the addon pod as _sidecar_ containers. |
151+
| State | The task state. See: [States](https://github.com/konveyor/tackle2-hub/tree/main/task#states). |
152+
| Locator | The task locator. An arbitrary user-defined value used for lookup. |
153+
| Priority | The task execution priority. See: [Priority](https://github.com/konveyor/tackle2-hub/tree/main/task#priority). |
154+
| Policy | The task execution policy. Determines when task is postponed. See: [Policies](https://github.com/konveyor/tackle2-hub/tree/main/task#policies). |
155+
| TTL | The task Time-To-Live in each state. See: [TTL](https://github.com/konveyor/tackle2-hub/tree/main/task#ttl-time-to-live). |
156+
| Data | The data provided to the addon. The schema is dictated by each addon. This may be _ANY_ document. |
157+
| Started | The UTC timestamp when the task execution started. |
158+
| Terminated | The UTC timestamp when execution completed. |
159+
| Errors | A list of reported errors. See: [Errors](https://github.com/konveyor/tackle2-hub/tree/main/task#errors). |
160+
| Events | A list of reported task processing events. See: [Events](https://github.com/konveyor/tackle2-hub/tree/main/task#events). |
161+
| Pod | The fully qualified name of the pod created. |
162+
| Retries | The number of times failure to create a pod is retried. This does not include when blocked by resource quota. |
163+
| Attached | Files attached to the task. |
164+
| \*Activity | The activity (log) entries are reported by the addon. Intended to reflect what the addon is doing. |
165+
| \*Total | Progress: The total number of items to be completed by the addon. |
166+
| \*Completed | Progress: The number of items completed by the addon. | |
163167

164168
### Events ###
165169

@@ -202,17 +206,17 @@ Note: A task may complete with a state=Succeeded with errors.
202206

203207
`*` indicates _terminal_ states.
204208

205-
| State | Definition |
206-
|:-------------|:----------------------------------------------------------------------------------------------|
207-
| Created | The task has been created but not submitted. |
208-
| Ready | The task has been submitted to the manager and will be scheduled for execution. |
209+
| State | Definition |
210+
|:-------------|:------------------------------------------------------------------------------------------------|
211+
| Created | The task has been created but not submitted. |
212+
| Ready | The task has been submitted to the manager and will be scheduled for execution. |
209213
| Postponed | The task has been postponed until another task has completed based on task scheduling _policy_. |
210-
| QuotaBlocked | The task pod has been (temporarily) prevented from being created by k8s resource quota. |
211-
| Pending | The task pod has been created and awaiting k8s scheduling. |
212-
| Running | The task pod is running. |
213-
| \*Succeeded | The task pod successfully completed. |
214-
| \*Failed | The task pod either failed to be started by k8s or completed with errors. |
215-
| \*Canceled | The task has been canceled. |
214+
| QuotaBlocked | The task pod has been (temporarily) prevented from being created by k8s resource quota. |
215+
| Pending | The task pod has been created and awaiting k8s scheduling. |
216+
| Running | The task pod is running. |
217+
| \*Succeeded | The task pod successfully completed. |
218+
| \*Failed | The task pod either failed to be started by k8s or completed with errors. |
219+
| \*Canceled | The task has been canceled. |
216220

217221

218222
### Policies ###
@@ -243,7 +247,7 @@ The `Task` CR defines a name kind of task. Each kind may define:
243247

244248
An `Addon` CR defines a named addon (aka plugin). It defines functionality provide by an image to
245249
be executed. The definition includes a container specification and selection criteria. An addon
246-
may have extensions. See: _Extensions_.
250+
may have extensions. See: [_Extensions_](https://github.com/konveyor/tackle2-hub/tree/main/task#extensions).
247251

248252
### Selection ###
249253

@@ -281,9 +285,11 @@ valid while the task is running.
281285
A task may be reaped after existing in a state for the defined duration.
282286
This is to prevent orphaned or stuck tasks from leaking resources such as buckets and files.
283287

284-
| State | Duration (default) | Action |
285-
|-----------|--------------------|----------|
286-
| Created | 72 (hour) | Deleted |
287-
| Succeeded | 72 (hour) | Deleted |
288-
| Failed | 30 (day) | Released |
288+
| State | Duration (default) | Action |
289+
|-----------|---------------------------------------------------------------------------------------------|----------|
290+
| Created | [Reaper.Created](https://github.com/konveyor/tackle2-hub/tree/main/settings#task-manager) | Deleted |
291+
| Succeeded | [Reaper.Succeeded](https://github.com/konveyor/tackle2-hub/tree/main/settings#task-manager) | Deleted |
292+
| Failed | [Reaper.Failed](https://github.com/konveyor/tackle2-hub/tree/main/settings#task-manager) | Released |
289293

294+
See [Reaper](https://github.com/konveyor/tackle2-hub/blob/main/reaper/README.md#reaper)
295+
settings for details.

0 commit comments

Comments
 (0)