Added agent registration docs (#1921)

---------

Co-authored-by: 6543 <6543@obermui.de>
This commit is contained in:
Thomas Anderson 2023-07-03 16:44:16 +03:00 committed by GitHub
parent a4cfa3a242
commit 3386696d71
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
4 changed files with 36 additions and 3 deletions

View file

@ -2,7 +2,7 @@
Agents are configured by the command line or environment variables. At the minimum you need the following information:
```yaml
```diff
# docker-compose.yml
version: '3'
@ -23,7 +23,7 @@ The following are automatically set and can be overridden:
By default the maximum processes that are run per agent is 1. If required you can add `WOODPECKER_MAX_WORKFLOWS` to increase your parallel processing on a per-agent basis.
```yaml
```diff
# docker-compose.yml
version: '3'
@ -36,6 +36,39 @@ services:
+ - WOODPECKER_MAX_WORKFLOWS=4
```
## Agent registration on server
When the agent starts, it connects to the server using token from `WOODPECKER_AGENT_SECRET`. The server identifies agent and, if such agent doesn't exist, register him.
There are two types of token, so would be two ways of agent registration.
### Using system token
_System token_ is a token that is used system-wide, e. g. when you set the same token in `WOODPECKER_AGENT_SECRET` on both the server and the agents.
In that case registration process would be as follows:
1. First time Agent communicates with Server using system token;
2. Server registers Agent in DB, generates ID and sends this ID back to Agent;
3. Agent stores ID in a file configured by `WOODPECKER_AGENT_ID_FILE`.
At the following startups Agent uses system token **and** ID.
### Using agent token
_Agent token_ is a token that is used by only particular agent. This unique token also configured by `WOODPECKER_AGENT_SECRET`, but only on the agent side.
In that case you probably doesn't configure `WOODPECKER_AGENT_SECRET` on the server side. The registration process would be as follows:
1. Administrator registers Agent manually in _Server settings - Agents - Add agent_;
![Agent creation](./new-agent-registration.png)
![Agent created](./new-agent-created.png)
2. The token generated in previous step have to be provided to Agent in `WOODPECKER_AGENT_SECRET`;
3. First time Agent communicates with Server using agent token;
4. Server identifies Agent by the token and fills additional information provided by Agent;
![Agent connected](./new-agent-connected.png)
At following startups Agent uses own token only.
## All agent configuration options
Here is the full list of configuration options and their default variables.

Binary file not shown.

After

Width:  |  Height:  |  Size: 5.3 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 4.4 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 25 KiB