diff --git a/charts/agent/README.md b/charts/agent/README.md index 1252984..19f144e 100644 --- a/charts/agent/README.md +++ b/charts/agent/README.md @@ -1,17 +1,15 @@ # nullplatform-agent -![Version: 2.34.0](https://img.shields.io/badge/Version-2.34.0-informational?style=flat-square) ![Type: application](https://img.shields.io/badge/Type-application-informational?style=flat-square) ![AppVersion: 2.32.1](https://img.shields.io/badge/AppVersion-2.32.1-informational?style=flat-square) - -Agent used to interact with services, scopes and telemetry inside a cluster - -**Homepage:** - -## Installation +This chart installs the **nullplatform agent** to operate on your behalf to operate the lifecycle of: +* Agent-backed scopes +* Services +* Actions ```bash -helm repo add nullplatform https://nullplatform.github.io/helm-charts -helm repo update -helm install nullplatform-agent nullplatform/nullplatform-agent +helm install nullplatform-agent nullplatform/nullplatform-agent \ + --set configuration.values.NP_API_KEY=$NP_API_KEY \ + --set configuration.values.TAGS="$AGENT_TAGS" \ + --set configuration.values.AGENT_REPO=$AGENT_REPO ``` ## Maintainers @@ -20,83 +18,98 @@ helm install nullplatform-agent nullplatform/nullplatform-agent | ---- | ------ | --- | | Nullplatform | | | -## Source Code +This chart supports configuring the agent container, the runtime args it receives, and the Kubernetes resources around +it (service account, RBAC, scheduling, and optional persistence). + +* Override `args` to change the command and map it up with secret-backed values +* Add any env variable needed to start the agent using `configuration.values` + +### Secrets and init scripts + +When `configuration.create` is `true`, the chart creates a Secret named +`${configuration.secretName}-${releaseName}` and mounts it into the pod with `envFrom`. + +If `initScripts` is set, the chart creates a ConfigMap named `init-scripts-${releaseName}` and sets +`INIT_SCRIPTS_CONFIGMAP` on the container for the agent to pick up. -* +### Environment variables -## Configuration +The chart expects these values to be supplied (typically via `--set configuration.values.*`): + +```bash +export NP_API_KEY= +export AGENT_TAGS= +export AGENT_REPO= +``` + +> `AGENT_REPO` supports a single repository or a comma-separated list. For private repos, include a token in the URL. + +| Configuration Section | Key | Value | Purpose | +|----------------------|-----|-------|---------| +| **Basic Deployment** | `replicaCount` | `1` | Number of pod replicas to run | +| | `namespace` | `nullplatform-tools` | Kubernetes namespace for deployment | +| | `workloadType` | `deployment` | Workload type: `deployment` or `statefulset` | +| **StatefulSet** | `statefulset.serviceName` | `nullplatform-agent` | Headless service name for StatefulSet | +| | `statefulset.podManagementPolicy` | `OrderedReady` | Pod management policy | +| | `statefulset.updateStrategy.type` | `RollingUpdate` | Update strategy for StatefulSet | +| | `statefulset.volumeClaimTemplates` | `[]` | PVC templates for StatefulSet | +| **Application Arguments** | `args[0]` | `"--tags=$(TAGS)"` | Sets application tags from env → `configuration.values.TAGS` | +| | `args[1]` | `"--apikey=$(NP_API_KEY)"` | Provides API key → `configuration.values.NP_API_KEY` | +| | `args[2]` | `"--runtime=host"` | Runs the agent on the host runtime | +| | `args[3]` | `"--command-executor-env=NP_API_KEY=$(NP_API_KEY)"` | Passes API key to command executor | +| | `args[4]` | `"--command-executor-debug"` | Enables debug for command execution | +| | `args[5]` | `"--webserver-enabled"` | Enables built-in web server | +| | `args[6]` | `"--command-executor-git-command-repos $(AGENT_REPO)"` | Repo(s) for agent-backed scope execution → `configuration.values.AGENT_REPO` | +| **Secret Configuration** | `configuration.create` | `true` | Creates a Kubernetes secret | +| | `configuration.secretName` | `nullplatform-agent-secret` | Base name for the secret (suffixed with release name) | +| | `configuration.values.TAGS` | `""` | Agent tags | +| | `configuration.values.NP_LOG_LEVEL` | `DEBUG` | Sets logging level to debug | +| | `configuration.values.NP_API_KEY` | `""` | Nullplatform API key (to be filled) | +| | `configuration.values.AGENT_REPO` | `""` | Git repo(s) for agent-backed scopes | +| **Container Image** | `image.repository` | `public.ecr.aws/nullplatform/controlplane-agent` | Container image repository | +| | `image.pullPolicy` | `Always` | Always pull image | +| | `image.tag` | `latest` | Image tag | +| **Image Pull Secret** | `imagePullSecret.create` | `false` | Create a new image pull secret (set to `true` and provide credentials) | +| | `imagePullSecret.name` | _(unset)_ | Name of the image pull secret (when set, the pod will reference it) | +| | `imagePullSecret.registry` | `""` | Container registry URL (required if `create: true`) | +| | `imagePullSecret.username` | `""` | Username for registry authentication (required if `create: true`) | +| | `imagePullSecret.password` | `""` | Password for registry authentication (required if `create: true`) | +| **Service Account** | `serviceAccount.create` | `true` | Creates a service account | +| | `serviceAccount.automount` | `true` | Auto-mounts service account token | +| | `serviceAccount.name` | `nullplatform-agent` | Service account name | +| | `serviceAccount.clusterWide` | `true` | ClusterRole vs Role (cluster-wide access when `true`) | +| | `serviceAccount.role.rules` | Full access (`*`) | RBAC rules for the created role | +| **Pod Configuration** | `podAnnotations` | `{ name: nullplatform-agent }` | Pod annotations | +| | `podLabels` | `{ name: nullplatform-agent }` | Pod labels | +| **Resource Management** | `resources` | `{}` | Optional CPU/memory requests and limits | +| **Health Checks** | `livenessProbe.httpGet.path` | `/health` | Health check endpoint path → **Correlates with**: `args[5]` webserver | +| | `livenessProbe.httpGet.port` | `8080` | Health check port → **Correlates with**: `args[5]` webserver | +| | `readinessProbe.httpGet.path` | `/health` | Readiness check endpoint path → **Correlates with**: `args[5]` webserver | +| | `readinessProbe.httpGet.port` | `8080` | Readiness check port → **Correlates with**: `args[5]` webserver | +| **Auto Scaling** | `autoscaling.enabled` | `false` | Horizontal pod autoscaling disabled | +| | `autoscaling.minReplicas` | `1` | Minimum replicas when scaling | +| | `autoscaling.maxReplicas` | `2` | Maximum replicas when scaling | +| | `autoscaling.targetCPUUtilizationPercentage` | `80` | CPU threshold for scaling | +| **Scheduling** | `nodeSelector` | `{}` | Node selector constraints | +| **Pod Scheduling** | `tolerations[0]` | Node not ready toleration | Allows pod to run on not-ready nodes for 5 minutes | +| | `tolerations[1]` | Node unreachable toleration | Allows pod to run on unreachable nodes for 5 minutes | +| | `affinity` | `{}` | Pod affinity/anti-affinity rules | +| **Priority Class** | `priorityClass.enabled` | `true` | Create and use a PriorityClass | +| | `priorityClass.value` | `500000` | Priority value for the agent pods | +| **Init Containers** | `initContainers` | `[]` | Init containers run before the agent | +| **Init Scripts** | `initScripts` | `[]` | Inline shell scripts mounted via ConfigMap | +| **Storage** | `volumes` | `[]` | Additional volumes to mount | +| | `volumeMounts` | `[]` | Additional volume mounts | +| **Lifecycle** | `lifecycle.preStop.exec.command` | `["/bin/sh","-c","pid=$(pgrep -f agent) && kill -15 $pid && sleep 30"]` | Graceful shutdown hook | ## Values -| Key | Type | Default | Description | -|-----|------|---------|-------------| -| affinity | object | `{}` | | -| args[0] | string | `"--tags=$(TAGS)"` | | -| args[1] | string | `"--apikey=$(NP_API_KEY)"` | | -| args[2] | string | `"--runtime=host"` | | -| args[3] | string | `"--command-executor-env=NP_API_KEY=$(NP_API_KEY)"` | | -| args[4] | string | `"--command-executor-debug"` | | -| args[5] | string | `"--webserver-enabled"` | | -| args[6] | string | `"--command-executor-git-command-repos $(AGENT_REPO)"` | | -| autoscaling.enabled | bool | `false` | | -| autoscaling.maxReplicas | int | `2` | | -| autoscaling.minReplicas | int | `1` | | -| autoscaling.targetCPUUtilizationPercentage | int | `80` | | -| configuration.create | bool | `true` | | -| configuration.secretName | string | `"nullplatform-agent-secret"` | | -| configuration.values.AGENT_REPO | string | `""` | | -| configuration.values.NP_API_KEY | string | `""` | | -| configuration.values.NP_LOG_LEVEL | string | `"DEBUG"` | | -| configuration.values.TAGS | string | `""` | | -| fullnameOverride | string | `""` | | -| image.pullPolicy | string | `"Always"` | | -| image.repository | string | `"public.ecr.aws/nullplatform/controlplane-agent"` | | -| image.tag | string | `"latest"` | | -| imagePullSecret.create | bool | `false` | | -| initContainers | list | `[]` | | -| initScripts | list | `[]` | | -| lifecycle.preStop.exec.command[0] | string | `"/bin/sh"` | | -| lifecycle.preStop.exec.command[1] | string | `"-c"` | | -| lifecycle.preStop.exec.command[2] | string | `"pid=$(pgrep -f agent) && kill -15 $pid && sleep 30"` | | -| livenessProbe.httpGet.path | string | `"/health"` | | -| livenessProbe.httpGet.port | int | `8080` | | -| nameOverride | string | `""` | | -| namespace | string | `"nullplatform-tools"` | | -| nodeSelector | object | `{}` | | -| podAnnotations.name | string | `"nullplatform-agent"` | | -| podLabels.name | string | `"nullplatform-agent"` | | -| podSecurityContext | object | `{}` | | -| priorityClass.enabled | bool | `true` | | -| priorityClass.value | int | `500000` | | -| readinessProbe.httpGet.path | string | `"/health"` | | -| readinessProbe.httpGet.port | int | `8080` | | -| replicaCount | int | `1` | | -| resources | object | `{}` | | -| securityContext | object | `{}` | | -| serviceAccount.annotations | object | `{}` | | -| serviceAccount.automount | bool | `true` | | -| serviceAccount.clusterWide | bool | `true` | | -| serviceAccount.create | bool | `true` | | -| serviceAccount.name | string | `"nullplatform-agent"` | | -| serviceAccount.role.rules[0].apiGroups[0] | string | `"*"` | | -| serviceAccount.role.rules[0].apiGroups[1] | string | `""` | | -| serviceAccount.role.rules[0].resources[0] | string | `"*"` | | -| serviceAccount.role.rules[0].verbs[0] | string | `"*"` | | -| statefulset.podManagementPolicy | string | `"OrderedReady"` | | -| statefulset.serviceName | string | `"nullplatform-agent"` | | -| statefulset.updateStrategy.type | string | `"RollingUpdate"` | | -| statefulset.volumeClaimTemplates | list | `[]` | | -| tolerations[0].effect | string | `"NoExecute"` | | -| tolerations[0].key | string | `"node.kubernetes.io/not-ready"` | | -| tolerations[0].operator | string | `"Exists"` | | -| tolerations[0].tolerationSeconds | int | `300` | | -| tolerations[1].effect | string | `"NoExecute"` | | -| tolerations[1].key | string | `"node.kubernetes.io/unreachable"` | | -| tolerations[1].operator | string | `"Exists"` | | -| tolerations[1].tolerationSeconds | int | `300` | | -| volumeMounts | list | `[]` | | -| volumes | list | `[]` | | -| workloadType | string | `"deployment"` | | - ----------------------------------------------- -Autogenerated from chart metadata using [helm-docs v1.14.2](https://github.com/norwoodj/helm-docs/releases/v1.14.2) +### Environment Variable Flow: +- **`configuration.values`** → **Secret** → **Pod envFrom** → **`args` command-line arguments** + +### Key Relationships: +1. **`NP_API_KEY`**: Defined in `configuration.values.NP_API_KEY` → Used in `args[1]` and `args[3]` +2. **`TAGS`**: Defined in `configuration.values.TAGS` → Used in `args[0]` +3. **Agent-backed scopes**: `AGENT_REPO` from `configuration.values` → Used in `args[6]` +4. **Web Server**: Enabled by `args[5]` → Health probes depend on this server running on port 8080 +5. **Storage**: `volumes` + `volumeMounts` enable persistence for agent data or cloned repos