Merge branch 'main' into task_t3ex6y/update_pr_description_to_match_standards_guide

Author: kodjomiles

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

@@ -4,13 +4,7 @@ sidebar_position: 2
 
 # Usage
 
-When using the execution agent, in the `url` field you need to provide a URL to a service (for example, a REST API) that will accept the invocation event.
-
-- The service can be a private service running inside your private network;
-- Or, it can be a public accessible service from the public internet (**note** in this scenario, the execution agent needs corresponding outbound network rules that will allow it to contact the public service).
-
-:::note
-**IMPORTANT**: To make use of the **Port execution agent**, you need to configure:
+To make use of the **Port execution agent**, you need to configure:
 
 <!-- TODO: add back the URLs here for changelog destination -->
 
@@ -22,37 +16,177 @@ For example:
 ```json showLineNumbers
 { "type": "WEBHOOK", "agent": true, "url": "URL_TO_API_INSIDE_YOUR_NETWORK" }
 ```
-:::
 
-Well Done! **Port Agent** is now running in your environment and will trigger any webhook that you've configured (for self-service actions, or changes in the software catalog).
+When using the execution agent, in the `url` field you need to provide a URL to a service (for example, a REST API) that will accept the invocation event.
 
-When a new invocation is detected, the agent will pull it from your Kafka topic and forward it to the internal API in your private network.
+- The service can be a private service running inside your private network;
+- Or, it can be a public accessible service from the public internet (**note** in this scenario, the execution agent needs corresponding outbound network rules that will allow it to contact the public service).
+
+Once configured, the Port Agent will run in your environment and trigger webhooks for self-service actions or software catalog changes.
+
+When a new invocation is detected, the agent pulls it from your Kafka topic and forwards it to the internal API in your private network.
 
 ![Port Execution Agent Logs](/img/self-service-actions/port-execution-agent/portAgentLogs.png)
 
+:::info Advanced configuration
+For a complete list of all available configuration parameters and their descriptions, see the [Port Agent Helm chart README](https://github.com/port-labs/helm-charts/tree/main/charts/port-agent).
+:::
 
-## Advanced configuration
-Some environments require special configuration when working with the Port agent. This includes working with self-signed certificates and/or proxies.
+## Self-signed certificate configuration
 
-Port's agent uses Python's [requests](https://requests.readthedocs.io/en/latest/) library. This allows passing advanced configuration using environment variables.
+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.
 
-To add an environment variable using the agent's Helm chart, either:
+### Option 1: Provide certificate in Helm values
 
-1. Using Helm's `--set` flag:
-```sh showLineNumbers
-helm upgrade --install <MY_INSTALLATION_NAME> port-labs/port-ocean \
+Use this option to provide the certificate content directly in your Helm values file or via the `--set-file` flag.
+
+**How to use:**
+1. Set `selfSignedCertificate.enabled` to `true`
+2. Provide the certificate content in `selfSignedCertificate.certificate`
+3. Keep `selfSignedCertificate.secret.useExistingSecret` as `false` (default)
+
+**Method A: Inline certificate in values.yaml**
+
+Configure in your `values.yaml`:
+```yaml
+selfSignedCertificate:
+  enabled: true
+  certificate: |
+    -----BEGIN CERTIFICATE-----
+    <YOUR_CERTIFICATE_CONTENT>
+    -----END CERTIFICATE-----
+  secret:
+    name: ""
+    key: crt
+    useExistingSecret: false
+```
+
+Install with:
+```bash
+helm install my-port-agent port-labs/port-agent \
+   --create-namespace --namespace port-agent \
+   -f values.yaml
+```
+
+**Method B: Reference certificate file using `--set-file`**
+
+Configure in your `custom_values.yaml`:
+```yaml
+selfSignedCertificate:
+  enabled: true
+  certificate: ""
+  secret:
+    name: ""
+    key: crt
+    useExistingSecret: false
+```
+
+Install with:
+```bash
+helm install my-port-agent port-labs/port-agent \
+   --create-namespace --namespace port-agent \
+   -f custom_values.yaml \
+   --set selfSignedCertificate.enabled=true \
+   --set-file selfSignedCertificate.certificate=/PATH/TO/CERTIFICATE.crt
+```
+
+### Option 2: Use existing Kubernetes secret
+
+Use this option to reference a pre-existing Kubernetes secret that you manage separately. The secret must contain the certificate data.
+
+**How to use:**
+1. Set `selfSignedCertificate.enabled` to `true`
+2. Set `selfSignedCertificate.secret.useExistingSecret` to `true`
+3. Specify the secret name in `selfSignedCertificate.secret.name`
+4. Specify the key within the secret in `selfSignedCertificate.secret.key` (defaults to `crt`)
+5. Leave `selfSignedCertificate.certificate` empty
+
+**Complete configuration:**
+```yaml
+selfSignedCertificate:
+  enabled: true
+  certificate: ""
+  secret:
+    name: my-ca-cert
+    key: ca.crt
+    useExistingSecret: true
+```
+
+### Automatic configuration
+
+When `selfSignedCertificate.enabled` is set to `true`, the Helm chart automatically:
+- Mounts the certificate to `/usr/local/share/ca-certificates/cert.crt`
+- Sets `SSL_CERT_FILE` and `REQUESTS_CA_BUNDLE` environment variables to point to the certificate
+
+### Multiple certificates
+
+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.
+
+**Configuration:**
+```yaml
+selfSignedCertificate:
+  enabled: true
+  secret:
+    name: primary-cert
+    key: ca.crt
+    useExistingSecret: true
+
+extraVolumes:
+  - name: additional-certs
+    secret:
+      secretName: secondary-certs
+extraVolumeMounts:
+  - name: additional-certs
+    mountPath: /usr/local/share/ca-certificates/cert2.crt
+    subPath: cert2.crt
+    readOnly: true
+```
+
+:::info Certificate requirements
+- Each certificate must be provided in PEM format as a separate file
+- Certificates must be mounted to `/usr/local/share/ca-certificates/` with a `.crt` file extension
+:::
+
+## Overriding configurations
+
+When installing the Port Agent, you can override default values in the `helm upgrade` command:
+
+By using the `--set` flag, you can override specific agent configuration parameters during agent installation/upgrade:
+
+```bash showLineNumbers
+helm upgrade --install my-port-agent port-labs/port-agent \
+    --create-namespace --namespace port-agent \
+    --set env.normal.PORT_ORG_ID="YOUR_ORG_ID" \
+    --set env.normal.KAFKA_CONSUMER_GROUP_ID="YOUR_CONSUMER_GROUP_ID" \
+    --set env.secret.PORT_CLIENT_ID="YOUR_CLIENT_ID" \
+    --set env.secret.PORT_CLIENT_SECRET="YOUR_CLIENT_SECRET" \
+    --set secret.useExistingSecret=false \
+    --set replicaCount=2 \
+    --set resources.limits.memory="512Mi"
+```
+
+## Extra environment variables
+
+To pass extra environment variables to the agent's runtime, you can use the `env.normal` section for non-sensitive variables.
+
+Using Helm's `--set` flag:
+```bash showLineNumbers
+helm upgrade --install my-port-agent port-labs/port-agent \
   # Standard installation flags
   # ...
-  --set env.normal.VAR_NAME=VAR_VALUE 
+  --set env.normal.HTTP_PROXY=http://my-proxy.com:1111 \
+  --set env.normal.HTTPS_PROXY=http://my-proxy.com:2222
 ```
 
-2. The Helm `values.yaml` file:
+Using the `values.yaml` file:
 ```yaml showLineNumbers
 # The rest of the configuration
 # ...
 env:
   normal:
-    VAR_NAME: VAR_VALUE
+    HTTP_PROXY: "http://my-proxy.com:1111"
+    HTTPS_PROXY: "http://my-proxy.com:2222"
+    NO_PROXY: "127.0.0.1,localhost"
 ```
 
 ### Proxy configuration
@@ -69,51 +203,17 @@ ALL_PROXY=http://my-proxy.com:3333
 
 #### `NO_PROXY`
 
-`NO_PROXY` allows blacklisting certain addresses from being handled through a proxy. This variable accepts a comma-seperated list of hostnames or urls.
+`NO_PROXY` allows blacklisting certain addresses from being handled through a proxy. This variable accepts a comma-separated list of hostnames or URLs.
 
 For example:
 ```sh showLineNumbers
 NO_PROXY=http://127.0.0.1,google.com
 ```
 
-For more information take a look at the Requests [proxy configuration documentation](https://requests.readthedocs.io/en/latest/user/advanced/#proxies).
-
-### SSL Environment Configuration
-
-### Certificate Configuration
-
-#### Self-signed certificate
-
-Use the following Helm values:
-- Set `selfSignedCertificate.enabled` to `true`.
-- Put your PEM-encoded CA content in `selfSignedCertificate.certificate`.
-
-The certificate should be mounted to `/usr/local/share/ca-certificates/`.
-
-`REQUESTS_CA_BUNDLE` is an environment variable used to specify a custom Certificate Authority (CA) bundle for verifying SSL/TLS certificates in HTTPS requests.
-
-Set `REQUESTS_CA_BUNDLE` to the file path of your CA bundle, which should contain one or more CA certificates in PEM format.
-
-For example:
-```sh
-REQUESTS_CA_BUNDLE=/path/to/cacert.pem
-```
-
-This configuration directs the `requests` library to use the specified CA bundle for SSL/TLS certificate verification, overriding default system settings. It's useful for trusting self-signed certificates or certificates from a private CA.
-
-#### Multiple certificates
-
-Use the following Helm values:
-- Keep your certificate via `selfSignedCertificate` as above.
-- Add other certificates by supplying files via `extraVolumes` and mounting them with `extraVolumeMounts` into the container at `/usr/local/share/ca-certificates/<your-cert-name>.crt`.
-
-:::info Certificate file requirements
-- Each certificate must be provided in a separate PEM file. Files containing multiple certificates are not supported.
-- Certificates must be mounted to `/usr/local/share/ca-certificates/` with a `.crt` file extension.
-:::
+For more information, see the Requests [proxy configuration documentation](https://requests.readthedocs.io/en/latest/user/advanced/#proxies).
 
 ## Next Steps
 
 Follow one of the guides below:
 
-- [GitLab Pipeline Trigger](/actions-and-automations/setup-backend/gitlab-pipeline/gitlab-pipeline.md) - Create an action that triggers GitLab Pipeline execution.
+- [GitLab Pipeline Trigger](/actions-and-automations/setup-backend/gitlab-pipeline/gitlab-pipeline.md) - Create an action that triggers GitLab Pipeline execution.

docs/api-reference/approve-an-action-run.api.mdx

@@ -5,7 +5,7 @@ description: "This route allows you to approve or decline a request to execute a
 sidebar_label: "Approve an action run"
 hide_title: true
 hide_table_of_contents: true
-api: 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
+api: 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
 sidebar_class_name: "patch api-method"
 info_path: api-reference/port-api
 custom_edit_url: null