Skip to content

chore: update network connectivity docs - #2289

Open
mpalav08 wants to merge 1 commit into
mainfrom
naas/surface-network-connection-issues
Open

mpalav08 wants to merge 1 commit into
mainfrom
naas/surface-network-connection-issues

Conversation

@mpalav08

@mpalav08 mpalav08 commented Sep 15, 2026

Copy link
Copy Markdown
Contributor

Proposed changes

Update network connectivity docs to include the following information:

Users can now confirm the vpce ID / peer connection ID acceptance status indicating if it has been accepted by the deployment after they apply their update to the AWS deployment.

Checklist

Before sharing this pull request, I completed the following checklist:

Footnotes

  1. Potentially sensitive information includes personally identify information (PII), authentication credentials, and live URLs. Refer to the style guide for guidance about placeholder content.

@mpalav08
mpalav08 requested a review from a team as a code owner September 15, 2026 23:16
@github-actions github-actions Bot added the documentation Improvements or additions to documentation label Sep 15, 2026
@github-actions

Copy link
Copy Markdown

Deploy Preview will be available once build job completes!

Name Link
😎 Deploy Preview https://frontdoor-test-docs.nginx.com/previews/docs/2289/

@promptless promptless Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for surfacing the acceptance status, @mpalav08 — this is a genuinely useful confirmation step for anyone waiting to see whether their connection went through. I ran the F5 Technical Writing Style Guide check that the gardening rotation expects before a writer picks this up. One style point applies to both new confirmation bullets, and I have a couple of technical-accuracy questions for a subject matter expert to confirm before merge.

Style

Both new sub-bullets read ... should be in an accepted state, indicating that the deployment accepted the connection. Two things there:

  • should is ambiguous — a reader can't tell if it's expected behavior or a recommendation (may-can-might). State the result directly in present tense (hedging, tense).
  • Written as one sentence it runs past the 20-word task limit and uses the -ing form indicating (sentence-length, gerunds). Splitting into two short sentences fixes both.

I've left an inline suggestion on each line with wording that keeps your meaning. Please confirm the exact on-screen label with an SME (see below) before accepting — I don't want the suggested wording to lock in a state name I can't verify.

Technical accuracy (for an SME to verify — I have not changed any of this)

  1. Immediacy after Save. Both bullets imply the ID reaches the accepted state right after Save Changes. If acceptance is asynchronous (the console may take a moment, or the user may need to refresh), the step should say so.
  2. Exact status label. Please confirm the console shows the wording "accepted" (versus, for example, "Accepted" or "Available") so the prose matches the UI.
  3. Menu path for the read-only view. The new peering bullet points readers to Cloud Settings > Upstream Network, while the Edit step just above uses Cloud Details > Upstream Network. This matches the private-endpoint pattern earlier in the page (Cloud Settings for the read-only Details view, Cloud Details inside Edit), so it's likely correct — just worth an SME confirming the read-only path is Cloud Settings.

Reading level

The surrounding steps are clean and imperative. The only complexity the change adds is the single long, hedged sentence flagged above; splitting it brings both bullets back in line with the rest of the procedure.

1. Ensure your deployment's **PrivateLink Connection Allow List** includes the AWS account ID or VPC endpoint ID to accept the PrivateLink connection.
- To add an entry to the allow list, go to your deployment's Details tab, select **Edit**, and add the VPC endpoint ID or AWS account ID to the allow list.
1. Select **Save Changes** to allow NGINXaaS to accept the PrivateLink connection request.
- The corresponding VPC endpoint ID under **Cloud Settings** > **Service Frontend** > **PrivateLink Connection Allow List** should be in an accepted state, indicating that the deployment accepted the connection.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should is ambiguous here, and stating a verification result as one long -ing sentence trips sentence-length, hedging, and gerunds. Suggested direct, present-tense wording (please confirm the exact status label with an SME before accepting):

Suggested change
- The corresponding VPC endpoint ID under **Cloud Settings** > **Service Frontend** > **PrivateLink Connection Allow List** should be in an accepted state, indicating that the deployment accepted the connection.
- The VPC endpoint ID under **Cloud Settings** > **Service Frontend** > **PrivateLink Connection Allow List** changes to an accepted state. This confirms the deployment accepted the connection.

Style topics: may-can-might, hedging, tense, gerunds, sentence-length.

1. Note the resulting **VPC Peering Connection ID**, for example `pcx-0123456789abcdef0`, shown in the AWS VPC console **Peering Connections** list.
1. On your deployment's Details tab, select **Edit**, go to **Cloud Details** > **Upstream Network**, select **+ Add Entry**, and add the VPC Peering Connection ID.
1. Select **Save Changes** to allow NGINXaaS to accept the peering connection request.
- The corresponding VPC peering connection ID under **Cloud Settings** > **Upstream Network** should be in an accepted state, indicating that the deployment accepted the connection.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same finding as the PrivateLink bullet: replace should be ... indicating with a direct present-tense statement. Suggested wording (confirm the exact status label with an SME first):

Suggested change
- The corresponding VPC peering connection ID under **Cloud Settings** > **Upstream Network** should be in an accepted state, indicating that the deployment accepted the connection.
- The VPC peering connection ID under **Cloud Settings** > **Upstream Network** changes to an accepted state. This confirms the deployment accepted the connection.

Style topics: may-can-might, hedging, tense, gerunds, sentence-length.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant