Skip to content

Commit

Permalink
docs fixes (#747)
Browse files Browse the repository at this point in the history 
* Fix AWS/GCP doc indexes

* Format table using HTML

Try to leverage GitBook's full width table feature

* Create docs branch and display manual instructions on release
  • Loading branch information
@davidfq
davidfq committed Jul 9, 2024
1 parent 001b9de commit 2864f2b
Show file tree
Hide file tree
Showing 4 changed files with 128 additions and 8 deletions.
114 changes: 107 additions & 7 deletions docs/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -234,13 +234,113 @@ NOTE: Refrain to use Terraform versions 1.4.x that are < v1.4.3. We've seen bugs

Depending on your Cloud Host / Data Sources, you will need:

| Condition | Tool | Test Command | Roles / Permissions (Examples, YMMV) |
|-----------------------------------|-----------------------------------------------------------------------------------------------|------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| if deploying to AWS | [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) 2.2+ | `aws --version` | <ul><li>[IAMFullAccess](https://us-east-1.console.aws.amazon.com/iam/home?region=us-east-1#/policies/arn:aws:iam::aws:policy/IAMFullAccess$serviceLevelSummary)</li><li>[AmazonSSMFullAccess](https://us-east-1.console.aws.amazon.com/iam/home?region=us-east-1#/policies/arn:aws:iam::aws:policy/AmazonSSMFullAccess$serviceLevelSummary)</li><li>[AWSLambda_FullAccess](https://us-east-1.console.aws.amazon.com/iam/home?region=us-east-1#/policies/arn:aws:iam::aws:policy/AWSLambda_FullAccess$serviceLevelSummary)</li><li>[AmazonS3FullAccess](https://us-east-1.console.aws.amazon.com/iam/home?region=us-east-1#/policies/arn:aws:iam::aws:policy/AmazonS3FullAccess$serviceLevelSummary)</li><li>[CloudWatchFullAccess](https://us-east-1.console.aws.amazon.com/iam/home?region=us-east-1#/policies/arn:aws:iam::aws:policy/CloudWatchFullAccess$serviceLevelSummary)</li></ul><br/>see [aws/getting-started.md](aws/getting-started.md) |
| if deploying to GCP | [Google Cloud CLI](https://cloud.google.com/sdk/docs/install) 1.0+ | `gcloud version` | <ul><li>[Service Account Creator](https://cloud.google.com/iam/docs/understanding-roles#iam.serviceAccountCreator)</li><li>[Cloud Functions Admin](https://cloud.google.com/iam/docs/understanding-roles#cloudfunctions.admin)</li><li>[Cloud Storage Admin](https://cloud.google.com/iam/docs/understanding-roles#storage.admin)</li><li>[Secret Manager Admin](https://cloud.google.com/iam/docs/understanding-roles#secretmanager.admin)</li><li>[Service Usage Admin](https://cloud.google.com/iam/docs/understanding-roles#serviceusage.serviceUsageAdmin)</li></ul><br/>see [gcp/getting-started.md](gcp/getting-started.md) |
| if connecting to Microsoft 365 | [Azure CLI](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli) 2.29+ | `az --version` | [Cloud Application Administrator](https://learn.microsoft.com/en-us/azure/active-directory/roles/permissions-reference#cloud-application-administrator) | | |
| if connecting to Google Workspace | [Google Cloud CLI](https://cloud.google.com/sdk/docs/install) 1.0+ | `gcloud version` | <ul><li>[Service Account Creator](https://cloud.google.com/iam/docs/understanding-roles#iam.serviceAccountCreator)</li><li>[Service Account Key Admin](https://cloud.google.com/iam/docs/understanding-roles#iam.serviceAccountKeyAdmin)</li><li>[Service Usage Admin](https://cloud.google.com/iam/docs/understanding-roles#serviceusage.serviceUsageAdmin)</li></ul><br/>see [sources/google-workspace/README.md](sources/google-workspace/README.md) |

<table data-full-width="true">
<thead>
<tr>
<th>Condition</th>
<th>Tool</th>
<th>Test Command</th>
<th>Roles / Permissions (Examples, YMMV)</th>
</tr>
</thead>
<tbody>
<tr>
<td>if deploying to AWS</td>
<td>
<a href="https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html">AWS CLI</a>
2.2+
</td>
<td><code>aws --version</code></td>
<td>
<ul>
<li>
<a
href="https://us-east-1.console.aws.amazon.com/iam/home?region=us-east-1#/policies/arn:aws:iam::aws:policy/IAMFullAccess$serviceLevelSummary">IAMFullAccess</a>
</li>
<li>
<a
href="https://us-east-1.console.aws.amazon.com/iam/home?region=us-east-1#/policies/arn:aws:iam::aws:policy/AmazonSSMFullAccess$serviceLevelSummary">AmazonSSMFullAccess</a>
</li>
<li>
<a
href="https://us-east-1.console.aws.amazon.com/iam/home?region=us-east-1#/policies/arn:aws:iam::aws:policy/AWSLambda_FullAccess$serviceLevelSummary">AWSLambda_FullAccess</a>
</li>
<li>
<a
href="https://us-east-1.console.aws.amazon.com/iam/home?region=us-east-1#/policies/arn:aws:iam::aws:policy/AmazonS3FullAccess$serviceLevelSummary">AmazonS3FullAccess</a>
</li>
<li>
<a
href="https://us-east-1.console.aws.amazon.com/iam/home?region=us-east-1#/policies/arn:aws:iam::aws:policy/CloudWatchFullAccess$serviceLevelSummary">CloudWatchFullAccess</a>
</li>
</ul>
<p>see <a href="aws/getting-started.md">aws/getting-started.md</a></p>
</td>
</tr>
<tr>
<td>if deploying to GCP</td>
<td><a href="https://cloud.google.com/sdk/docs/install">Google Cloud CLI</a> 1.0+</td>
<td><code>gcloud version</code></td>
<td>
<ul>
<li>
<a href="https://cloud.google.com/iam/docs/understanding-roles#iam.serviceAccountCreator">Service Account
Creator</a>
</li>
<li>
<a href="https://cloud.google.com/iam/docs/understanding-roles#cloudfunctions.admin">Cloud Functions
Admin</a>
</li>
<li>
<a href="https://cloud.google.com/iam/docs/understanding-roles#storage.admin">Cloud Storage Admin</a>
</li>
<li>
<a href="https://cloud.google.com/iam/docs/understanding-roles#secretmanager.admin">Secret Manager Admin</a>
</li>
<li>
<a href="https://cloud.google.com/iam/docs/understanding-roles#serviceusage.serviceUsageAdmin">Service Usage
Admin</a>
</li>
</ul>
<p>see <a href="gcp/getting-started.md">gcp/getting-started.md</a></p>
</td>
</tr>
<tr>
<td>if connecting to Microsoft 365</td>
<td>
<a href="https://docs.microsoft.com/en-us/cli/azure/install-azure-cli">Azure CLI</a> 2.29+
</td>
<td><code>az --version</code></td>
<td>
<a
href="https://learn.microsoft.com/en-us/azure/active-directory/roles/permissions-reference#cloud-application-administrator">Cloud
Application Administrator</a>
</td>
</tr>
<tr>
<td>if connecting to Google Workspace</td>
<td><a href="https://cloud.google.com/sdk/docs/install">Google Cloud CLI</a> 1.0+</td>
<td><code>gcloud version</code></td>
<td>
<ul>
<li>
<a href="https://cloud.google.com/iam/docs/understanding-roles#iam.serviceAccountCreator">Service Account
Creator</a>
</li>
<li>
<a href="https://cloud.google.com/iam/docs/understanding-roles#iam.serviceAccountKeyAdmin">Service Account
Key Admin</a>
</li>
<li>
<a href="https://cloud.google.com/iam/docs/understanding-roles#serviceusage.serviceUsageAdmin">Service Usage
Admin</a>
</li>
</ul>
<p>see <a href="sources/google-workspace/">sources/google-workspace/README.md</a></p>
</td>
</tr>
</tbody>
</table>

For testing your psoxy instance, you will need:

Expand Down
1 change: 1 addition & 0 deletions docs/aws/README.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
# AWS
1 change: 0 additions & 1 deletion docs/gcp/README.md
View file

This file was deleted.

1 change: 1 addition & 0 deletions docs/gcp/README.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
# GCP
19 changes: 19 additions & 0 deletions tools/release/publish.sh
View file
Original file line number Diff line number Diff line change
Expand Up @@ -89,6 +89,25 @@ fi
printf "Opening release ${BLUE}${RELEASE}${NC} in browser; review / update notes and then publish as latest ...\n"
gh release view $RELEASE --web

printf "Do you want to create a docs branch based on the release? (Y/n)\n"
read -p "(Y/n) " -n 1 -r
REPLY=${REPLY:-Y}
echo # Move to a new line
if [[ "$REPLY" =~ ^[Yy][Ee]?[Ss]?$ ]]; then
if git rev-parse --verify "docs-$RELEASE" >/dev/null 2>&1; then
printf "${RED}Branch docs-${RELEASE} already exists.${NC}\n"
else
git checkout -b "docs-$RELEASE"
git push origin "docs-$RELEASE"
git checkout main
printf "Docs branch ${GREEN}docs-$RELEASE${NC} created and pushed. View it at: ${BLUE}https://github.com/Worklytics/psoxy/tree/docs-$RELEASE${NC}\n"
printf "Manual steps to publish docs in GitBook: \n"
printf "1. Create a new space under the Psoxy collection with the same name than the release ${GREEN}X.Y.Z${NC}\n"
printf "2. Enable GitHub Sync on the new space and sync with the branch: ${GREEN}docs-$RELEASE${NC}\n"
printf "3. Share → Publish to the web → Publish in collection\n"
printf "4. Now, go back to the collection and customize: General → Default space → select ${GREEN}X.Y.Z${NC}\n"
fi
fi

printf " Then update example templates to point to it:\n"
if [ -d ~/code/psoxy-example-aws/ ]; then
Expand Down

0 comments on commit 2864f2b

Please sign in to comment.