Skip to content

Commit bb0b69d

Browse files
kodjomileskodjomiles
committed
Update Humanitec integration guide for clarity and completeness
- Adjusted image width for better visibility in `humanitec-integration.md`. - Revised instructions for copying blueprints to improve clarity. - Enhanced section headers and tips for better organization and readability. - Added a conclusion to summarize the integration process and its benefits.
1 parent c3a57c6 commit bb0b69d

File tree

1 file changed

+68
-61
lines changed

1 file changed

+68
-61
lines changed

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

Lines changed: 68 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ import HumanitecSharedValues from "/docs/guides/templates/humanitec/_humanitec_s
3232

3333
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.
3434

35-
<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" />
3636

3737
## Common use cases
3838

@@ -55,38 +55,37 @@ As a first step, you need to create blueprint definitions in Port for the Humani
5555
1. Go to the [Builder](https://app.getport.io/settings/data-model/data-model) page in your Port organization.
5656
2. Click on the **+ Blueprint** button at the top of the page.
5757
3. Click on `{...} Edit JSON` button at the top right corner.
58-
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:
5959

60-
<HumanitecApplicationBlueprint/>
60+
<HumanitecApplicationBlueprint/>
6161

62-
<HumanitecEnvironmentBlueprint/>
62+
<HumanitecEnvironmentBlueprint/>
6363

64-
<HumanitecWorkloadBlueprint/>
64+
<HumanitecWorkloadBlueprint/>
6565

66-
<HumanitecResourceGraphBlueprint/>
66+
<HumanitecResourceGraphBlueprint/>
6767

68-
<HumanitecResourceBlueprint/>
68+
<HumanitecResourceBlueprint/>
6969

70-
<HumanitecSecretStores/>
70+
<HumanitecSecretStores/>
7171

72-
<HumanitecSharedValues/>
72+
<HumanitecSharedValues/>
7373

74-
<HumanitecValueSetVersions/>
74+
<HumanitecValueSetVersions/>
7575

76-
<HumanitecDeploymentSets/>
76+
<HumanitecDeploymentSets/>
7777

78-
<HumanitecPipelines/>
78+
<HumanitecPipelines/>
7979

80-
<HumanitecDeploymentDeltas/>
80+
<HumanitecDeploymentDeltas/>
8181

82-
<HumanitecUsers/>
82+
<HumanitecUsers/>
8383

84-
<HumanitecGroups/>
84+
<HumanitecGroups/>
8585

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

9190
## Set up the integration
9291

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

107106
1. Create the following Python files in a folder named `integration` at the base directory of your GitHub repository:
108107
- `main.py` - Orchestrates the synchronization of data from Humanitec to Port, ensuring that resource entities are accurately mirrored and updated on your Port catalog.
109-
- `config.py` - Contains the configuration constants for the integration, including cache TTL, connection pooling, and other settings.
110-
- `requirements.txt` - This file contains the dependencies or necessary external packages need to run the integration
111-
112108

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

114-
<details>
115-
<summary><b>Main Executable Script (Click to expand)</b></summary>
113+
<HumanitecExporterMainScript/>
116114

117-
<HumanitecExporterMainScript/>
118-
119-
</details>
120-
121-
<details>
122-
<summary><b>Config (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.
123118

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

126-
</details>
123+
<HumanitecExporterConfig/>
127124

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

129-
<details>
130-
<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>
131131

132-
<HumanitecExporterRequirements/>
132+
<HumanitecExporterRequirements/>
133133

134-
</details>
134+
</details>
135135

136136

137137
2. Create the following Python files in a folder named `clients` at the base directory of the `integration` folder:
138-
- `port_client.py` – Manages authentication and API requests to Port, facilitating the creation and updating of entities within Port's system.
139-
- `humanitec_client.py` – Handles API interactions with Humanitec, including retrieving data with caching mechanisms to optimize performance.
140-
- `cache.py` - Provides an in-memory caching mechanism with thread-safe operations for setting, retrieving, and deleting cache entries asynchronously.
141-
- `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.
142-
- `retryable_http_client.py` - Provides a retryable HTTP client with exponential backoff and jitter to handle failed API calls due to disonnected HTTP connections.
143138

144-
<details>
145-
<summary><b>Port Client (Click to expand)</b></summary>
139+
- `port_client.py` – Manages authentication and API requests to Port, facilitating the creation and updating of entities within Port's system.
146140

147-
<HumanitecExporterPortClient/>
141+
Add the following code to the `port_client.py` file:
142+
<details>
143+
<summary><b>Port Client (Click to expand)</b></summary>
148144

149-
</details>
145+
<HumanitecExporterPortClient/>
150146

151-
<details>
152-
<summary><b>Humanitec Client (Click to expand)</b></summary>
147+
</details>
148+
- `humanitec_client.py` – Handles API interactions with Humanitec, including retrieving data with caching mechanisms to optimize performance.
153149

154-
<HumanitecExporterHumanitecClient/>
150+
Add the following code to the `humanitec_client.py` file:
151+
<details>
152+
<summary><b>Humanitec Client (Click to expand)</b></summary>
155153

156-
</details>
154+
<HumanitecExporterHumanitecClient/>
157155

156+
</details>
157+
- `cache.py` - Provides an in-memory caching mechanism with thread-safe operations for setting, retrieving, and deleting cache entries asynchronously.
158158

159-
<details>
160-
<summary><b>Cache (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>
161162

162-
<HumanitecExporterCacheScript/>
163+
<HumanitecExporterCacheScript/>
163164

164-
</details>
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.
165167

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

169-
<HumanitecExporterCircuitBreaker/>
172+
<HumanitecExporterCircuitBreaker/>
170173

171-
</details>
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.
172176

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>
173180

174-
<details>
181+
<HumanitecExporterRetryableHttpClient/>
175182

176-
<HumanitecExporterRetryableHttpClient/>
183+
</details>
177184

178-
</details>
179185

180186

181187
### Create the GitHub workflow
182188

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

185-
:::tip Cron
191+
:::tip Cron expression
186192
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').
187193
:::
188194

@@ -227,6 +233,7 @@ jobs:
227233
228234
</details>
229235
236+
## Conclusion
230237
231238
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.
232239

0 commit comments

Comments
 (0)