Skip to content

Conversation

@mk-armah
Copy link
Member

@mk-armah mk-armah commented Oct 29, 2025

User description

Description

This documentation is inspired by aws's documentation(s) and the underlying structure of the integration.

Added docs pages

Please also include the path for the added docs

  • Resource and Property Reference (/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws-v3/resource-and-property-reference)
  • Blueprint (/platform-overview/port-components/blueprint)
  • ...
  • ...

PR Type

Documentation, Enhancement


Description

  • Restructured AWS v3 documentation from flat examples to organized resource reference

  • Added comprehensive SQS Queue resource documentation with blueprint and properties

  • Reorganized existing resources (S3, EC2, ECS, Organizations) into service-based structure

  • Updated property tables with standardized "Availability" column (Default/Optional)

  • Added support for SQS queues in Overview.md supported resources list


Diagram Walkthrough

flowchart LR
  A["Flat Examples Structure"] -->|Reorganize| B["Service-Based Resource Reference"]
  B --> C["Amazon SQS"]
  B --> D["Amazon S3"]
  B --> E["Amazon EC2"]
  B --> F["Amazon ECS"]
  B --> G["AWS Organizations"]
  C -->|Add| H["SQS Queue Documentation"]
  D -->|Migrate| I["S3 Bucket Reference"]
  E -->|Migrate| J["EC2 Instance Reference"]
  F -->|Migrate| K["ECS Cluster Reference"]
  G -->|Migrate| L["Organizations Account Reference"]
Loading

File Walkthrough

Relevant files
Documentation
29 files
Overview.md
Add SQS Queues to supported resources                                       
+1/-0     
examples.md
Remove old flat examples structure                                             
+0/-112 
aws_v3_examples.mdc
Remove documentation generation rules file                             
+0/-282 
_category_.json
Remove examples category configuration                                     
+0/-4     
_account_info_blueprint.mdx
Remove old account info blueprint file                                     
+0/-21   
_account_info_port_app_config.mdx
Remove old account info config file                                           
+0/-17   
_organizations_accounts_properties.mdx
Remove old organizations properties file                                 
+0/-16   
_s3_bucket_properties.mdx
Remove old S3 properties file                                                       
+0/-15   
_category_.json
Create resource reference category configuration                 
+4/-0     
resource-and-property-reference.md
Create main resource reference landing page                           
+15/-0   
amazon-simple-queue-service.md
Add SQS service documentation with actions table                 
+37/-0   
_category_.json
Create SQS service category configuration                               
_sqs_queue_blueprint.mdx
Add SQS Queue blueprint with five properties                         
+56/-0   
_sqs_queue_port_app_config.mdx
Add SQS Queue mapping configuration                                           
+31/-0   
_sqs_queue_properties.mdx
Add SQS Queue properties reference table                                 
+37/-0   
_category_.json
Create S3 service category configuration                                 
+4/-0     
amazon-simple-storage-service.md
Create S3 service documentation with actions                         
+37/-0   
_s3_bucket_properties.mdx
Migrate S3 properties with updated table format                   
+15/-0   
_category_.json
Create EC2 service category configuration                               
+4/-0     
amazon-elastic-compute-cloud.md
Create EC2 service documentation with actions                       
+33/-0   
_ec2_instance_properties.mdx
Update EC2 properties table with Availability column         
+55/-55 
_category_.json
Create ECS service category configuration                               
+4/-0     
amazon-elastic-container-service.md
Create ECS service documentation with actions                       
+32/-0   
_ecs_cluster_properties.mdx
Update ECS properties table with Availability column         
+22/-18 
_category_.json
Create AWS Organizations category configuration                   
+4/-0     
aws-organizations.md
Create Organizations service documentation                             
+33/-0   
_organizations_accounts_blueprint.mdx
Add unlisted frontmatter to Organizations blueprint           
+4/-0     
_organizations_accounts_port_app_config.mdx
Add unlisted frontmatter to Organizations config                 
+4/-0     
_organizations_accounts_properties.mdx
Create Organizations properties with Availability column 
+20/-0   
Miscellaneous
1 files
guide-metadata.json
Update guide metadata isNew flag                                                 
+1/-1     
Additional files
6 files
_ec2_instance_blueprint.mdx [link]   
_ec2_instance_port_app_config.mdx [link]   
_ecs_cluster_blueprint.mdx [link]   
_ecs_cluster_port_app_config.mdx [link]   
_s3_bucket_blueprint.mdx [link]   
_s3_bucket_port_app_config.mdx [link]   

shariff-6 and others added 10 commits October 9, 2025 16:10
- Add comprehensive SQS queue example for AWS v3 integration
- Include blueprint definition with 5 key properties (queueName, queueUrl, queueArn, fifoQueue, visibilityTimeout)
- Add complete mapping configuration with all 24 SQS queue properties
- Add detailed properties table with action requirements (Default vs GetQueueTagsAction)
- Update examples.md with SQS queue section and imports
- Update Overview.md to include SQS queues in supported resources list
@qodo-merge-pro qodo-merge-pro bot changed the title Aws V3 Documentation Aws V3 Documentation Oct 29, 2025
@qodo-merge-pro
Copy link

qodo-merge-pro bot commented Oct 29, 2025

PR Compliance Guide 🔍

Below is a summary of compliance checks for this PR:

Security Compliance
🟢
No security concerns identified No security vulnerabilities detected by AI analysis. Human verification advised for critical code.
Ticket Compliance
🎫 No ticket provided
  • Create ticket/issue
Codebase Duplication Compliance
Codebase context is not defined

Follow the guide to enable codebase context checks.

Custom Compliance
🟢
Generic: Meaningful Naming and Self-Documenting Code

Objective: Ensure all identifiers clearly express their purpose and intent, making code
self-documenting

Status: Passed

Generic: Secure Error Handling

Objective: To prevent the leakage of sensitive system information through error messages while
providing sufficient detail for internal debugging.

Status: Passed

Generic: Secure Logging Practices

Objective: To ensure logs are useful for debugging and auditing without exposing sensitive
information like PII, PHI, or cardholder data.

Status: Passed

Generic: Comprehensive Audit Trails

Objective: To create a detailed and reliable record of critical system actions for security analysis
and compliance.

Status:
No runtime code: The PR adds documentation and metadata only, with no executable code paths where critical
actions could be logged, so audit trail compliance cannot be assessed from this diff.

Referred Code
- `SQS Queues`: Queue information including attributes, policies, and configuration details.
Generic: Robust Error Handling and Edge Case Management

Objective: Ensure comprehensive error handling that provides meaningful context and graceful
degradation

Status:
Config only: Only documentation and configuration snippets were added without executable logic, so
error handling and edge case management cannot be evaluated from this diff.

Referred Code
resources:
  - kind: AWS::SQS::Queue
    selector:
      query: 'true'
    port:
      entity:
        mappings:
          identifier: .QueueUrl
          title: .QueueName
          blueprint: sqsQueue
          properties:
            queueName: .QueueName
            queueUrl: .QueueUrl
            queueArn: .QueueArn
            fifoQueue: .FifoQueue
            visibilityTimeout: .VisibilityTimeout
          relations:
            awsAccount: .awsAccount

</details></details></td></tr>
<tr><td><details>
<summary><strong>Generic: Security-First Input Validation and Data Handling</strong></summary><br>

**Objective:** Ensure all data inputs are validated, sanitized, and handled securely to prevent <br>vulnerabilities<br>

**Status:** <br><a href='https://github.com/port-labs/port-docs/pull/2960/files#diff-cdae5b29379a8b63d3ecb8d94a5012ac3ab5848d6f15401ddb3e9f4c308ef473R8-R51'><strong>Docs config only</strong></a>: The changes are documentation and example configuration without input-handling code paths, <br>so validation, authz, and secure data handling cannot be determined from this diff.<br>
<details open><summary>Referred Code</summary>

```txt
```json showLineNumbers
{
  "identifier": "sqsQueue",
  "title": "SQS Queue",
  "icon": "AWS",
  "description": "This blueprint represents an AWS SQS queue in our software catalog",
  "schema": {
    "properties": {
      "queueName": {
        "type": "string",
        "title": "Queue Name"
      },
      "queueUrl": {
        "type": "string",
        "title": "Queue URL",
        "format": "url"
      },
      "queueArn": {
        "type": "string",
        "title": "Queue ARN"
      },


 ... (clipped 23 lines)
  • Update
Compliance status legend 🟢 - Fully Compliant
🟡 - Partial Compliant
🔴 - Not Compliant
⚪ - Requires Further Human Verification
🏷️ - Compliance label

@aws-amplify-eu-west-1
Copy link

This pull request is automatically being deployed by Amplify Hosting (learn more).

Access this pull request here: https://pr-2960.d2ngvl90zqbob8.amplifyapp.com

@sivanel97
Copy link
Contributor

/review

@qodo-merge-pro
Copy link

qodo-merge-pro bot commented Nov 2, 2025

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 3 🔵🔵🔵⚪⚪
🧪 No relevant tests
🔒 No security concerns identified
⚡ Recommended focus areas for review

Admonition Syntax

Mixed use of ::: and :::: admonitions may break rendering. Standardize to a single Docusaurus-style admonition syntax across the doc.

::::info Property naming conventions
The AWS Hosted by Port integration returns all resource properties in **PascalCase** (for example: `Arn`, `BucketName`, `CreationDate`). When writing mappings and JQ expressions, reference properties using PascalCasing as shown in the examples below.
::::
Admonition Inconsistency

Uses ::::info which likely won’t render. Align with other pages using :::info and ensure closing fences match.

::::info All properties available by default
EKS clusters expose their key properties via the default DescribeCluster action.
::::
Mapping Consistency

Property and relation casing deviates from PascalCase convention stated in Overview. Validate that fields like QueueUrl/QueueName and relation awsAccount match the actual integration payload (.__ExtraContext.AccountId vs .awsAccount).

          identifier: .QueueUrl
          title: .QueueName
          blueprint: sqsQueue
          properties:
            queueName: .QueueName
            queueUrl: .QueueUrl
            queueArn: .QueueArn
            fifoQueue: .FifoQueue
            visibilityTimeout: .VisibilityTimeout
          relations:
            awsAccount: .awsAccount

</details>

</td></tr>
</table>

@port-labs port-labs deleted a comment from qodo-merge-pro bot Nov 2, 2025
@hadar-co
Copy link
Contributor

hadar-co commented Nov 2, 2025

/improve

@qodo-merge-pro
Copy link

qodo-merge-pro bot commented Nov 2, 2025

PR Code Suggestions ✨

Latest suggestions up to dfd275d

CategorySuggestion                                                                                                                                    Impact
Possible bug
Standardize mapping structure and relations

Standardize the SQS mapping configuration to align with other resource examples.
This includes prefixing JQ paths with .Properties, quoting the blueprint value,
and using the standard account relation with the correct path.

docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws-v3/resource-and-property-reference/amazon-simple-queue-service/aws-sqs-queue/_sqs_queue_port_app_config.mdx [5-22]

 resources:
   - kind: AWS::SQS::Queue
     selector:
       query: 'true'
     port:
       entity:
         mappings:
-          identifier: .QueueUrl
-          title: .QueueName
-          blueprint: sqsQueue
+          identifier: .Properties.QueueUrl
+          title: .Properties.QueueName
+          blueprint: '"sqsQueue"'
           properties:
-            queueName: .QueueName
-            queueUrl: .QueueUrl
-            queueArn: .QueueArn
-            fifoQueue: .FifoQueue
-            visibilityTimeout: .VisibilityTimeout
+            queueName: .Properties.QueueName
+            queueUrl: .Properties.QueueUrl
+            queueArn: .Properties.QueueArn
+            fifoQueue: .Properties.FifoQueue
+            visibilityTimeout: .Properties.VisibilityTimeout
           relations:
-            awsAccount: .awsAccount
+            account: .__ExtraContext.AccountId
  • Apply / Chat
Suggestion importance[1-10]: 8

__

Why: The suggestion correctly identifies that the SQS mapping example is inconsistent with other examples in the PR, which could confuse users. It proposes aligning the JQ paths to use .Properties, quoting the blueprint value, and standardizing the relations block, which significantly improves the correctness and consistency of the documentation.

Medium
Organization
best practice
Fix heading capitalization

Convert the heading to sentence case, capitalizing only the first word and
proper nouns.

docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws-v3/resource-and-property-reference/resource-and-property-reference.md [5]

-## Supported Resource Types
+## Supported resource types
  • Apply / Chat
Suggestion importance[1-10]: 5

__

Why:
Relevant best practice - Pattern 2: Use sentence case for headers.

Low
Possible issue
Fix admonition syntax and casing

Correct the admonition syntax from :::: to the standard ::: for proper
rendering. Also, fix a typo by changing "PascalCasing" to "PascalCase" for
consistency.

docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws-v3/Overview.md [45-47]

-::::info Property naming conventions
-The AWS Hosted by Port integration returns all resource properties in **PascalCase** (for example: `Arn`, `BucketName`, `CreationDate`). When writing mappings and JQ expressions, reference properties using PascalCasing as shown in the examples below.
-::::
+:::info Property naming conventions
+The AWS Hosted by Port integration returns all resource properties in **PascalCase** (for example: `Arn`, `BucketName`, `CreationDate`). When writing mappings and JQ expressions, reference properties using PascalCase as shown in the examples below.
+:::

[Suggestion processed]

Suggestion importance[1-10]: 4

__

Why: The suggestion correctly identifies a non-standard admonition syntax (::::) which may not render correctly, and also fixes a minor typo ("PascalCasing" to "PascalCase"), improving documentation quality and consistency.

Low
Maintainability
Standardize admonition and formatting

Standardize the admonition syntax from :::: to ::: for correct rendering.
Additionally, format the DescribeCluster action name as code for improved
clarity and consistency.

docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws-v3/resource-and-property-reference/amazon-elastic-kubernetes-service/amazon-elastic-kubernetes-service.md [20-22]

-::::info All properties available by default
-EKS clusters expose their key properties via the default DescribeCluster action.
-::::
+:::info All properties available by default
+EKS clusters expose their key properties via the default `DescribeCluster` action.
+:::
  • Apply / Chat
Suggestion importance[1-10]: 4

__

Why: The suggestion correctly identifies and fixes the non-standard :::: admonition syntax. It also improves readability by formatting the action name DescribeCluster as code, which is a good practice for technical documentation.

Low

best practice
Use standard admonition fence

Correct the admonition syntax from the non-standard :::: to the standard ::: to
ensure it renders correctly.

docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws-v3/resource-and-property-reference/aws-lambda/aws-lambda.md [21-23]

-::::info Optional properties note
+:::info Optional properties note
 Properties of optional actions will not appear in the response unless you explicitly include the action that provides them in your configuration.
-::::
+:::
  • Apply / Chat
Suggestion importance[1-10]: 3

__

Why: This suggestion correctly points out the use of non-standard :::: admonition syntax and suggests changing it to the standard ::: to ensure proper rendering, which is a valid and helpful fix for the documentation.

Low

best practice
Fix admonition syntax and casing
Suggestion Impact:The commit changed the admonition from "::::info" to ":::info" and capitalized the title to "Custom Resource for Account Resync," matching the suggestion.

code diff:

-::::info Custom resource for account resync
+:::info Custom Resource for Account Resync
 Use `AWS::Account::Info` to resync AWS account data when you do not have organization-level permissions. If you do have AWS Organizations permissions and want to retrieve richer data (e.g., org account metadata, parents, and tags), see the AWS Organizations documentation under [AWS Organizations](../aws-organizations/aws-organizations.md).
-::::
+:::

Correct the admonition syntax from four colons to three to ensure it renders
correctly, and capitalize the title for consistency.

docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws-v3/resource-and-property-reference/aws-account/aws-account.md [12-14]

-::::info Custom resource for account resync
+:::info Custom Resource for Account Resync
 Use `AWS::Account::Info` to resync AWS account data when you do not have organization-level permissions. If you do have AWS Organizations permissions and want to retrieve richer data (e.g., org account metadata, parents, and tags), see the AWS Organizations documentation under [AWS Organizations](../aws-organizations/aws-organizations.md).
-::::
+:::

[Suggestion processed]

Suggestion importance[1-10]: 5

__

Why: The suggestion corrects the admonition syntax from :::: to ::: which fixes a rendering issue, and also improves consistency by changing the title to title case.

Low
Normalize table spacing and alignment
Suggestion Impact:The commit adjusted the spacing in the table row to align columns, matching the suggested formatting change.

code diff:

-| **GetBucketLocationAction**          | Retrieve the bucket's region. [Reference](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetBucketLocation.html)                                 | Optional  | `s3:GetBucketLocation`                                  |
+| **GetBucketLocationAction**          | Retrieve the bucket's region. [Reference](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetBucketLocation.html) | Optional | `s3:GetBucketLocation` |

Fix spacing alignment in the markdown table for better source code readability.

docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws-v3/resource-and-property-reference/amazon-simple-storage-service/amazon-simple-storage-service.md [20]

-| **GetBucketLocationAction**          | Retrieve the bucket's region. [Reference](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetBucketLocation.html)                                 | Optional  | `s3:GetBucketLocation`                                  |
+| **GetBucketLocationAction**          | Retrieve the bucket's region. [Reference](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetBucketLocation.html) | Optional | `s3:GetBucketLocation` |

[Suggestion processed]

Suggestion importance[1-10]: 2

__

Why: The suggestion proposes a minor formatting fix to align a markdown table column, which improves source code readability but has no effect on the rendered output.

Low
Maintainability
Standardize admonition title casing

Standardize the admonition title to use Title Case for consistency with other
titles in the documentation.

docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws-v3/resource-and-property-reference/amazon-elastic-container-service/amazon-elastic-container-service.md [47-49]

-:::info Optional properties note
+:::info Optional Properties Note
 Properties of optional actions will not appear in the response unless you explicitly include the action that provides them in your configuration.
 :::
  • Apply / Chat
Suggestion importance[1-10]: 3

__

Why: The suggestion improves documentation consistency by standardizing the casing of admonition titles, which is a minor stylistic improvement.

Low
Unify YAML quoting for blueprint

Standardize the YAML blueprint value to use double quotes for consistency across
documentation examples.

docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws-v3/resource-and-property-reference/aws-account/aws-account-info/_aws_account_port_app_config.mdx [5-14]

 resources:
   - kind: AWS::Account::Info
     selector:
       query: 'true'
     port:
       entity:
         mappings:
           identifier: .Properties.Id
           title: .Properties.Name
-          blueprint: '"awsAccount"'
+          blueprint: "\"awsAccount\""
  • Apply / Chat
Suggestion importance[1-10]: 3

__

Why: The suggestion correctly points out an inconsistency in YAML string quoting for the blueprint value and proposes a fix to align it with other examples, which is a minor style improvement.

Low
  • Update

Previous suggestions

✅ Suggestions up to commit dfd275d
CategorySuggestion                                                                                                                                    Impact
Possible bug
Standardize mapping paths and relations

Correct the SQS mapping configuration by adding the .Properties prefix to JQ
paths, standardizing the relations path to .__ExtraContext.AccountId, and
quoting the blueprint value.

docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws-v3/resource-and-property-reference/amazon-simple-queue-service/aws-sqs-queue/_sqs_queue_port_app_config.mdx [5-22]

 resources:
   - kind: AWS::SQS::Queue
     selector:
       query: 'true'
     port:
       entity:
         mappings:
-          identifier: .QueueUrl
-          title: .QueueName
-          blueprint: sqsQueue
+          identifier: .Properties.QueueUrl
+          title: .Properties.QueueName
+          blueprint: '"sqsQueue"'
           properties:
-            queueName: .QueueName
-            queueUrl: .QueueUrl
-            queueArn: .QueueArn
-            fifoQueue: .FifoQueue
-            visibilityTimeout: .VisibilityTimeout
+            queueName: .Properties.QueueName
+            queueUrl: .Properties.QueueUrl
+            queueArn: .Properties.QueueArn
+            fifoQueue: .Properties.FifoQueue
+            visibilityTimeout: .Properties.VisibilityTimeout
           relations:
-            awsAccount: .awsAccount
+            awsAccount: .__ExtraContext.AccountId
Suggestion importance[1-10]: 8

__

Why: The suggestion corrects multiple errors in the SQS mapping configuration, including missing .Properties prefixes, an incorrect relation path, and inconsistent blueprint quoting, which would likely cause the integration mapping to fail.

Medium
Fix admonition fence syntax

Correct the admonition block syntax from four colons (::::) to the standard
three colons (:::) to ensure proper rendering in Docusaurus.

docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws-v3/resource-and-property-reference/amazon-elastic-kubernetes-service/amazon-elastic-kubernetes-service.md [20-22]

-::::info All properties available by default
+:::info All properties available by default
 EKS clusters expose their key properties via the default DescribeCluster action.
-::::
+:::
Suggestion importance[1-10]: 5

__

Why: The suggestion correctly identifies and fixes the invalid :::: admonition syntax, which could cause rendering issues, ensuring consistency with Docusaurus standards.

Low
Use valid admonition delimiters

Fix the admonition block syntax from four colons (::::) to the standard three
(:::) for correct rendering and consistency.

docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws-v3/Overview.md [45-47]

-::::info Property naming conventions
-The AWS Hosted by Port integration returns all resource properties in **PascalCase** (for example: `Arn`, `BucketName`, `CreationDate`). When writing mappings and JQ expressions, reference properties using PascalCasing as shown in the examples below.
-::::
+:::info Property naming conventions
+The AWS Hosted by Port integration returns all resource properties in **PascalCase** (for example: `Arn`, `BucketName`, `CreationDate`). When writing mappings and JQ expressions, reference properties using PascalCase as shown in the examples below.
+:::
Suggestion importance[1-10]: 5

__

Why: The suggestion correctly points out the non-standard :::: admonition syntax and proposes fixing it to :::, which prevents potential rendering errors and ensures consistency.

Low

best practice
Fix admonition block syntax
Suggestion Impact:The commit changed the admonition markers from ::::: to ::: and :::: to :::, matching the suggested fix; it also adjusted the title casing.

code diff:

-::::info Custom resource for account resync
+:::info Custom Resource for Account Resync
 Use `AWS::Account::Info` to resync AWS account data when you do not have organization-level permissions. If you do have AWS Organizations permissions and want to retrieve richer data (e.g., org account metadata, parents, and tags), see the AWS Organizations documentation under [AWS Organizations](../aws-organizations/aws-organizations.md).
-::::
+:::

Correct the admonition block syntax from four colons (::::) to the standard
three colons (:::) to ensure proper rendering in Docusaurus.

docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws-v3/resource-and-property-reference/aws-account/aws-account.md [12-14]

-::::info Custom resource for account resync
+:::info Custom resource for account resync
 Use `AWS::Account::Info` to resync AWS account data when you do not have organization-level permissions. If you do have AWS Organizations permissions and want to retrieve richer data (e.g., org account metadata, parents, and tags), see the AWS Organizations documentation under [AWS Organizations](../aws-organizations/aws-organizations.md).
-::::
+:::
Suggestion importance[1-10]: 5

__

Why: The suggestion correctly identifies and fixes the invalid :::: admonition syntax, which could cause rendering issues, ensuring consistency with Docusaurus standards.

Low
✅ Suggestions up to commit fa2b9c9
CategorySuggestion                                                                                                                                    Impact
Possible bug
Align EC2 action name usage

Correct the EC2 action name in the example from DescribeInstanceStatusAction to
GetInstanceStatusAction to match the name used in other parts of the
documentation and prevent user confusion.

docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws-v3/resource-and-property-reference/resource-and-property-reference.md [65-73]

-To collect additional properties from AWS resources, add the optional actions you need to the `includeActions` field of your configuration. For example, to include status details from EC2 instances by enabling the `DescribeInstanceStatusAction`, add the following:
+To collect additional properties from AWS resources, add the optional actions you need to the `includeActions` field of your configuration. For example, to include status details from EC2 instances by enabling the `GetInstanceStatusAction`, add the following:
 
 ```yaml
 - kind: AWS::EC2::Instance
   selector:
     query: 'true'
     includeActions:
-      - DescribeInstanceStatusAction
+      - GetInstanceStatusAction


 <!-- /improve --apply_suggestion=0 -->


<details><summary>Suggestion importance[1-10]: 8</summary>

__

Why: The suggestion identifies a critical inconsistency in an action name (`DescribeInstanceStatusAction` vs. `GetInstanceStatusAction`) between different documentation files, which would likely cause user configuration errors.


</details></details></td><td align=center>Medium

</td></tr><tr><td>



<details><summary>Fix admonition delimiter syntax</summary>

___

**Correct the admonition block syntax from four colons (<code>::::</code>) to the standard <br>three (<code>:::</code>) to ensure proper rendering and maintain consistency.**

[docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws-v3/resource-and-property-reference/amazon-elastic-kubernetes-service/amazon-elastic-kubernetes-service.md [20-22]](https://github.com/port-labs/port-docs/pull/2960/files#diff-0aa9b3c1fea44f2b40721233acb7d0e2c142fb8d465d5ff5db5689fccff8ed09R20-R22)

```diff
-::::info All properties available by default
+:::info All properties available by default
 EKS clusters expose their key properties via the default DescribeCluster action.
-::::
+:::
Suggestion importance[1-10]: 4

__

Why: The suggestion correctly identifies inconsistent and potentially invalid syntax for an admonition block, proposing a fix that aligns with standard Docusaurus formatting and improves documentation quality.

Low
Correct info block formatting

Standardize the admonition block syntax by changing the non-standard four colons
(::::) to the correct three (:::) for consistency and to avoid rendering
problems.

docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws-v3/resource-and-property-reference/aws-lambda/aws-lambda.md [21-23]

-::::info Optional properties note
+:::info Optional properties note
 Properties of optional actions will not appear in the response unless you explicitly include the action that provides them in your configuration.
-::::
+:::
Suggestion importance[1-10]: 4

__

Why: The suggestion correctly points out non-standard syntax for an admonition block and proposes a change to the standard ::: format, which improves consistency and prevents potential rendering issues.

Low

best practice
Normalize mapping and relation fields

In the SQS queue mapping configuration, quote the blueprint value and update the
relations mapping to use account: .__ExtraContext.AccountId for consistency with
other resource examples.

docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws-v3/resource-and-property-reference/amazon-simple-queue-service/aws-sqs-queue/_sqs_queue_port_app_config.mdx [5-22]

 resources:
   - kind: AWS::SQS::Queue
     selector:
       query: 'true'
     port:
       entity:
         mappings:
           identifier: .QueueUrl
           title: .QueueName
-          blueprint: sqsQueue
+          blueprint: '"sqsQueue"'
           properties:
             queueName: .QueueName
             queueUrl: .QueueUrl
             queueArn: .QueueArn
             fifoQueue: .FifoQueue
             visibilityTimeout: .VisibilityTimeout
           relations:
-            awsAccount: .awsAccount
+            account: .__ExtraContext.AccountId
Suggestion importance[1-10]: 7

__

Why: This suggestion correctly identifies inconsistencies in the blueprint value and the relations mapping compared to other examples in the PR. Applying the fix improves consistency and prevents potential configuration errors.

Medium
Typo
Fix admonition and capitalization

Fix the admonition syntax from :::: to ::: to ensure it renders correctly, and
adjust the capitalization of PascalCase for consistency.

docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws-v3/Overview.md [45-47]

-::::info Property naming conventions
-The AWS Hosted by Port integration returns all resource properties in **PascalCase** (for example: `Arn`, `BucketName`, `CreationDate`). When writing mappings and JQ expressions, reference properties using PascalCasing as shown in the examples below.
-::::
+:::info Property naming conventions
+The AWS Hosted by Port integration returns all resource properties in **PascalCase** (for example: `Arn`, `BucketName`, `CreationDate`). When writing mappings and JQ expressions, reference properties using PascalCase as shown in the examples below.
+:::
Suggestion importance[1-10]: 5

__

Why: The suggestion correctly identifies that the admonition syntax :::: is incorrect and should be ::: for it to render properly, which is a valid documentation bug fix. It also suggests a minor consistency improvement for PascalCase.

Low
Enhancement
Code-format action name

Add backticks around DescribeClusters in the info block for consistent code
formatting.

docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws-v3/resource-and-property-reference/amazon-elastic-container-service/amazon-elastic-container-service.md [22-24]

 :::info All properties available by default
-ECS clusters expose their key properties via the default DescribeClusters action.
+ECS clusters expose their key properties via the default `DescribeClusters` action.
 :::
Suggestion importance[1-10]: 4

__

Why: The suggestion correctly points out that the action name DescribeClusters should be wrapped in backticks for code formatting, which improves readability and consistency with other documentation pages.

Low
Maintainability
Normalize table spacing
Suggestion Impact:The commit adjusted the spacing in the GetBucketLocationAction row, removing the extra space before "Optional" (and also trimmed excessive spacing in the row), aligning with the suggestion's intent.

code diff:

-| **GetBucketLocationAction**          | Retrieve the bucket's region. [Reference](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetBucketLocation.html)                                 | Optional  | `s3:GetBucketLocation`                                  |
+| **GetBucketLocationAction**          | Retrieve the bucket's region. [Reference](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetBucketLocation.html) | Optional | `s3:GetBucketLocation` |

In the S3 actions table, remove a double space before "Optional" to normalize
spacing.

docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws-v3/resource-and-property-reference/amazon-simple-storage-service/amazon-simple-storage-service.md [20]

-| **GetBucketLocationAction**          | Retrieve the bucket's region. [Reference](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetBucketLocation.html)                                 | Optional  | `s3:GetBucketLocation`                                  |
+| **GetBucketLocationAction**          | Retrieve the bucket's region. [Reference](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetBucketLocation.html)                                 | Optional | `s3:GetBucketLocation`                                  |
Suggestion importance[1-10]: 2

__

Why: This is a minor stylistic suggestion to remove a double space in a markdown table. While it improves source code consistency, it has no effect on the rendered output.

Low
Possible issue
Remove misleading admonition

Remove the misleading "Optional properties note" for the ECS Service, as only
default actions are listed, which could cause confusion.

docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws-v3/resource-and-property-reference/amazon-elastic-container-service/amazon-elastic-container-service.md [47-49]

-:::info Optional properties note
-Properties of optional actions will not appear in the response unless you explicitly include the action that provides them in your configuration.
-:::
+<!-- Removed optional properties note to avoid confusion; only default actions are listed for ECS Service -->
Suggestion importance[1-10]: 5

__

Why: The suggestion correctly points out that the "Optional properties note" is misleading for the AWS::ECS::Service resource, as only a default action is documented. Removing it prevents user confusion.

Low
Organization
best practice
Provide complete Organizations config example

Add the complete mapping configuration for AWS::Organizations::Account, matching
the pattern used in other resources, so the reference page provides a working
example.

docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws-v3/resource-and-property-reference/aws-organizations/aws-organizations-account/_organizations_accounts_port_app_config.mdx [1]

+```yaml showLineNumbers
+resources:
+  - kind: AWS::Organizations::Account
+    selector:
+      query: 'true'
+      includeActions:
+        # Optional: enable to fetch additional properties
+        # - ListTagsForResourceAction
+        # - ListParentsAction
+    port:
+      entity:
+        mappings:
+          identifier: .Properties.Id
+          title: .Properties.AccountName
+          blueprint: '"awsOrganizationsAccount"'
+          properties:
+            id: .Properties.Id
+            accountName: .Properties.AccountName
+            arn: .Properties.Arn
+            email: .Properties.Email
+            status: .Properties.Status
+            joinedTimestamp: .Properties.JoinedTimestamp
+            joinedMethod: .Properties.JoinedMethod
+            tags: .Properties.Tags
+            parents: .Properties.Parents
+          relations:
+            account: .__ExtraContext.AccountId
+```
 
-
Suggestion importance[1-10]: 5

__

Why:
Relevant best practice - Avoid empty placeholder files; include complete, functional examples or remove unused stubs to maintain documentation accuracy and completeness.

Low
Maintainability
Standardize relation naming

Standardize the relation name in the SQS queue blueprint from awsAccount to
account for consistency with other resource definitions.

docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws-v3/resource-and-property-reference/amazon-simple-queue-service/aws-sqs-queue/_sqs_queue_blueprint.mdx [39-46]

 "relations": {
-  "awsAccount": {
-    "title": "AWS Account",
+  "account": {
+    "title": "Account",
     "target": "awsAccount",
     "required": true,
     "many": false
   }
 }
Suggestion importance[1-10]: 4

__

Why: The suggestion correctly identifies an inconsistency in the SQS blueprint's relation naming (awsAccount) compared to other blueprints in the PR, which use account. Applying this change improves documentation consistency.

Low

best practice
Normalize IAM permission formatting

Standardize the formatting of IAM permissions in the EKS Cluster actions table
by using a comma to separate multiple actions for better readability and
consistency.

docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws-v3/resource-and-property-reference/amazon-elastic-kubernetes-service/amazon-elastic-kubernetes-service.md [18]

-| **DescribeClusterAction** | Retrieve detailed configuration data for each cluster. [Reference](https://docs.aws.amazon.com/eks/latest/APIReference/API_DescribeCluster.html) | Default | `eks:DescribeCluster` `eks:ListClusters`  |
+| **DescribeClusterAction** | Retrieve detailed configuration data for each cluster. [Reference](https://docs.aws.amazon.com/eks/latest/APIReference/API_DescribeCluster.html) | Default | `eks:ListClusters`, `eks:DescribeCluster` |
Suggestion importance[1-10]: 3

__

Why: The suggestion correctly identifies an inconsistent format for listing multiple IAM permissions. Applying the change to use a comma separator improves readability and aligns with the format used elsewhere in the documentation.

Low

@sivanel97
Copy link
Contributor

/improve

@port-labs port-labs deleted a comment from hadar-co Nov 3, 2025
@port-labs port-labs deleted a comment from hadar-co Nov 3, 2025
@port-labs port-labs deleted a comment from qodo-merge-pro bot Nov 3, 2025
@port-labs port-labs deleted a comment from qodo-merge-pro bot Nov 3, 2025
@port-labs port-labs deleted a comment from qodo-merge-pro bot Nov 3, 2025
@port-labs port-labs deleted a comment from qodo-merge-pro bot Nov 3, 2025
@qodo-merge-pro
Copy link

qodo-merge-pro bot commented Nov 3, 2025

Persistent suggestions updated to latest commit dfd275d

@sivanel97
Copy link
Contributor

/improve

@qodo-merge-pro
Copy link

qodo-merge-pro bot commented Nov 3, 2025

Persistent suggestions updated to latest commit dfd275d

mk-armah and others added 2 commits November 3, 2025 13:31
…oviders/aws-v3/resource-and-property-reference/amazon-simple-storage-service/amazon-simple-storage-service.md

Co-authored-by: qodo-merge-pro[bot] <151058649+qodo-merge-pro[bot]@users.noreply.github.com>
…oviders/aws-v3/resource-and-property-reference/aws-account/aws-account.md

Co-authored-by: qodo-merge-pro[bot] <151058649+qodo-merge-pro[bot]@users.noreply.github.com>
Comment on lines +45 to +47
::::info Property naming conventions
The AWS Hosted by Port integration returns all resource properties in **PascalCase** (for example: `Arn`, `BucketName`, `CreationDate`). When writing mappings and JQ expressions, reference properties using PascalCasing as shown in the examples below.
::::
Copy link

Choose a reason for hiding this comment

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

Suggestion: Fix admonition syntax and casing

Suggested change
::::info Property naming conventions
The AWS Hosted by Port integration returns all resource properties in **PascalCase** (for example: `Arn`, `BucketName`, `CreationDate`). When writing mappings and JQ expressions, reference properties using PascalCasing as shown in the examples below.
::::
:::info Property naming conventions
The AWS Hosted by Port integration returns all resource properties in **PascalCase** (for example: `Arn`, `BucketName`, `CreationDate`). When writing mappings and JQ expressions, reference properties using PascalCase as shown in the examples below.
:::

Copy link
Contributor

@sivanel97 sivanel97 left a comment

Choose a reason for hiding this comment

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

Left some comments as examples.

Mostly the capitalization is a bit off, only the first letter in the headers and titles should be capitalized.

And also suggested a new placement for the reference link in the tables in each resource page.


The following example demonstrates how to ingest your AWS EC2 instances to Port.

#### EC2 Instance Supported Actions
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
#### EC2 Instance Supported Actions
#### EC2 instance supported actions

@@ -1,5 +1,5 @@
<details>
<summary><b>EC2 instance blueprint (Click to expand)</b></summary>
<summary><b>EC2 Instance Blueprint (Click to expand)</b></summary>
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
<summary><b>EC2 Instance Blueprint (Click to expand)</b></summary>
<summary><b>EC2 instance blueprint (click to expand)</b></summary>

All headers should have a capital letter only for the first word :)

@@ -1,5 +1,5 @@
<details>
<summary><b>EC2 instance mapping configuration (Click to expand)</b></summary>
<summary><b>EC2 Instance Mapping Configuration (Click to expand)</b></summary>
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
<summary><b>EC2 Instance Mapping Configuration (Click to expand)</b></summary>
<summary><b>EC2 instance mapping configuration (click to expand)</b></summary>

same :)

@@ -1,5 +1,5 @@
<details>
<summary><b>ECS cluster blueprint (Click to expand)</b></summary>
<summary><b>ECS Cluster Blueprint (Click to expand)</b></summary>
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
<summary><b>ECS Cluster Blueprint (Click to expand)</b></summary>
<summary><b>ECS cluster blueprint (click to expand)</b></summary>

same here and in the other instances

@@ -0,0 +1,82 @@
# AWS Resource and Property Reference
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
# AWS Resource and Property Reference
# AWS resource and property reference

Copy link
Member Author

Choose a reason for hiding this comment

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

This is fine

Comment on lines +67 to +73
```yaml
- kind: AWS::EC2::Instance
selector:
query: 'true'
includeActions:
- DescribeInstanceStatusAction
```
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
```yaml
- kind: AWS::EC2::Instance
selector:
query: 'true'
includeActions:
- DescribeInstanceStatusAction
```
```yaml showLineNumbers
- kind: AWS::EC2::Instance
selector:
query: 'true'
includeActions:
- DescribeInstanceStatusAction

@@ -0,0 +1,4 @@
{
"label": "Amazon Relational Database Service",
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
"label": "Amazon Relational Database Service",
"label": "Amazon relational database service",

Copy link
Member Author

@mk-armah mk-armah Nov 3, 2025

Choose a reason for hiding this comment

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

Its a bit tough comprehending this because the casing are actually trademarks of the resource types .
AWS deliberately presents them this way, making a bit unusual if its looked at some other way, I don't know if you get me

Copy link
Member Author

@mk-armah mk-armah Nov 3, 2025

Choose a reason for hiding this comment

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

For example

Screenshot 2025-11-03 at 4 58 51 PM

@@ -0,0 +1,31 @@
# Amazon Relational Database Service
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
# Amazon Relational Database Service
# Amazon relational database service

Copy link
Member Author

@mk-armah mk-armah Nov 3, 2025

Choose a reason for hiding this comment

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

Here, because its a deliberate trademark name, you can see that the sentence after it were all in the right casing (lower case) except the Amazon Relational Database Service

Screenshot 2025-11-03 at 5 03 43 PM

Comment on lines +18 to +19
| **DescribeDBInstancesAction** | Discover DB instances and retrieve configuration details. [Reference](https://docs.aws.amazon.com/rds/latest/APIReference/API_DescribeDBInstances.html) | Default | `rds:DescribeDBInstances` |
| **ListTagsForResourceAction** | Retrieve tags for each DB instance. [Reference](https://docs.aws.amazon.com/rds/latest/APIReference/API_ListTagsForResource.html) | Optional | `rds:ListTagsForResource` |
Copy link
Contributor

Choose a reason for hiding this comment

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


| Action | Description | Type | Required AWS Permission |
|--------------------------|--------------------------------------------------------------------|---------|------------------------------------|
| **DescribeClustersAction** | Discover ECS clusters and retrieve detailed configuration data. [Reference](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_DescribeClusters.html) | Default | `ecs:ListClusters`, `ecs:DescribeClusters` |
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
| **DescribeClustersAction** | Discover ECS clusters and retrieve detailed configuration data. [Reference](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_DescribeClusters.html) | Default | `ecs:ListClusters`, `ecs:DescribeClusters` |
| [**DescribeClustersAction**](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_DescribeClusters.html) | Discover ECS clusters and retrieve detailed configuration data. | Default | `ecs:ListClusters`, `ecs:DescribeClusters` |

Maybe the reference link can be attached to the action name itself? It just seems a bit odd at the end of the description to have "Reference". WDYT?

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

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants