AWS Legacy
Port's AWS Legacy integration allows you to import your AWS resources into Port, according to your configuration. After the initial import of data, the integration will also listen to live events from AWS to update data in Port in real time.
Core support
To move to AWS v3, follow the migration steps. You can keep AWS Legacy running alongside v3 for resource kinds you still need from the legacy integration.
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, EC2 Instances and other AWS objects.
- Watch for AWS resources changes (create/update/delete) in real-time, and automatically apply the changes to your entities in Port.
- Use relations to create complete, easily digestible views of your AWS infrastructure inside Port.
How it works
Port's AWS integration can retrieve all the resources supported by the Cloud Control API, and export them to Port as entities of existing blueprints.
The AWS integration allows you to perform extract, transform, load (ETL) on data from the Cloud Control API into the desired software catalog data model.
Setup
Choose one of the following installation methods:
The prerequisites required for installation are listed below.
Permissions
- To get Port API credentials, check out the Port API documentation.
- In order to successfully deploy the AWS Legacy integration, it's crucial to ensure that the user who deploys the integration in the AWS Organization has the appropriate access permissions to create all of the relevant resources (ECS, IAM, and VPC).
- Terraform >= 1.9.1
- A logged in AWS CLI 2
- Certificate domain name (Optional)
Permissions
- To get Port API credentials, check out the Port API documentation.
- In order to successfully deploy the AWS Legacy integration, it's crucial to ensure that the user who deploys the integration in the AWS Organization has the appropriate access permissions to create all of the relevant resources (ECS, IAM, and VPC).
- To get Port API credentials, check out the Port API documentation.
- Create an IAM user with the following permissions:
arn:aws:iam::aws:policy/ReadOnlyAccessaccount:ListRegionssts:AssumeRole
- Run the following Docker image:
ghcr.io/port-labs/port-ocean-aws:latest. - (For live updates): expose the port
8000to the internet.
Environment variables
Add the following environment variables to the Docker container:Environment variables (click to expand)
Variable Description OCEAN__PORT__CLIENT_IDYour Port client ID. OCEAN__PORT__CLIENT_SECRETYour Port client secret. OCEAN__PORT__BASE_URLYour Port API URL - https://api.port.io for EU, https://api.us.port.io for US.OCEAN__INTEGRATION__CONFIG__AWS_ACCESS_KEY_IDThe AWS Access Key ID of the IAM user. OCEAN__INTEGRATION__CONFIG__AWS_SECRET_ACCESS_KEYThe AWS Secret Access Key of the IAM user. OCEAN__INTEGRATION__CONFIG__LIVE_EVENTS_API_KEY(Optional) A secret string that you define to secure incoming requests to your live events endpoint. This is not an AWS key, you can use any secure random string (e.g. generate one using openssl rand -hex 32).OCEAN__INTEGRATION__CONFIG__ORGANIZATION_ROLE_ARN(Optional) AWS Organization Role ARN, used to read organization accounts for multi-account access. OCEAN__INTEGRATION__CONFIG__ACCOUNT_READ_ROLE_NAME(Optional) AWS Account Read Role Name, the role name used to read accounts in which the integration is not installed on, used for multi-account access. OCEAN__INTEGRATION__CONFIG__MAXIMUM_CONCURRENT_ACCOUNTS(Optional) Controls the maximum number of accounts synced concurrently. OCEAN__EVENT_LISTENERThe event listener object. OCEAN__INTEGRATION__IDENTIFIERThe identifier of the integration. OCEAN__INTEGRATION__TYPEShould be set to aws.
The AWS Legacy integration is deployed using Helm on your cluster. You can check out the Helm chart here.
You should have the following information ready:
- Port API credentials, you can check out the Port API documentation.
PORT_CLIENT_IDPORT_CLIENT_SECRET
- AWS credentials:
AWS_ACCESS_KEY_ID: The Access Key ID from the IAM user.AWS_SECRET_ACCESS_KEY: The Secret Access Key from the IAM user.
Helm installation command (click to expand)
helm repo add --force-update port-labs https://port-labs.github.io/helm-charts
helm upgrade --install aws port-labs/port-ocean \
--set port.clientId="$PORT_CLIENT_ID" \
--set port.clientSecret="$PORT_CLIENT_SECRET_ID" \
--set port.baseUrl="https://api.port.io" \
--set initializePortResources=true \
--set sendRawDataExamples=true \
--set scheduledResyncInterval=1440 \
--set integration.identifier="my-aws" \
--set integration.type="aws" \
--set integration.eventListener.type="POLLING" \
--set integration.config.awsAccessKeyId="$AWS_ACCESS_KEY_ID" \
--set integration.config.awsSecretAccessKey="$AWS_SECRET_ACCESS_KEY" \
--set integration.config.maximumConcurrentAccounts=50
The port.baseUrl and OCEAN__PORT__BASE_URL parameters select which Port API instance to use:
- EU (app.port.io) →
https://api.port.io - US (app.us.port.io) →
https://api.us.port.io
Multiple account support
For running the AWS integration with multiple accounts using Helm, you'll need to make sure that you have the following (check out our multiple accounts guide for how to get them):
- An organization role ARN.
- A role with Read permissions set up across your AWS accounts.
- IRSA or a user with the previous read-permissions role bound to them.
Helm multi-account command (click to expand)
helm repo add --force-update port-labs https://port-labs.github.io/helm-charts
helm upgrade --install aws port-labs/port-ocean \
--set port.clientId="$PORT_CLIENT_ID" \
--set port.clientSecret="$PORT_CLIENT_SECRET_ID" \
--set port.baseUrl="https://api.port.io" \
--set initializePortResources=true \
--set sendRawDataExamples=true \
--set scheduledResyncInterval=1440 \
--set integration.identifier="my-aws" \
--set integration.type="aws" \
--set integration.eventListener.type="POLLING" \
--set integration.config.awsAccessKeyId="$AWS_ACCESS_KEY_ID" \
--set integration.config.awsSecretAccessKey="$AWS_SECRET_ACCESS_KEY" \
--set integration.config.accountReadRoleName="$YOUR_ACCOUNT_READ_ROLE_NAME" \
--set integration.config.organizationRoleArn="$YOUR_ORGANIZATION_ROLE_ARN" \
--set integration.config.maximumConcurrentAccounts=50
If you are using IRSA, you'll need to:
- Create an IAM role with the following permissions:
arn:aws:iam::aws:policy/ReadOnlyAccessaccount:ListRegionssts:AssumeRole
- Create a service account in your K8s cluster, then assign the appropriate IAM role to the service account.
You should have the following information ready:
- Port API credentials, you can check out the Port API documentation.
PORT_CLIENT_IDPORT_CLIENT_SECRET
- Kubernetes service account name (
SERVICE_ACCOUNT) with the IAM role attached.
Helm installation command (click to expand)
helm repo add --force-update port-labs https://port-labs.github.io/helm-charts
helm upgrade --install aws port-labs/port-ocean \
--set port.clientId="$PORT_CLIENT_ID" \
--set port.clientSecret="$PORT_CLIENT_SECRET_ID" \
--set port.baseUrl="https://api.port.io" \
--set initializePortResources=true \
--set sendRawDataExamples=true \
--set scheduledResyncInterval=1440 \
--set integration.identifier="my-aws" \
--set integration.type="aws" \
--set integration.eventListener.type="POLLING" \
--set integration.config.maximumConcurrentAccounts=50 \
--set podServiceAccount.name="$SERVICE_ACCOUNT"
The port.baseUrl and OCEAN__PORT__BASE_URL parameters select which Port API instance to use:
- EU (app.port.io) →
https://api.port.io - US (app.us.port.io) →
https://api.us.port.io
Multiple account support
For running the AWS integration with multiple accounts using Helm, you'll need to make sure that you have the following (check out our multiple accounts guide for how to get them):
- An organization role ARN.
- A role with Read permissions set up across your AWS accounts.
- IRSA or a user with the previous read-permissions role bound to them.
Helm multi-account command (click to expand)
helm repo add --force-update port-labs https://port-labs.github.io/helm-charts
helm upgrade --install aws port-labs/port-ocean \
--set port.clientId="$PORT_CLIENT_ID" \
--set port.clientSecret="$PORT_CLIENT_SECRET_ID" \
--set port.baseUrl="https://api.port.io" \
--set initializePortResources=true \
--set sendRawDataExamples=true \
--set scheduledResyncInterval=1440 \
--set integration.identifier="my-aws" \
--set integration.type="aws" \
--set integration.eventListener.type="POLLING" \
--set podServiceAccount.name="$SERVICE_ACCOUNT" \
--set integration.config.accountReadRoleName="$YOUR_ACCOUNT_READ_ROLE_NAME" \
--set integration.config.organizationRoleArn="$YOUR_ORGANIZATION_ROLE_ARN" \
--set integration.config.maximumConcurrentAccounts=50
The AWS integration is deployed using Terraform on AWS ECS cluster service. It uses our Terraform Ocean Integration Factory module to deploy the integration.
This installation guide is for the AWS integration only.
It does not take into consideration the live events infrastructure which is optional.
The variables referring to live events (such as live_events_api_key) are optional and can be removed if not needed. Note that live_events_api_key is a secret you define yourself (not an AWS credential) - see the variables table below for details.
Use the following Terraform installation command to deploy the AWS integration:
Terraform installation command (click to expand)
# Logging into your AWS account
aws sso login
# Copying the following module into a main.tf file
echo 'module "aws" {
source = "port-labs/integration-factory/ocean//examples/aws_container_app"
version = ">=0.0.24"
port = {
client_id = "$PORT_CLIENT_ID"
client_secret = "$PORT_CLIENT_SECRET_ID"
base_url = "https://api.port.io"
}
initialize_port_resources = true # When set to true the integration will create default blueprints + JQ Mappings
scheduled_resync_interval = 1440
integration = {
identifier = "my-aws-integration" # Change the identifier to describe your integration
config = {
live_events_api_key = "$YOUR_CUSTOM_API_KEY" # A secret you define to secure your live events endpoint
}
}
event_listener = {
type = "POLLING"
}
allow_incoming_requests = true # Whether to allow incoming requests
create_default_sg = false # Whether to create the default security group
subnets = ["subnet-1","subnet-2","subnet-3"] # The subnets to deploy the LB to
vpc_id = "vpc-1" # The LB VPC ID
cluster_name = "port-ocean-aws-exporter" # The ECS cluster name
}' > main.tf
# Initializing Terraform and Providers
terraform init
# Creating the resources
terraform apply
Terraform variables (click to expand)
| Variable | Description |
|---|---|
subnets | List of subnet IDs where the ECS tasks will run. |
port.client_id | The client ID for the Port integration. |
port.client_secret | The client secret for the Port integration. |
integration.identifier | The identifier for the integration. |
integration.config.live_events_api_key | A secret string that you define to secure incoming requests to your live events endpoint. This is not an AWS key. You can use any secure random string (e.g. generate one using openssl rand -hex 32). AWS EventBridge will include this key when sending events to your integration, allowing it to validate that requests are legitimate. |
integration.config.organization_role_arn (optional) | ARN of the role used to assume the organization role. |
integration.config.account_read_role_name (optional) | Name of the role used to assume the read role in the account. |
integration.config.maximum_concurrent_accounts (optional) | Maximum number of accounts to sync concurrently. |
cluster_name (optional) | Name of the ECS cluster. |
vpc_id | VPC ID where the cluster will be created. |
initialize_port_resources | Boolean to initialize Port resources. |
scheduled_resync_interval | The interval to resync the integration in minutes. |
create_default_sg | Boolean to create a default security group. |
allow_incoming_requests | Boolean to allow incoming requests to the ECS tasks. |
Infrastructure
The AWS integration uses the following AWS infrastructure:
- AWS ECS Cluster Service.
- AWS ECS Cluster (creates a new one by default).
- AWS ECS Task Role.
- AWS ECS Task Execution Role.
- AWS EC2 Load Balancer.
- AWS SSM Parameter Store.
- AWS API Gateway.
- AWS EventBridge Rules.
Live events diagram (click to expand)
Run the Docker command
docker run -i --rm --platform=linux/amd64 \
-e OCEAN__PORT__CLIENT_ID="$PORT_CLIENT_ID" \
-e OCEAN__PORT__CLIENT_SECRET="$PORT_CLIENT_SECRET" \
-e OCEAN__PORT__BASE_URL="https://api.port.io" \
-e OCEAN__INITIALIZE_PORT_RESOURCES=true \
-e OCEAN__SEND_RAW_DATA_EXAMPLES=true \
-e OCEAN__EVENT_LISTENER='{"type": "ONCE"}' \
-e OCEAN__INTEGRATION__CONFIG__AWS_ACCESS_KEY_ID=$AWS_ACCESS_KEY_ID \
-e OCEAN__INTEGRATION__CONFIG__AWS_SECRET_ACCESS_KEY=$AWS_SECRET_ACCESS_KEY \
-e OCEAN__INTEGRATION__CONFIG__MAXIMUM_CONCURRENT_ACCOUNTS=50 \
ghcr.io/port-labs/port-ocean-aws:latest
- Multiple account support : enable the integration to collect data from multiple AWS accounts.
- Live events : set up real-time event processing after completing the installation.
Recommended resource sizes
To ensure optimal performance and avoid out-of-memory (OOM) errors, we recommend the following resources for this integration:
- CPU Limit:
800m - CPU Request:
200m - Memory Limit:
2Gi - Memory Request:
2Gi
Set resource values using the commands below:
helm install my-integration port-labs/port-ocean \
# ... other parameters
--set ocean.resources.limits.cpu=800m \
--set ocean.resources.limits.memory=2Gi \
--set ocean.resources.requests.cpu=200m \
--set ocean.resources.requests.memory=2Gi
Configuration
Port integrations use a YAML mapping block to ingest data from the third-party api into Port.
The mapping makes use of the JQ JSON processor 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 the AWS Legacy integration.
Default mapping configuration (click to expand)
resources:
- kind: AWS::Organizations::Account
selector:
query: 'true'
port:
entity:
mappings:
identifier: .Id
title: .Name
blueprint: '"awsAccount"'
properties:
arn: .Arn
email: .Email
status: .Status
joined_method: .JoinedMethod
joined_timestamp: .JoinedTimestamp | sub(" "; "T")
- kind: AWS::S3::Bucket
selector:
query: 'true'
useGetResourceAPI: 'true'
port:
entity:
mappings:
identifier: .Identifier
title: .Identifier
blueprint: '"cloudResource"'
properties:
kind: .__Kind
region: .Properties.RegionalDomainName | capture(".*\\.(?<region>[^\\.]+)\\.amazonaws\\.com")
| .region
tags: .Properties.Tags
arn: .Properties.Arn
link: .Properties | select(.Arn != null) | "https://console.aws.amazon.com/go/view?arn="
+ .Arn
relations:
account: .__AccountId
- kind: AWS::EC2::Instance
selector:
query: 'true'
port:
entity:
mappings:
identifier: .Identifier
title: .Identifier
blueprint: '"cloudResource"'
properties:
kind: .__Kind
region: .__Region
tags: .Properties.Tags
arn: .Properties.Arn
link: .Properties | select(.Arn != null) | "https://console.aws.amazon.com/go/view?arn="
+ .Arn
relations:
account: .__AccountId
- kind: AWS::ECS::Cluster
selector:
query: 'true'
useGetResourceAPI: 'true'
port:
entity:
mappings:
identifier: .Properties.Arn
title: .Identifier
blueprint: '"cloudResource"'
properties:
kind: .__Kind
region: .__Region
tags: .Properties.Tags
arn: .Properties.Arn
link: .Properties | select(.Arn != null) | "https://console.aws.amazon.com/go/view?arn="
+ .Arn
relations:
account: .__AccountId
Monitoring and sync status
To learn more about how to monitor and check the sync status of your integration, see the relevant documentation.
Mapping & selectors per resource
Use the explorer below to view the mapping and blueprint definition for each resource type. For additional resources and advanced configurations, see the examples page.
{
"identifier": "awsAccount",
"title": "AWS Account",
"icon": "AWS",
"schema": {
"properties": {
"arn": {
"type": "string",
"title": "ARN"
},
"email": {
"type": "string",
"title": "Email"
},
"status": {
"type": "string",
"title": "Status",
"enum": ["ACTIVE", "SUSPENDED", "PENDING_CLOSURE"],
"enumColors": {
"ACTIVE": "green",
"SUSPENDED": "red",
"PENDING_CLOSURE": "yellow"
}
},
"joined_method": {
"type": "string",
"title": "Joined Method",
"enum": ["INVITED", "CREATED"]
},
"joined_timestamp": {
"type": "string",
"title": "Joined Timestamp",
"format": "date-time"
}
},
"required": []
},
"mirrorProperties": {},
"calculationProperties": {},
"aggregationProperties": {},
"relations": {}
}
- kind: AWS::Organizations::Account
selector:
query: 'true'
port:
entity:
mappings:
identifier: .Id
title: .Name
blueprint: '"awsAccount"'
properties:
arn: .Arn
email: .Email
status: .Status
joined_method: .JoinedMethod
joined_timestamp: .JoinedTimestamp | sub(" "; "T")
Further examples
Refer to the examples page for practical configurations and their corresponding blueprint definitions.