From 743f9d9ffde1583deb13d68cff1a99251c6f553a Mon Sep 17 00:00:00 2001 From: Chris Durbin Date: Mon, 27 Nov 2023 13:04:08 -0500 Subject: [PATCH 1/4] HARMONY-1576: Document the cloud-access API. --- services/harmony/app/markdown/cloud-access.md | 33 +++++++++++++++++++ services/harmony/app/markdown/docs.md | 4 ++- services/harmony/app/markdown/endpoints.md | 3 +- 3 files changed, 37 insertions(+), 3 deletions(-) create mode 100644 services/harmony/app/markdown/cloud-access.md diff --git a/services/harmony/app/markdown/cloud-access.md b/services/harmony/app/markdown/cloud-access.md new file mode 100644 index 000000000..560e876f2 --- /dev/null +++ b/services/harmony/app/markdown/cloud-access.md @@ -0,0 +1,33 @@ +### Getting in region S3 AWS access keys using the cloud-access API + +Harmony supports analysis in place without rather than forcing a user to download the outputs from their requests. The results for each harmony request are stored an AWS S3 bucket in the us-west-2 region. In order to access these results natively in S3 the user can get temporary AWS access credentials using the harmony cloud-access endpoints. Note that data can only be accessed from within the us-west-2 region. + +#### Get AWS S3 access credentials as JSON + +``` + +{{root}}/cloud-access + +``` +**Example {{exampleCounter}}** - Getting AWS S3 access credentials as JSON using the `cloud-access` API + +The returned JSON response returns fields required to set the AWS S3 access credentials: + +| field | description | +|-------|---------------------------------------------------------------| +| AccessKeyId | The AWS access key ID. | +| SecretAccessKey | The AWS secret access key. | +| SessionToken | The AWS session token associated with the access keys. | +| Expiration | The date and time when the access credentials expire. | +--- +**Table {{tableCounter}}** - Harmony cloud-access response fields + +#### Get AWS S3 access credentials as a shell script to use in a terminal + +``` + +{{root}}/cloud-access.sh + +``` +**Example {{exampleCounter}}** - Getting a shell script that can be sourced to set AWS S3 credentials + diff --git a/services/harmony/app/markdown/docs.md b/services/harmony/app/markdown/docs.md index 2fb611d2f..cc1d6b330 100644 --- a/services/harmony/app/markdown/docs.md +++ b/services/harmony/app/markdown/docs.md @@ -14,4 +14,6 @@ !!!include(jobs.md)!!! -!!!include(stac.md)!!! \ No newline at end of file +!!!include(stac.md)!!! + +!!!include(cloud-access.md)!!! \ No newline at end of file diff --git a/services/harmony/app/markdown/endpoints.md b/services/harmony/app/markdown/endpoints.md index a6e4b450e..b18498f1d 100644 --- a/services/harmony/app/markdown/endpoints.md +++ b/services/harmony/app/markdown/endpoints.md @@ -6,8 +6,7 @@ All of the public endpoints for Harmony users other than the OGC Coverages and W |------------------------|-------------------------------------------------------------------------------------------| | / | The Harmony landing page | | /capabilities | [Get harmony capabilities for the provided collection](#capabilities-details) | -| /cloud-access | Generates JSON with temporary credentials for accessing processed data in S3 | -| /cloud-access.sh | Generates shell scripts that can be run to access processed data in S3 | +| /cloud-access | [Generates AWS credentials for accessing processed data in S3](#cloud-access-details) | | /docs | These documentation pages | | /docs/api | The Swagger documentation for the OGC Coverages API | | /jobs | [The jobs API for getting job status, pausing/continuing/canceling jobs](#jobs-details) | From 65067ec0087e6bf25363d905f158825542cacb2b Mon Sep 17 00:00:00 2001 From: Chris Durbin Date: Mon, 27 Nov 2023 13:55:01 -0500 Subject: [PATCH 2/4] HARMONY-1580: Document the versions API. --- services/harmony/app/markdown/docs.md | 4 ++- services/harmony/app/markdown/versions.md | 30 +++++++++++++++++++++++ 2 files changed, 33 insertions(+), 1 deletion(-) create mode 100644 services/harmony/app/markdown/versions.md diff --git a/services/harmony/app/markdown/docs.md b/services/harmony/app/markdown/docs.md index cc1d6b330..a3d24b763 100644 --- a/services/harmony/app/markdown/docs.md +++ b/services/harmony/app/markdown/docs.md @@ -16,4 +16,6 @@ !!!include(stac.md)!!! -!!!include(cloud-access.md)!!! \ No newline at end of file +!!!include(cloud-access.md)!!! + +!!!include(versions.md)!!! \ No newline at end of file diff --git a/services/harmony/app/markdown/versions.md b/services/harmony/app/markdown/versions.md new file mode 100644 index 000000000..e1cd6206e --- /dev/null +++ b/services/harmony/app/markdown/versions.md @@ -0,0 +1,30 @@ +### Getting the versions of images used in each of the Harmony backend service chains + +Using the `versions` endpoint, a user can get a list of all of the docker images and versions used in harmony backend service chains. Service providers use this endpoint to verify the versions of their services deployed to an environment. + +#### Get backend service version information + +``` + +{{root}}/versions + +``` +**Example {{exampleCounter}}** - Getting backend service versions using the `versions` API + +The returned JSON response is an array of service version information with the following fields: + +| field | description | +|-------|------------------------------------------------------------------| +| name | The name of the backend service chain as defined in services.yml. | +| images | An array of the images used in the service chain. | + +Each image has the following fields: +| field | description | +|-------|--------------------------------------------------------------------| +| image | The name of the docker image. | +| tag | The docker image tag. | +| lastUpdated | (optional) The time the image was last updated if available. | +| imageDigest | (optional) The image digest if available. | + +--- +**Table {{tableCounter}}** - Harmony versions response fields \ No newline at end of file From 0afde571a1359ba492953d75a0817661897a7a60 Mon Sep 17 00:00:00 2001 From: Chris Durbin Date: Mon, 27 Nov 2023 14:01:46 -0500 Subject: [PATCH 3/4] HARMONY-1580: Add hyperlink from the endpoints table list to the versions endpoint documentation. --- services/harmony/app/markdown/endpoints.md | 24 +++++++++++----------- 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/services/harmony/app/markdown/endpoints.md b/services/harmony/app/markdown/endpoints.md index b18498f1d..44a9f979b 100644 --- a/services/harmony/app/markdown/endpoints.md +++ b/services/harmony/app/markdown/endpoints.md @@ -2,18 +2,18 @@ All of the public endpoints for Harmony users other than the OGC Coverages and WMS APIs are listed in the following table. The Coverages and WMS APIs are described in the [Using the Service APIs section](#using-the-service-apis). -| route | description | -|------------------------|-------------------------------------------------------------------------------------------| -| / | The Harmony landing page | -| /capabilities | [Get harmony capabilities for the provided collection](#capabilities-details) | -| /cloud-access | [Generates AWS credentials for accessing processed data in S3](#cloud-access-details) | -| /docs | These documentation pages | -| /docs/api | The Swagger documentation for the OGC Coverages API | -| /jobs | [The jobs API for getting job status, pausing/continuing/canceling jobs](#jobs-details) | -| /stac | [The API for retrieving STAC catalog and catalog items for processed data](#stac-details) | -| /staging-bucket-policy | The policy generator for external (user) bucket storage | -| /versions | Returns JSON indicating what version (image tag) each deployed service is running | -| /workflow-ui | The Workflow UI for monitoring and interacting with running jobs | +| route | description | +|------------------------|-------------------------------------------------------------------------------------------------| +| / | The Harmony landing page | +| /capabilities | [Get harmony capabilities for the provided collection](#capabilities-details) | +| /cloud-access | [Generates AWS credentials for accessing processed data in S3](#cloud-access-details) | +| /docs | These documentation pages | +| /docs/api | The Swagger documentation for the OGC Coverages API | +| /jobs | [The jobs API for getting job status, pausing/continuing/canceling jobs](#jobs-details) | +| /stac | [The API for retrieving STAC catalog and catalog items for processed data](#stac-details) | +| /staging-bucket-policy | The policy generator for external (user) bucket storage | +| /versions | [Returns JSON indicating the image and tag each deployed service is running](#versions-details) | +| /workflow-ui | The Workflow UI for monitoring and interacting with running jobs | --- **Table {{tableCounter}}** - Harmony routes other than OGC Coverages and WMS From 56c3c6e005248acfcbae5ee20f0439f07b23288a Mon Sep 17 00:00:00 2001 From: Chris Durbin Date: Mon, 27 Nov 2023 15:27:10 -0500 Subject: [PATCH 4/4] HARMONY-1580: Link to services.yml in the harmony repo. --- services/harmony/app/markdown/versions.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/services/harmony/app/markdown/versions.md b/services/harmony/app/markdown/versions.md index e1cd6206e..681220a05 100644 --- a/services/harmony/app/markdown/versions.md +++ b/services/harmony/app/markdown/versions.md @@ -13,10 +13,10 @@ Using the `versions` endpoint, a user can get a list of all of the docker images The returned JSON response is an array of service version information with the following fields: -| field | description | -|-------|------------------------------------------------------------------| -| name | The name of the backend service chain as defined in services.yml. | -| images | An array of the images used in the service chain. | +| field | description | +|-------|-----------------------------------------------------------------------------------------------------------------------------------| +| name | The name of the backend service chain as defined in [services.yml](https://github.com/nasa/harmony/blob/main/config/services.yml). | +| images | An array of the images used in the service chain. | Each image has the following fields: | field | description |