From 793c79abbc4c6bc9ebcb0869324ea4e336c3af04 Mon Sep 17 00:00:00 2001 From: eliranb Date: Tue, 13 Aug 2024 14:52:33 +0300 Subject: [PATCH 1/5] initial commit --- charts/lightrun-agents/.helmignore | 23 +++ charts/lightrun-agents/Chart.yaml | 18 ++ charts/lightrun-agents/README.md | 171 ++++++++++++++++++ .../templates/java-agent-cr.yaml | 36 ++++ charts/lightrun-agents/templates/secret.yaml | 16 ++ charts/lightrun-agents/values.yaml | 4 + 6 files changed, 268 insertions(+) create mode 100644 charts/lightrun-agents/.helmignore create mode 100644 charts/lightrun-agents/Chart.yaml create mode 100644 charts/lightrun-agents/README.md create mode 100644 charts/lightrun-agents/templates/java-agent-cr.yaml create mode 100644 charts/lightrun-agents/templates/secret.yaml create mode 100644 charts/lightrun-agents/values.yaml diff --git a/charts/lightrun-agents/.helmignore b/charts/lightrun-agents/.helmignore new file mode 100644 index 0000000..0e8a0eb --- /dev/null +++ b/charts/lightrun-agents/.helmignore @@ -0,0 +1,23 @@ +# Patterns to ignore when building packages. +# This supports shell glob matching, relative path matching, and +# negation (prefixed with !). Only one pattern per line. +.DS_Store +# Common VCS dirs +.git/ +.gitignore +.bzr/ +.bzrignore +.hg/ +.hgignore +.svn/ +# Common backup files +*.swp +*.bak +*.tmp +*.orig +*~ +# Various IDEs +.project +.idea/ +*.tmproj +.vscode/ diff --git a/charts/lightrun-agents/Chart.yaml b/charts/lightrun-agents/Chart.yaml new file mode 100644 index 0000000..0a6261d --- /dev/null +++ b/charts/lightrun-agents/Chart.yaml @@ -0,0 +1,18 @@ +apiVersion: v2 +name: lightrun-agents +description: A Helm chart for Kubernetes that deploy lightrun agents CRDs + +# A chart can be either an 'application' or a 'library' chart. +# +# Application charts are a collection of templates that can be packaged into versioned archives +# to be deployed. +# +# Library charts provide useful utilities or functions for the chart developer. They're included as +# a dependency of application charts to inject those utilities and functions into the rendering +# pipeline. Library charts do not define any templates and therefore cannot be deployed. +type: application + +# This is the chart version. This version number should be incremented each time you make changes +# to the chart and its templates, including the app version. +# Versions are expected to follow Semantic Versioning (https://semver.org/) +version: 0.0.1 diff --git a/charts/lightrun-agents/README.md b/charts/lightrun-agents/README.md new file mode 100644 index 0000000..ec91aec --- /dev/null +++ b/charts/lightrun-agents/README.md @@ -0,0 +1,171 @@ +# Helm Chart for Deploying Lightrun Agents +This Helm chart allows you to deploy and manage Lightrun Agents as custom resources in your Kubernetes cluster. +Currently only java based agents are supported. +The LightrunJavaAgent custom resource will be configured based on the values provided in the values.yaml file. + +## Prerequisites +- Kubernetes 1.16+ +- Helm 3.0+ +- Ability to fetch images of the init containers from [Lightrun Repository Dockerhub](https://hub.docker.com/u/lightruncom). or alternatively have them available in private registry. +## Installation +### 1 - Add the repo to your Helm repository list +```shell +helm repo add lightrun-k8s-operator https://lightrun-platform.github.io/lightrun-k8s-operator + +``` +### 2 - Prepare values.yaml +The "values.yaml" file contains the following configurable parameters for each java agent object: + +| Parameter | Description | Default | +|----------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------| +| `javaAgents[].agentCliFlags` | [Command-line flags for the Lightrun Java Agent.](https://docs.lightrun.com/jvm/agent-configuration/#additional-command-line-flags). | Optional `""` (empty string) | +| `javaAgents[].agentConfig` | [Additional configuration for the Lightrun Java Agent.](https://docs.lightrun.com/jvm/agent-configuration/#agent-flags) | Optional `{}` (empty map) | +| `javaAgents[].agentEnvVarName` | Specifies the Java environment variable name used for adding `--agentpath` | Optional (if not provided, defaults to `"JAVA_TOOL_OPTIONS"`) | +| `javaAgents[].agentName` | Custom name to assign to the Lightrun Java Agent. | Optional (if not provided, defaults to pod name) | +| `javaAgents[].agentPoolCredentials.existingSecret` | Name of an existing Kubernetes secret containing api key and pinned cert hash for agent pool. [secret example](https://github.com/lightrun-platform/lightrun-k8s-operator/blob/main/examples/lightrunjavaagent.yaml#L64-L73) | Optional (if not provided, defaults to `name-secret`) | +| `javaAgents[].agentPoolCredentials.apiKey` | Lightrun agent API key. | Required if `existingSecret` not set | +| `javaAgents[].agentPoolCredentials.pinnedCertHash` | 64 character sha256 certificate public key hash for pinning | Required if `existingSecret` not set | +| `javaAgents[].agentTags` | [List of Lightrun Java Agent tags.](https://docs.lightrun.com/jvm/tagging/#manage-lightrun-java-agent-tags) | Optional `[]` (empty list) | +| `javaAgents[].containerSelector` | Selector for containers within the deployment to inject the Lightrun Java Agent. | Required | +| `javaAgents[].deploymentName` | Name of the Kubernetes deployment to attach the Lightrun Java Agent. | Required | +| `javaAgents[].initContainer.image` | Image for the Lightrun Java Agent init container. | Required | +| `javaAgents[].initContainer.sharedVolumeMountPath` | Mount path for the shared volume in the init container. | Optional (if not provided, defaults to `"/lightrun"`" | +| `javaAgents[].initContainer.sharedVolumeName` | Name of the shared volume for the init container. | Optional (if not provided, defaults to `"lightrun-agent-init"`" | +| `javaAgents[].name` | Name of the Lightrun Java Agent custom resource. | Required | +| `javaAgents[].namespace` | Namespace of the Lightrun Java Agent custom resource. Must be in the same namespace as the workload | Required | +| `javaAgents[].serverHostname` | Hostname of the Lightrun server to connect the agent. | Required | + +#### 2.1 - Set `initContainer.image` + +Based on your workload's OS and architecture, you should select the appropriate DockerHub repository from the following options: +- [linux amd64](https://hub.docker.com/repository/docker/lightruncom/k8s-operator-init-java-agent-linux/general) +- [linux arm64](https://hub.docker.com/repository/docker/lightruncom/k8s-operator-init-java-agent-linux-arm64/general) +- [alpine amd64](https://hub.docker.com/repository/docker/lightruncom/k8s-operator-init-java-agent-alpine/general) +- [alpine arm64](https://hub.docker.com/repository/docker/lightruncom/k8s-operator-init-java-agent-alpine-arm64/general) + +After determining the appropriate image, you'll need to choose a tag. The tag can either be "latest," which corresponds to the most up-to-date version, or it can be a specific Lightrun version following the convention `-init.`. Typically, the `` part is 0, but it's always good to verify on the DockerHub repository. + +For your convenience, here are some possible combinations of how the final image might look: +```text +Linux amd64 with the latest version -> lightruncom/k8s-operator-init-java-agent-linux:latest +Linux amd64 with a specific version -> lightruncom/k8s-operator-init-java-agent-linux:1.39.1-init.0 +Linux arm64 with the latest version -> lightruncom/k8s-operator-init-java-agent-linux-arm64:latest +Linux arm64 with a specific version -> lightruncom/k8s-operator-init-java-agent-linux-arm64:1.39.1-init.0 +Alpine amd64 with the latest version -> lightruncom/k8s-operator-init-java-agent-alpine:latest +Alpine amd64 with a specific version -> lightruncom/k8s-operator-init-java-agent-alpine:1.39.1-init.0 +Alpine arm64 with the latest version -> lightruncom/k8s-operator-init-java-agent-alpine-arm64:latest +Alpine arm64 with a specific version -> lightruncom/k8s-operator-init-java-agent-alpine-arm64:1.39.1-init.0 +``` +#### 2.2 Install the chart + +When installing the chart, it's important to understand that the -n flag provided in the helm install command does not determine where the actual resources will be deployed. Instead, deployment is controlled by the javaAgents[].namespace parameter for each object in the values.yaml file. + +Use the -n flag to specify a namespace, either using the same namespace where your Lightrun Kubernetes Operator is installed or creating a new namespace specifically for this purpose, such as "lightrun-agents". This namespace will be referenced if you need to uninstall the chart later. +```bash +helm install lightrun-k8s-operator/lightrun-agents -n -f values.yaml +``` + +## Examples +### Basic +- The `my-service-1` does not use an `existingSecret` and instead the `agentPoolCredentials.apiKey` and `agentPoolCredentials.pinnedCertHash` are provided directly. + +- The `my-service-2` uses an `existingSecret` named `my-existing-secret` +```yaml +javaAgents: + - name: 'my-service-1' + namespace: 'my-namespace-1' + deploymentName: "my-deployment-1" + containerSelector: + - my-container-1 + serverHostname: 'lightrun.example.com' + initContainer: + image: "lightruncom/k8s-operator-init-java-agent-linux:latest" + agentPoolCredentials: + existingSecret: "" + apiKey: "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" + pinnedCertHash: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" + agentTags: + - env-production + - service-my-server + - region-us_east_1 + - provider-aws + - name: 'my-service-2' + namespace: 'my-namespace-2' + initContainer: + image: "lightruncom/k8s-operator-init-java-agent-linux:latest" + deploymentName: "my-deployment-2" + containerSelector: + - my-container-2 + serverHostname: 'lightrun.example.com' + agentPoolCredentials: + existingSecret: "my-existing-secret" + apiKey: "" + pinnedCertHash: "" + agentTags: + - env-production + - service-my-other-server + - region-us_east_1 + - provider-aws +``` + +### Full +- The `my-service-1` does not use an `existingSecret` and instead the `agentPoolCredentials.apiKey` and `agentPoolCredentials.pinnedCertHash` are provided directly. + +- The `my-service-2` uses an `existingSecret` named `my-existing-secret` +```yaml +javaAgents: + - name: 'my-service-1' + namespace: 'my-namespace-1' + deploymentName: "my-deployment-1" + containerSelector: + - my-container-1 + serverHostname: 'lightrun.example.com' + agentEnvVarName: '_JAVA_OPTIONS' + agentConfig: + max_log_cpu_cost: "2" + agentCliFlags: "--lightrun_extra_class_path=:,lightrun_init_wait_time_ms" + initContainer: + image: "lightruncom/k8s-operator-init-java-agent-linux:latest" + sharedVolumeName: 'my-shared-volume' + sharedVolumeMountPath: '/mypath' + agentPoolCredentials: + existingSecret: "" + apiKey: "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" + pinnedCertHash: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" + agentTags: + - env-production + - service-my-server + - region-us_east_1 + - provider-aws + - name: 'my-service-2' + namespace: 'my-namespace-2' + initContainer: + image: "lightruncom/k8s-operator-init-java-agent-linux:latest" + sharedVolumeName: 'my-shared-volume' + sharedVolumeMountPath: '/mypath' + deploymentName: "my-deployment-2" + containerSelector: + - my-container-2 + serverHostname: 'lightrun.example.com' + agentEnvVarName: 'JAVA_OPTS' + agentConfig: + max_log_cpu_cost: "2" + agentCliFlags: "--lightrun_extra_class_path=:,lightrun_init_wait_time_ms" + agentPoolCredentials: + existingSecret: "my-existing-secret" + apiKey: "" + pinnedCertHash: "" + agentTags: + - env-production + - service-my-other-server + - region-us_east_1 + - provider-aws +``` + +## Uninstallation +To uninstall the chart: + +```bash +helm uninstall -n +``` +This command removes all the Kubernetes components associated with the chart and deletes the release. diff --git a/charts/lightrun-agents/templates/java-agent-cr.yaml b/charts/lightrun-agents/templates/java-agent-cr.yaml new file mode 100644 index 0000000..b53808e --- /dev/null +++ b/charts/lightrun-agents/templates/java-agent-cr.yaml @@ -0,0 +1,36 @@ +{{ range .Values.javaAgents }} +--- +apiVersion: agents.lightrun.com/v1beta +kind: LightrunJavaAgent +metadata: + name: {{ .name }} + namespace: {{ .namespace }} +spec: + initContainer: + image: {{ .initContainer.image }} + sharedVolumeName: {{ .initContainer.sharedVolumeName | default "lightrun-agent-init" }} + sharedVolumeMountPath: {{ .initContainer.sharedVolumeMountPath | default "/lightrun" }} + deploymentName: {{ .deploymentName }} + containerSelector: {{- toYaml .containerSelector | nindent 4 }} + {{- if .agentPoolCredentials.existingSecret }} + secretName: {{ .agentPoolCredentials.existingSecret }} + {{- else }} + secretName: {{ .name }}-secret + {{- end }} + serverHostname: {{ .serverHostname }} + agentEnvVarName: {{ .agentEnvVarName | default "JAVA_TOOL_OPTIONS" }} + {{- if .agentConfig }} + agentConfig: {{ toYaml .agentConfig | nindent 4 }} + {{- end }} + {{- if .agentCliFlags }} + agentCliFlags: {{ .agentCliFlags }} + {{- end }} + agentTags: + {{- range .agentTags }} + - {{. -}} + {{- end }} + {{- if .agentName }} + agentName: {{ .agentName }} + {{- end }} +{{- end }} + \ No newline at end of file diff --git a/charts/lightrun-agents/templates/secret.yaml b/charts/lightrun-agents/templates/secret.yaml new file mode 100644 index 0000000..db77543 --- /dev/null +++ b/charts/lightrun-agents/templates/secret.yaml @@ -0,0 +1,16 @@ +{{ range .Values.javaAgents }} +{{- if not .agentPoolCredentials.existingSecret }} +--- +apiVersion: v1 +metadata: + name: {{ .name }}-secret + namespace: {{ .namespace }} +stringData: + # Lightrun key you can take from the server UI at the "setup agent" step + lightrun_key: {{ .agentPoolCredentials.apiKey }} + # Server certificate hash. It is ensuring that agent is connected to the right Lightrun server + pinned_cert_hash: {{ .agentPoolCredentials.pinnedCertHash }} +kind: Secret +type: Opaque +{{- end }} +{{- end }} diff --git a/charts/lightrun-agents/values.yaml b/charts/lightrun-agents/values.yaml new file mode 100644 index 0000000..f051d1e --- /dev/null +++ b/charts/lightrun-agents/values.yaml @@ -0,0 +1,4 @@ +# Default values for lightrun-javaagent. +# This is a YAML-formatted file. +# Declare variables to be passed into your templates. +javaAgents: [] From 6b44e5edf29e5b1fbf6339e8b3be57f518760760 Mon Sep 17 00:00:00 2001 From: eliranb Date: Tue, 13 Aug 2024 16:04:54 +0300 Subject: [PATCH 2/5] add config checks --- .../templates/_checkConfig.tpl | 98 +++++++++++++++++++ charts/lightrun-agents/templates/notes.txt | 2 + 2 files changed, 100 insertions(+) create mode 100644 charts/lightrun-agents/templates/_checkConfig.tpl create mode 100644 charts/lightrun-agents/templates/notes.txt diff --git a/charts/lightrun-agents/templates/_checkConfig.tpl b/charts/lightrun-agents/templates/_checkConfig.tpl new file mode 100644 index 0000000..e77268d --- /dev/null +++ b/charts/lightrun-agents/templates/_checkConfig.tpl @@ -0,0 +1,98 @@ +{{/* +Template for checking configuration + +The messages templated here will be combined into a single `fail` call. + +Message format: + +``` +checker: + MESSAGE +``` +*/}} +{{/* +Compile all warnings into a single message, and call fail. + +Due to gotpl scoping, we can't make use of `range`, so we have to add action lines. +*/}} +{{- define "checkConfig" -}} +{{- $messages := list -}} +{{/* add templates here */}} + +{{- $messages = append $messages (include "checkNamespace" .) -}} +{{- $messages = append $messages (include "checkSecret" .) -}} +{{- $messages = append $messages (include "checkName" .) -}} +{{- $messages = append $messages (include "checkContainerSelector" .) -}} +{{- $messages = append $messages (include "checkDeploymentName" .) -}} +{{- $messages = append $messages (include "checkInitContainerImage" .) -}} +{{- $messages = append $messages (include "checkServerHostname" .) -}} + + +{{- /* prepare output */}} +{{- $messages = without $messages "" -}} +{{- $message := join "\n" $messages -}} + +{{- /* print output */}} +{{- if $message -}} +{{- printf "\nCONFIGURATION CHECKS:\n%s" $message | fail -}} +{{- end -}} +{{- end -}} + + +{{- define "checkContainerSelector" -}} +{{- range .Values.javaAgents }} +{{- if not .containerSelector }} +{{- printf "containerSelector Checker:\nError: The 'containerSelector' field is missing in %s java agent object. Please specify a 'containerSelector' paramter.\n" .name }} +{{- end }} +{{- end }} +{{- end -}} + +{{- define "checkDeploymentName" -}} +{{- range .Values.javaAgents }} +{{- if not .deploymentName }} +{{- printf "deploymentName Checker:\nError: The 'deploymentName' field is missing in %s java agent object. Please specify a 'deploymentName' paramter.\n" .name }} +{{- end }} +{{- end }} +{{- end -}} + +{{- define "checkInitContainerImage" -}} +{{- range .Values.javaAgents }} +{{- if not .initContainer.image }} +{{- printf "initContainerImage Checker:\nError: The 'initContainer.image' field is missing in %s java agent object. Please specify a 'initContainer.image' parameter.\n" .name }} +{{- end }} +{{- end }} +{{- end -}} + +{{- define "checkName" -}} +{{- range .Values.javaAgents }} +{{- if not .name }} +{{- printf "Name Checker:\nError: The '.name' field is missing in %s java agent object. Please specify a '.name' parameter.\n" .name }} +{{- end }} +{{- end }} +{{- end -}} + +{{- define "checkServerHostname" -}} +{{- range .Values.javaAgents }} +{{- if not .serverHostname }} +{{- printf "serverHostname Checker:\nError: The '.serverHostname' field is missing in %s java agent object. Please specify a '.serverHostname' parameter.\n" .name }} +{{- end }} +{{- end }} +{{- end -}} + +{{- define "checkNamespace" -}} +{{- range .Values.javaAgents }} +{{- if not .namespace }} +{{- printf "Namespace Checker:\nError: The 'namespace' field is missing in %s java agent object. Please specify a namespace.\n" .name }} +{{- end }} +{{- end }} +{{- end -}} + +{{- define "checkSecret" -}} +{{- range .Values.javaAgents }} +{{- if and .agentPoolCredentials.existingSecret .agentPoolCredentials.apiKey .agentPoolCredentials.pinnedCertHash }} +{{- printf "Secret Checker:\nError: both '.agentPoolCredentials.existingSecret' field and '.agentPoolCredentials.apiKey' '.agentPoolCredentials.pinnedCertHash' are provided in %s java agent object. Please choose either existingSecret or apiKey and pinnedCertHash.\n" .name }} +{{- end }} +{{- end }} +{{- end -}} + + diff --git a/charts/lightrun-agents/templates/notes.txt b/charts/lightrun-agents/templates/notes.txt new file mode 100644 index 0000000..84568f0 --- /dev/null +++ b/charts/lightrun-agents/templates/notes.txt @@ -0,0 +1,2 @@ +{{- /* run checkConfig */}} +{{ include "checkConfig" . }} \ No newline at end of file From 0bab21daf176ea5dcba4a18debb6ac1987006e03 Mon Sep 17 00:00:00 2001 From: eliranb Date: Tue, 13 Aug 2024 17:52:48 +0300 Subject: [PATCH 3/5] fixes to README and checkConfig --- charts/lightrun-agents/README.md | 81 +++++----- .../templates/_checkConfig.tpl | 139 ++++++------------ charts/lightrun-agents/templates/notes.txt | 4 +- 3 files changed, 99 insertions(+), 125 deletions(-) diff --git a/charts/lightrun-agents/README.md b/charts/lightrun-agents/README.md index ec91aec..c44a619 100644 --- a/charts/lightrun-agents/README.md +++ b/charts/lightrun-agents/README.md @@ -1,51 +1,57 @@ # Helm Chart for Deploying Lightrun Agents -This Helm chart allows you to deploy and manage Lightrun Agents as custom resources in your Kubernetes cluster. -Currently only java based agents are supported. -The LightrunJavaAgent custom resource will be configured based on the values provided in the values.yaml file. + +This Helm chart enables the deployment and management of Lightrun Agents as custom resources within your Kubernetes cluster. Currently, only Java-based agents are supported. The LightrunJavaAgent custom resource will be configured according to the settings specified in the values.yaml file. ## Prerequisites -- Kubernetes 1.16+ -- Helm 3.0+ -- Ability to fetch images of the init containers from [Lightrun Repository Dockerhub](https://hub.docker.com/u/lightruncom). or alternatively have them available in private registry. + +- Kubernetes 1.19+ +- Ability to fetch images of the init containers from [Lightrun Repository Dockerhub](https://hub.docker.com/u/lightruncom). or alternatively have them available in private registry. + ## Installation + ### 1 - Add the repo to your Helm repository list + ```shell helm repo add lightrun-k8s-operator https://lightrun-platform.github.io/lightrun-k8s-operator ``` + ### 2 - Prepare values.yaml -The "values.yaml" file contains the following configurable parameters for each java agent object: - -| Parameter | Description | Default | -|----------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------| -| `javaAgents[].agentCliFlags` | [Command-line flags for the Lightrun Java Agent.](https://docs.lightrun.com/jvm/agent-configuration/#additional-command-line-flags). | Optional `""` (empty string) | -| `javaAgents[].agentConfig` | [Additional configuration for the Lightrun Java Agent.](https://docs.lightrun.com/jvm/agent-configuration/#agent-flags) | Optional `{}` (empty map) | -| `javaAgents[].agentEnvVarName` | Specifies the Java environment variable name used for adding `--agentpath` | Optional (if not provided, defaults to `"JAVA_TOOL_OPTIONS"`) | -| `javaAgents[].agentName` | Custom name to assign to the Lightrun Java Agent. | Optional (if not provided, defaults to pod name) | -| `javaAgents[].agentPoolCredentials.existingSecret` | Name of an existing Kubernetes secret containing api key and pinned cert hash for agent pool. [secret example](https://github.com/lightrun-platform/lightrun-k8s-operator/blob/main/examples/lightrunjavaagent.yaml#L64-L73) | Optional (if not provided, defaults to `name-secret`) | -| `javaAgents[].agentPoolCredentials.apiKey` | Lightrun agent API key. | Required if `existingSecret` not set | -| `javaAgents[].agentPoolCredentials.pinnedCertHash` | 64 character sha256 certificate public key hash for pinning | Required if `existingSecret` not set | -| `javaAgents[].agentTags` | [List of Lightrun Java Agent tags.](https://docs.lightrun.com/jvm/tagging/#manage-lightrun-java-agent-tags) | Optional `[]` (empty list) | -| `javaAgents[].containerSelector` | Selector for containers within the deployment to inject the Lightrun Java Agent. | Required | -| `javaAgents[].deploymentName` | Name of the Kubernetes deployment to attach the Lightrun Java Agent. | Required | -| `javaAgents[].initContainer.image` | Image for the Lightrun Java Agent init container. | Required | -| `javaAgents[].initContainer.sharedVolumeMountPath` | Mount path for the shared volume in the init container. | Optional (if not provided, defaults to `"/lightrun"`" | -| `javaAgents[].initContainer.sharedVolumeName` | Name of the shared volume for the init container. | Optional (if not provided, defaults to `"lightrun-agent-init"`" | -| `javaAgents[].name` | Name of the Lightrun Java Agent custom resource. | Required | -| `javaAgents[].namespace` | Namespace of the Lightrun Java Agent custom resource. Must be in the same namespace as the workload | Required | -| `javaAgents[].serverHostname` | Hostname of the Lightrun server to connect the agent. | Required | - -#### 2.1 - Set `initContainer.image` + +The values.yaml file includes the following configurable parameters for each Java agent object: + +| Parameter | Description | Default | +| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | +| `javaAgents[].agentCliFlags` | [Command-line flags for the Lightrun Java Agent.](https://docs.lightrun.com/jvm/agent-configuration/#additional-command-line-flags). | Optional `""` (empty string) | +| `javaAgents[].agentConfig` | [Additional configuration for the Lightrun Java Agent.](https://docs.lightrun.com/jvm/agent-configuration/#agent-flags). | Optional `{}` (empty map) | +| `javaAgents[].agentEnvVarName` | Specifies the Java environment variable name used to add `--agentpath`. | Optional (if not provided, defaults to `"JAVA_TOOL_OPTIONS"`) | +| `javaAgents[].agentName` | Custom name to assign to the Lightrun Java Agent. | Optional (if not provided, defaults to pod name) | +| `javaAgents[].agentPoolCredentials.existingSecret` | Name of an existing Kubernetes secret that contains the API key and pinned certificate hash for the agent pool. [secret example](https://github.com/lightrun-platform/lightrun-k8s-operator/blob/main/examples/lightrunjavaagent.yaml#L64-L73). | Optional (if not provided, defaults to `name-secret`) | +| `javaAgents[].agentPoolCredentials.apiKey` | Lightrun agent API key. | Required if `existingSecret` not set | +| `javaAgents[].agentPoolCredentials.pinnedCertHash` | 64 character sha256 certificate public key hash for pinning. | Required if `existingSecret` not set | +| `javaAgents[].agentTags` | [List of Lightrun Java Agent tags](https://docs.lightrun.com/jvm/tagging/#manage-lightrun-java-agent-tags). | Optional `[]` (empty list) | +| `javaAgents[].containerSelector` | Selector for containers within the deployment to inject the Lightrun Java Agent. | Required | +| `javaAgents[].deploymentName` | Name of the Kubernetes deployment to attach the Lightrun Java Agent. | Required | +| `javaAgents[].initContainer.image` | Image for the Lightrun Java Agent init container. | Required | +| `javaAgents[].initContainer.sharedVolumeMountPath` | Mount path for the shared volume in the init container. | Optional (if not provided, defaults to `"/lightrun"`" | +| `javaAgents[].initContainer.sharedVolumeName` | Name of the shared volume for the init container. | Optional (if not provided, defaults to `"lightrun-agent-init"`" | +| `javaAgents[].name` | Name of the Lightrun Java Agent custom resource. | Required | +| `javaAgents[].namespace` | Namespace of the Lightrun Java Agent custom resource. Must be in the same namespace as the workload | Required | +| `javaAgents[].serverHostname` | Hostname of the Lightrun server to connect the agent. | Required | + +#### 2.1 - Set `initContainer.image` Based on your workload's OS and architecture, you should select the appropriate DockerHub repository from the following options: + - [linux amd64](https://hub.docker.com/repository/docker/lightruncom/k8s-operator-init-java-agent-linux/general) - [linux arm64](https://hub.docker.com/repository/docker/lightruncom/k8s-operator-init-java-agent-linux-arm64/general) - [alpine amd64](https://hub.docker.com/repository/docker/lightruncom/k8s-operator-init-java-agent-alpine/general) -- [alpine arm64](https://hub.docker.com/repository/docker/lightruncom/k8s-operator-init-java-agent-alpine-arm64/general) +- [alpine arm64](https://hub.docker.com/repository/docker/lightruncom/k8s-operator-init-java-agent-alpine-arm64/general) -After determining the appropriate image, you'll need to choose a tag. The tag can either be "latest," which corresponds to the most up-to-date version, or it can be a specific Lightrun version following the convention `-init.`. Typically, the `` part is 0, but it's always good to verify on the DockerHub repository. +After determining the appropriate image, you will need to choose a tag. The tag can either be "latest," which corresponds to the most up-to-date Lightrun version, or it can be a specific Lightrun version following the convention `-init.`. Typically, the `` part is 0, but it is always good to verify on the DockerHub repository. For your convenience, here are some possible combinations of how the final image might look: + ```text Linux amd64 with the latest version -> lightruncom/k8s-operator-init-java-agent-linux:latest Linux amd64 with a specific version -> lightruncom/k8s-operator-init-java-agent-linux:1.39.1-init.0 @@ -56,20 +62,25 @@ Alpine amd64 with a specific version -> lightruncom/k8s-operator-init-java-agent Alpine arm64 with the latest version -> lightruncom/k8s-operator-init-java-agent-alpine-arm64:latest Alpine arm64 with a specific version -> lightruncom/k8s-operator-init-java-agent-alpine-arm64:1.39.1-init.0 ``` + #### 2.2 Install the chart -When installing the chart, it's important to understand that the -n flag provided in the helm install command does not determine where the actual resources will be deployed. Instead, deployment is controlled by the javaAgents[].namespace parameter for each object in the values.yaml file. +When installing the chart, it is important to understand that the -n flag provided in the helm install command does not determine where the actual resources will be deployed. Instead, deployment is controlled by the javaAgents[].namespace parameter for each object in the values.yaml file. Use the -n flag to specify a namespace, either using the same namespace where your Lightrun Kubernetes Operator is installed or creating a new namespace specifically for this purpose, such as "lightrun-agents". This namespace will be referenced if you need to uninstall the chart later. + ```bash helm install lightrun-k8s-operator/lightrun-agents -n -f values.yaml ``` ## Examples + ### Basic + - The `my-service-1` does not use an `existingSecret` and instead the `agentPoolCredentials.apiKey` and `agentPoolCredentials.pinnedCertHash` are provided directly. - The `my-service-2` uses an `existingSecret` named `my-existing-secret` + ```yaml javaAgents: - name: 'my-service-1' @@ -109,9 +120,11 @@ javaAgents: ``` ### Full + - The `my-service-1` does not use an `existingSecret` and instead the `agentPoolCredentials.apiKey` and `agentPoolCredentials.pinnedCertHash` are provided directly. - The `my-service-2` uses an `existingSecret` named `my-existing-secret` + ```yaml javaAgents: - name: 'my-service-1' @@ -127,7 +140,7 @@ javaAgents: initContainer: image: "lightruncom/k8s-operator-init-java-agent-linux:latest" sharedVolumeName: 'my-shared-volume' - sharedVolumeMountPath: '/mypath' + sharedVolumeMountPath: '/mypath' agentPoolCredentials: existingSecret: "" apiKey: "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" @@ -150,7 +163,7 @@ javaAgents: agentEnvVarName: 'JAVA_OPTS' agentConfig: max_log_cpu_cost: "2" - agentCliFlags: "--lightrun_extra_class_path=:,lightrun_init_wait_time_ms" + agentCliFlags: "--lightrun_extra_class_path=:,lightrun_init_wait_time_ms" agentPoolCredentials: existingSecret: "my-existing-secret" apiKey: "" @@ -163,9 +176,11 @@ javaAgents: ``` ## Uninstallation + To uninstall the chart: ```bash helm uninstall -n ``` + This command removes all the Kubernetes components associated with the chart and deletes the release. diff --git a/charts/lightrun-agents/templates/_checkConfig.tpl b/charts/lightrun-agents/templates/_checkConfig.tpl index e77268d..3c746cc 100644 --- a/charts/lightrun-agents/templates/_checkConfig.tpl +++ b/charts/lightrun-agents/templates/_checkConfig.tpl @@ -1,98 +1,57 @@ {{/* -Template for checking configuration - -The messages templated here will be combined into a single `fail` call. - -Message format: - -``` -checker: - MESSAGE -``` -*/}} -{{/* Compile all warnings into a single message, and call fail. - -Due to gotpl scoping, we can't make use of `range`, so we have to add action lines. */}} -{{- define "checkConfig" -}} -{{- $messages := list -}} -{{/* add templates here */}} - -{{- $messages = append $messages (include "checkNamespace" .) -}} -{{- $messages = append $messages (include "checkSecret" .) -}} -{{- $messages = append $messages (include "checkName" .) -}} -{{- $messages = append $messages (include "checkContainerSelector" .) -}} -{{- $messages = append $messages (include "checkDeploymentName" .) -}} -{{- $messages = append $messages (include "checkInitContainerImage" .) -}} -{{- $messages = append $messages (include "checkServerHostname" .) -}} - - -{{- /* prepare output */}} -{{- $messages = without $messages "" -}} -{{- $message := join "\n" $messages -}} - -{{- /* print output */}} -{{- if $message -}} -{{- printf "\nCONFIGURATION CHECKS:\n%s" $message | fail -}} -{{- end -}} -{{- end -}} +{{- define "javaAgents.checkConfig" -}} +{{- $objectErrors := dict -}} {{/* Create a dictionary to store errors by agent name */}} -{{- define "checkContainerSelector" -}} {{- range .Values.javaAgents }} -{{- if not .containerSelector }} -{{- printf "containerSelector Checker:\nError: The 'containerSelector' field is missing in %s java agent object. Please specify a 'containerSelector' paramter.\n" .name }} -{{- end }} -{{- end }} + {{- $objectName := .name }} + {{- $objectErrorMsgs := list -}} {{/* Create a list to store errors for the current agent */}} + + {{- /* Add error messages to the list if fields are missing */}} + {{- if not .namespace }} + {{- $objectErrorMsgs = append $objectErrorMsgs "Namespace Checker:\n Error: The 'namespace' field is missing. Please provide the 'namespace' parameter." -}} + {{- end }} + {{- if not .serverHostname }} + {{- $objectErrorMsgs = append $objectErrorMsgs "Server Hostname Checker:\n Error: The 'serverHostname' field is missing. Please provide the 'serverHostname' parameter." -}} + {{- end }} + {{- if not .name }} + {{- $objectErrorMsgs = append $objectErrorMsgs "Name Checker:\n Error: The 'name' field is missing. Please provide the 'name' parameter." -}} + {{- end }} + {{- if not .initContainer.image }} + {{- $objectErrorMsgs = append $objectErrorMsgs "Init Container Image Checker:\n Error: The 'initContainer.image' field is missing. Please provide the 'initContainer.image' parameter." -}} + {{- end }} + {{- if not .deploymentName }} + {{- $objectErrorMsgs = append $objectErrorMsgs "Deployment Name Checker:\n Error: The 'deploymentName' field is missing. Please provide the 'deploymentName' parameter." -}} + {{- end }} + {{- if not .containerSelector }} + {{- $objectErrorMsgs = append $objectErrorMsgs "Container Selector Checker:\n Error: The 'containerSelector' field is missing. Please provide the 'containerSelector' parameter." -}} + {{- end }} + + {{- if .agentPoolCredentials.existingSecret }} + {{- if and .agentPoolCredentials.apiKey .agentPoolCredentials.pinnedCertHash }} + {{- $objectErrorMsgs = append $objectErrorMsgs "Secret Checker:\n Error: Both 'agentPoolCredentials.existingSecret' and 'agentPoolCredentials.apiKey' with 'agentPoolCredentials.pinnedCertHash' are defined. Please use only one of the following: 'existingSecret' or 'apiKey' with 'pinnedCertHash'." -}} + {{- end }} + {{- end }} + + {{- if not .agentPoolCredentials.existingSecret }} + {{- if not (and .agentPoolCredentials.apiKey .agentPoolCredentials.pinnedCertHash) }} + {{- $objectErrorMsgs = append $objectErrorMsgs "Secret Checker:\n Error: neither 'agentPoolCredentials.existingSecret' nor 'agentPoolCredentials.apiKey' with 'agentPoolCredentials.pinnedCertHash' are defined. Please use one of the following: 'existingSecret' or 'apiKey' with 'pinnedCertHash'." -}} + {{- end }} + {{- end }} + + {{- if $objectErrorMsgs }} + {{- $objectErrors = merge $objectErrors (dict $objectName $objectErrorMsgs) -}} + {{- end }} +{{- end }} + +{{- /* Prepare and print output */}} +{{- if $objectErrors }} + {{- $output := list -}} + {{- range $name, $errors := $objectErrors }} + {{- $output = append $output (printf "Errors for Java agent '%s':\n%s" $name (join "\n" $errors)) -}} + {{- end }} + {{- printf "\nCONFIGURATION CHECKS:\n%s" (join "\n\n" $output) | fail -}} {{- end -}} - -{{- define "checkDeploymentName" -}} -{{- range .Values.javaAgents }} -{{- if not .deploymentName }} -{{- printf "deploymentName Checker:\nError: The 'deploymentName' field is missing in %s java agent object. Please specify a 'deploymentName' paramter.\n" .name }} -{{- end }} -{{- end }} -{{- end -}} - -{{- define "checkInitContainerImage" -}} -{{- range .Values.javaAgents }} -{{- if not .initContainer.image }} -{{- printf "initContainerImage Checker:\nError: The 'initContainer.image' field is missing in %s java agent object. Please specify a 'initContainer.image' parameter.\n" .name }} -{{- end }} -{{- end }} {{- end -}} - -{{- define "checkName" -}} -{{- range .Values.javaAgents }} -{{- if not .name }} -{{- printf "Name Checker:\nError: The '.name' field is missing in %s java agent object. Please specify a '.name' parameter.\n" .name }} -{{- end }} -{{- end }} -{{- end -}} - -{{- define "checkServerHostname" -}} -{{- range .Values.javaAgents }} -{{- if not .serverHostname }} -{{- printf "serverHostname Checker:\nError: The '.serverHostname' field is missing in %s java agent object. Please specify a '.serverHostname' parameter.\n" .name }} -{{- end }} -{{- end }} -{{- end -}} - -{{- define "checkNamespace" -}} -{{- range .Values.javaAgents }} -{{- if not .namespace }} -{{- printf "Namespace Checker:\nError: The 'namespace' field is missing in %s java agent object. Please specify a namespace.\n" .name }} -{{- end }} -{{- end }} -{{- end -}} - -{{- define "checkSecret" -}} -{{- range .Values.javaAgents }} -{{- if and .agentPoolCredentials.existingSecret .agentPoolCredentials.apiKey .agentPoolCredentials.pinnedCertHash }} -{{- printf "Secret Checker:\nError: both '.agentPoolCredentials.existingSecret' field and '.agentPoolCredentials.apiKey' '.agentPoolCredentials.pinnedCertHash' are provided in %s java agent object. Please choose either existingSecret or apiKey and pinnedCertHash.\n" .name }} -{{- end }} -{{- end }} -{{- end -}} - - diff --git a/charts/lightrun-agents/templates/notes.txt b/charts/lightrun-agents/templates/notes.txt index 84568f0..58bcfe3 100644 --- a/charts/lightrun-agents/templates/notes.txt +++ b/charts/lightrun-agents/templates/notes.txt @@ -1,2 +1,2 @@ -{{- /* run checkConfig */}} -{{ include "checkConfig" . }} \ No newline at end of file +{{- /* run checkConfigs */}} +{{ include "javaAgents.checkConfig" . }} \ No newline at end of file From af3a0d7d0f709eb729308f901414004132f8fa3e Mon Sep 17 00:00:00 2001 From: eliranb Date: Tue, 13 Aug 2024 18:03:38 +0300 Subject: [PATCH 4/5] add Pack Lightrun Agents Helm chart step in the release.yaml --- .github/workflows/release.yaml | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml index 18609fd..244f8f1 100644 --- a/.github/workflows/release.yaml +++ b/.github/workflows/release.yaml @@ -9,6 +9,7 @@ on: - lightrun-init-agent/* - .github/** - helm-chart/* + - charts/* - grafana/* - config/* - examples/* @@ -60,6 +61,11 @@ jobs: yq -i '.version = "${{steps.release_tag.outputs.new_tag}}"' helm-chart/Chart.yaml yq -i '.controllerManager.manager.image.tag = "${{steps.release_tag.outputs.new_tag}}"' helm-chart/values.yaml helm package ./helm-chart -u -d ./helm-repo/ + - name: Pack Lightrun Agents Helm chart + shell: bash + run: | + yq -i '.version = "${{steps.release_tag.outputs.new_tag}}"' charts/lightrun-agents/Chart.yaml + helm package ./charts/lightrun-agents -u -d ./helm-repo/ - name: Login to DockerHub if: ${{ success() }} From 15f1c0cd274f3f9ebc949b2c49dcebd7e42b21be Mon Sep 17 00:00:00 2001 From: eliranb Date: Thu, 15 Aug 2024 13:00:54 +0300 Subject: [PATCH 5/5] add example to values.yaml --- charts/lightrun-agents/values.yaml | 95 ++++++++++++++++++++++++++++++ 1 file changed, 95 insertions(+) diff --git a/charts/lightrun-agents/values.yaml b/charts/lightrun-agents/values.yaml index f051d1e..62386bf 100644 --- a/charts/lightrun-agents/values.yaml +++ b/charts/lightrun-agents/values.yaml @@ -2,3 +2,98 @@ # This is a YAML-formatted file. # Declare variables to be passed into your templates. javaAgents: [] +## Examples +### Basic +#- The `my-service-1` does not use an `existingSecret` and instead the `agentPoolCredentials.apiKey` and `agentPoolCredentials.pinnedCertHash` are provided directly. + +#- The `my-service-2` uses an `existingSecret` named `my-existing-secret` + +#javaAgents: +# - name: 'my-service-1' +# namespace: 'my-namespace-1' +# deploymentName: "my-deployment-1" +# containerSelector: +# - my-container-1 +# serverHostname: 'lightrun.example.com' +# initContainer: +# image: "lightruncom/k8s-operator-init-java-agent-linux:latest" +# agentPoolCredentials: +# existingSecret: "" +# apiKey: "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" +# pinnedCertHash: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" +# agentTags: +# - env-production +# - service-my-server +# - region-us_east_1 +# - provider-aws +# - name: 'my-service-2' +# namespace: 'my-namespace-2' +# initContainer: +# image: "lightruncom/k8s-operator-init-java-agent-linux:latest" +# deploymentName: "my-deployment-2" +# containerSelector: +# - my-container-2 +# serverHostname: 'lightrun.example.com' +# agentPoolCredentials: +# existingSecret: "my-existing-secret" +# apiKey: "" +# pinnedCertHash: "" +# agentTags: +# - env-production +# - service-my-other-server +# - region-us_east_1 +# - provider-aws + +### Full + +# - The `my-service-1` does not use an `existingSecret` and instead the `agentPoolCredentials.apiKey` and `agentPoolCredentials.pinnedCertHash` are provided directly. + +# - The `my-service-2` uses an `existingSecret` named `my-existing-secret` + +#javaAgents: +# - name: 'my-service-1' +# namespace: 'my-namespace-1' +# deploymentName: "my-deployment-1" +# containerSelector: +# - my-container-1 +# serverHostname: 'lightrun.example.com' +# agentEnvVarName: '_JAVA_OPTIONS' +# agentConfig: +# max_log_cpu_cost: "2" +# agentCliFlags: "--lightrun_extra_class_path=:,lightrun_init_wait_time_ms" +# initContainer: +# image: "lightruncom/k8s-operator-init-java-agent-linux:latest" +# sharedVolumeName: 'my-shared-volume' +# sharedVolumeMountPath: '/mypath' +# agentPoolCredentials: +# existingSecret: "" +# apiKey: "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" +# pinnedCertHash: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" +# agentTags: +# - env-production +# - service-my-server +# - region-us_east_1 +# - provider-aws +# - name: 'my-service-2' +# namespace: 'my-namespace-2' +# initContainer: +# image: "lightruncom/k8s-operator-init-java-agent-linux:latest" +# sharedVolumeName: 'my-shared-volume' +# sharedVolumeMountPath: '/mypath' +# deploymentName: "my-deployment-2" +# containerSelector: +# - my-container-2 +# serverHostname: 'lightrun.example.com' +# agentEnvVarName: 'JAVA_OPTS' +# agentConfig: +# max_log_cpu_cost: "2" +# agentCliFlags: "--lightrun_extra_class_path=:,lightrun_init_wait_time_ms" +# agentPoolCredentials: +# existingSecret: "my-existing-secret" +# apiKey: "" +# pinnedCertHash: "" +# agentTags: +# - env-production +# - service-my-other-server +# - region-us_east_1 +# - provider-aws \ No newline at end of file