From b32c6a8cafb8f7bbf40d9a8ced94ca19383c5da3 Mon Sep 17 00:00:00 2001 From: MatanGevaPort Date: Sun, 19 Oct 2025 12:00:08 +0300 Subject: [PATCH 1/3] added new guide for k8s-exporter's jq env vars option --- .../kubernetes-stack/kubernetes/advanced.md | 91 +++++++++++++++++-- 1 file changed, 85 insertions(+), 6 deletions(-) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/kubernetes-stack/kubernetes/advanced.md b/docs/build-your-software-catalog/sync-data-to-catalog/kubernetes-stack/kubernetes/advanced.md index 9a7e2a226f..f44b40f96a 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/kubernetes-stack/kubernetes/advanced.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/kubernetes-stack/kubernetes/advanced.md @@ -32,6 +32,7 @@ The following advanced configuration parameters are available: {label: "Bulk Sync", value: "bulkSync"}, {label: "Event listener type", value: "eventListenerType"}, {label: "CRDs to discover", value: "crdsToDiscover"}, +{label: "JQ Configuration", value: "jqConfiguration"}, ]} > @@ -133,6 +134,85 @@ For more information how to use the `crdsToDiscover` parameter, please refer to + + +The K8s exporter supports configuration options to control access to environment variables within JQ queries used in resource mappings. + +### `allowAllEnvironmentVariablesInJQ` + +The `allowAllEnvironmentVariablesInJQ` parameter controls whether all environment variables are accessible in JQ queries. + +- **Default value**: `true` (all environment variables are accessible) +- **Security implications**: When set to `true`, JQ queries in your resource mappings can access any environment variable available to the exporter pod, including sensitive information like API keys, passwords, and other secrets. + +:::warning Security Risk +Setting `allowAllEnvironmentVariablesInJQ` to `true` can expose sensitive environment variables to JQ queries. This includes: +- Port credentials (`PORT_CLIENT_ID`, `PORT_CLIENT_SECRET`) +- Kubernetes service account tokens +- Any other environment variables injected into the pod +- Secrets mounted as environment variables + +Only enable this setting if you trust all JQ queries in your resource mappings and understand the security implications. +::: + +### `allowedEnvironmentVariablesInJQ` + +The `allowedEnvironmentVariablesInJQ` parameter specifies which environment variables are allowed in JQ queries when `allowAllEnvironmentVariablesInJQ` is set to `false`. This parameter accepts a comma-separated list that can include: +- Specific environment variable names (e.g., `CLUSTER_NAME`) +- JQ expressions/patterns for matching multiple variables (e.g., `CLUSTER_*` to match all cluster-related environment variables) + +- **Default value**: `""` (empty - no environment variables allowed when `allowAllEnvironmentVariablesInJQ` is `false`) +- **Use case**: Restrict access to only specific, safe environment variables in JQ queries for enhanced security. Use patterns to allow groups of related environment variables. + +:::tip Recommended Security Practice +For production environments, set `allowAllEnvironmentVariablesInJQ` to `false` and explicitly list only the environment variables your JQ queries need in `allowedEnvironmentVariablesInJQ`. +::: + +#### Configuration Examples + +#### Example 1: Allow all environment variables (default, less secure) + +```bash +--set allowAllEnvironmentVariablesInJQ=true +``` + +#### Example 2: Restrict to specific environment variables (recommended) + +```bash +--set allowAllEnvironmentVariablesInJQ=false \ +--set allowedEnvironmentVariablesInJQ="CLUSTER_NAME,NAMESPACE,REGION" +``` + +#### Example 3: Using values.yaml file + +```yaml +allowAllEnvironmentVariablesInJQ: false +allowedEnvironmentVariablesInJQ: "CLUSTER_NAME,NAMESPACE,REGION" +``` + +#### Example 4: Using patterns to allow groups of variables + +```bash +--set allowAllEnvironmentVariablesInJQ=false \ +--set allowedEnvironmentVariablesInJQ="CLUSTER_*,NAMESPACE,REGION_*" +``` + +This configuration allows: +- All environment variables starting with `CLUSTER_` (e.g., `CLUSTER_NAME`, `CLUSTER_ID`) +- Specific variable: `NAMESPACE` +- All environment variables starting with `REGION_` (e.g., `REGION_US`, `REGION_EU`) + +#### Example 5: Using patterns in values.yaml + +```yaml +allowAllEnvironmentVariablesInJQ: false +allowedEnvironmentVariablesInJQ: "CLUSTER_*,NAMESPACE_*,REGION_*" +``` + +This configuration allows all environment variables that start with `CLUSTER_`, `NAMESPACE_`, or `REGION_`. + + + ## Security Configuration @@ -155,12 +235,12 @@ By using the `--set` flag, you can override specific exporter configuration para ```bash showLineNumbers helm upgrade --install k8s-exporter port-labs/port-k8s-exporter \ --create-namespace --namespace port-k8s-exporter \ - --set secret.secrets.portClientId="YOUR_PORT_CLIENT_ID" \ - --set secret.secrets.portClientSecret="YOUR_PORT_CLIENT_SECRET" \ - --set stateKey="k8s-exporter" \ + --set secret.secrets.portClientId="YOUR_PORT_CLIENT_ID" \ + --set secret.secrets.portClientSecret="YOUR_PORT_CLIENT_SECRET" \ + --set stateKey="k8s-exporter" \ # highlight-next-line - --set eventListenerType="KAFKA" \ - --set extraEnv=[{"name":"CLUSTER_NAME","value":"my-cluster"}] + --set eventListenerType="KAFKA" \ + --set extraEnv=[{"name":"CLUSTER_NAME","value":"my-cluster"}] ``` For example, to set the parameters from the [security configuration](#security-configuration) section: @@ -175,7 +255,6 @@ For example, to set the parameters from the [security configuration](#security-c - A complete list of configuration parameters available when using the helm chart is available [here](https://github.com/port-labs/helm-charts/tree/main/charts/port-k8s-exporter#chart); - An example skeleton `values.yml` file is available [here](https://github.com/port-labs/helm-charts/blob/main/charts/port-k8s-exporter/values.yaml). - ## Extra environment variables To pass extra environment variables to the exporter's runtime, you can use the Helm chart provided with the installation. You can do this in one of two ways: From 48d4f386f02ff24fad5ba538be349edfec327984 Mon Sep 17 00:00:00 2001 From: MatanGevaPort Date: Sun, 26 Oct 2025 10:28:03 +0200 Subject: [PATCH 2/3] Fixed docs --- .../kubernetes-stack/kubernetes/advanced.md | 65 ++++++------------- 1 file changed, 19 insertions(+), 46 deletions(-) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/kubernetes-stack/kubernetes/advanced.md b/docs/build-your-software-catalog/sync-data-to-catalog/kubernetes-stack/kubernetes/advanced.md index f44b40f96a..a82e3b0b50 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/kubernetes-stack/kubernetes/advanced.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/kubernetes-stack/kubernetes/advanced.md @@ -142,8 +142,8 @@ The K8s exporter supports configuration options to control access to environment The `allowAllEnvironmentVariablesInJQ` parameter controls whether all environment variables are accessible in JQ queries. -- **Default value**: `true` (all environment variables are accessible) -- **Security implications**: When set to `true`, JQ queries in your resource mappings can access any environment variable available to the exporter pod, including sensitive information like API keys, passwords, and other secrets. +- **Default value**: `true` (all environment variables are accessible within JQ queries) +- **Security implications**: When set to `true`, JQ queries in your resource mappings can access any environment variable available to the exporter pod, including sensitive information like API keys, passwords, and other secrets (if those are mapped to the exporter pod as environment variables). :::warning Security Risk Setting `allowAllEnvironmentVariablesInJQ` to `true` can expose sensitive environment variables to JQ queries. This includes: @@ -152,64 +152,37 @@ Setting `allowAllEnvironmentVariablesInJQ` to `true` can expose sensitive enviro - Any other environment variables injected into the pod - Secrets mounted as environment variables -Only enable this setting if you trust all JQ queries in your resource mappings and understand the security implications. +Due to the potential security implication, if you have a need to limit the exposure of environment variables in the exporter's JQ, please set this parameter to `false` and explicitly specify the variables that need to be accessed using JQ through the `allowedEnvironmentVariablesInJQ` parameter. ::: ### `allowedEnvironmentVariablesInJQ` -The `allowedEnvironmentVariablesInJQ` parameter specifies which environment variables are allowed in JQ queries when `allowAllEnvironmentVariablesInJQ` is set to `false`. This parameter accepts a comma-separated list that can include: -- Specific environment variable names (e.g., `CLUSTER_NAME`) -- JQ expressions/patterns for matching multiple variables (e.g., `CLUSTER_*` to match all cluster-related environment variables) +The `allowedEnvironmentVariablesInJQ` parameter specifies which environment variables are allowed in JQ queries when `allowAllEnvironmentVariablesInJQ` is set to `false`. This parameter accepts a list of JQ expressions that evaluate to environment variable names or patterns. -- **Default value**: `""` (empty - no environment variables allowed when `allowAllEnvironmentVariablesInJQ` is `false`) -- **Use case**: Restrict access to only specific, safe environment variables in JQ queries for enhanced security. Use patterns to allow groups of related environment variables. +Each entry in the list is a JQ expression that should return: +- A specific environment variable name (e.g., `"CLUSTER_NAME"`) +- A pattern for matching multiple variables (e.g., `"^CLUSTER_"` to match all cluster-related environment variables) +- An array of environment variable names or patterns -:::tip Recommended Security Practice -For production environments, set `allowAllEnvironmentVariablesInJQ` to `false` and explicitly list only the environment variables your JQ queries need in `allowedEnvironmentVariablesInJQ`. -::: - -#### Configuration Examples - -#### Example 1: Allow all environment variables (default, less secure) - -```bash ---set allowAllEnvironmentVariablesInJQ=true -``` +- **Default value**: `^PORT_, CLUSTER_NAME` +- **Use case**: Restrict access to only specific, safe environment variables in JQ queries for enhanced security. Use JQ expressions to dynamically determine which environment variables should be accessible. -#### Example 2: Restrict to specific environment variables (recommended) - -```bash ---set allowAllEnvironmentVariablesInJQ=false \ ---set allowedEnvironmentVariablesInJQ="CLUSTER_NAME,NAMESPACE,REGION" -``` - -#### Example 3: Using values.yaml file +#### Configuration Example ```yaml allowAllEnvironmentVariablesInJQ: false -allowedEnvironmentVariablesInJQ: "CLUSTER_NAME,NAMESPACE,REGION" -``` - -#### Example 4: Using patterns to allow groups of variables - -```bash ---set allowAllEnvironmentVariablesInJQ=false \ ---set allowedEnvironmentVariablesInJQ="CLUSTER_*,NAMESPACE,REGION_*" +allowedEnvironmentVariablesInJQ: + - ^CLUSTER_ + - AWS_REGION + - AWS_ACCOUNT_ID +resources: + - kind: v1/namespaces +... ``` This configuration allows: - All environment variables starting with `CLUSTER_` (e.g., `CLUSTER_NAME`, `CLUSTER_ID`) -- Specific variable: `NAMESPACE` -- All environment variables starting with `REGION_` (e.g., `REGION_US`, `REGION_EU`) - -#### Example 5: Using patterns in values.yaml - -```yaml -allowAllEnvironmentVariablesInJQ: false -allowedEnvironmentVariablesInJQ: "CLUSTER_*,NAMESPACE_*,REGION_*" -``` - -This configuration allows all environment variables that start with `CLUSTER_`, `NAMESPACE_`, or `REGION_`. +- Specific variables: `AWS_REGION` & `AWS_ACCOUNT_ID` From 48e70ea08ebc5dfa53d590751f72086acc2c1b80 Mon Sep 17 00:00:00 2001 From: MatanGevaPort Date: Mon, 27 Oct 2025 12:56:35 +0200 Subject: [PATCH 3/3] changed headings --- .../kubernetes-stack/kubernetes/advanced.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/kubernetes-stack/kubernetes/advanced.md b/docs/build-your-software-catalog/sync-data-to-catalog/kubernetes-stack/kubernetes/advanced.md index a82e3b0b50..2b204c38fb 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/kubernetes-stack/kubernetes/advanced.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/kubernetes-stack/kubernetes/advanced.md @@ -138,7 +138,7 @@ For more information how to use the `crdsToDiscover` parameter, please refer to The K8s exporter supports configuration options to control access to environment variables within JQ queries used in resource mappings. -### `allowAllEnvironmentVariablesInJQ` +

`allowAllEnvironmentVariablesInJQ`

The `allowAllEnvironmentVariablesInJQ` parameter controls whether all environment variables are accessible in JQ queries. @@ -148,26 +148,26 @@ The `allowAllEnvironmentVariablesInJQ` parameter controls whether all environmen :::warning Security Risk Setting `allowAllEnvironmentVariablesInJQ` to `true` can expose sensitive environment variables to JQ queries. This includes: - Port credentials (`PORT_CLIENT_ID`, `PORT_CLIENT_SECRET`) -- Kubernetes service account tokens -- Any other environment variables injected into the pod -- Secrets mounted as environment variables +- Kubernetes service account tokens. +- Any other environment variables injected into the pod. +- Secrets mounted as environment variables. Due to the potential security implication, if you have a need to limit the exposure of environment variables in the exporter's JQ, please set this parameter to `false` and explicitly specify the variables that need to be accessed using JQ through the `allowedEnvironmentVariablesInJQ` parameter. ::: -### `allowedEnvironmentVariablesInJQ` +

`allowedEnvironmentVariablesInJQ`

The `allowedEnvironmentVariablesInJQ` parameter specifies which environment variables are allowed in JQ queries when `allowAllEnvironmentVariablesInJQ` is set to `false`. This parameter accepts a list of JQ expressions that evaluate to environment variable names or patterns. Each entry in the list is a JQ expression that should return: - A specific environment variable name (e.g., `"CLUSTER_NAME"`) - A pattern for matching multiple variables (e.g., `"^CLUSTER_"` to match all cluster-related environment variables) -- An array of environment variable names or patterns +- An array of environment variable names or patterns. - **Default value**: `^PORT_, CLUSTER_NAME` - **Use case**: Restrict access to only specific, safe environment variables in JQ queries for enhanced security. Use JQ expressions to dynamically determine which environment variables should be accessible. -#### Configuration Example +

Configuration Example

```yaml allowAllEnvironmentVariablesInJQ: false