Skip to content

Commit 8b06856

Browse files
sivanel97sivanel97
authored
Merge pull request #2844 from port-labs/PORT-16432-bug-add-documentation-for-aws-integration-live-events
feat: Add live events setup documentation for AWS integration
2 parents 2f09bb4 + 512959e commit 8b06856

File tree

1 file changed

+201
-0
lines changed
  • docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws/installations

1 file changed

+201
-0
lines changed

‎docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws/installations/live-events.md‎

Lines changed: 201 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,201 @@
1+
---
2+
sidebar_position: 3
3+
---
4+
5+
import Tabs from "@theme/Tabs";
6+
import TabItem from "@theme/TabItem";
7+
import Image from "@theme/IdealImage";
8+
9+
# Live events setup
10+
11+
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.
12+
13+
:::info Supported account type
14+
Live events are currently only available for **Single account installations** (not multi-account).
15+
:::
16+
17+
## Prerequisites
18+
19+
Before setting up live events, ensure you have:
20+
21+
- Complete the [AWS integration installation](./installation.md).
22+
- Your Port API key for authentication.
23+
- Permissions to create EventBridge rules on your AWS account.
24+
25+
:::tip Terraform vs Manual Installation
26+
- **Terraform users**: Use the provided Terraform module for automated setup.
27+
- **Manual installation users**: Follow the AWS console setup steps.
28+
:::
29+
30+
## Live-events flow
31+
32+
The live events flow is comprised of the following steps:
33+
34+
1. **AWS Services** generate events when resources change.
35+
2. **CloudTrail** captures these events.
36+
3. **EventBridge Rules** filter and route specific events.
37+
4. **API Gateway** receives the events and forwards them to Port.
38+
5. Your **Port Integration** processes the events and updates your software catalog.
39+
40+
<img src='/img/build-your-software-catalog/sync-data-to-catalog/cloud-providers/aws/live-events-diagram.svg' width='50%' border='1px' />
41+
<br></br>
42+
43+
## Setup methods
44+
45+
<Tabs>
46+
<TabItem value="terraform" label="Terraform (Recommended)" default>
47+
48+
If you installed the AWS integration using Terraform, use the provided module to set up live events.
49+
50+
<h3>Supported resource types</h3>
51+
52+
The default Terraform module supports live events for these resource types:
53+
54+
- **EC2 Instances** (`AWS::EC2::Instance`)
55+
- **S3 Buckets** (`AWS::S3::Bucket`)
56+
- **CloudFormation Stacks** (`AWS::CloudFormation::Stack`)
57+
58+
<h3>Add custom resource types</h3>
59+
60+
To add live events for additional resource types (like SSM Parameters), use the `aws_event_rule` module:
61+
62+
<details>
63+
<summary><b>AWS event rule module (click to expand)</b></summary>
64+
65+
```hcl showLineNumbers
66+
module "aws_event_rule" {
67+
source = "port-labs/integration-factory/ocean//modules/aws_helpers/event"
68+
69+
name = "port-aws-ocean-sync-ssm-parameters"
70+
description = "Capture Parameter Store change events"
71+
72+
event_pattern = {
73+
source = ["aws.ssm"]
74+
detail-type = ["Parameter Store Change"]
75+
}
76+
77+
input_paths = {
78+
resource_type = "AWS::SSM::Parameter"
79+
account_id = "$.account"
80+
aws_region = "$.region"
81+
event_name = "$.detail-type"
82+
identifier = "$.resources.0"
83+
}
84+
85+
api_key_param = "<live_events_api_key>"
86+
target_arn = "<api_gateway_arn>/production/POST/integration/webhook"
87+
}
88+
```
89+
</details>
90+
91+
<details>
92+
<summary><b>Configuration parameters (click to expand)</b></summary>
93+
94+
| Parameter | Description | Example |
95+
|-----------|-------------|---------|
96+
| `name` | EventBridge rule name | `"port-aws-ocean-sync-ssm-parameters"` |
97+
| `description` | Rule description | `"Capture Parameter Store change events"` |
98+
| `event_pattern` | AWS event pattern to match | `{ source = ["aws.ssm"], detail-type = ["Parameter Store Change"] }` |
99+
| `input_paths` | JSON path mappings for event transformation | See example above |
100+
| `api_key_param` | Port API key parameter | `"<live_events_api_key>"` |
101+
| `target_arn` | API Gateway target ARN | `"<api_gateway_arn>/production/POST/integration/webhook"` |
102+
103+
</details>
104+
105+
</TabItem>
106+
<TabItem value="manual" label="Manual AWS Console Setup">
107+
108+
If you installed the AWS integration manually, follow these steps to create EventBridge rules in the AWS console:
109+
110+
<h3>Step 1: Create a rule</h3>
111+
112+
1. Go to **EventBridge** → **Rules** → **Create rule**.
113+
2. **Rule name**: Give it a descriptive name (e.g., `port-live-updates-ssm`).
114+
3. Click **Next**.
115+
116+
<h3>Step 2: Define the event pattern</h3>
117+
118+
1. **Event source**: Select "AWS events or services".
119+
2. **Event service**: Select the relevant AWS service (e.g., "Systems Manager").
120+
3. **Event type**: Select the type of event (e.g., "Parameter Store").
121+
4. **Event Type Specification**: Select "Specific detail type(s)" and choose the event type (e.g., "Parameter Store Change").
122+
5. Click **Next**.
123+
124+
<h3>Step 3: Configure the target</h3>
125+
126+
1. **Target type**: Select "AWS Service".
127+
2. **Target**: Select "API Gateway".
128+
3. **Target location**: Select "Target in this account".
129+
4. **API**: Select the API Gateway created for your integration.
130+
5. **Deployment stage**: Select "production".
131+
6. **Integration target**: Enter `/integration/webhook` (HTTP POST).
132+
133+
<h3>Step 4: Add required headers</h3>
134+
135+
Add these required headers:
136+
137+
| Header Name | Value |
138+
|-------------|-------|
139+
| `Content-Type` | `application/json` |
140+
| `x-port-aws-ocean-api-key` | `<your-api-key>` (replace with actual key) |
141+
142+
<h3>Step 5: Transform the Event Data</h3>
143+
144+
Port expects a simplified payload. Use Input Transformer to map the raw AWS event:
145+
146+
**Input Path (mapping):**
147+
```json showLineNumbers
148+
{
149+
"accountId": "$.account",
150+
"awsRegion": "$.region",
151+
"eventName": "$.detail-type",
152+
"identifier": "$.resources.0"
153+
}
154+
```
155+
156+
**Template (output):**
157+
```json showLineNumbers
158+
{
159+
"resource_type": "AWS::SSM::Parameter",
160+
"accountId": "<accountId>",
161+
"awsRegion": "<awsRegion>",
162+
"eventName": "<eventName>",
163+
"identifier": "<identifier>"
164+
}
165+
```
166+
167+
:::tip Resource Type Mapping
168+
Replace `"AWS::SSM::Parameter"` with the appropriate AWS resource type:
169+
- EC2 Instances: `"AWS::EC2::Instance"`
170+
- S3 Buckets: `"AWS::S3::Bucket"`
171+
- CloudFormation Stacks: `"AWS::CloudFormation::Stack"`
172+
:::
173+
174+
<h3>Step 6: Review & Create</h3>
175+
176+
1. Click **Next** → **Next** → **Create rule**.
177+
2. AWS will now forward matching events to Port automatically.
178+
179+
</TabItem>
180+
</Tabs>
181+
182+
183+
## Supported AWS services
184+
185+
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).
186+
187+
### Add other services
188+
189+
To add live events for additional AWS services, follow these steps:
190+
1. Identify the service's event source and detail type.
191+
2. Create an EventBridge rule with the appropriate pattern.
192+
3. Configure the input transformer with the correct resource type.
193+
194+
:::info Default Terraform installation
195+
196+
The default setup comes preconfigured with support for three AWS resource types:
197+
- `EC2 Instances`.
198+
- `S3 Buckets`.
199+
- `CloudFormation Stacks`.
200+
:::
201+

0 commit comments

Comments
 (0)