Skip to content

Commit b7abc39

Browse files
hadar-cohadar-co
authored
Merge pull request #2716 from port-labs/humanitec-integration-update
Enhance Humanitec integration documentation and add new components
2 parents 7afb35a + 0d2d312 commit b7abc39

8 files changed

+624
-134
lines changed

‎docs/guides/all/humanitec-integration.md‎

Lines changed: 76 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -12,9 +12,12 @@ import HumanitecResourceBlueprint from "/docs/guides/templates/humanitec/_humani
1212
import HumanitecResourceGraphBlueprint from "/docs/guides/templates/humanitec/_humanitec_resource_graph_blueprint.mdx";
1313
import HumanitecExporterCacheScript from "/docs/guides/templates/humanitec/_humanitec_exporter_cache.mdx";
1414
import HumanitecExporterMainScript from "/docs/guides/templates/humanitec/_humanitec_exporter_main.mdx";
15+
import HumanitecExporterConfig from "/docs/guides/templates/humanitec/_humanitec_exporter_config.mdx";
1516
import HumanitecExporterRequirements from "/docs/guides/templates/humanitec/_humanitec_exporter_requirements.mdx";
1617
import HumanitecExporterPortClient from "/docs/guides/templates/humanitec/_humanitec_exporter_port_client.mdx";
1718
import HumanitecExporterHumanitecClient from "/docs/guides/templates/humanitec/_humanitec_exporter_humanitec_client.mdx";
19+
import HumanitecExporterCircuitBreaker from "/docs/guides/templates/humanitec/_humanitec_exporter_circuit_breaker.mdx";
20+
import HumanitecExporterRetryableHttpClient from "/docs/guides/templates/humanitec/_humanitec_exporter_retryable_http_client.mdx";
1821
import HumanitecGroups from "/docs/guides/templates/humanitec/_humanitec_groups.mdx";
1922
import HumanitecUsers from "/docs/guides/templates/humanitec/_humanitec_users.mdx";
2023
import HumanitecPipelines from "/docs/guides/templates/humanitec/_humanitec_pipelines.mdx";
@@ -29,7 +32,7 @@ import HumanitecSharedValues from "/docs/guides/templates/humanitec/_humanitec_s
2932

3033
This guide demonstrates how to create a GitHub worklow integration to facilitate the ingestion of Humanitec applications, environments, workloads, resources, resource graphs, pipelines, deployment deltas, deployment sets, secret stores, shared values, value set versions, users, groups into your Port catalog on schedule.
3134

32-
<img src="/img/guides/humanitecEnvironments.png" alt="Humanitec Integration" width="75%" border="1px" />
35+
<img src="/img/guides/humanitecEnvironments.png" alt="Humanitec Integration" width="100%" border="1px" />
3336

3437
## Common use cases
3538

@@ -52,38 +55,37 @@ As a first step, you need to create blueprint definitions in Port for the Humani
5255
1. Go to the [Builder](https://app.getport.io/settings/data-model/data-model) page in your Port organization.
5356
2. Click on the **+ Blueprint** button at the top of the page.
5457
3. Click on `{...} Edit JSON` button at the top right corner.
55-
4. Copy and paste the following blueprint JSON into the editor, repeating the process for each blueprint:
58+
4. Copy, paste and save the following blueprints JSON into the editor, repeating the process for each blueprint:
5659

57-
<HumanitecApplicationBlueprint/>
60+
<HumanitecApplicationBlueprint/>
5861

59-
<HumanitecEnvironmentBlueprint/>
62+
<HumanitecEnvironmentBlueprint/>
6063

61-
<HumanitecWorkloadBlueprint/>
64+
<HumanitecWorkloadBlueprint/>
6265

63-
<HumanitecResourceGraphBlueprint/>
66+
<HumanitecResourceGraphBlueprint/>
6467

65-
<HumanitecResourceBlueprint/>
68+
<HumanitecResourceBlueprint/>
6669

67-
<HumanitecSecretStores/>
70+
<HumanitecSecretStores/>
6871

69-
<HumanitecSharedValues/>
72+
<HumanitecSharedValues/>
7073

71-
<HumanitecValueSetVersions/>
74+
<HumanitecValueSetVersions/>
7275

73-
<HumanitecDeploymentSets/>
76+
<HumanitecDeploymentSets/>
7477

75-
<HumanitecPipelines/>
78+
<HumanitecPipelines/>
7679

77-
<HumanitecDeploymentDeltas/>
80+
<HumanitecDeploymentDeltas/>
7881

79-
<HumanitecUsers/>
82+
<HumanitecUsers/>
8083

81-
<HumanitecGroups/>
84+
<HumanitecGroups/>
8285

83-
84-
:::tip Blueprint Properties
85-
You may select the blueprints depending on what you want to track in your Humanitec account.
86-
:::
86+
:::tip Blueprint selection
87+
You should select the blueprints depending on what you want to track in your Humanitec account.
88+
:::
8789

8890
## Set up the integration
8991

@@ -103,58 +105,90 @@ In your GitHub repository, [go to **Settings > Secrets**](https://docs.github.co
103105

104106
1. Create the following Python files in a folder named `integration` at the base directory of your GitHub repository:
105107
- `main.py` - Orchestrates the synchronization of data from Humanitec to Port, ensuring that resource entities are accurately mirrored and updated on your Port catalog.
106-
- `requirements.txt` - This file contains the dependencies or necessary external packages need to run the integration
107108

109+
Add the following code to the `main.py` file:
110+
<details>
111+
<summary><b>Main Executable Script (Click to expand)</b></summary>
108112

113+
<HumanitecExporterMainScript/>
109114

110-
<details>
111-
<summary><b>Main Executable Script (Click to expand)</b></summary>
115+
</details>
116+
117+
- `config.py` - Contains the configuration constants for the integration, including cache TTL, connection pooling, and other settings.
112118

113-
<HumanitecExporterMainScript/>
119+
Add the following code to the `config.py` file:
120+
<details>
121+
<summary><b>Config (Click to expand)</b></summary>
114122

115-
</details>
123+
<HumanitecExporterConfig/>
116124

125+
</details>
126+
- `requirements.txt` - This file contains the dependencies or necessary external packages need to run the integration
117127

118-
<details>
119-
<summary><b>Requirements (Click to expand)</b></summary>
128+
Add the following code to the `requirements.txt` file:
129+
<details>
130+
<summary><b>Requirements (Click to expand)</b></summary>
120131

121-
<HumanitecExporterRequirements/>
132+
<HumanitecExporterRequirements/>
122133

123-
</details>
134+
</details>
124135

125136

126137
2. Create the following Python files in a folder named `clients` at the base directory of the `integration` folder:
138+
127139
- `port_client.py` – Manages authentication and API requests to Port, facilitating the creation and updating of entities within Port's system.
140+
141+
Add the following code to the `port_client.py` file:
142+
<details>
143+
<summary><b>Port Client (Click to expand)</b></summary>
144+
145+
<HumanitecExporterPortClient/>
146+
147+
</details>
128148
- `humanitec_client.py` – Handles API interactions with Humanitec, including retrieving data with caching mechanisms to optimize performance.
149+
150+
Add the following code to the `humanitec_client.py` file:
151+
<details>
152+
<summary><b>Humanitec Client (Click to expand)</b></summary>
153+
154+
<HumanitecExporterHumanitecClient/>
155+
156+
</details>
129157
- `cache.py` - Provides an in-memory caching mechanism with thread-safe operations for setting, retrieving, and deleting cache entries asynchronously.
130158

131-
<details>
132-
<summary><b>Port Client (Click to expand)</b></summary>
159+
Add the following code to the `cache.py` file:
160+
<details>
161+
<summary><b>Cache (Click to expand)</b></summary>
162+
163+
<HumanitecExporterCacheScript/>
133164

134-
<HumanitecExporterPortClient/>
165+
</details>
166+
- `circuit_breaker.py` - Implements a circuit breaker pattern to handle transient failures in API calls, preventing cascading failures and improving the reliability of the integration.
135167

136-
</details>
168+
Add the following code to the `circuit_breaker.py` file:
169+
<details>
170+
<summary><b>Circuit Breaker (Click to expand)</b></summary>
137171

138-
<details>
139-
<summary><b>Humanitec Client (Click to expand)</b></summary>
172+
<HumanitecExporterCircuitBreaker/>
140173

141-
<HumanitecExporterHumanitecClient/>
174+
</details>
175+
- `retryable_http_client.py` - Provides a retryable HTTP client with exponential backoff and jitter to handle failed API calls due to disonnected HTTP connections.
142176

143-
</details>
177+
Add the following code to the `retryable_http_client.py` file:
178+
<details>
179+
<summary><b>Retryable HTTP Client (Click to expand)</b></summary>
144180

181+
<HumanitecExporterRetryableHttpClient/>
145182

146-
<details>
147-
<summary><b>Cache (Click to expand)</b></summary>
183+
</details>
148184

149-
<HumanitecExporterCacheScript/>
150185

151-
</details>
152186

153187
### Create the GitHub workflow
154188

155189
Create the file `.github/workflows/humanitec-exporter.yaml` in the `.github/workflows` folder of your repository.
156190

157-
:::tip Cron
191+
:::tip Cron expression
158192
Adjust the cron expression to fit your schedule. By default, the workflow is set to run at 2:00 AM every Monday ('0 2 * * 1').
159193
:::
160194

@@ -199,6 +233,7 @@ jobs:
199233
200234
</details>
201235
236+
## Conclusion
202237
203238
Done! Any change that happens to your application, environment, workloads, resources, resource graphs, pipelines, deployment deltas, deployment sets, secret stores, shared values, value set versions, users, groups in Humanitec will be synced to Port on the schedule interval defined in the GitHub workflow.
204239

‎docs/guides/templates/humanitec/_humanitec_deployment_deltas.mdx‎

Lines changed: 59 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -3,56 +3,68 @@
33

44
```json showLineNumbers
55
{
6-
"identifier": "humanitecDeploymentDelta",
7-
"title": "Humanitec Deployment Delta",
8-
"icon": "Deployment",
9-
"schema": {
10-
"properties": {
11-
"status": {
12-
"title": "Status",
13-
"description": "The status of the deployment delta",
14-
"type": "string",
15-
"icon": "DefaultProperty"
16-
},
17-
"createdAt": {
18-
"title": "Created At",
19-
"description": "The date and time when the deployment delta was created",
20-
"type": "string",
21-
"format": "date-time",
22-
"icon": "DefaultProperty"
23-
},
24-
"createdBy": {
25-
"title": "Created By",
26-
"description": "The user who created the deployment delta",
27-
"type": "string",
28-
"icon": "DefaultProperty"
29-
},
30-
"comment": {
31-
"title": "Comment",
32-
"description": "Comment for the deployment delta",
33-
"type": "string",
34-
"icon": "DefaultProperty"
35-
},
36-
"environment": {
37-
"title": "Environment",
38-
"description": "The environment for the deployment delta",
39-
"type": "string",
40-
"icon": "DefaultProperty"
41-
}
6+
"identifier": "humanitecDeploymentDelta",
7+
"title": "Humanitec Deployment Delta",
8+
"icon": "Deployment",
9+
"schema": {
10+
"properties": {
11+
"archived": {
12+
"title": "Archived",
13+
"description": "Whether the deployment delta is archived",
14+
"type": "boolean",
15+
"icon": "DefaultProperty"
4216
},
43-
"required": []
44-
},
45-
"mirrorProperties": {},
46-
"calculationProperties": {},
47-
"aggregationProperties": {},
48-
"relations": {
49-
"humanitecApplication": {
50-
"title": "Application",
51-
"target": "humanitecApplication",
52-
"required": false,
53-
"many": false
17+
"contributers": {
18+
"title": "Contributers",
19+
"description": "The contributers of the deployment delta",
20+
"type": "array",
21+
"icon": "DefaultProperty"
22+
},
23+
"createdAt": {
24+
"title": "Created At",
25+
"description": "The date and time when the deployment delta was created",
26+
"type": "string",
27+
"format": "date-time",
28+
"icon": "DefaultProperty"
29+
},
30+
"createdBy": {
31+
"title": "Created By",
32+
"description": "The user who created the deployment delta",
33+
"type": "string",
34+
"icon": "DefaultProperty"
35+
},
36+
"modules": {
37+
"title": "Modules",
38+
"description": "The modules for the deployment delta",
39+
"type": "object",
40+
"icon": "DefaultProperty"
41+
},
42+
"shared": {
43+
"title": "Shared",
44+
"description": "The shared for the deployment delta",
45+
"type": "array",
46+
"icon": "DefaultProperty"
5447
}
48+
},
49+
"required": []
50+
},
51+
"mirrorProperties": {},
52+
"calculationProperties": {},
53+
"aggregationProperties": {},
54+
"relations": {
55+
"humanitecApplication": {
56+
"title": "Application",
57+
"target": "humanitecApplication",
58+
"required": false,
59+
"many": false
60+
},
61+
"humanitecEnvironment": {
62+
"title": "Environment",
63+
"target": "humanitecEnvironment",
64+
"required": false,
65+
"many": false
5566
}
67+
}
5668
}
5769
```
5870

‎docs/guides/templates/humanitec/_humanitec_exporter_cache.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
import asyncio
44
from typing import Dict, Any
55

6+
67
class InMemoryCache:
78
def __init__(self):
89
self.cache = {}

0 commit comments

Comments
 (0)