PORT 15551 documentation screenshots

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

@@ -0,0 +1,142 @@
+---
+sidebar_position: 1
+---
+
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+import Image from "@theme/IdealImage";
+import MetricsAndSyncStatus from "/docs/build-your-software-catalog/sync-data-to-catalog/templates/_metrics_and_sync_status.mdx"
+
+# Overview
+
+:::warning Beta Feature
+AWS Hosted by Port is currently in **beta mode** and is not yet available for all Port users. Contact Port's support team to get access to this integration.
+:::
+
+Port's AWS Hosted by Port integration allows you to import your AWS resources into Port with **zero maintenance required**. The integration is fully hosted and managed by Port, providing a seamless experience for discovering and managing your AWS infrastructure.
+
+The integration periodically syncs your AWS resources to ensure your Port catalog stays up-to-date with your AWS infrastructure.
+
+## Common use cases
+
+Easily fill your software catalog with data directly from your AWS Organization, for example:
+
+- Map all the resources in your AWS Accounts, including **ECS Clusters**, **S3 Buckets**, and **EC2 Instances** with zero maintenance required.
+- Keep your Port catalog synchronized with your AWS infrastructure through periodic updates.
+- Use relations to create complete, easily digestible views of your AWS infrastructure inside Port.
+- Enjoy a fully managed experience with no infrastructure to maintain or updates to apply.
+
+## Supported resources
+
+The integration currently supports the following AWS resource types:
+- `S3 Buckets`: Complete bucket information including properties, tags, and metadata.
+- `ECS Clusters`: Cluster details, services, and task definitions.
+- `EC2 Instances`: Instance information, security groups, and networking details.
+
+:::info More Resource Types Coming Soon
+We're actively working on adding support for additional AWS resource types to provide comprehensive coverage of your AWS infrastructure.
+:::
+
+## Key advantages
+
+AWS Hosted by Port provides several advantages over the [self-hosted AWS integration](/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws/installations/installation.md):
+
+- **Fully hosted**: No infrastructure to maintain, update, or monitor.
+- **Simplified installation**: Just deploy CloudFormation templates to create IAM roles.
+- **Complete data**: Ensures no missing or incomplete resource information.
+
+## Getting started
+
+Continue to the [installation](./installations.md) guide to learn how to install AWS Hosted by Port.
+
+For detailed information about the IAM role architecture and security model, see the [IAM Role Architecture](./iam-role-architecture.md) guide.
+
+## Configuration
+
+Port integrations use a [YAML mapping block](/build-your-software-catalog/customize-integrations/configure-mapping#configuration-structure) to ingest data from the third-party api into Port.
+
+The mapping makes use of the [JQ JSON processor](https://stedolan.github.io/jq/manual/) to select, modify, concatenate, transform and perform other operations on existing fields and values from the integration API.
+
+### Default mapping configuration
+
+This is the default mapping configuration you get after installing AWS Hosted by Port.
+
+<details>
+<summary><b>Default mapping configuration (click to expand)</b></summary>
+
+```yaml showLineNumbers
+deleteDependentEntities: true
+createMissingRelatedEntities: true
+enableMergeEntity: true
+resources:
+  - kind: AWS::Account::Info
+    selector:
+      query: 'true'
+    port:
+      entity:
+        mappings:
+          identifier: .Properties.Id
+          title: .Properties.Name
+          blueprint: '"awsAccount"'
+  - kind: AWS::S3::Bucket
+    selector:
+      query: 'true'
+    port:
+      entity:
+        mappings:
+          identifier: .Properties.Arn
+          title: .Properties.BucketName
+          blueprint: '"s3Bucket"'
+          properties:
+            arn: .Properties.Arn
+            region: .Properties.LocationConstraint
+            creationDate: .Properties.CreationDate
+            tags: .Properties.Tags
+          relations:
+            account: .__ExtraContext.AccountId
+  - kind: AWS::EC2::Instance
+    selector:
+      query: 'true'
+    port:
+      entity:
+        mappings:
+          identifier: .Properties.InstanceId
+          title: .Properties.InstanceId
+          blueprint: '"ec2Instance"'
+          properties:
+            instanceType: .Properties.InstanceType
+            state: .Properties.State.Name
+            publicIpAddress: .Properties.PublicIpAddress
+            privateIpAddress: .Properties.PrivateIpAddress
+            tags: .Properties.Tags
+            arn: >-
+              "arn:aws:ec2:" + .__Region + ":" + .__AccountId + ":instance/" +
+              .Properties.InstanceId
+          relations:
+            account: .__ExtraContext.AccountId
+  - kind: AWS::ECS::Cluster
+    selector:
+      query: 'true'
+    port:
+      entity:
+        mappings:
+          identifier: .Properties.ClusterArn
+          title: .Properties.ClusterName
+          blueprint: '"ecsCluster"'
+          properties:
+            status: .Properties.Status
+            runningTasksCount: .Properties.RunningTasksCount
+            activeServicesCount: .Properties.ActiveServicesCount
+            pendingTasksCount: .Properties.PendingTasksCount
+            registeredContainerInstancesCount: .Properties.RegisteredContainerInstancesCount
+            capacityProviders: .Properties.CapacityProviders
+            clusterArn: .Properties.ClusterArn
+            tags: .Properties.Tags
+          relations:
+            account: .__ExtraContext.AccountId
+
+```
+
+</details>
+
+<MetricsAndSyncStatus/>

docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws-v3/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "AWS Hosted by Port",
+  "position": 12
+}

docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws-v3/iam-role-architecture.md

@@ -0,0 +1,91 @@
+---
+sidebar_position: 3
+---
+
+# IAM role architecture
+
+AWS Hosted by Port uses a strategically designed IAM role that provides comprehensive read-only access to all AWS services. The role is created automatically by the CloudFormation template and uses the AWS managed `ReadOnlyAccess` policy for future-proofing and operational simplicity.
+
+:::warning Role modifications
+We recommend keeping the IAM role and its permissions unchanged after deployment.  
+The integration is designed to work with the full `ReadOnlyAccess` policy, which ensures:
+
+- **Complete resource discovery** across all AWS services.
+- **Future compatibility** when Port adds support for new AWS services.
+- **Reliable operation** without permission-related issues.
+:::
+
+If you prefer to create the IAM role manually rather than using the CloudFormation template, the following sections describe the setup we implement. This will help you understand the reasoning behind our design choices and adapt them if you decide to configure the role differently.
+
+## Role structure
+
+For multi-account setups, the role structure is replicated across all target accounts.
+
+### OIDC identity provider
+
+The CloudFormation template creates an OIDC identity provider that connects to Port's EKS cluster:
+
+```yaml showLineNumbers
+PortIntegrationOIDCProvider:
+  Type: AWS::IAM::OIDCProvider
+  Properties:
+    Url: 'https://oidc.eks.eu-west-1.amazonaws.com/id/56E5F51C07138118A9183ECEAA68FAF4'
+    ClientIdList:
+      - sts.amazonaws.com
+    Tags:
+      - Key: port:integration
+        Value: !Ref IntegrationIdentifier
+```
+
+**Key details**:
+- **EKS OIDC URL**: Points to Port's production EKS cluster in EU-West-1.
+- **Client ID**: Uses `sts.amazonaws.com` for IRSA authentication.
+- **Reusable**: Can be shared across multiple integrations in the same account.
+- **Optional**: Can be disabled if you already have a Port OIDC provider.
+
+### Trust policy
+
+The IAM role uses an **OIDC (OpenID Connect) trust policy** with **IRSA (IAM Roles for Service Accounts)** that allows Port's EKS cluster to assume the role:
+
+```json showLineNumbers
+{
+  "Version": "2012-10-17",
+  "Statement": [{
+    "Effect": "Allow",
+    "Principal": { 
+      "Federated": "arn:aws:iam::YOUR_ACCOUNT_ID:oidc-provider/oidc.eks.eu-west-1.amazonaws.com/id/56E5F51C07138118A9183ECEAA68FAF4"
+    },
+    "Action": "sts:AssumeRoleWithWebIdentity",
+    "Condition": {
+      "StringEquals": {
+        "oidc.eks.eu-west-1.amazonaws.com/id/56E5F51C07138118A9183ECEAA68FAF4:aud": "sts.amazonaws.com",
+        "oidc.eks.eu-west-1.amazonaws.com/id/56E5F51C07138118A9183ECEAA68FAF4:sub": "system:serviceaccount:org-YOUR_ORG_ID-port-oidc-sa"
+      }
+    }
+  }]
+}
+```
+
+**Key security features**:
+- **OIDC authentication**: Role is tied to Port's specific EKS service account.
+- **Temporary credentials**: All access uses short-lived tokens (typically 1 hour).
+
+### Permissions policy
+
+The role uses the **AWS managed `ReadOnlyAccess` policy**, which provides comprehensive read-only access to all AWS services:
+
+```yaml showLineNumbers
+ManagedPolicyArns:
+  - arn:aws:iam::aws:policy/ReadOnlyAccess
+```
+
+**Strategic benefits**:
+- **Future-proof**: Automatically includes new AWS services without CloudFormation updates.
+- **Operational simplicity**: No need to redeploy when adding support for new services.
+- **Comprehensive coverage**: Access to all AWS services with read-only permissions.
+- **AWS maintained**: AWS manages and updates the policy as needed.
+- **Read-Only security**: Only read permissions, no write/delete/create access.
+
+## Security considerations
+
+From a security view point the integration uses a **read-only** role. It can list/describe and read metadata/tags, but cannot create, modify, delete, or change any resource.