Tweak the updated deployment docs #2603

jhkennedy · 2025-02-15T01:33:06Z

I've:

mostly just restructured the deployment section into 3 parts and used collapsing details for the security-environment-specific sections (I'd love to use tabs, but GitHub doesn't support that)
I added alerts to show what parts require an ASF employee to be in the loop

Since I'm making use of GitHub's markdown, I recommend reviewing the README as rendered in GitHub:
https://github.com/ASFHyP3/hyp3/blob/jhk-deploy-docs/README.md

jhkennedy · 2025-02-17T19:24:28Z

README.md

+> [!WARNING]
+> This step must be done by an ASF employee.


I called out what steps require ASF to be in the loop, but maybe we don't need to with the top-level warning?

https://github.com/ASFHyP3/hyp3/pull/2603/files#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5R30-R34

I think it's fine to call out these steps, but I want to clearly distinguish steps that would require ASF even if someone forks HyP3 and deploys to their own AWS account, because I feel like the expectation with an open-source project is that anyone should be able to fork and build/deploy it. If that's not the case, we should call that out. (Also see my question on the top-level warning.)

jtherrmann · 2025-02-20T16:02:01Z

README.md

+> It's not currently possible to deploy HyP3 fully independent of ASF due to our integration with 
+> [ASF Vertex](https://search.alaska.edu). If you'd like your own deployment of HyP3, please open an issue here or


It's not currently possible to deploy HyP3 fully independent of ASF due to our integration with ASF Vertex

Is this just referring to our use of the asf-urs cookie?

jtherrmann · 2025-02-20T16:07:11Z

README.md

+> [!WARNING]
+> This stack should only be deployed once per AWS account. This stack also
+> assumes you are only deploying into a single AWS Region. If you are deploying into
+> multiple regions in the same AWS account, you'll need to adjust the IAM permissions
+> that are limited to a single region.


This [!WARNING] block isn't rendering correctly for me.

Oh, I think that none of the admonitions within the collapsible sections are rendering correctly.

jtherrmann · 2025-02-20T16:10:25Z

README.md

-Then update all of the fields (`environment`, `domain`, `template_bucket`, etc.) as appropriate for your deployment.
-Also make sure to update the top-level `name` of the workflow and the name of the branch to deploy from.
-(This is typically `main` for prod deployments, `develop` for test deployments, or a feature branch name for sandbox deployments.)
+> ![TIP]


Suggested change

> ![TIP]

> [!TIP]

Alex-Lewandowski

I really appreciate this update to the deployment docs. The instructions are easy to understand and follow. The drop-down sections improve navigation. I added a few comments, mostly minor. There are a couple of broken links.

Alex-Lewandowski · 2025-02-21T22:45:06Z

README.md


-*Security environment(s): ASF*
+<details>
+<summary>ASF: Create a CloudFormation templates bucket</summary>


The list of steps below could be ordered. Change "navigating" to "Navigate."

Alex-Lewandowski · 2025-02-21T22:49:31Z

README.md

+a service user's credentials or by assuming a deployment with a service user.
+
+<details>
+<summary>ASF: Create a service user and deployment role</summary>


Line 108: "Set the account-wide..." -> "Account-wide..."

Alex-Lewandowski · 2025-02-21T22:56:15Z

README.md


-*Security environment(s): JPL*
+##### Roles-as-code for JPL accounts


Add a note indicating that the following jpl.nasa.gov links are only reachable if you have been given access.

Or not, idk. There are multiple links in this doc that require permission to access. We could add a disclaimer at the top, or maybe it's not necessary.

Alex-Lewandowski · 2025-02-21T22:58:37Z

README.md


 In order to integrate a JPL deployment into our CI/CD pipelines, a JPL-created "service user"
 is needed to get long-term (90-day) AWS access keys. When requesting a service user, you'll
 need to request an appropriate deployment policy containing all the necessary permissions for
 deployment is attached to the user. An appropriate deployment policy can be created in a
-JPL account by deploying the `hyp3-ci` stack. From the repository root, run:
+JPL account by deploying the [JPL CI stack](cicd-stacks/JPL-deployment-ci-cf.yml). 


Broken link

Alex-Lewandowski · 2025-02-21T23:05:49Z

README.md

@@ -150,9 +189,13 @@ the `hyp3-ci` CloudFormation Stack Resources.
 Once the JPL service user has been created, you should receive a set of AWS Access Keys
 which can be used to deploy HyP3 via CI/CD tooling.

-### Create Earthdata Login user
+> [!IMPORTANT]
+> These keys will be stored in the associated JPL-managed AWS account an AWS SecretsManager secret


Missing an "in": "associated JPL-managed AWS account an AWS SecretsManager" -> "associated JPL-managed AWS account in an AWS SecretsManager"

Alex-Lewandowski · 2025-02-22T00:00:22Z

README.md

-### Create Earthdata Login user
+> [!IMPORTANT]
+> These keys will be stored in the associated JPL-managed AWS account an AWS SecretsManager secret
+> with the same name as the service user. They automatically rotated by JPL every 90 days and so


Suggested change

> with the same name as the service user. They automatically rotated by JPL every 90 days and so

> with the same name as the service user. JPL automatically rotates them every 90 days and so

Alex-Lewandowski · 2025-02-22T00:01:13Z

README.md

@@ -164,9 +207,7 @@ you will need to create an Earthdata Login user for your deployment if you do no
 5. Log into Vertex as the new user, and confirm you can download files, e.g. https://datapool.asf.alaska.edu/METADATA_SLC/SA/S1A_IW_SLC__1SDV_20230130T184017_20230130T184044_047017_05A3C3_381F.iso.xml


Suggested change

5. Log into Vertex as the new user, and confirm you can download files, e.g. https://datapool.asf.alaska.edu/METADATA_SLC/SA/S1A_IW_SLC__1SDV_20230130T184017_20230130T184044_047017_05A3C3_381F.iso.xml

5. Log into Vertex as a new user and confirm you can download files, e.g. https://datapool.asf.alaska.edu/METADATA_SLC/SA/S1A_IW_SLC__1SDV_20230130T184017_20230130T184044_047017_05A3C3_381F.iso.xml

Alex-Lewandowski · 2025-02-22T00:05:03Z

README.md

+#### Optional
+
+<details>
+<summary>##### JPL: Allow a public HyP3 content bucket for JPL accounts</summary>


Suggested change

<summary>##### JPL: Allow a public HyP3 content bucket for JPL accounts</summary>

<summary>JPL: Allow a public HyP3 content bucket for JPL accounts</summary>

Alex-Lewandowski · 2025-02-22T00:05:37Z

README.md


-*Security environment(s): ASF, EDC*
+<details>
+<summary>##### All: Grant AWS account permission to pull the hyp3-gamma container</summary>


Suggested change

<summary>##### All: Grant AWS account permission to pull the hyp3-gamma container</summary>

<summary>All: Grant AWS account permission to pull the hyp3-gamma container</summary>

Alex-Lewandowski · 2025-02-22T00:08:13Z

README.md

+- JPL-public 
+
+> [!IMPORTANT]
+> JPL deployments _must_ start with the JPL security environment, but can be migrated to the `JPL-public` one


Suggested change

> JPL deployments _must_ start with the JPL security environment, but can be migrated to the `JPL-public` one

> JPL deployments _must_ start with the JPL security environment, but can be migrated to `JPL-public`

Add alerts/admotions and collapsing sections

6167df7

jhkennedy requested a review from jtherrmann February 15, 2025 01:33

fixes

919cf64

jhkennedy marked this pull request as ready for review February 15, 2025 01:45

jhkennedy requested review from a team as code owners February 15, 2025 01:45

jhkennedy added 3 commits February 16, 2025 12:03

tweak wording

26e51ae

encourage branch protection

8e18b15

fix alerts

6a38572

jhkennedy commented Feb 17, 2025

View reviewed changes

jtherrmann reviewed Feb 20, 2025

View reviewed changes

jtherrmann added 2 commits February 20, 2025 07:30

Merge branch 'deployment-docs' into jhk-deploy-docs

6378738

Merge branch 'deployment-docs' into jhk-deploy-docs

ff7bc0a

jtherrmann marked this pull request as draft February 21, 2025 20:50

Merge branch 'deployment-docs' into jhk-deploy-docs

307d6f0

Alex-Lewandowski approved these changes Feb 24, 2025

View reviewed changes

jtherrmann mentioned this pull request Feb 27, 2025

Update deployment docs #2579

Draft

6 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Tweak the updated deployment docs #2603

Tweak the updated deployment docs #2603

jhkennedy commented Feb 15, 2025 •

edited

Loading

jhkennedy Feb 17, 2025

jtherrmann Feb 20, 2025

jtherrmann Feb 20, 2025

jtherrmann Feb 20, 2025

jtherrmann Feb 20, 2025

jtherrmann Feb 20, 2025

Alex-Lewandowski left a comment

Alex-Lewandowski Feb 21, 2025

Alex-Lewandowski Feb 21, 2025

Alex-Lewandowski Feb 21, 2025

Alex-Lewandowski Feb 22, 2025

Alex-Lewandowski Feb 21, 2025

Alex-Lewandowski Feb 21, 2025

Alex-Lewandowski Feb 22, 2025

Alex-Lewandowski Feb 22, 2025

Alex-Lewandowski Feb 22, 2025

Alex-Lewandowski Feb 22, 2025

Alex-Lewandowski Feb 22, 2025

		> It's not currently possible to deploy HyP3 fully independent of ASF due to our integration with
		> [ASF Vertex](https://search.alaska.edu). If you'd like your own deployment of HyP3, please open an issue here or


		Security environment(s): JPL
		##### Roles-as-code for JPL accounts

	> with the same name as the service user. They automatically rotated by JPL every 90 days and so
	> with the same name as the service user. JPL automatically rotates them every 90 days and so

		@@ -164,9 +207,7 @@ you will need to create an Earthdata Login user for your deployment if you do no
		5. Log into Vertex as the new user, and confirm you can download files, e.g. https://datapool.asf.alaska.edu/METADATA_SLC/SA/S1A_IW_SLC__1SDV_20230130T184017_20230130T184044_047017_05A3C3_381F.iso.xml

	5. Log into Vertex as the new user, and confirm you can download files, e.g. https://datapool.asf.alaska.edu/METADATA_SLC/SA/S1A_IW_SLC__1SDV_20230130T184017_20230130T184044_047017_05A3C3_381F.iso.xml
	5. Log into Vertex as a new user and confirm you can download files, e.g. https://datapool.asf.alaska.edu/METADATA_SLC/SA/S1A_IW_SLC__1SDV_20230130T184017_20230130T184044_047017_05A3C3_381F.iso.xml

	<summary>##### JPL: Allow a public HyP3 content bucket for JPL accounts</summary>
	<summary>JPL: Allow a public HyP3 content bucket for JPL accounts</summary>

	<summary>##### All: Grant AWS account permission to pull the hyp3-gamma container</summary>
	<summary>All: Grant AWS account permission to pull the hyp3-gamma container</summary>

	> JPL deployments _must_ start with the JPL security environment, but can be migrated to the `JPL-public` one
	> JPL deployments _must_ start with the JPL security environment, but can be migrated to `JPL-public`

Tweak the updated deployment docs #2603

Are you sure you want to change the base?

Tweak the updated deployment docs #2603

Conversation

jhkennedy commented Feb 15, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Alex-Lewandowski left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jhkennedy commented Feb 15, 2025 •

edited

Loading