diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws-v3/Overview.md b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws-v3/Overview.md new file mode 100644 index 0000000000..9c8181e48a --- /dev/null +++ b/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. + +
+Default mapping configuration (click to expand) + +```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 + +``` + +
+ + \ No newline at end of file diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws-v3/_category_.json b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws-v3/_category_.json new file mode 100644 index 0000000000..f17ac698a6 --- /dev/null +++ b/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 +} diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws-v3/iam-role-architecture.md b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws-v3/iam-role-architecture.md new file mode 100644 index 0000000000..21a8c81b5e --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws-v3/installations.md b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws-v3/installations.md new file mode 100644 index 0000000000..306d3b9cb1 --- /dev/null +++ b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws-v3/installations.md @@ -0,0 +1,177 @@ +--- +sidebar_position: 2 +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; + +# Installation + +:::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. +::: + +AWS Hosted by Port is available through [Port's Ocean SaaS framework](https://ocean.getport.io/integrations-library/). + +The installation process is simple - you only need to create IAM roles in your AWS accounts to grant the integration access to read your resources. The integration handles everything else automatically. + +**How the integration works:** + +AWS Hosted by Port runs on **Port's servers** and connects to your AWS accounts using **OIDC (OpenID Connect)** authentication. Here's how it works: + +1. **You create IAM roles** in your AWS accounts using Port's CloudFormation templates. +2. **Port's servers assume these roles** using OIDC to get temporary AWS credentials. +3. **Port discovers your AWS resources** by calling AWS APIs with the assumed roles. +4. **Port exports the resources** to your Port account in the software catalog. +5. **Port periodically syncs** to keep your catalog up-to-date with your AWS infrastructure. + +:::tip Why Can't I Use an Existing Role? +AWS Hosted by Port requires specific OIDC trust relationships and permissions that are automatically configured by the CloudFormation template. Using an existing role would require manual configuration of these complex trust relationships, which is why we provide the CloudFormation template to ensure proper setup. + +For detailed information about the IAM role architecture and permissions, see the [IAM Role Architecture](./iam-role-architecture.md) documentation. +::: + +## Installation methods + + + + + +For a single AWS account, you will deploy a CloudFormation stack that creates the necessary IAM roles. + +

Step 1: Access AWS Console

+ +- **Log into your AWS account**: + - Go to [AWS Console](https://console.aws.amazon.com/). + - Sign in with your AWS account credentials. + +

Step 2: Deploy CloudFormation Stack

+ +- **Access the CloudFormation template**: + - Go to [Data Sources](https://app.getport.io/settings/data-sources) page. + - Click on the `+ Data source` button in the top right corner of the page. + - Select **AWS Hosted by Port** from the cloud providers section. + - Select **Single Account**. + - In step 3 of the installation form, click the `Click here` link. This will open CloudFormation with pre-configured parameters. + - This will open CloudFormation with pre-configured parameters. + +- **Deploy via AWS console**: + - In the CloudFormation console, review the pre-configured parameters. + - Scroll down to the bottom of the page. + - Check the box that states **"I acknowledge that AWS CloudFormation might create IAM resources with custom names"**. + + - Click `Create Stack`. + + +

Step 3: Configure Integration in Port

+ +- **Get the role ARN**: + - Ensure the stack shows `CREATE_COMPLETE` status. + + - After CloudFormation deployment completes, go to the **Outputs** tab. + - Copy the value of **PortIntegrationRoleArn**. + + - Paste it into the **Account Role Arn** field in the Port integration form. + - Click `Done`. + +- **Verify connection**: + - Port will automatically detect the IAM role created by CloudFormation. + - The integration will start discovering your AWS resources. + + + + + +For multiple AWS accounts, you will use AWS Organizations and deploy the integration across multiple accounts using CloudFormation StackSets. + +

Understanding AWS Organizations

+ +- **Management account**: The main account that manages your organization. +- **Member accounts**: Individual AWS accounts in your organization. +- **Organizational units (OUs)**: Logical groupings of accounts (like folders in a file system). +- **OU IDs**: Unique identifiers for organizational units (format: `ou-abcd-12345678`). +- **Root**: The top-level container for all accounts and OUs (format: `r-xxxxxxxxx`). + +**Example organization structure**: +``` +Root (r-1234) +├── Management Account (123456789012) +├── Production OU (ou-prod-12345678) +│ ├── Account: prod-app (234567890123) +│ └── Account: prod-db (345678901234) +├── Staging OU (ou-staging-87654321) +│ └── Account: staging (456789012345) +└── Development OU (ou-dev-11223344) + └── Account: dev (567890123456) +``` + +

Step 1: Prepare Your Organization

+ +:::caution Management Account Access Required +You must run the multi-account installation from your AWS Organizations **management account**. This is because only the management account can deploy StackSets across member accounts. +::: + +- **Find your OU ID**: + - Log into your AWS Organizations management account. + - Navigate to [AWS Organizations](https://us-east-1.console.aws.amazon.com/organizations/v2/home/accounts) service. + - Under **Organizational structure** copy the OU ID from the details page (format `ou-xxxx-xxxxxxxx` or `r-xxxx`). + - You can also target specific account IDs if needed using the `Account scope` field. + +

Step 2: Deploy Multi-Account CloudFormation Stack

+ +- **Access the CloudFormation template**: + - Go to the [Data sources](https://app.getport.io/settings/data-sources) page of your portal. + - Click on the `+ Data source` button in the top right corner of the page. + - Select **AWS Hosted by Port** from the cloud providers section. + - Select **Multiple Accounts** and paste the OU ID you previously copied. + - Choose the scope of the account (**All accounts**, **All accounts except selected**, **Selected accounts only**). + - In step 3 of the installation form, click the `Click here` link, this will open CloudFormation with pre-configured parameters. + +- **Deploy via AWS console**: + - In the CloudFormation console, review the pre-configured parameters. + - Scroll down to the bottom of the page. + - Check the box **"I acknowledge that AWS CloudFormation might create IAM resources with custom names"**. + + - Click `Create Stack`. + + +

Step 3: Monitor Deployment

+ +- **Check StackSet status**: + - Go to **CloudFormation** → **Stacks** in your management account. + - Make sure your stack status is `CREATE_COMPLETE`. + + +- **Verify IAM roles**: + - Check that the IAM roles were created in each target account. + +

Step 4: Configure Integration in Port

+ +- **Get the role ARN**: + - After CloudFormation deployment completes, go to the **Outputs** tab. + - Copy the value of **PortIntegrationRoleArn**. + + - Paste it into the **Account Role Arn** field in the Port integration form. + - Click `Done`. + +- **Verify multi-Account connection**: + - Port will automatically detect the IAM roles across all accounts. + - The integration will start discovering resources from all configured accounts. + + + + + +## Troubleshooting + +Common Installation Issue - CloudFormation Stack Creation Failures. + +**Error**: `Stack creation failed: CREATE_FAILED` + +**Solutions**: +- **Insufficient IAM permissions**: Ensure your AWS user has CloudFormation and IAM permissions. +- **OIDC provider already Eeists**: Set "Create OIDC Provider" to `false` if you already have one. + diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws/_category_.json b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws/_category_.json index 799b42596e..7597159280 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws/_category_.json +++ b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws/_category_.json @@ -1,4 +1,4 @@ { "label": "AWS", - "position": 10 + "position": 11 } diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws/installations/installation.md b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws/installations/installation.md index 44ed1d8d7a..f556dcbd7b 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws/installations/installation.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws/installations/installation.md @@ -23,7 +23,6 @@ Make sure you set up properly using our [Multiple Accounts guide](./multi_accoun ::: Choose one of the following installation methods: -Not sure which method is right for your use case? Check the available [installation methods](/build-your-software-catalog/sync-data-to-catalog/#installation-methods). diff --git a/static/img/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws/CloudFormationcheckbox.png b/static/img/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws/CloudFormationcheckbox.png new file mode 100644 index 0000000000..07fd946a1d Binary files /dev/null and b/static/img/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws/CloudFormationcheckbox.png differ diff --git a/static/img/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws/CreateCompleteStatus.png b/static/img/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws/CreateCompleteStatus.png new file mode 100644 index 0000000000..ad08b618d9 Binary files /dev/null and b/static/img/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws/CreateCompleteStatus.png differ diff --git a/static/img/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws/PortIntegreationRoleArnValue.png b/static/img/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws/PortIntegreationRoleArnValue.png new file mode 100644 index 0000000000..7720c10e85 Binary files /dev/null and b/static/img/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws/PortIntegreationRoleArnValue.png differ