Installation

Permissions

• To get Port API credentials, you check out the Port API documentation.
• In order to successfully deploy the AWS 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).

Multiple Account Support

To do the following:

1. Enable multiple accounts for the integration.
2. View account data.

Make sure you set up properly using our Multiple Accounts guide

Choose one of the following installation methods:

Helm (Scheduled)

The AWS integration is deployed using Helm on you cluster. You can check out the Helm chart here.

Prerequisites

IAM User

• create IAM user with the following permissions:
  • arn:aws:iam::aws:policy/ReadOnlyAccess
  • account:ListRegions
  • sts:AssumeRole
• Helm 3
• A logged in aws CLI 2
• AWS Access Key ID and Secret Access Key

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.getport.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"

IRSA

If you are using IRSA. You'll need to:

• create an IAM role with the following permissions:
  • arn:aws:iam::aws:policy/ReadOnlyAccess
  • account:ListRegions
  • sts:AssumeRole
• create a service account in your K8s cluster. Then you can set the following values, after assigning the appropriate IAM role to the service account:

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.getport.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"

Multiple account support

For running the AWS integration using helm, you'll need to make sure that you have the following: (Check out our multiple accounts guide for how to get them)

1. An organization role ARN
2. A Role with Read permissions set-up across your AWS accounts
3. IRSA or a user with the previous read-permissions role bound to them.

Then, you'll be able to run the integration: (You can switch the podServiceAccount.name configuration to your integration.config.awsAccessKeyId, integration.config.awsSecretAccessKey configurations)

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.getport.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"

Terraform (Real Time)

The AWS integration is deployed using Terraform on AWS ECS cluster service.
It uses our Terraform Ocean Integration Factory module to deploy the integration.

Prerequisites

• Terraform >= 1.9.1
• A logged in aws CLI 2
• Certificate domain name (Optional)

Live-Events

This installation guide is for the AWS integration only. It does not take into consideration the live-events infrastructure which is optional. The env variables referring to the live events (such as LIVE_EVENTS_API_KEY) are optional and can be removed if not needed.

	# Logging into you 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.getport.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" # AWS API Key for custom events, used to validate the event source for real-time event updates.
		}
	}
	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

Variables

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 user-defined API key for authenticating with the live events API, for example "my-secret".
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.
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

On Prem (Once)

Prerequisites

• Create an IAM user with the following permissions:
  • arn:aws:iam::aws:policy/ReadOnlyAccess
  • account:ListRegions
  • sts:AssumeRole
• Run the following Docker image: ghcr.io/port-labs/port-ocean-aws:latest.
• (For live updates): expose the port 8000 to the internet.
• Add the following environment variables to the Docker container:

Environment Variables

Variable	Description
OCEAN__PORT__CLIENT_ID	Your Port client ID.
OCEAN__PORT__CLIENT_SECRET	Your Port client secret.
OCEAN__PORT__BASE_URL	Your Port API URL - https://api.getport.io for EU, https://api.us.getport.io for US
OCEAN__INTEGRATION__CONFIG__AWS_ACCESS_KEY_ID	The AWS Access Key ID of the IAM user.
OCEAN__INTEGRATION__CONFIG__AWS_SECRET_ACCESS_KEY	The AWS Secret Access Key of the IAM user.
OCEAN__INTEGRATION__CONFIG__LIVE_EVENTS_API_KEY	(Optional) AWS API Key for live events, used to validate the event source for real-time event, it's value is completely up to you
OCEAN__INTEGRATION__CONFIG__ORGANIZATION_ROLE_ARN	(Optional) AWS Organization Role ARN, in case the account the integration is installed on is not the root account, 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 the account in which the integration is not installed on, used for multi-account access..
OCEAN__EVENT_LISTENER	The event listener object.
OCEAN__INTEGRATION__IDENTIFIER	The identifier of the integration.
OCEAN__INTEGRATION__TYPE	should be set to aws.

For example:

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.getport.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 \
ghcr.io/port-labs/port-ocean-aws:latest

Further Examples

Refer to the examples page for practical configurations and their corresponding blueprint definitions.