Skip to content

Commit 64fb6ae

Browse files
Amichai-Skaliter-PortAmichai-Skaliter-Port
committed
Enhance Port Agent Documentation: Add Configuration Parameters and Proxy Settings for Self-signed Certificates
1 parent 6dd76a4 commit 64fb6ae

File tree

1 file changed

+186
-57
lines changed
  • docs/actions-and-automations/setup-backend/webhook/port-execution-agent

1 file changed

+186
-57
lines changed

‎docs/actions-and-automations/setup-backend/webhook/port-execution-agent/usage.md‎

Lines changed: 186 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -30,100 +30,159 @@ When a new invocation is detected, the agent will pull it from your Kafka topic
3030

3131
![Port Execution Agent Logs](/img/self-service-actions/port-execution-agent/portAgentLogs.png)
3232

33+
## Configuration
34+
35+
The following table lists the configuration parameters of the `port-agent` chart and default values.
36+
37+
| Parameter | Description | Default |
38+
|------------------------------------------------------|--------------------------------------------------------------------------------------------|--------------------------------------------|
39+
| `image.repository` | Image repository | `ghcr.io/port-labs/port-agent` |
40+
| `image.pullPolicy` | Image pull policy | `IfNotPresent` |
41+
| `image.tag` | Image tag | `""` |
42+
| `replicaCount` | Number of port-agent replicas | `1` |
43+
| `imagePullSecrets` | Image pull secrets | `[]` |
44+
| `nameOverride` | Chart name override | `""` |
45+
| `fullnameOverride` | Fully qualified app name override | `""` |
46+
| `secret.annotations` | Annotations for Secret object | `{}` |
47+
| `secret.name` | Secret object name | `""` |
48+
| `secret.useExistingSecret` | Enable this if you wish to create your own secret with credentials | `false` |
49+
| `podServiceAccount.name` | Service account to attach to the pod | `null` |
50+
| `env.normal.STREAMER_NAME` | Streamer name, available: [`KAFKA`] | `"KafkaToWebhookStreamer"` |
51+
| `env.normal.PORT_ORG_ID` | Your Port org id - **Required** | `""` |
52+
| `env.normal.PORT_API_BASE_URL` | Port API base url | `"https://api.getport.io"` |
53+
| `env.normal.KAFKA_CONSUMER_GROUP_ID` | Kafka consumer group id - **Required if using any Kafka streamer** | `""` |
54+
| `env.normal.KAFKA_CONSUMER_SECURITY_PROTOCOL` | Kafka consumer security protocol | `"SASL_SSL"` |
55+
| `env.normal.KAFKA_CONSUMER_AUTHENTICATION_MECHANISM` | Kafka consumer authentication mechanism | `"SCRAM-SHA-512"` |
56+
| `env.normal.KAFKA_CONSUMER_AUTO_OFFSET_RESET` | Kafka consumer auto offset reset | `"largest"` |
57+
| `env.secret.PORT_CLIENT_ID` | Port API client id | `""` |
58+
| `env.secret.PORT_CLIENT_SECRET` | Port API client secret | `""` |
59+
| `controlThePayloadConfig` | Override the default control the payload configuration file with custom json configuration | `""` |
60+
| `podAnnotations` | Annotations to be added to the pod | `{}` |
61+
| `podSecurityContext` | Security context applied to the pod | `{}` |
62+
| `containerSecurityContext` | Security context applied to the container | `{}` |
63+
| `extraVolumes` | Additional volumes to be added to the pod | `[]` |
64+
| `extraVolumeMounts` | Additional volume mounts to be added to the container | `[]` |
65+
| `resources` | Container resource requests & limits | `{}` |
66+
| `nodeSelector` | NodeSelector applied to the pod | `{}` |
67+
| `tolerations` | Tolerations applied to the pod | `[]` |
68+
| `affinity` | Affinity applied to the pod | `{}` |
69+
| `selfSignedCertificate.enabled` | Enable self-signed certificate trust for the agent | `false` |
70+
| `selfSignedCertificate.certificate` | The value of the self-signed certificate | `""` |
71+
| `selfSignedCertificate.secret.useExistingSecret` | Enable this if you wish to use your own secret with the self-signed certificate | `false` |
72+
| `selfSignedCertificate.secret.key` | The key in the existing self-signed certificate secret | `crt` |
73+
| `selfSignedCertificate.secret.name` | The name of an existing secret containing the self-signed certificate | `""` |
3374

34-
## Advanced configuration
35-
Some environments require special configuration when working with the Port agent. This includes working with self-signed certificates and/or proxies.
75+
:::note
76+
Ensure your Kafka topic has enough partitions when increasing `replicaCount` beyond 1. Each replica acts as a consumer in the consumer group.
77+
:::
3678

37-
Port's agent uses Python's [requests](https://requests.readthedocs.io/en/latest/) library. This allows passing advanced configuration using environment variables.
79+
## Self-signed certificate configuration
3880

39-
To add an environment variable using the agent's Helm chart, either:
81+
For self-hosted 3rd-party applications with self-signed certificates, the agent can be configured to trust custom CA certificates. The `selfSignedCertificate` parameters control this behavior.
4082

41-
1. Using Helm's `--set` flag:
42-
```sh showLineNumbers
43-
helm upgrade --install <MY_INSTALLATION_NAME> port-labs/port-ocean \
44-
# Standard installation flags
45-
# ...
46-
--set env.normal.VAR_NAME=VAR_VALUE
47-
```
83+
### Option 1: Provide certificate in Helm values
4884

49-
2. The Helm `values.yaml` file:
50-
```yaml showLineNumbers
51-
# The rest of the configuration
52-
# ...
53-
env:
54-
normal:
55-
VAR_NAME: VAR_VALUE
56-
```
85+
Use this option to provide the certificate content directly in your Helm values file or via the `--set-file` flag. The Helm chart will create and manage a Kubernetes secret containing the certificate.
5786

58-
### Proxy configuration
87+
**How to use:**
88+
1. Set `selfSignedCertificate.enabled` to `true`
89+
2. Provide the certificate content in `selfSignedCertificate.certificate`
90+
3. Keep `selfSignedCertificate.secret.useExistingSecret` as `false` (default)
5991

60-
#### `HTTP_PROXY`, `HTTPS_PROXY` & `ALL_PROXY`
61-
`HTTP_PROXY`, `HTTPS_PROXY`, and `ALL_PROXY` are environment variables used to specify a proxy server for handling HTTP, HTTPS, or all types of requests, respectively. The values assigned to these settings should be the URL of the proxy server.
92+
**Method A: Inline certificate in values.yaml**
6293

63-
For example:
64-
```sh showLineNumbers
65-
HTTP_PROXY=http://my-proxy.com:1111
66-
HTTPS_PROXY=http://my-proxy.com:2222
67-
ALL_PROXY=http://my-proxy.com:3333
94+
Configure in your `values.yaml`:
95+
```yaml
96+
selfSignedCertificate:
97+
enabled: true
98+
certificate: |
99+
-----BEGIN CERTIFICATE-----
100+
<YOUR_CERTIFICATE_CONTENT>
101+
-----END CERTIFICATE-----
102+
secret:
103+
name: ""
104+
key: crt
105+
useExistingSecret: false
68106
```
69107
70-
#### `NO_PROXY`
71-
72-
`NO_PROXY` allows blacklisting certain addresses from being handled through a proxy. This variable accepts a comma-seperated list of hostnames or urls.
73-
74-
For example:
75-
```sh showLineNumbers
76-
NO_PROXY=http://127.0.0.1,google.com
108+
Install with:
109+
```bash
110+
helm install my-port-agent port-labs/port-agent \
111+
--create-namespace --namespace port-agent \
112+
-f values.yaml
77113
```
78114

79-
For more information take a look at the Requests [proxy configuration documentation](https://requests.readthedocs.io/en/latest/user/advanced/#proxies).
80-
81-
### SSL Environment Configuration
82-
83-
### Self-signed Certificate Configuration
84-
85-
#### Option 1: Provide certificate in Helm values
115+
**Method B: Reference certificate file using `--set-file`**
86116

117+
Configure in your `custom_values.yaml`:
87118
```yaml
88119
selfSignedCertificate:
89120
enabled: true
90-
certificate: |
91-
-----BEGIN CERTIFICATE-----
92-
<YOUR_CERTIFICATE_CONTENT>
93-
-----END CERTIFICATE-----
121+
certificate: ""
94122
secret:
123+
name: ""
124+
key: crt
95125
useExistingSecret: false
96126
```
97127
98-
#### Option 2: Use existing Kubernetes secret
128+
Install with:
129+
```bash
130+
helm install my-port-agent port-labs/port-agent \
131+
--create-namespace --namespace port-agent \
132+
-f custom_values.yaml \
133+
--set selfSignedCertificate.enabled=true \
134+
--set-file selfSignedCertificate.certificate=/PATH/TO/CERTIFICATE.crt
135+
```
136+
137+
### Option 2: Use existing Kubernetes secret
138+
139+
Use this option to reference a pre-existing Kubernetes secret that you manage separately. The secret must contain the certificate data.
99140

141+
**How to use:**
142+
1. Set `selfSignedCertificate.enabled` to `true`
143+
2. Set `selfSignedCertificate.secret.useExistingSecret` to `true`
144+
3. Specify the secret name in `selfSignedCertificate.secret.name`
145+
4. Specify the key within the secret in `selfSignedCertificate.secret.key` (defaults to `crt`)
146+
5. Leave `selfSignedCertificate.certificate` empty
147+
148+
**Complete configuration:**
100149
```yaml
101150
selfSignedCertificate:
102151
enabled: true
152+
certificate: ""
103153
secret:
104-
name: <SECRET_NAME>
105-
key: <CERTIFICATE_KEY>
154+
name: my-ca-cert
155+
key: ca.crt
106156
useExistingSecret: true
107157
```
108158
109-
The Helm chart automatically:
159+
### Automatic configuration
160+
161+
When `selfSignedCertificate.enabled` is set to `true`, the Helm chart automatically:
110162
- Mounts the certificate to `/usr/local/share/ca-certificates/cert.crt`
111-
- Sets `SSL_CERT_FILE` and `REQUESTS_CA_BUNDLE` environment variables
112-
- Configures Python libraries (requests, httpx) to trust the certificate
163+
- Sets `SSL_CERT_FILE` and `REQUESTS_CA_BUNDLE` environment variables to point to the certificate
113164

114-
#### Multiple certificates
165+
### Multiple certificates
115166

116-
When multiple certificates are required, one certificate must be provided via `selfSignedCertificate` as described above. Additional certificates can be mounted using `extraVolumes` and `extraVolumeMounts`:
167+
For environments requiring multiple custom certificates, use the `extraVolumes` and `extraVolumeMounts` parameters alongside the built-in `selfSignedCertificate` feature. One certificate must be provided via `selfSignedCertificate`, and additional certificates can be mounted as extra volumes.
117168

169+
**Configuration:**
118170
```yaml
171+
selfSignedCertificate:
172+
enabled: true
173+
secret:
174+
name: primary-cert
175+
key: ca.crt
176+
useExistingSecret: true
177+
119178
extraVolumes:
120179
- name: additional-certs
121180
secret:
122-
secretName: <ADDITIONAL_CERT_SECRET_NAME>
181+
secretName: secondary-certs
123182
extraVolumeMounts:
124183
- name: additional-certs
125-
mountPath: /usr/local/share/ca-certificates/<CERT_NAME>.crt
126-
subPath: <CERT_NAME>.crt
184+
mountPath: /usr/local/share/ca-certificates/cert2.crt
185+
subPath: cert2.crt
127186
readOnly: true
128187
```
129188

@@ -132,8 +191,78 @@ extraVolumeMounts:
132191
- Certificates must be mounted to `/usr/local/share/ca-certificates/` with a `.crt` file extension
133192
:::
134193

194+
## Overriding configurations
195+
196+
When installing the Port Agent, you can override default values in the `helm upgrade` command:
197+
198+
By using the `--set` flag, you can override specific agent configuration parameters during agent installation/upgrade:
199+
200+
```bash showLineNumbers
201+
helm upgrade --install my-port-agent port-labs/port-agent \
202+
--create-namespace --namespace port-agent \
203+
--set env.normal.PORT_ORG_ID="YOUR_ORG_ID" \
204+
--set env.normal.KAFKA_CONSUMER_GROUP_ID="YOUR_CONSUMER_GROUP_ID" \
205+
--set env.secret.PORT_CLIENT_ID="YOUR_CLIENT_ID" \
206+
--set env.secret.PORT_CLIENT_SECRET="YOUR_CLIENT_SECRET" \
207+
--set secret.useExistingSecret=false \
208+
--set replicaCount=2 \
209+
--set resources.limits.memory="512Mi"
210+
```
211+
212+
## All configuration parameters
213+
214+
- A complete list of configuration parameters is available in the [Port Agent Helm chart repository](https://github.com/port-labs/helm-charts/tree/main/charts/port-agent);
215+
- An example `values.yaml` file with all available parameters is available [here](https://github.com/port-labs/helm-charts/blob/main/charts/port-agent/values.yaml).
216+
217+
## Extra environment variables
218+
219+
To pass extra environment variables to the agent's runtime, you can use the `env.normal` section for non-sensitive variables.
220+
221+
Using Helm's `--set` flag:
222+
```bash showLineNumbers
223+
helm upgrade --install my-port-agent port-labs/port-agent \
224+
# Standard installation flags
225+
# ...
226+
--set env.normal.HTTP_PROXY=http://my-proxy.com:1111 \
227+
--set env.normal.HTTPS_PROXY=http://my-proxy.com:2222
228+
```
229+
230+
Using the `values.yaml` file:
231+
```yaml showLineNumbers
232+
# The rest of the configuration
233+
# ...
234+
env:
235+
normal:
236+
HTTP_PROXY: "http://my-proxy.com:1111"
237+
HTTPS_PROXY: "http://my-proxy.com:2222"
238+
NO_PROXY: "127.0.0.1,localhost"
239+
```
240+
241+
### Proxy configuration
242+
243+
#### `HTTP_PROXY`, `HTTPS_PROXY` & `ALL_PROXY`
244+
`HTTP_PROXY`, `HTTPS_PROXY`, and `ALL_PROXY` are environment variables used to specify a proxy server for handling HTTP, HTTPS, or all types of requests, respectively. The values assigned to these settings should be the URL of the proxy server.
245+
246+
For example:
247+
```sh showLineNumbers
248+
HTTP_PROXY=http://my-proxy.com:1111
249+
HTTPS_PROXY=http://my-proxy.com:2222
250+
ALL_PROXY=http://my-proxy.com:3333
251+
```
252+
253+
#### `NO_PROXY`
254+
255+
`NO_PROXY` allows blacklisting certain addresses from being handled through a proxy. This variable accepts a comma-separated list of hostnames or URLs.
256+
257+
For example:
258+
```sh showLineNumbers
259+
NO_PROXY=http://127.0.0.1,google.com
260+
```
261+
262+
For more information, see the Requests [proxy configuration documentation](https://requests.readthedocs.io/en/latest/user/advanced/#proxies).
263+
135264
## Next Steps
136265

137266
Follow one of the guides below:
138267

139-
- [GitLab Pipeline Trigger](/actions-and-automations/setup-backend/gitlab-pipeline/gitlab-pipeline.md) - Create an action that triggers GitLab Pipeline execution.
268+
- [GitLab Pipeline Trigger](/actions-and-automations/setup-backend/gitlab-pipeline/gitlab-pipeline.md) - Create an action that triggers GitLab Pipeline execution.

0 commit comments

Comments
 (0)