Repository Service for TUF Worker
repository-service-tuf-worker is part of Repository Service for TUF (RSTUF)
These instructions will cover usage information and for the docker container.
In order to run this container you'll need docker installed.
Other requirements include:
- repository-service-tuf-api service
- Compatible broker and result backend service with Celery. Recomended: RabbitMQ or Redis
- PostgreSQL server
- Online key (see Online Key details below)
The RSTUF Worker requires an online key which is used for signing the TUF metadata when a target is added or removed.
Here are some things you need to know:
- The key must be compatible with Secure Systems Library. If you do not have a key we suggest you use the RSTUF CLI tool to generate the key.
- This key must be the same one used during the RSTUF CLI ceremony.
For more information read the Deployment documentation.
docker run --env="RSTUF_STORAGE_BACKEND=LocalStorage" \
--env="RSTUF_LOCAL_STORAGE_BACKEND_PATH=/metadata" \
--env="RSTUF_BROKER_SERVER=guest:guest@rabbitmq:5672" \
--env="RSTUF_REDIS_SERVER=redis://redis" \
--env="RSTUF_SQL_SERVER=postgresql://postgres:secret@postgres:5432" \
ghcr.io/repository-service-tuf/repository-service-tuf-worker:latest \
Broker server address.
The broker must to be compatible with Celery. See Celery Broker Instructions
Example: guest:guest@rabbitmq:5672
Redis server address.
The result backend must to be compatible with Celery. See Celery Task result backend settings
Example: redis://redis
RSTUF requires PostgreSQL.
Example: postgres:secret@postgres:5432
-
Optional variables:
-
RSTUF_SQL_USER
optional information about the user nameIf using this optional variable:
- Do not include the user in the
RSTUF_SQL_SERVER
. - The
RSTUF_SQL_PASSWORD
becomes required
- Do not include the user in the
-
RSTUF_SQL_PASSWORD
use this variable to provide the password separately.- Do not include the password in the
RSTUF_SQL_SERVER
- This environment variable supports container secrets when the
/run/secrets
volume is added to the path.
- Do not include the password in the
Example:
RSTUF_SQL_SERVER=sqlserver:5432 RSTUF_SQL_USER=postgres RSTUF_SQL_PASSWORD=/run/secrets/POSTGRES_PASSWORD
-
Redis Server port number. Default: 6379
Redis Server DB number for Result Backend (tasks). Default: 0
Important: It should use the same db id as used by RSTUF API.
Redis Server DB number for repository settings. Default: 1
This settings are shared accress the Repository Workers
(repository-service-tuf-worker
) to have dynamic configuration.
Select a supported type of Storage Service.
Available types:
LocalStorage
(container volume)AWSS3
(AWS S3)
-
(Required)
RSTUF_LOCAL_STORAGE_BACKEND_PATH
- Define the directory where the data will be saved, example:
storage
- Define the directory where the data will be saved, example:
-
(Required)
RSTUF_AWS_STORAGE_BUCKET
The name of s3 bucket to use.
-
(Required)
RSTUF_AWS_ACCESS_KEY_ID
The access key to use when creating the client session to the S3.
This environment variable supports container secrets when the
/run/secrets
volume is added to the path. Example:RSTUF_AWS_ACCESS_KEY_ID=/run/secrets/S3_ACCESS_KEY
-
(Required)
RSTUF_AWS_SECRET_ACCESS_KEY
The secret key to use when creating the client session to the S3.
This environment variable supports container secrets when the
/run/secrets
volume is added to the path. Example:RSTUF_AWS_SECRET_ACCESS_KEY=/run/secrets/S3_SECRET_KEY
-
(Optional)
RSTUF_AWS_DEFAULT_REGION
The name of the region associated with the S3.
-
(Optional)
RSTUF_AWS_ENDPOINT_URL
The complete URL to use for the constructed client. Normally, the client automatically constructs the appropriate URL to use when communicating with a service.
NOTE: The AWS3 supports all boto3
environment variables.
Timeout for publishing JSON metadata files. Default: 60.0 (seconds)
This timeout avoids race conditions leading to publishing JSON metadata files by multiple
Worker's services. It guarantees that the metadata is consistent in the backend
storage service (RSTUF_STORAGE_BACKEND
).
In most use cases, the timeout of 60.0 seconds is sufficient.
Select a supported type of Key Vault Service.
LocalKeyVault
(container volume)
NOTE: You can start the worker service without a keyvault backend, but you need to configure one before the bootstrap ceremony.
-
(Required)
RSTUF_LOCAL_KEYVAULT_PATH
Define the path for the container volume mounted Example:
RSTUF_LOCAL_KEYVAULT_PATH=/var/opt/repository-service-tuf/key_storage
-
(Required)
RSTUF_LOCAL_KEYVAULT_KEYS
Define the key(s) with format
<file>,<password>,<(optional) type>
-
file
: defines the key file-
base64|<key content in base64>
allows to inform directly the key content. It will dynamically manage and write a key file inRSTUF_LOCAL_KEYVAULT_PATH
(write permissions required).Requires content as base64.
Example:
RSTUF_LOCAL_KEYVAULT_KEYS=base64|LnRveC8KdmVudi8KLmlkZWEvCi52c2NvZGUvC...,strongPass,rsa
-
-
password
: credential used to load the key -
(optional)
type
: The key type. Default:ed25519
[Note: At the moment RSTUF Worker supports
ed25519
,rsa
,ecdsa
]Example:
RSTUF_LOCAL_KEYVAULT_KEYS=online.key,strongPass,rsa
Accepts multiple keys separated by "
:
".It accepts multiple keys, but RSTUF supports the usage of only one online key for signing.
The Local Key Vault will find the key that matches the online key defined in the root metadata.
Allowing multiple keys is helpful for performing metadata/key rotation without disruption.
Example:
RSTUF_LOCAL_KEYVAULT_KEYS=online.key,strongPass:online-rsa.key,newStrongPass,rsa
This environment variable supports container secrets when the
/run/secrets
volume is added to the path. The content must be in the standard format<file>,<password>,<(optional) type>
Example:
RSTUF_LOCAL_KEYVAULT_KEYS=/run/secrets/ONLINE_KEY_1:/run/secrets/ONLINE_KEY_2
-
Directory path for online signing key file. Expected file format is unencrypted PKCS8/PEM.
Make sure to use the secrets management service of your deployment platform to protect the private key!
Replaces RSTUF_KEYVAULT_BACKEND
and related settings.
Example:
RSTUF_ONLINE_KEY_DIR=/run/secrets
- RSTUF worker expects related private key under
/run/secrets/<file name>
Custom Worker ID. Default: hostname
(Container hostname)
Container data directory. Default: /data
$DATA_DIR
. Default:/data
The repository-service-tuf-worker
uses supervisord and uses a
supervisor.conf
from $DATA_DIR
.
It can be used to customize/tuning performance of Celery.