diff --git a/content/en/04-tutorials/05-config-map-scripts/index.md b/content/en/04-tutorials/05-config-map-scripts/index.md new file mode 100644 index 0000000..2741b59 --- /dev/null +++ b/content/en/04-tutorials/05-config-map-scripts/index.md @@ -0,0 +1,66 @@ +The following tutorial demonstrates how to configure scripts for Pixie's observability platform using Kubernetes ConfigMaps, rather than the default Control Plane. + +## Motivation + +This feature is for customers who want to manage their PxL scripts outside of a control plane. It provides to ability to supply PxL scripts via in-cluster ConfigMaps either instead of or in addition to scripts from a control plane. + +As an example, if your product needed to install Pixie with a set of scripts pre-loaded, this would solve that problem. + + + +## Turning on the feature + +You can enable loading scripts from ConfigMaps by setting the `PL_CRON_SCRIPT_SOURCES` environment variable on the `vizier-query-broker` deployment. The value of this environment variable should be a space-separated list of sources. Currently, the valid sources are `cloud` and `configmaps`. If nothing is supplied, the query broker will default to `cloud` only. + +As an example, you could enable both sources by running: + +```bash +px deploy -y --patches "vizier-query-broker:{\"spec\":{\"template\":{\"spec\":{\"containers\":[{\"env\":[{\"name\":\"PL_CRON_SCRIPT_SOURCES\",\"value\":\"cloud configmaps\"}], \"name\":\"app\"}]}}}} +``` + +## ConfigMap Format + +Each ConfigMap must be in the same namespace as the query broker, and must also have the `purpose=cron-script` label. + +Each ConfigMap must contain the following data: +- a `script.pxl` key with the pixel script as its value +- a `cron.yaml` key that a valid YAML string with a `frequency_s` key, whose value controls how frequently in seconds the script is executed +- an optional `configs.yaml` key which contains a YAML string that configures OpenTelemetry data export + +An example configured to send data to an OpenTelemetry endpoint: +```yaml +--- +apiVersion: v1 +kind: ConfigMap +metadata: + name: my-configmap-script + namespace: pl + labels: + purpose: cron-script +data: + script.pxl: | + # YOUR PIXEL SCRIPT + configs.yaml: | + otelEndpointConfig: + insecure: true + url: + cron.yaml: | + frequency_s: 15 +``` + +An example without data export: +```yaml +--- +apiVersion: v1 +kind: ConfigMap +metadata: + name: my-configmap-script + namespace: pl + labels: + purpose: cron-script +data: + script.pxl: | + # YOUR PIXEL SCRIPT + cron.yaml: | + frequency_s: 15 +```