From ceff42e272077c81cf2441ec452e9a4a13b248fc Mon Sep 17 00:00:00 2001 From: Shalev Avhar Date: Sun, 28 Sep 2025 13:49:46 +0300 Subject: [PATCH 1/5] feat: Add live events setup documentation for AWS integration This new document outlines the process for configuring live events in Port's AWS integration, including prerequisites, setup methods (Terraform and manual), testing procedures, and troubleshooting tips. It also details supported AWS services and resource types for real-time event processing. --- .../aws/installations/live-events.md | 269 ++++++++++++++++++ 1 file changed, 269 insertions(+) create mode 100644 docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws/installations/live-events.md diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws/installations/live-events.md b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws/installations/live-events.md new file mode 100644 index 0000000000..19a75843e2 --- /dev/null +++ b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws/installations/live-events.md @@ -0,0 +1,269 @@ +--- +sidebar_position: 3 +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import Image from "@theme/IdealImage"; + +# Live Events Setup + +Port's AWS integration supports real-time event processing, allowing for accurate real-time representation of your AWS infrastructure inside Port. This guide explains how to set up live events for your AWS resources. + +:::info Current Limitations +Live events are currently only available for: +- **Single account installations** (not multi-account) +- **Default Terraform installation** with support for 3 resource types by default: + - EC2 Instances + - S3 Buckets + - CloudFormation Stacks +::: + +## Prerequisites + +Before setting up live events, ensure you have: + +1. **AWS Integration Installed**: Complete the [AWS integration installation](./installation.md) first +2. **API Gateway Setup**: The integration requires an API Gateway endpoint (automatically created with Terraform installation) +3. **Port API Key**: Your Port API key for authentication +4. **AWS Permissions**: Ability to create EventBridge rules in your AWS account + +:::tip Terraform vs Manual Installation +- **Terraform users**: Use the provided Terraform module for automated setup +- **Manual installation users**: Follow the AWS console setup steps +::: + +## How Live Events Work + + + +Live events work by: + +1. **AWS Services** generate events when resources change +2. **CloudTrail** captures these events +3. **EventBridge Rules** filter and route specific events +4. **API Gateway** receives the events and forwards them to Port +5. **Port Integration** processes the events and updates your software catalog + +## Setup Methods + + + + +If you installed the AWS integration using Terraform, use the provided module to set up live events. + +### Supported Resource Types + +The default Terraform module supports live events for these resource types: + +- **EC2 Instances** (`AWS::EC2::Instance`) +- **S3 Buckets** (`AWS::S3::Bucket`) +- **CloudFormation Stacks** (`AWS::CloudFormation::Stack`) + +### Adding Custom Resource Types + +To add live events for additional resource types (like SSM Parameters), use the `aws_event_rule` module: + +```hcl +module "aws_event_rule" { + source = "port-labs/integration-factory/ocean//modules/aws_helpers/event" + + name = "port-aws-ocean-sync-ssm-parameters" + description = "Capture Parameter Store change events" + + event_pattern = { + source = ["aws.ssm"] + detail-type = ["Parameter Store Change"] + } + + input_paths = { + resource_type = "AWS::SSM::Parameter" + account_id = "$.account" + aws_region = "$.region" + event_name = "$.detail-type" + identifier = "$.resources.0" + } + + api_key_param = "" + target_arn = "/production/POST/integration/webhook" +} +``` + +### Configuration Parameters + +| Parameter | Description | Example | +|-----------|-------------|---------| +| `name` | EventBridge rule name | `"port-aws-ocean-sync-ssm-parameters"` | +| `description` | Rule description | `"Capture Parameter Store change events"` | +| `event_pattern` | AWS event pattern to match | `{ source = ["aws.ssm"], detail-type = ["Parameter Store Change"] }` | +| `input_paths` | JSON path mappings for event transformation | See example above | +| `api_key_param` | Port API key parameter | `""` | +| `target_arn` | API Gateway target ARN | `"/production/POST/integration/webhook"` | + + + + +If you installed the AWS integration manually, follow these steps to create EventBridge rules in the AWS console. + +### Step 1: Create a Rule + +1. Go to **EventBridge** → **Rules** → **Create rule** +2. **Rule name**: Give it a descriptive name (e.g., `port-live-updates-ssm`) +3. Click **Next** + +### Step 2: Define the Event Pattern + +1. **Event source**: Select "AWS events or services" +2. **Event service**: Select the relevant AWS service (e.g., "Systems Manager") +3. **Event type**: Select the type of event (e.g., "Parameter Store") +4. **Event Type Specification**: Select "Specific detail type(s)" and choose the event type (e.g., "Parameter Store Change") +5. Click **Next** + +### Step 3: Configure the Target + +1. **Target type**: Select "AWS Service" +2. **Target**: Select "API Gateway" +3. **Target location**: Select "Target in this account" +4. **API**: Select the API Gateway created for your integration +5. **Deployment stage**: Select "production" +6. **Integration target**: Enter `/integration/webhook` (HTTP POST) + +### Step 4: Add Required Headers + +Add these required headers: + +| Header Name | Value | +|-------------|-------| +| `Content-Type` | `application/json` | +| `x-port-aws-ocean-api-key` | `` (replace with actual key) | + +### Step 5: Transform the Event Data + +Port expects a simplified payload. Use Input Transformer to map the raw AWS event: + +**Input Path (mapping):** +```json +{ + "accountId": "$.account", + "awsRegion": "$.region", + "eventName": "$.detail-type", + "identifier": "$.resources.0" +} +``` + +**Template (output):** +```json +{ + "resource_type": "AWS::SSM::Parameter", + "accountId": "", + "awsRegion": "", + "eventName": "", + "identifier": "" +} +``` + +:::tip Resource Type Mapping +Replace `"AWS::SSM::Parameter"` with the appropriate AWS resource type: +- EC2 Instances: `"AWS::EC2::Instance"` +- S3 Buckets: `"AWS::S3::Bucket"` +- CloudFormation Stacks: `"AWS::CloudFormation::Stack"` +::: + +### Step 6: Review & Create + +1. Click **Next** → **Next** → **Create rule** +2. AWS will now forward matching events to Port automatically + + + + +## Testing Your Setup + +### Verify Existing Rules + +If you have other live event rules (e.g., S3 Bucket sync), verify they're working: + +1. Go to **EventBridge** → **Rules** +2. Check that your rules are **Enabled** +3. Look for any recent invocations in the **Metrics** tab + +### Test Live Events + +1. **Trigger a test event**: + - Modify/create a resource (e.g., create an SSM Parameter) + - Update an existing resource + - Delete a resource + +2. **Verify in Port**: + - Check your software catalog for real-time updates + - Look for the resource changes in Port's interface + +### Example Test for SSM Parameters + +1. Go to **Systems Manager** → **Parameter Store** +2. Create a new parameter: + - Name: `/test/my-parameter` + - Type: `String` + - Value: `test-value` +3. Check Port for the new parameter entity + +## Troubleshooting + +### Common Issues + +**Events not appearing in Port:** +- Verify the EventBridge rule is enabled +- Check that the API Gateway endpoint is correct +- Ensure the Port API key is valid +- Verify the input transformer mapping is correct + +**Wrong resource type in Port:** +- Check the `resource_type` field in your input transformer template +- Ensure it matches the expected AWS resource type + +**Missing headers:** +- Verify both `Content-Type` and `x-port-aws-ocean-api-key` headers are set +- Check that the API key is the correct one for your Port environment + +### Debugging Steps + +1. **Check EventBridge Metrics**: + - Go to EventBridge → Rules → Your Rule → Metrics + - Look for successful invocations and any errors + +2. **Check API Gateway Logs**: + - Go to API Gateway → Your API → Stages → production → Logs + - Look for incoming requests and any errors + +3. **Verify Event Pattern**: + - Test your event pattern with sample events + - Use EventBridge's "Test pattern" feature + +## Supported AWS Services + +The following AWS services can be configured for live events: + +| Service | Event Source | Detail Type | Resource Type | +|---------|--------------|-------------|---------------| +| EC2 | `aws.ec2` | `EC2 Instance State-change Notification` | `AWS::EC2::Instance` | +| S3 | `aws.s3` | `Object Created`, `Object Deleted` | `AWS::S3::Bucket` | +| CloudFormation | `aws.cloudformation` | `CloudFormation Stack State Change` | `AWS::CloudFormation::Stack` | +| Systems Manager | `aws.ssm` | `Parameter Store Change` | `AWS::SSM::Parameter` | + +:::info Adding More Services +To add live events for additional AWS services, follow the same pattern: +1. Identify the service's event source and detail type +2. Create an EventBridge rule with the appropriate pattern +3. Configure the input transformer with the correct resource type +::: + +## Next Steps + +After setting up live events: + +1. **Monitor Performance**: Keep an eye on EventBridge metrics and API Gateway logs +2. **Scale as Needed**: Add more resource types as your requirements grow +3. **Optimize Patterns**: Fine-tune event patterns to reduce noise and improve performance + +For more advanced configuration options, see the [AWS integration examples](../examples/examples.md). + From 79591b312a7e38499655b5f6c257f024cf5a9f80 Mon Sep 17 00:00:00 2001 From: Sivan Elkabes Date: Mon, 13 Oct 2025 10:34:01 +0300 Subject: [PATCH 2/5] Fixed styling issues --- .../aws/installations/live-events.md | 70 +++++++++---------- 1 file changed, 35 insertions(+), 35 deletions(-) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws/installations/live-events.md b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws/installations/live-events.md index 19a75843e2..905a7c93c6 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws/installations/live-events.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws/installations/live-events.md @@ -6,53 +6,53 @@ import Tabs from "@theme/Tabs"; import TabItem from "@theme/TabItem"; import Image from "@theme/IdealImage"; -# Live Events Setup +# Live events setup Port's AWS integration supports real-time event processing, allowing for accurate real-time representation of your AWS infrastructure inside Port. This guide explains how to set up live events for your AWS resources. :::info Current Limitations Live events are currently only available for: -- **Single account installations** (not multi-account) -- **Default Terraform installation** with support for 3 resource types by default: - - EC2 Instances - - S3 Buckets - - CloudFormation Stacks +- **Single account installations** (not multi-account). +- **Default Terraform installation** with support for three resource types by default: + - EC2 Instances. + - S3 Buckets. + - CloudFormation Stacks. ::: ## Prerequisites Before setting up live events, ensure you have: -1. **AWS Integration Installed**: Complete the [AWS integration installation](./installation.md) first -2. **API Gateway Setup**: The integration requires an API Gateway endpoint (automatically created with Terraform installation) -3. **Port API Key**: Your Port API key for authentication -4. **AWS Permissions**: Ability to create EventBridge rules in your AWS account +- **AWS Integration Installed**: Complete the [AWS integration installation](./installation.md). +- **API Gateway Setup**: The integration requires an API Gateway endpoint (automatically created with Terraform installation). +- **Port API Key**: Your Port API key for authentication. +- **AWS Permissions**: Ability to create EventBridge rules in your AWS account. :::tip Terraform vs Manual Installation - **Terraform users**: Use the provided Terraform module for automated setup - **Manual installation users**: Follow the AWS console setup steps ::: -## How Live Events Work +## How live events work - + Live events work by: -1. **AWS Services** generate events when resources change -2. **CloudTrail** captures these events -3. **EventBridge Rules** filter and route specific events -4. **API Gateway** receives the events and forwards them to Port -5. **Port Integration** processes the events and updates your software catalog +1. **AWS Services** generate events when resources change. +2. **CloudTrail** captures these events. +3. **EventBridge Rules** filter and route specific events. +4. **API Gateway** receives the events and forwards them to Port. +5. **Port Integration** processes the events and updates your software catalog. -## Setup Methods +## Setup methods If you installed the AWS integration using Terraform, use the provided module to set up live events. -### Supported Resource Types +

Supported resource types

The default Terraform module supports live events for these resource types: @@ -60,11 +60,11 @@ The default Terraform module supports live events for these resource types: - **S3 Buckets** (`AWS::S3::Bucket`) - **CloudFormation Stacks** (`AWS::CloudFormation::Stack`) -### Adding Custom Resource Types +

Adding custom resource types

To add live events for additional resource types (like SSM Parameters), use the `aws_event_rule` module: -```hcl +```hcl showLineNumbers module "aws_event_rule" { source = "port-labs/integration-factory/ocean//modules/aws_helpers/event" @@ -89,7 +89,7 @@ module "aws_event_rule" { } ``` -### Configuration Parameters +

Configuration parameters

| Parameter | Description | Example | |-----------|-------------|---------| @@ -105,13 +105,13 @@ module "aws_event_rule" { If you installed the AWS integration manually, follow these steps to create EventBridge rules in the AWS console. -### Step 1: Create a Rule +

Step 1: Create a rule

1. Go to **EventBridge** → **Rules** → **Create rule** 2. **Rule name**: Give it a descriptive name (e.g., `port-live-updates-ssm`) 3. Click **Next** -### Step 2: Define the Event Pattern +

Step 2: Define the event pattern

1. **Event source**: Select "AWS events or services" 2. **Event service**: Select the relevant AWS service (e.g., "Systems Manager") @@ -119,7 +119,7 @@ If you installed the AWS integration manually, follow these steps to create Even 4. **Event Type Specification**: Select "Specific detail type(s)" and choose the event type (e.g., "Parameter Store Change") 5. Click **Next** -### Step 3: Configure the Target +

Step 3: Configure the target

1. **Target type**: Select "AWS Service" 2. **Target**: Select "API Gateway" @@ -128,7 +128,7 @@ If you installed the AWS integration manually, follow these steps to create Even 5. **Deployment stage**: Select "production" 6. **Integration target**: Enter `/integration/webhook` (HTTP POST) -### Step 4: Add Required Headers +

Step 4: Add required headers

Add these required headers: @@ -137,12 +137,12 @@ Add these required headers: | `Content-Type` | `application/json` | | `x-port-aws-ocean-api-key` | `` (replace with actual key) | -### Step 5: Transform the Event Data +

Step 5: Transform the Event Data

Port expects a simplified payload. Use Input Transformer to map the raw AWS event: **Input Path (mapping):** -```json +```json showLineNumbers { "accountId": "$.account", "awsRegion": "$.region", @@ -152,7 +152,7 @@ Port expects a simplified payload. Use Input Transformer to map the raw AWS even ``` **Template (output):** -```json +```json showLineNumbers { "resource_type": "AWS::SSM::Parameter", "accountId": "", @@ -169,7 +169,7 @@ Replace `"AWS::SSM::Parameter"` with the appropriate AWS resource type: - CloudFormation Stacks: `"AWS::CloudFormation::Stack"` ::: -### Step 6: Review & Create +

Step 6: Review & Create

1. Click **Next** → **Next** → **Create rule** 2. AWS will now forward matching events to Port automatically @@ -177,9 +177,9 @@ Replace `"AWS::SSM::Parameter"` with the appropriate AWS resource type: -## Testing Your Setup +## Testing your setup -### Verify Existing Rules +### Verify existing rules If you have other live event rules (e.g., S3 Bucket sync), verify they're working: @@ -187,7 +187,7 @@ If you have other live event rules (e.g., S3 Bucket sync), verify they're workin 2. Check that your rules are **Enabled** 3. Look for any recent invocations in the **Metrics** tab -### Test Live Events +### Test live events 1. **Trigger a test event**: - Modify/create a resource (e.g., create an SSM Parameter) @@ -198,7 +198,7 @@ If you have other live event rules (e.g., S3 Bucket sync), verify they're workin - Check your software catalog for real-time updates - Look for the resource changes in Port's interface -### Example Test for SSM Parameters +### Example test for SSM parameters 1. Go to **Systems Manager** → **Parameter Store** 2. Create a new parameter: @@ -209,7 +209,7 @@ If you have other live event rules (e.g., S3 Bucket sync), verify they're workin ## Troubleshooting -### Common Issues +### Common issues **Events not appearing in Port:** - Verify the EventBridge rule is enabled From 8efe17f44e3251483a1cd4cea24978e089cde18b Mon Sep 17 00:00:00 2001 From: Sivan Elkabes Date: Mon, 13 Oct 2025 10:56:03 +0300 Subject: [PATCH 3/5] Edited the content of the page. --- .../aws/installations/live-events.md | 87 ++++++++++--------- 1 file changed, 47 insertions(+), 40 deletions(-) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws/installations/live-events.md b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws/installations/live-events.md index 905a7c93c6..32c49fb8f3 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws/installations/live-events.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws/installations/live-events.md @@ -8,36 +8,36 @@ import Image from "@theme/IdealImage"; # Live events setup -Port's AWS integration supports real-time event processing, allowing for accurate real-time representation of your AWS infrastructure inside Port. This guide explains how to set up live events for your AWS resources. +Port's AWS integration supports real-time event processing, allowing for accurate representation of your AWS infrastructure inside Port. This guide explains how to set up live events for your AWS resources. :::info Current Limitations Live events are currently only available for: - **Single account installations** (not multi-account). - **Default Terraform installation** with support for three resource types by default: - - EC2 Instances. - - S3 Buckets. - - CloudFormation Stacks. + - `EC2 Instances`. + - `S3 Buckets`. + - `CloudFormation Stacks`. ::: ## Prerequisites Before setting up live events, ensure you have: -- **AWS Integration Installed**: Complete the [AWS integration installation](./installation.md). -- **API Gateway Setup**: The integration requires an API Gateway endpoint (automatically created with Terraform installation). -- **Port API Key**: Your Port API key for authentication. -- **AWS Permissions**: Ability to create EventBridge rules in your AWS account. +- **AWS integration installed**: Complete the [AWS integration installation](./installation.md). +- **API Gateway setup**: The integration requires an API Gateway endpoint (automatically created with Terraform installation). +- **Port API key**: Your Port API key for authentication. +- **AWS permissions**: Ability to create EventBridge rules in your AWS account. :::tip Terraform vs Manual Installation -- **Terraform users**: Use the provided Terraform module for automated setup -- **Manual installation users**: Follow the AWS console setup steps +- **Terraform users**: Use the provided Terraform module for automated setup. +- **Manual installation users**: Follow the AWS console setup steps. ::: ## How live events work -Live events work by: +The live events flow follows these steps: 1. **AWS Services** generate events when resources change. 2. **CloudTrail** captures these events. @@ -64,6 +64,9 @@ The default Terraform module supports live events for these resource types: To add live events for additional resource types (like SSM Parameters), use the `aws_event_rule` module: +
+AWS event rule module (click to expand) + ```hcl showLineNumbers module "aws_event_rule" { source = "port-labs/integration-factory/ocean//modules/aws_helpers/event" @@ -88,8 +91,10 @@ module "aws_event_rule" { target_arn = "/production/POST/integration/webhook" } ``` +
-

Configuration parameters

+
+Configuration parameters (click to expand) | Parameter | Description | Example | |-----------|-------------|---------| @@ -100,6 +105,8 @@ module "aws_event_rule" { | `api_key_param` | Port API key parameter | `""` | | `target_arn` | API Gateway target ARN | `"/production/POST/integration/webhook"` | +
+ @@ -107,26 +114,26 @@ If you installed the AWS integration manually, follow these steps to create Even

Step 1: Create a rule

-1. Go to **EventBridge** → **Rules** → **Create rule** -2. **Rule name**: Give it a descriptive name (e.g., `port-live-updates-ssm`) -3. Click **Next** +1. Go to **EventBridge** → **Rules** → **Create rule**. +2. **Rule name**: Give it a descriptive name (e.g., `port-live-updates-ssm`). +3. Click **Next**.

Step 2: Define the event pattern

-1. **Event source**: Select "AWS events or services" -2. **Event service**: Select the relevant AWS service (e.g., "Systems Manager") -3. **Event type**: Select the type of event (e.g., "Parameter Store") -4. **Event Type Specification**: Select "Specific detail type(s)" and choose the event type (e.g., "Parameter Store Change") -5. Click **Next** +1. **Event source**: Select "AWS events or services". +2. **Event service**: Select the relevant AWS service (e.g., "Systems Manager"). +3. **Event type**: Select the type of event (e.g., "Parameter Store"). +4. **Event Type Specification**: Select "Specific detail type(s)" and choose the event type (e.g., "Parameter Store Change"). +5. Click **Next**.

Step 3: Configure the target

-1. **Target type**: Select "AWS Service" -2. **Target**: Select "API Gateway" -3. **Target location**: Select "Target in this account" -4. **API**: Select the API Gateway created for your integration -5. **Deployment stage**: Select "production" -6. **Integration target**: Enter `/integration/webhook` (HTTP POST) +1. **Target type**: Select "AWS Service". +2. **Target**: Select "API Gateway". +3. **Target location**: Select "Target in this account". +4. **API**: Select the API Gateway created for your integration. +5. **Deployment stage**: Select "production". +6. **Integration target**: Enter `/integration/webhook` (HTTP POST).

Step 4: Add required headers

@@ -171,8 +178,8 @@ Replace `"AWS::SSM::Parameter"` with the appropriate AWS resource type:

Step 6: Review & Create

-1. Click **Next** → **Next** → **Create rule** -2. AWS will now forward matching events to Port automatically +1. Click **Next** → **Next** → **Create rule**. +2. AWS will now forward matching events to Port automatically. @@ -183,20 +190,20 @@ Replace `"AWS::SSM::Parameter"` with the appropriate AWS resource type: If you have other live event rules (e.g., S3 Bucket sync), verify they're working: -1. Go to **EventBridge** → **Rules** -2. Check that your rules are **Enabled** -3. Look for any recent invocations in the **Metrics** tab +1. Go to **EventBridge** → **Rules**. +2. Check that your rules are **Enabled**. +3. Look for any recent invocations in the **Metrics** tab. ### Test live events 1. **Trigger a test event**: - - Modify/create a resource (e.g., create an SSM Parameter) - - Update an existing resource - - Delete a resource + - Modify/create a resource (e.g., create an SSM Parameter). + - Update an existing resource. + - Delete a resource. 2. **Verify in Port**: - - Check your software catalog for real-time updates - - Look for the resource changes in Port's interface + - Check your software catalog for real-time updates. + - Look for the resource changes in Port's interface. ### Example test for SSM parameters @@ -205,7 +212,7 @@ If you have other live event rules (e.g., S3 Bucket sync), verify they're workin - Name: `/test/my-parameter` - Type: `String` - Value: `test-value` -3. Check Port for the new parameter entity +3. Check Port for the new parameter entity. ## Troubleshooting @@ -261,9 +268,9 @@ To add live events for additional AWS services, follow the same pattern: After setting up live events: -1. **Monitor Performance**: Keep an eye on EventBridge metrics and API Gateway logs -2. **Scale as Needed**: Add more resource types as your requirements grow -3. **Optimize Patterns**: Fine-tune event patterns to reduce noise and improve performance +1. **Monitor Performance**: Keep an eye on EventBridge metrics and API Gateway logs. +2. **Scale as Needed**: Add more resource types as your requirements grow. +3. **Optimize Patterns**: Fine-tune event patterns to reduce noise and improve performance. For more advanced configuration options, see the [AWS integration examples](../examples/examples.md). From f2fcc13b81972c21dafcde31480428de64a0ae7b Mon Sep 17 00:00:00 2001 From: Sivan Elkabes Date: Sun, 19 Oct 2025 15:05:47 +0300 Subject: [PATCH 4/5] update live-events page with Shalev --- .../aws/installations/live-events.md | 106 +++--------------- 1 file changed, 16 insertions(+), 90 deletions(-) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws/installations/live-events.md b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws/installations/live-events.md index 32c49fb8f3..5a5c617b61 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws/installations/live-events.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws/installations/live-events.md @@ -11,12 +11,7 @@ import Image from "@theme/IdealImage"; Port's AWS integration supports real-time event processing, allowing for accurate representation of your AWS infrastructure inside Port. This guide explains how to set up live events for your AWS resources. :::info Current Limitations -Live events are currently only available for: -- **Single account installations** (not multi-account). -- **Default Terraform installation** with support for three resource types by default: - - `EC2 Instances`. - - `S3 Buckets`. - - `CloudFormation Stacks`. +Live events are currently only available for **Single account installations** (not multi-account). ::: ## Prerequisites @@ -35,8 +30,6 @@ Before setting up live events, ensure you have: ## How live events work - - The live events flow follows these steps: 1. **AWS Services** generate events when resources change. @@ -45,6 +38,9 @@ The live events flow follows these steps: 4. **API Gateway** receives the events and forwards them to Port. 5. **Port Integration** processes the events and updates your software catalog. + +

+ ## Setup methods @@ -184,93 +180,23 @@ Replace `"AWS::SSM::Parameter"` with the appropriate AWS resource type: -## Testing your setup - -### Verify existing rules - -If you have other live event rules (e.g., S3 Bucket sync), verify they're working: - -1. Go to **EventBridge** → **Rules**. -2. Check that your rules are **Enabled**. -3. Look for any recent invocations in the **Metrics** tab. - -### Test live events - -1. **Trigger a test event**: - - Modify/create a resource (e.g., create an SSM Parameter). - - Update an existing resource. - - Delete a resource. - -2. **Verify in Port**: - - Check your software catalog for real-time updates. - - Look for the resource changes in Port's interface. - -### Example test for SSM parameters - -1. Go to **Systems Manager** → **Parameter Store** -2. Create a new parameter: - - Name: `/test/my-parameter` - - Type: `String` - - Value: `test-value` -3. Check Port for the new parameter entity. -## Troubleshooting +## Supported AWS services -### Common issues +The complete list of AWS services that support live events can be found [here](https://docs.aws.amazon.com/cloudcontrolapi/latest/userguide/supported-resources.html). -**Events not appearing in Port:** -- Verify the EventBridge rule is enabled -- Check that the API Gateway endpoint is correct -- Ensure the Port API key is valid -- Verify the input transformer mapping is correct +### Add other services -**Wrong resource type in Port:** -- Check the `resource_type` field in your input transformer template -- Ensure it matches the expected AWS resource type +To add live events for additional AWS services, follow these steps: +1. Identify the service's event source and detail type. +2. Create an EventBridge rule with the appropriate pattern. +3. Configure the input transformer with the correct resource type. -**Missing headers:** -- Verify both `Content-Type` and `x-port-aws-ocean-api-key` headers are set -- Check that the API key is the correct one for your Port environment +:::info Default Terraform installation -### Debugging Steps - -1. **Check EventBridge Metrics**: - - Go to EventBridge → Rules → Your Rule → Metrics - - Look for successful invocations and any errors - -2. **Check API Gateway Logs**: - - Go to API Gateway → Your API → Stages → production → Logs - - Look for incoming requests and any errors - -3. **Verify Event Pattern**: - - Test your event pattern with sample events - - Use EventBridge's "Test pattern" feature - -## Supported AWS Services - -The following AWS services can be configured for live events: - -| Service | Event Source | Detail Type | Resource Type | -|---------|--------------|-------------|---------------| -| EC2 | `aws.ec2` | `EC2 Instance State-change Notification` | `AWS::EC2::Instance` | -| S3 | `aws.s3` | `Object Created`, `Object Deleted` | `AWS::S3::Bucket` | -| CloudFormation | `aws.cloudformation` | `CloudFormation Stack State Change` | `AWS::CloudFormation::Stack` | -| Systems Manager | `aws.ssm` | `Parameter Store Change` | `AWS::SSM::Parameter` | - -:::info Adding More Services -To add live events for additional AWS services, follow the same pattern: -1. Identify the service's event source and detail type -2. Create an EventBridge rule with the appropriate pattern -3. Configure the input transformer with the correct resource type +with support for three resource types by default: + - `EC2 Instances`. + - `S3 Buckets`. + - `CloudFormation Stacks`. ::: -## Next Steps - -After setting up live events: - -1. **Monitor Performance**: Keep an eye on EventBridge metrics and API Gateway logs. -2. **Scale as Needed**: Add more resource types as your requirements grow. -3. **Optimize Patterns**: Fine-tune event patterns to reduce noise and improve performance. - -For more advanced configuration options, see the [AWS integration examples](../examples/examples.md). - From a1571807bc830097935b4ccdaf5867ee508cee3e Mon Sep 17 00:00:00 2001 From: Sivan Elkabes Date: Sun, 19 Oct 2025 16:53:57 +0300 Subject: [PATCH 5/5] Attend the CR comments --- .../aws/installations/live-events.md | 21 +++++++++---------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws/installations/live-events.md b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws/installations/live-events.md index 5a5c617b61..a233bad634 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws/installations/live-events.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws/installations/live-events.md @@ -10,7 +10,7 @@ import Image from "@theme/IdealImage"; Port's AWS integration supports real-time event processing, allowing for accurate representation of your AWS infrastructure inside Port. This guide explains how to set up live events for your AWS resources. -:::info Current Limitations +:::info Supported account type Live events are currently only available for **Single account installations** (not multi-account). ::: @@ -18,25 +18,24 @@ Live events are currently only available for **Single account installations** (n Before setting up live events, ensure you have: -- **AWS integration installed**: Complete the [AWS integration installation](./installation.md). -- **API Gateway setup**: The integration requires an API Gateway endpoint (automatically created with Terraform installation). -- **Port API key**: Your Port API key for authentication. -- **AWS permissions**: Ability to create EventBridge rules in your AWS account. +- Complete the [AWS integration installation](./installation.md). +- Your Port API key for authentication. +- Permissions to create EventBridge rules on your AWS account. :::tip Terraform vs Manual Installation - **Terraform users**: Use the provided Terraform module for automated setup. - **Manual installation users**: Follow the AWS console setup steps. ::: -## How live events work +## Live-events flow -The live events flow follows these steps: +The live events flow is comprised of the following steps: 1. **AWS Services** generate events when resources change. 2. **CloudTrail** captures these events. 3. **EventBridge Rules** filter and route specific events. 4. **API Gateway** receives the events and forwards them to Port. -5. **Port Integration** processes the events and updates your software catalog. +5. Your **Port Integration** processes the events and updates your software catalog.

@@ -56,7 +55,7 @@ The default Terraform module supports live events for these resource types: - **S3 Buckets** (`AWS::S3::Bucket`) - **CloudFormation Stacks** (`AWS::CloudFormation::Stack`) -

Adding custom resource types

+

Add custom resource types

To add live events for additional resource types (like SSM Parameters), use the `aws_event_rule` module: @@ -106,7 +105,7 @@ module "aws_event_rule" { -If you installed the AWS integration manually, follow these steps to create EventBridge rules in the AWS console. +If you installed the AWS integration manually, follow these steps to create EventBridge rules in the AWS console:

Step 1: Create a rule

@@ -194,7 +193,7 @@ To add live events for additional AWS services, follow these steps: :::info Default Terraform installation -with support for three resource types by default: +The default setup comes preconfigured with support for three AWS resource types: - `EC2 Instances`. - `S3 Buckets`. - `CloudFormation Stacks`.