Improve documentation of config parameters (GSI-463) (#30)

Make clear that the file ingest endpoint and the corresponding public key are coming from GHGA Central.

ghga_datasteward_kit/file_ingest.py

@@ -31,10 +31,19 @@ class IngestConfig(SubmissionStoreConfig):
     """Config options for calling the file ingest endpoint"""
 
     file_ingest_baseurl: str = Field(
-        ..., description="Base URL under which the /ingest endpoint is available."
+        ...,
+        description=(
+            "Base URL under which the /ingest endpoint is available."
+            + " This is an endpoint exposed by GHGA Central. This value is provided by"
+            + " GHGA Central on demand."
+        ),
     )
     file_ingest_pubkey: str = Field(
-        ..., description="Public key used for encryption of the payload."
+        ...,
+        description=(
+            "Public key provided by GHGA Central used to encrypt the communication with"
+            + " GHGA Central."
+        ),
     )
     input_dir: Path = Field(
         ...,

ghga_datasteward_kit/s3_upload/config.py

@@ -40,22 +40,42 @@ class LegacyConfig(BaseSettings):
     Required options for legacy file uploads.
     """
 
-    s3_endpoint_url: SecretStr = Field(..., description="URL of the S3 server")
+    s3_endpoint_url: SecretStr = Field(
+        ..., description="URL of the local data hub's S3 server."
+    )
     s3_access_key_id: SecretStr = Field(
-        ..., description="Access key ID for the S3 server"
+        ...,
+        description=(
+            "This parameter plus the s3_secret_access_key serve as credentials for"
+            + " accessing the internal staging bucket (as in"
+            + " `bucket_id`) on the local data hub's S3 server with s3:GetObject and"
+            + " s3:PutObject privileges. These credentials should"
+            + " never be shared with GHGA Central."
+        ),
     )
     s3_secret_access_key: SecretStr = Field(
-        ..., description="Secret access key for the S3 server"
+        ...,
+        description=("Secret access key corresponding to the `s3_access_key_id`."),
     )
     bucket_id: str = Field(
-        ..., description="Bucket id where the encrypted, uploaded file is stored"
+        ...,
+        description=(
+            "Bucket ID of the internal staging bucket of the local data hub's S3 system"
+            "where the encrypted files are uploaded to."
+        ),
     )
     part_size: int = Field(
         16, description="Upload part size in MiB. Has to be between 5 and 5120."
     )
     output_dir: Path = Field(
         ...,
-        description="Directory for the output metadata file",
+        description=(
+            "Directory for the output metadata files. For each file upload one metadata"
+            + " file in yaml format will be generated. It contains details on the files"
+            + " such as checksums, the original file path, the auto generated object ID"
+            + " used on the S3 system, and the ID of the secret (the secret itself is"
+            + " automatically communicated to GHGA Central) used to encrypt the file."
+        ),
     )
 
     @validator("output_dir")
@@ -72,9 +92,17 @@ class Config(LegacyConfig):
     """
 
     secret_ingest_pubkey: str = Field(
-        ..., description="Public key used for encryption of the payload."
+        ...,
+        description=(
+            "Public key provided by GHGA Central used to encrypt the communication with"
+            + " GHGA Central."
+        ),
     )
     secret_ingest_baseurl: str = Field(
         ...,
-        description="Base URL under which the /ingest_secret endpoint is available.",
+        description=(
+            "Base URL under which the /ingest_secret endpoint is available."
+            + " This is an endpoint exposed by GHGA Central. This value is provided by"
+            + " GHGA Central on demand."
+        ),
     )

ingest_config.md

@@ -9,9 +9,9 @@
 
 - **`submission_store_dir`** *(string)*: The directory where the submission JSONs will be stored.
 
-- **`file_ingest_baseurl`** *(string)*: Base URL under which the /ingest endpoint is available.
+- **`file_ingest_baseurl`** *(string)*: Base URL under which the /ingest endpoint is available. This is an endpoint exposed by GHGA Central. This value is provided by GHGA Central on demand.
 
-- **`file_ingest_pubkey`** *(string)*: Public key used for encryption of the payload.
+- **`file_ingest_pubkey`** *(string)*: Public key provided by GHGA Central used to encrypt the communication with GHGA Central.
 
 - **`input_dir`** *(string)*: Path to directory containing output files from the upload/batch_upload command.
 

s3_upload_config.md

@@ -7,18 +7,18 @@
 ## Properties
 
 
-- **`s3_endpoint_url`** *(string)*: URL of the S3 server.
+- **`s3_endpoint_url`** *(string)*: URL of the local data hub's S3 server.
 
-- **`s3_access_key_id`** *(string)*: Access key ID for the S3 server.
+- **`s3_access_key_id`** *(string)*: This parameter plus the s3_secret_access_key serve as credentials for accessing the internal staging bucket (as in `bucket_id`) on the local data hub's S3 server with s3:GetObject and s3:PutObject privileges. These credentials should never be shared with GHGA Central.
 
-- **`s3_secret_access_key`** *(string)*: Secret access key for the S3 server.
+- **`s3_secret_access_key`** *(string)*: Secret access key corresponding to the `s3_access_key_id`.
 
-- **`bucket_id`** *(string)*: Bucket id where the encrypted, uploaded file is stored.
+- **`bucket_id`** *(string)*: Bucket ID of the internal staging bucket of the local data hub's S3 systemwhere the encrypted files are uploaded to.
 
 - **`part_size`** *(integer)*: Upload part size in MiB. Has to be between 5 and 5120. Default: `16`.
 
-- **`output_dir`** *(string)*: Directory for the output metadata file.
+- **`output_dir`** *(string)*: Directory for the output metadata files. For each file upload one metadata file in yaml format will be generated. It contains details on the files such as checksums, the original file path, the auto generated object ID used on the S3 system, and the ID of the secret (the secret itself is automatically communicated to GHGA Central) used to encrypt the file.
 
-- **`secret_ingest_pubkey`** *(string)*: Public key used for encryption of the payload.
+- **`secret_ingest_pubkey`** *(string)*: Public key provided by GHGA Central used to encrypt the communication with GHGA Central.
 
-- **`secret_ingest_baseurl`** *(string)*: Base URL under which the /ingest_secret endpoint is available.
+- **`secret_ingest_baseurl`** *(string)*: Base URL under which the /ingest_secret endpoint is available. This is an endpoint exposed by GHGA Central. This value is provided by GHGA Central on demand.