Skip to content

Commit 9b56d39

Browse files
sivanel97sivanel97
authored
Merge pull request #2784 from port-labs/PORT-15551-documentation-screenshots
PORT 15551 documentation screenshots
2 parents 78bfa36 + 28d3402 commit 9b56d39

File tree

9 files changed

+415
-2
lines changed

9 files changed

+415
-2
lines changed

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

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
---
2+
sidebar_position: 1
3+
---
4+
5+
import Tabs from "@theme/Tabs";
6+
import TabItem from "@theme/TabItem";
7+
import Image from "@theme/IdealImage";
8+
import MetricsAndSyncStatus from "/docs/build-your-software-catalog/sync-data-to-catalog/templates/_metrics_and_sync_status.mdx"
9+
10+
# Overview
11+
12+
:::warning Beta Feature
13+
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.
14+
:::
15+
16+
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.
17+
18+
The integration periodically syncs your AWS resources to ensure your Port catalog stays up-to-date with your AWS infrastructure.
19+
20+
## Common use cases
21+
22+
Easily fill your software catalog with data directly from your AWS Organization, for example:
23+
24+
- Map all the resources in your AWS Accounts, including **ECS Clusters**, **S3 Buckets**, and **EC2 Instances** with zero maintenance required.
25+
- Keep your Port catalog synchronized with your AWS infrastructure through periodic updates.
26+
- Use relations to create complete, easily digestible views of your AWS infrastructure inside Port.
27+
- Enjoy a fully managed experience with no infrastructure to maintain or updates to apply.
28+
29+
## Supported resources
30+
31+
The integration currently supports the following AWS resource types:
32+
- `S3 Buckets`: Complete bucket information including properties, tags, and metadata.
33+
- `ECS Clusters`: Cluster details, services, and task definitions.
34+
- `EC2 Instances`: Instance information, security groups, and networking details.
35+
36+
:::info More Resource Types Coming Soon
37+
We're actively working on adding support for additional AWS resource types to provide comprehensive coverage of your AWS infrastructure.
38+
:::
39+
40+
## Key advantages
41+
42+
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):
43+
44+
- **Fully hosted**: No infrastructure to maintain, update, or monitor.
45+
- **Simplified installation**: Just deploy CloudFormation templates to create IAM roles.
46+
- **Complete data**: Ensures no missing or incomplete resource information.
47+
48+
## Getting started
49+
50+
Continue to the [installation](./installations.md) guide to learn how to install AWS Hosted by Port.
51+
52+
For detailed information about the IAM role architecture and security model, see the [IAM Role Architecture](./iam-role-architecture.md) guide.
53+
54+
## Configuration
55+
56+
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.
57+
58+
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.
59+
60+
### Default mapping configuration
61+
62+
This is the default mapping configuration you get after installing AWS Hosted by Port.
63+
64+
<details>
65+
<summary><b>Default mapping configuration (click to expand)</b></summary>
66+
67+
```yaml showLineNumbers
68+
deleteDependentEntities: true
69+
createMissingRelatedEntities: true
70+
enableMergeEntity: true
71+
resources:
72+
- kind: AWS::Account::Info
73+
selector:
74+
query: 'true'
75+
port:
76+
entity:
77+
mappings:
78+
identifier: .Properties.Id
79+
title: .Properties.Name
80+
blueprint: '"awsAccount"'
81+
- kind: AWS::S3::Bucket
82+
selector:
83+
query: 'true'
84+
port:
85+
entity:
86+
mappings:
87+
identifier: .Properties.Arn
88+
title: .Properties.BucketName
89+
blueprint: '"s3Bucket"'
90+
properties:
91+
arn: .Properties.Arn
92+
region: .Properties.LocationConstraint
93+
creationDate: .Properties.CreationDate
94+
tags: .Properties.Tags
95+
relations:
96+
account: .__ExtraContext.AccountId
97+
- kind: AWS::EC2::Instance
98+
selector:
99+
query: 'true'
100+
port:
101+
entity:
102+
mappings:
103+
identifier: .Properties.InstanceId
104+
title: .Properties.InstanceId
105+
blueprint: '"ec2Instance"'
106+
properties:
107+
instanceType: .Properties.InstanceType
108+
state: .Properties.State.Name
109+
publicIpAddress: .Properties.PublicIpAddress
110+
privateIpAddress: .Properties.PrivateIpAddress
111+
tags: .Properties.Tags
112+
arn: >-
113+
"arn:aws:ec2:" + .__Region + ":" + .__AccountId + ":instance/" +
114+
.Properties.InstanceId
115+
relations:
116+
account: .__ExtraContext.AccountId
117+
- kind: AWS::ECS::Cluster
118+
selector:
119+
query: 'true'
120+
port:
121+
entity:
122+
mappings:
123+
identifier: .Properties.ClusterArn
124+
title: .Properties.ClusterName
125+
blueprint: '"ecsCluster"'
126+
properties:
127+
status: .Properties.Status
128+
runningTasksCount: .Properties.RunningTasksCount
129+
activeServicesCount: .Properties.ActiveServicesCount
130+
pendingTasksCount: .Properties.PendingTasksCount
131+
registeredContainerInstancesCount: .Properties.RegisteredContainerInstancesCount
132+
capacityProviders: .Properties.CapacityProviders
133+
clusterArn: .Properties.ClusterArn
134+
tags: .Properties.Tags
135+
relations:
136+
account: .__ExtraContext.AccountId
137+
138+
```
139+
140+
</details>
141+
142+
<MetricsAndSyncStatus/>

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

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{
2+
"label": "AWS Hosted by Port",
3+
"position": 12
4+
}

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

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
---
2+
sidebar_position: 3
3+
---
4+
5+
# IAM role architecture
6+
7+
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.
8+
9+
:::warning Role modifications
10+
We recommend keeping the IAM role and its permissions unchanged after deployment.
11+
The integration is designed to work with the full `ReadOnlyAccess` policy, which ensures:
12+
13+
- **Complete resource discovery** across all AWS services.
14+
- **Future compatibility** when Port adds support for new AWS services.
15+
- **Reliable operation** without permission-related issues.
16+
:::
17+
18+
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.
19+
20+
## Role structure
21+
22+
For multi-account setups, the role structure is replicated across all target accounts.
23+
24+
### OIDC identity provider
25+
26+
The CloudFormation template creates an OIDC identity provider that connects to Port's EKS cluster:
27+
28+
```yaml showLineNumbers
29+
PortIntegrationOIDCProvider:
30+
Type: AWS::IAM::OIDCProvider
31+
Properties:
32+
Url: 'https://oidc.eks.eu-west-1.amazonaws.com/id/56E5F51C07138118A9183ECEAA68FAF4'
33+
ClientIdList:
34+
- sts.amazonaws.com
35+
Tags:
36+
- Key: port:integration
37+
Value: !Ref IntegrationIdentifier
38+
```
39+
40+
**Key details**:
41+
- **EKS OIDC URL**: Points to Port's production EKS cluster in EU-West-1.
42+
- **Client ID**: Uses `sts.amazonaws.com` for IRSA authentication.
43+
- **Reusable**: Can be shared across multiple integrations in the same account.
44+
- **Optional**: Can be disabled if you already have a Port OIDC provider.
45+
46+
### Trust policy
47+
48+
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:
49+
50+
```json showLineNumbers
51+
{
52+
"Version": "2012-10-17",
53+
"Statement": [{
54+
"Effect": "Allow",
55+
"Principal": {
56+
"Federated": "arn:aws:iam::YOUR_ACCOUNT_ID:oidc-provider/oidc.eks.eu-west-1.amazonaws.com/id/56E5F51C07138118A9183ECEAA68FAF4"
57+
},
58+
"Action": "sts:AssumeRoleWithWebIdentity",
59+
"Condition": {
60+
"StringEquals": {
61+
"oidc.eks.eu-west-1.amazonaws.com/id/56E5F51C07138118A9183ECEAA68FAF4:aud": "sts.amazonaws.com",
62+
"oidc.eks.eu-west-1.amazonaws.com/id/56E5F51C07138118A9183ECEAA68FAF4:sub": "system:serviceaccount:org-YOUR_ORG_ID-port-oidc-sa"
63+
}
64+
}
65+
}]
66+
}
67+
```
68+
69+
**Key security features**:
70+
- **OIDC authentication**: Role is tied to Port's specific EKS service account.
71+
- **Temporary credentials**: All access uses short-lived tokens (typically 1 hour).
72+
73+
### Permissions policy
74+
75+
The role uses the **AWS managed `ReadOnlyAccess` policy**, which provides comprehensive read-only access to all AWS services:
76+
77+
```yaml showLineNumbers
78+
ManagedPolicyArns:
79+
- arn:aws:iam::aws:policy/ReadOnlyAccess
80+
```
81+
82+
**Strategic benefits**:
83+
- **Future-proof**: Automatically includes new AWS services without CloudFormation updates.
84+
- **Operational simplicity**: No need to redeploy when adding support for new services.
85+
- **Comprehensive coverage**: Access to all AWS services with read-only permissions.
86+
- **AWS maintained**: AWS manages and updates the policy as needed.
87+
- **Read-Only security**: Only read permissions, no write/delete/create access.
88+
89+
## Security considerations
90+
91+
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.

0 commit comments

Comments
 (0)